Class: EncodedStream

• Inheritance
• Description
• Class protocol
  • Compatibility-VW5.4
  • instance creation
  • utilities
• Instance protocol
  • Compatibility-VW5.4
  • accessing
  • chunk input/output
  • queries
  • stream protocol
  • testing
  • utilities

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--EncodedStream

Package:

stx:libbasic

Category:

Collections-Text-Encodings

Version:

rev: 1.57 date: 2019/04/01 15:17:35

user: cg

file: EncodedStream.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

a stream which transparently decodes from an external decoding,
looking for '{ Encoding: xxx' near the beginning of the file.

especially targeted towards reading ST/X source files.

Class protocol:

 on: aStream encodedBy: aStreamEncoder

 stream: streamArg encoder: encoder

|s|
s := EncodedStream stream:Transcript encoder:(CharacterEncoder encoderToEncodeFrom:#utf8 into:#unicode).
s nextPutAll:('öäü' utf8Encoded)

|s|
s := EncodedStream stream:('öäü' readStream) encoder:(CharacterEncoder encoderToEncodeFrom:#utf8 into:#unicode).
s next:3

 stream: streamArg encoding: encodingSymbol

|baseStream s|
baseStream := '' readWriteStream.
s := EncodedStream stream:baseStream encoding:#utf8.
s nextPutAll:'öäü'.
baseStream reset; contents.

s contents

 decodedStreamFor: aStream

given a positionable stream, guess its encoding (by reading the
first few lines, looking for a string with an encoding hint,
and return an appropriate encoded string, which does the decoding
on the fly. Used mostly to read UTF8 files (source code)

 encoderFor: anEncodingSymbol

Instance protocol:

 on: aStream encodedBy: aStreamEncoder

Initialize the receiver on aStream with aStreamEncoder.

 encoder

 encoder: aCharacterEncoder

 encoding

 inputStream

 lineNumber

the linenumber doesn't change when characters are decoded

 pathName

if our base stream has a pathname, delegate...

 readStream

read from self

 stream

 stream: something

 nextChunk

reads a smalltalk chunk.
as a side effect, check for an encoding chunk

 contentsSpecies

(comment from inherited method)
this should return the class of which an instance is
returned by the #contents method. Here, Array is returned,
since the abstract Stream-class has no idea of the underlying
collection class.
It is redefined in some subclasses - for example, to return String.

 isEncoderFor: encodingString

 atEnd

(comment from inherited method)
return true if the end of the stream has been reached;
- we do not know here how to do it, it must be redefined in subclass

 close

(comment from inherited method)
close the stream - nothing done here.
Added for compatibility with external streams.

 collection

return the underlying container; nil, if there is none (eg. external streams).
Here we return nil, as the underlying collection (if any) is useless to the outside world

 contents

decoder may decide to return nil from #next, even though the

 emphasis: anObject

(comment from inherited method)
ignored here
- allows Streams to be used interchangable with text streams

 flush

(comment from inherited method)
write out all unbuffered data - ignored here, but added
to make internalStreams protocol compatible with externalStreams

 isEmpty

(comment from inherited method)
return true, if the contents of the stream is empty

 next

(comment from inherited method)
return the next element of the stream
- we do not know here how to do it, it must be redefined in subclass

 next: nCharactersToRead

(comment from inherited method)
return the next count elements of the stream as aCollection,
which depends on the streams type - (see #contentsSpecies).

 nextPut: aCharacter

(comment from inherited method)
put the argument, anObject onto the receiver
- we do not know here how to do it, it must be redefined in subclass

 nextPutAll: aCollection

 nextPutAll: aCollection startingAt: start to: stop

append the elements from first index to last index
of the argument, aCollection onto the receiver (i.e. both outstreams)

 peek

(comment from inherited method)
return the next element of the stream without advancing (i.e.
the following send of next will return this element again.)
- we do not know here how to do it, it must be redefined in subclass

 position

only use #position/#position: to restore a previous position.
Computing relative positions does not work!

usage example(s):

#position: nils peekChar - make sure, that it positions before peekChar

 position0Based

to be obsoleted - use position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 position0Based: newPosition

to be obsoleted - use position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 position1Based

to be obsoleted - use position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 position1Based: newPosition

to be obsoleted - use position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 position: newPosition

only use #position/#position: to restore a previous position.
Computing relative positions does not work!
Use #skip: to advance forward.

 reset

 setToEnd

Modified (comment): / 09-01-2018 / 17:50:27 / stefan

 size

not always correct, but probably better than 0.
Better use #isEmpty.

usage example(s):

self error:'size of input is unknown (due to decoding)'

 skip: nrToSkip

can only skip forward

 sync

 syncData

 isEncodedStream

(comment from inherited method)
true, iff this is an encoder/decoder stream

 isOpen

for compatibility with externalStream:
return true, if this stream is open.

 isPositionable

(comment from inherited method)
return true, if the stream supports positioning (some do not).
Since this is an abstract class, false is returned here - just to make certain.

 isReadable

 isWritable

 skipEncodingChunk

if this is a valid chunk (i.e. not a comment or encoding-directive),