"

 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.

"

Object subclass:#Stream

	instanceVariableNames:'signalAtEnd'

	classVariableNames:'StreamErrorSignal PositionErrorSignal ReadErrorSignal

		WriteErrorSignal EndOfStreamSignal EndOfStreamQuerySignal'

	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:

    [Class variables:]

	StreamErrorSignal       <Signal>        parent of all stream errors

	PositionErrorSignal     <Signal>        position attemted on a stream

						which does not support positioning

	ReadErrorSignal         <Signal>        raised on read errors

	WriteErrorSignal        <Signal>        raised on write errors

	EndOfStreamSignal       <Signal>        raised at end of stream if signalAtEnd

						is enabled.

	EndOfStreamQuerySignal  <QuerySignal>   raised at end of stream if signalAtEnd

						is defaulted (nil).

    [author:]

	Claus Gittinger

"

! !

!Stream class methodsFor:'initialization'!

initialize

    StreamErrorSignal isNil ifTrue:[

	StreamErrorSignal := ErrorSignal newSignalMayProceed:false.

	StreamErrorSignal nameClass:self message:#streamErrorSignal.

	StreamErrorSignal notifierString:'Stream error'.

	PositionErrorSignal := StreamErrorSignal newSignalMayProceed:true.

	PositionErrorSignal nameClass:self message:#positionErrorSignal.

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

	ReadErrorSignal := StreamErrorSignal newSignalMayProceed:false.

	ReadErrorSignal nameClass:self message:#readErrorSignal.

	ReadErrorSignal notifierString:'read error'.

	WriteErrorSignal := StreamErrorSignal newSignalMayProceed:false.

	WriteErrorSignal nameClass:self message:#writeErrorSignal.

	WriteErrorSignal notifierString:'write error'.

	EndOfStreamSignal := StreamErrorSignal newSignalMayProceed:true.

	EndOfStreamSignal nameClass:self message:#endOfStreamSignal.

	EndOfStreamSignal notifierString:'end of stream'.

	EndOfStreamQuerySignal := QuerySignal new defaultAnswer:nil.

	EndOfStreamQuerySignal parent:EndOfStreamSignal.

	EndOfStreamQuerySignal nameClass:self message:#endOfStreamQuerySignal.

	EndOfStreamQuerySignal notifierString:'end of stream'.

    ]

! !

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

endOfStreamQuerySignal

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

    ^ EndOfStreamQuerySignal

!

endOfStreamSignal

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

    ^ EndOfStreamSignal

!

positionErrorSignal

    "return the signal raised if positioning is requested for

     a stream which does not support that kind of operation"

    ^ PositionErrorSignal

!

readErrorSignal

    "return the signal raised on read errors"

    ^ ReadErrorSignal

!

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

    ^ StreamErrorSignal

!

writeErrorSignal

    "return the signal raised on write errors"

    ^ WriteErrorSignal

! !

!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 (currently) to NOT raise a signal."

    signalAtEnd := aBoolean.

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

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

! !

!Stream methodsFor:'closing'!

close

    "close the stream - nothing done here.

     Added for compatibility with external streams."

    ^ 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]

    "

! !

!Stream methodsFor:'error handling'!

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

    signalAtEnd == true ifTrue:[

	"/ always raise ...

	^ EndOfStreamSignal raiseRequestFrom:self

    ].

    signalAtEnd == false ifTrue:[

	"/ never raise ...

	^ nil

    ].

    ^ EndOfStreamQuerySignal raiseRequestFrom:self

    "Modified: / 11.11.1997 / 16:14:41 / cg"

! !

!Stream methodsFor:'misc'!

binary

    "switch to binary mode. In binary mode, reading of text streams

     returns byte-valued integers instead of characters; writing expects

     byte-valued integers respectively.

     Ignored here, but added to make internalStreams protocol compatible 

     with externalStreams."

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

!

text

    "switch to text mode. 

     Ignored here, but added to make internalStreams protocol compatible 

     with externalStreams."

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

    "Created: 13.9.1996 / 18:33:26 / cg"

! !

!Stream methodsFor:'non homogenous reading'!

