"

 COPYRIGHT (c) 1989 by Claus Gittinger

 COPYRIGHT (c) 2017 Jan Vrany

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Object subclass:#Stream

	instanceVariableNames:'signalAtEnd'

	classVariableNames:'ChunkSeparator EndOfStreamSignal LineTooLongErrorSignal

		PositionErrorSignal ReadErrorSignal StreamErrorSignal

		WriteErrorSignal'

	poolDictionaries:''

	category:'Streams'

!

!Stream class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

 COPYRIGHT (c) 2017 Jan Vrany

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    An abstract class defining common behavior for all stream-like objects.

    See concrete subclasses for more detail.

    The protocol as implemented here is often only provided as a fallBack

    for very uncommon cases. Much of it is redefined for performance.

    (In streams which know more about their internal representation ...)

    Subclasses should (at least) implement:

        #next           (if readable)

        #nextPut:       (if writable)

        #contents

        #atEnd

        #isReadable

        #isWritable

    Peekable & Positionable streams should (at least) implement:

        #peek

        #position

        #position:

    [instance variables:]

        signalAtEnd             <nil | Boolean> controls behavior when a read

                                                is attempted past the end-of-stream

                                                if true, the endOfStreamSignal is raised.

                                                if false, nil is returned.

                                                if nil (the default), the signal

                                                is raised, but if there is no handler,

                                                nil is returned.

    [Class variables / Exceptions:]

        StreamError             <Exception>     parent of all stream errors

        PositionError           <Exception>     position attemted on a stream

                                                which does not support positioning,

                                                or if the position is invalid.

        ReadError               <Exception>     raised on read errors

        WriteError              <Exception>     raised on write errors

        EndOfStreamSignal       <Signal>        raised at end of stream if signalAtEnd

                                                is enabled.

    [caveat:]

        The Stream hierarchy has a few little quirks in it, which are a consequence of some early historic

        decisions. The biggest problem is the distinction between readable and writeable streams based on inheritance,

        instead of by either using state (i.e. a flag) or delegation.

        The problem is that there are streams which can be both, and maybe even dynamically change their opinion,

        on whether being readable/writable.

        (For example, a buffer may be write-only while filled, but become readonly, when given to a consumer.)

        The above decision to base this on inheritance lead to the ugly ReadStream - WriteStream - ReadWriteStream

        hierarchy, with some subclasses undoing the blocking of their superclass.

        Classes named 'ReadStream', 'WriteStream', 'ReadWriteStream', 'PeekableStream' and 'PositionableStream' should

        all be eliminated in favour of a few flags in the 'Stream' superclass.

        It is really time for a new stream hierarchy (XStreams, for example).

        (On the other hand: there is so much code around, which depends on the current situation, that such a change

         must really be thought through - most got used to these issues and live with it more or less happily)

    [author:]

        Claus Gittinger

"

! !

!Stream class methodsFor:'initialization'!

initSignals

    StreamErrorSignal := StreamError.

    StreamErrorSignal notifierString:'Stream error'.

    PositionErrorSignal := PositionError.

    PositionErrorSignal notifierString:'stream has no concept of a position'.

    ReadErrorSignal := ReadError.

    ReadErrorSignal notifierString:'read error'.

    WriteErrorSignal := WriteError.

    WriteErrorSignal notifierString:'write error'.

    LineTooLongErrorSignal := QuerySignal new.

    LineTooLongErrorSignal parent:StreamError.

    LineTooLongErrorSignal nameClass:self message:#lineTooLongErrorSignal.

    LineTooLongErrorSignal notifierString:'line too long'.

    EndOfStreamSignal := EndOfStreamNotification.

    EndOfStreamSignal notifierString:'end of stream'.

    "Created: / 7.9.2001 / 14:15:13 / cg"

    "Modified: / 7.9.2001 / 14:15:27 / cg"

!

initialize

    ChunkSeparator := $!!.

    LineTooLongErrorSignal isNil ifTrue:[

	self initSignals

    ]

    "Modified: / 1.11.1998 / 15:57:37 / stefan"

    "Modified: / 7.9.2001 / 14:15:51 / cg"

! !

!Stream class methodsFor:'instance creation'!

