"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      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' }"

Object subclass:#Stream

	instanceVariableNames:'signalAtEnd'

	classVariableNames:'StreamErrorSignal PositionErrorSignal ReadErrorSignal

		WriteErrorSignal EndOfStreamSignal LineTooLongErrorSignal

		ChunkSeparator'

	poolDictionaries:''

	category:'Streams'

!

!Stream class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      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.

    [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 methodsFor:'accessing'!

contents

    "return the entire contents of the stream

     - we do not know here how to do it, it must be redefined in subclasses."

    ^ self subclassResponsibility

    "Modified: 15.5.1996 / 17:36:29 / cg"

!

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.

     The default is to raise a signal, but return nil if

     not handled."

    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:'closing'!

close

    "close the stream - nothing done here.

     Added for compatibility with external streams."

    ^ self

! !

!Stream methodsFor:'converting'!

asStream

    ^ self

! !

!Stream methodsFor:'emphasis'!

bold

    "set emphasis to #bold.

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:#bold.

    "Created: 14.5.1996 / 17:37:37 / cg"

    "Modified: 3.6.1996 / 16:57:17 / cg"

!

boldItalic

    "set emphasis to #boldItalic

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:#(bold italic).

    "Created: 14.5.1996 / 17:37:47 / cg"

    "Modified: 3.6.1996 / 17:15:22 / cg"

!

emphasis

    "ignored here - allows Streams to be used interchangable with

     text streams"

    ^ nil

    "Created: 14.5.1996 / 17:39:45 / cg"

!

emphasis:anEmphasis

    "ignored here.

     this allows Streams to be used interchangeable with printStreams"

    ^ self

    "Created: 14.5.1996 / 17:38:07 / cg"

!

italic 

    "set emphasis to #italic.

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:#italic.

    "Created: 14.5.1996 / 17:37:55 / cg"

    "Modified: 3.6.1996 / 17:15:32 / cg"

!

normal

    "set emphasis to #normal.

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:nil

    "Created: 14.5.1996 / 17:37:59 / cg"

    "Modified: 3.6.1996 / 17:15:35 / cg"

!

strikeout

    "set emphasis to #strikeout.

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:#strikeout.

    "Modified: 3.6.1996 / 16:57:56 / cg"

    "Created: 3.6.1996 / 17:15:45 / cg"

!

underline

    "set emphasis to #underline.

     this allows Streams to be used interchangeable with printStreams"

    self emphasis:#underline.

    "Created: 3.6.1996 / 17:00:03 / cg"

    "Modified: 3.6.1996 / 17:15:38 / cg"

! !

!Stream methodsFor:'enumerating'!

do:aBlock

    "evaluate the argument, aBlock for all remaining elements,

     up to the end of the stream"

    [self atEnd] whileFalse:[

	aBlock value:(self next)

    ]

    "

     |s|

     s := ReadStream on:#(1 2 3 4 5 6 7 8 9).

     s next.

     s next.

     s do:[:element | Transcript showCR:element]

    "

!

linesDo:aBlock

    "evaluate the argument, aBlock for all lines,

     up to the end of the stream"

    [self atEnd] whileFalse:[

        aBlock value:(self nextLine)

    ]

    "

     |s|

     s := '/etc/hosts' asFilename readStream.

     s linesDo:[:line | Transcript showCR:line].

     s close

    "

    "

     Filename readingFile:'/etc/hosts' 

     do:[:s |

         s linesDo:[:line | Transcript showCR:line].

     ].

    "

! !

!Stream methodsFor:'error handling'!

checkNilFileStream

    "Do nothing if this is a valid FileStream

     (i.e. the previous open operation was successful).

     Also implemented in UndefinedObject, to raise an Error there.

     This is an aid for converting from the old error reporting (returning nil)

     to the new error reporting (with real Exceptions).

     It will vanish as soon as the conversion has been done"

    ^ self

!

pastEnd

    "someone tried to read after the end of the stream.

     If signalAtEnd == true, raise a signal. If its false, return nil.

     Otherwise raise the signal, but only if handled; otherwise return nil."

    <resource: #obsolete>

    self obsoleteMethodWarning:'use #pastEndRead'.

    self pastEndRead

!

pastEndRead

    "someone tried to read after the end of the stream.

     If signalAtEnd == true, raise a signal. 

     If it is false, return nil.

     Otherwise raise a notification, which is ignored if not handled; 

     otherwise return nil."

    signalAtEnd == true ifTrue:[

        "raise - a hard error..."

        ^ EndOfStreamError raiseRequestFrom:self

    ].

    signalAtEnd == false ifTrue:[

        "never raise ..."

        ^ nil

    ].

    "EndOfStreamNotification is ignored, if there is no handler.

     In this case, nil is returned"

    ^ EndOfStreamNotification raiseRequestFrom:self

    " ... no handler, no raise

     |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.

     EndOfStreamNotification handle:[:ex |

        Transcript showCR:'end reached'.