nextBytes:count

    "read the next count bytes and return it either as a byteArray (binary mode)

     or as a string (text mode).

     If EOF is encountered while reading, a truncated byteArry or short string 

     is returned. If EOF is already reached before the first byte can be read,

     nil is returned."

    |data n|

    self isBinary ifTrue:[

        data := ByteArray new:count

    ] ifFalse:[

        data := String new:count

    ].

    n := self nextBytes:count into:data startingAt:1.

    n ~~ count ifTrue:[

        n == 0 ifTrue:[

            ^ nil

        ].

        data := data copyTo:n

    ].

    ^ data

    "Created: / 21.6.1997 / 11:18:57 / cg"

    "Modified: / 30.3.1998 / 18:04:58 / cg"

!

nextBytes:count into:anObject

    "read the next count bytes into an object and return the number of

     bytes read. On EOF, 0 is returned.

     If the receiver is some socket/pipe-like stream, an exception

     is raised if the connection is broken.

     The object must have non-pointer indexed instvars (i.e. it must be 

     a ByteArray, String, Float- or DoubleArray).

     If anObject is a string or byteArray and reused, this provides the

     fastest possible physical I/O (since no new objects are allocated).

     Use with care - non object oriented i/o.

     Warning: in general, you cannot use this method to pass data from other 

     architectures since it does not care for byte order or float representation."

    ^ self nextBytes:count into:anObject startingAt:1

    "Modified: 22.4.1997 / 10:41:39 / cg"

!

nextBytes:numBytes into:aCollection startingAt:initialIndex

    "return the next numBytes from the stream. If the end is

     reached before, only that many bytes are copyied into the

     collection.

     Returns the number of bytes that have been actually read.

     The receiver must support reading of binary bytes.

     Notice: this method is privided here for protocol completeness

	     with externalStreams - it is normally not used with other

	     streams."

    |n "{Class: SmallInteger }"

     dstIndex|

    dstIndex := initialIndex.

    n := 0.

    [self atEnd] whileFalse:[

	n == numBytes ifTrue:[

	    ^ n

	].

	aCollection byteAt:dstIndex put:(self nextByte).

	dstIndex := dstIndex + 1.

	n := n + 1.

    ].

    ^ n

    "

     |s n buffer|

     buffer := ByteArray new:10.

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

     s next:3.

     n := s nextBytes:9 into:buffer startingAt:1.

     Transcript showCR:('n = %1; buffer = <%2>' bindWith:n with:buffer)

    "

    "Modified: 22.4.1997 / 10:43:08 / cg"

!

nextBytes:numBytes into:aCollection startingAt:initialIndex blockSize:blockSize

    "like nextBytes:into:startingAt:, but read in blocks of the given size.

     This leads to better beahvior when reading large chunks from a slow device,

     such as a cdrom drive (since a single unix-read is not interruptable)."

    |nR oR n|

    nR := numBytes.

    oR := initialIndex.

    [nR > 0] whileTrue:[

	n := nR.

	n > blockSize ifTrue:[n := blockSize].

	n := self nextBytes:n into:aCollection startingAt:oR.

	n == 0 ifTrue:[

	    ^ numBytes - nR

	].

	oR := oR + n.

	nR := nR - n

    ].

    ^ numBytes

    "Created: 24.4.1997 / 21:09:34 / cg"

    "Modified: 24.4.1997 / 21:19:50 / cg"

!

nextBytesInto:anObject

    "read bytes into an object, regardless of binary/text mode.

     The number of bytes to read is defined by the objects size.

     Return the number of bytes read. On EOF, 0 is returned.

     If the receiver is some socket/pipe-like stream, an exception

     is raised if the connection is broken.

     The object to read into must have non-pointer indexed instvars 

     (i.e. it must be a ByteArray, String, Float- or DoubleArray).     

     If anObject is a string or byteArray and reused, this provides the

     fastest possible physical I/O (since no new objects are allocated).

     Use with care - non object oriented i/o.

     Warning: in general, you cannot use this method to pass data from other 

     architectures since it does not care for byte order or float representation."

    ^ self nextBytes:(anObject byteSize) into:anObject startingAt:1

    " to read 100 bytes from a stream:

     |b aStream|