new

    "{ Pragma: +optSpace }"

    "report an error - Streams are created using on:-messages"

    self error:'Streams cannot be created with new'

! !

!Stream class methodsFor:'Signal constants'!

endOfStreamSignal

    "return the signal raised if read past end of stream is attemted"

    ^ EndOfStreamNotification

!

incompleteNextCountSignal

    "return the signal raised if not all requested elements are returned"

    ^ IncompleteNextCountError

!

lineTooLongErrorSignal

    "return the signal raised if a line is read which is too long (>32k)"

    ^ LineTooLongErrorSignal

    "Created: / 15.10.1998 / 12:11:14 / cg"

!

positionErrorSignal

    "return the signal raised if positioning is requested for

     a stream which does not support that kind of operation"

    ^ PositionError

!

readErrorSignal

    "return the signal raised on read errors"

    ^ ReadError

!

streamErrorSignal

    "return the parent of all stream errors;

     handling this one also handles all other errors.

     Also, this one may be raised for errors not related to read/write

     operations, such as failed ioctls in externalStream etc."

    ^ StreamError

!

writeErrorSignal

    "return the signal raised on write errors"

    ^ WriteError

! !

!Stream class methodsFor:'constants'!

chunkSeparator

    "return the chunk-separation character"

    ^ ChunkSeparator

! !

!Stream class methodsFor:'testing'!

isAbstract

    ^ self == Stream

! !

!Stream class methodsFor:'utilities'!

streamContents:blockWithArg

    "create a write-stream instance of the receiver-class,

     evaluate blockWithArg, passing that stream,

     extract and return the streams contents.

     Similar to collection>>streamContents:, but usable if

     you don't know the type of collection in advance 

     (eg: especially for CharacterWriteStream)"

    |stream|

    stream := self new.

    blockWithArg value:stream.

    ^ stream contents

    "

     CharacterWriteStream streamContents:[:s |

        s nextPutLine:'hello'.

        s nextPutLine:'world'

     ]     

    "

! !

!Stream methodsFor:'Compatibility-Dolphin'!

display:someObject

    "dolphin compatibility"

    "/ someObject printOn:self.

    self nextPutAll: someObject asString.

! !

!Stream methodsFor:'Compatibility-VW'!

commit

    "alias for flush -- ST80 compatibility"

    ^ self flush

    "Modified: 7.5.1996 / 23:55:39 / stefan"

!

nl

    "append a newline to the stream.

     This is only allowed, if the receiver supports writing."

    self nextPut:(Character nl)

! !

!Stream methodsFor:'accessing'!

contents

    "return the entire contents of the stream.

     For a readStream, that is the rest (i.e. upToEnd),

     for a writeStream, that is the collected data. As we do not know here,

     what we are, this is the responsibility of a subclass..."

    ^ self subclassResponsibility

!

encoder

    "for compatibility with encoded stream"

    ^ CharacterEncoder nullEncoderInstance

!

signalAtEnd

    "return the signalAtEnd flag setting.

     If true, reading past the end will always raise an EndOfStream exception.

     If false, no exception is raised and nil is returned from all reading messages.

     If nil (default), the exception is raised if there is a handler; otherwise, nil is returned.

     The default is nil (for ST80 compatibility) i.e. to only raise a signal if there is a handler."

    ^ signalAtEnd

    "Created: 5.2.1996 / 18:24:53 / stefan"

    "Modified: 15.5.1996 / 17:35:55 / cg"

!

signalAtEnd:aBoolean

    "set the signalAtEnd flag setting. 

     If true, reading past the end will raise an EndOfStream exception. 

     If false, no exception is raised and nil is returned from all reading messages.

     If nil (default), the exception is raised if there is a handler; otherwise, nil is returned.

     The default (nil) is both st80 backward compatible (i.e. returning nil)

     AND allows for modern code to provide a handler."

    signalAtEnd := aBoolean.

    "default behavior: return nil if unhandled ...

     |s|

     s := '12' readStream.

     Transcript showCR:s next.

     Transcript showCR:s next.

     Transcript showCR:s next.

     Transcript showCR:s next.

    "

    "... raise error if handled.

     |s|

     s := '12' readStream.

     Stream endOfStreamSignal handle:[:ex |

        Transcript showCR:'end reached'.

        ex return

     ] do:[

        Transcript showCR:s next.

        Transcript showCR:s next.

        Transcript showCR:s next.

        Transcript showCR:s next.

     ]

    "

    "force raise (useful for debugging):

     |s|

     s := '12' readStream.

     s signalAtEnd:true.

     Transcript showCR:s next.

     Transcript showCR:s next.

     Transcript showCR:s next.

     Transcript showCR:s next.

    "

    "force no-raise (useful for compatibility with other systems):

     |s|

     s := '12' readStream.

     s signalAtEnd:false.

     Stream endOfStreamSignal handle:[:ex |

        Transcript showCR:'end reached'.

        ex return

     ] do:[

        Transcript showCR:s next.

        Transcript showCR:s next.

        Transcript showCR:s next.

        Transcript showCR:s next.

     ]

    "

    "Modified: / 16.6.1998 / 16:04:41 / cg"

! !

!Stream methodsFor:'converting'!

asLineNumberReadStream

    "returns a new stream, which keeps track of the line number.

     It can be asked for the current linenumber,

     which is useful eg. for error message generation"

    ^ LineNumberReadStream on:self

!

asStream

    ^ self

! !

!Stream methodsFor:'defaults'!

bufferSizeForBulkCopy

    "return the size of buffer used when copying big files/bulk data 

     from one stream to another."

    ^ 128 * 1024

    "Created: / 13-03-2019 / 16:50:04 / Stefan Vogel"

    "Modified (comment): / 13-03-2019 / 23:21:13 / Stefan Vogel"

!

bufferSizeForNormalCopy

    "return the default buffer size used when copying files 

     from one stream to another, and no bufferSize is given."

    ^ 8 * 1024

    "Created: / 25-05-2019 / 16:49:23 / Claus Gittinger"

! !

!Stream methodsFor:'emphasis'!

bold

    "set emphasis to #bold.

     Normal streams will ignore this,

     which allows arbitrary Streams to be used interchangeable with printStreams"

    self emphasis:#bold.

    "Created: / 14-05-1996 / 17:37:37 / cg"

    "Modified: / 20-06-2017 / 08:41:50 / cg"

!

boldItalic

    "set emphasis to #boldItalic

     Normal streams will ignore this,

     which allows arbitrary Streams to be used interchangeable with printStreams"

    self emphasis:#(bold italic).

    "Created: / 14-05-1996 / 17:37:47 / cg"

    "Modified: / 03-06-1996 / 17:15:22 / cg"

    "Modified (comment): / 20-06-2017 / 08:37:36 / cg"

!

emphasis

    "ignored here 

     - allows Streams to be used interchangable with text streams"

    ^ nil

    "Created: / 14-05-1996 / 17:39:45 / cg"

    "Modified (comment): / 20-06-2017 / 08:37:15 / cg"

!

emphasis:anEmphasis

    "ignored here 

     - allows Streams to be used interchangable with text streams"

    ^ self

    "Created: / 14-05-1996 / 17:38:07 / cg"

    "Modified (comment): / 20-06-2017 / 08:37:54 / cg"

!

italic

    "set emphasis to #italic.

     Normal streams will ignore this,

     which allows arbitrary Streams to be used interchangeable with printStreams"

    self emphasis:#italic.

    "Created: / 14-05-1996 / 17:37:55 / cg"

    "Modified: / 20-06-2017 / 08:42:01 / cg"

!

normal

    "set emphasis to #normal.

     Normal streams will ignore this,

     which allows arbitrary Streams to be used interchangeable with printStreams"

    self emphasis:nil

    "Created: / 14-05-1996 / 17:37:59 / cg"

    "Modified: / 03-06-1996 / 17:15:35 / cg"

    "Modified (comment): / 20-06-2017 / 08:38:04 / cg"

!

strikeout

    "set emphasis to #strikeout.

     Normal streams will ignore this,

     which allows arbitrary Streams to be used interchangeable with printStreams"

    self emphasis:#strikeout.

    "Created: / 03-06-1996 / 17:15:45 / cg"

    "Modified (comment): / 20-06-2017 / 08:38:07 / cg"

!

underline

    "set emphasis to #underline.