"

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

       classVariableNames:''

       poolDictionaries:''

       category:'Streams'

!

Stream comment:'

COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

$Header: /cvs/stx/stx/libbasic/Stream.st,v 1.23 1995-09-10 20:20:06 claus Exp $

'!

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

"

!

version

"

$Header: /cvs/stx/stx/libbasic/Stream.st,v 1.23 1995-09-10 20:20:06 claus Exp $

"

!

documentation

"

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

    See concrete subclasses for more detail.

    Subclasses should (at least) implement:

	#next           (if readable)

	#nextPut:       (if writable)

	#contents

	#atEnd

	#isReadable

	#isWritable

"

! !

!Stream class methodsFor:'instance creation'!

new

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

    ^ self error:'Streams cannot be created with new'

! !

!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 subclass"

    ^ self subclassResponsibility

! !

!Stream methodsFor:'reading'!

next

    "return the next element of the stream

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

    ^ self subclassResponsibility

!

next:count

    "return the next count elements of the stream as a Collection."

    |answerStream 

     cnt  "{ Class: SmallInteger }" |

    answerStream := WriteStream on:(self contentsSpecies new).

    cnt := count.

    1 to:cnt do:[:index |

	answerStream nextPut:(self next)

    ].

    ^ answerStream contents

    "

     (ReadStream on:#(1 2 3 4 5)) next:3

     (ReadStream on:'hello') next:3

    "

!

nextAvailable:count

    "return the next count elements of the stream as a Collection.

     If the stream reaches the end before count elements have been read,

     return what is available. (i.e. a shorter collection)"

    |answerStream

     cnt  "{ Class: SmallInteger }"|

    answerStream := WriteStream on:(self contentsSpecies new).

    cnt := count.

    1 to:cnt do:[:index |

	self atEnd ifTrue:[

	    ^ answerStream contents

	].

	answerStream nextPut:(self next)

    ].

    ^ answerStream contents

    "

     (ReadStream on:#(1 2 3 4 5)) nextAvailable:3

     (ReadStream on:#(1 2 3 4 5)) nextAvailable:10 

     (ReadStream on:'hello') nextAvailable:3

     (ReadStream on:'hello') nextAvailable:10 

    "

!

nextMatchFor:anObject

    "read an element from the receiver, return true if it was equal to

     the argument, anObject"

    ^ (self next = anObject)

    "

     |s|

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

     s nextMatchFor:2

    "

    "

     |s|

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

     s nextMatchFor:2.

     s nextMatchFor:2

    "

!

skip:count 

    "skip count objects, return the receiver"

    |n "{ Class: SmallInteger }"|

    n := count.

    "dont know how to unread ..."

    n < 0 ifTrue:[

	^ self error:'stream is not positionable'

    ].

    n timesRepeat:self next

    "

     |s|

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

     s skip:4.

     s next

    "

!

skipFor:anObject

    "skip all objects up-to and including anObject; return the element after anObject."

    (self skipThrough:anObject) notNil ifTrue:[

	^ self next

    ].

    ^ nil

    "

     |s|

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

     s skipFor:4.

    "

!

skipThrough:anObject

    "skip all objects up-to and including anObject. Return the receiver if

     skip was successfull, otherwise (i.e. if not found) return nil.

     The next read operation will return the element after anObject."

    |nextElement|

    [self atEnd] whileFalse:[

	nextElement := self next.

	(nextElement = anObject) ifTrue: [ ^ self ]

    ].

    ^ nil

    "

     |s|

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

     s skipThrough:4.

     s next

    "

!

upTo:anObject

    "read a collection of all objects up-to anObject and return these

     elements, but excluding anObject. 

     The next read operation will return the element after anObject.

     Compare this with #through: which also reads up to some object

     and also positions behind it, but DOES include it in the returned

     value."

    |answerStream element|

    answerStream := WriteStream on:(self contentsSpecies new).

    [self atEnd] whileFalse:[

	element := self next.

	(element = anObject) ifTrue: [

	    ^ answerStream contents

	].

	answerStream nextPut: element.

    ].

    ^ answerStream contents

    "

     |s|

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

     Transcript showCr:(s upTo:4).  

     Transcript showCr:s next

     |s|

     s := ReadStream on:'hello world'.

     Transcript showCr:(s upTo:Character space).

     Transcript showCr:(s upToEnd)

     (ReadStream on:'12345678905') upTo:$5; upTo:$5 

     (ReadStream on:'123456') upTo:$7     

     (ReadStream on:#(1 2 3 4 5 6)) upTo:4  

     (ReadStream on:'line 1

		     line 2') upTo:Character cr  

     'Makefile' asFilename readStream upTo:Character cr;upTo:Character cr  

    "

!

upToEnd

    "return a collection of the elements up-to the end.

     Return nil if the stream-end is reached before."

    |answerStream|

    answerStream := WriteStream on:(self contentsSpecies new).

    [self atEnd] whileFalse:[

	answerStream nextPut:(self next)

    ].

    ^ answerStream contents

    "

     (ReadStream on:'1234567890') upToEnd

     ('123456' readStream) next; next; upToEnd

     ('1 23456' readStream) upTo:Character space; upToEnd 

    "

!

through:anObject

    "read a collection of all objects up-to anObject and return these

     elements, including anObject. 

     The next read operation will return the element after anObject.

     Compare this with #upTo: which also reads up to some object

     and also positions behind it, but does not include it in the returned

     value."

    |answerStream element|

    answerStream := WriteStream on:(self contentsSpecies new).

    [self atEnd] whileFalse:[

	element := self next.

	answerStream nextPut:element.

	(element = anObject) ifTrue: [

	    ^ answerStream contents

	]

    ].

    ^ answerStream contents

    "

     |s|

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

     Transcript showCr:(s through:4).  

     Transcript showCr:s next

    "

    "

     |s|

     s := ReadStream on:'hello world'.

     Transcript showCr:(s through:Character space).

     Transcript showCr:(s upToEnd)

    "

! !

!Stream methodsFor:'writing'!

commit

    "write out all unbuffered data - ignored here, but added

     to make internalStreams protocol compatible with externalStreams"

!

nextPut:anObject

    "put the argument, anObject onto the receiver

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

    ^ self subclassResponsibility

!

next:count put:anObject

    "put the argument, anObject count times onto the receiver"

    |n "{ Class: SmallInteger }"|

    n := count.

    n timesRepeat:[self nextPut:anObject].

    ^ anObject

    "

     |s|

     s := WriteStream on:#().

     s nextPut:1.

     s next:5 put:2.

     s nextPut:3.

     s contents

    "

!

nextPutAll:aCollection

    "put all elements of the argument, aCollection onto the receiver"

    aCollection do:[:element |

	self nextPut:element

    ].

    ^ aCollection

    "

     |s|

     s := WriteStream on:#().

     s nextPutAll:(1 to:5).

     s nextPutAll:#('one' 'two' 'three').

     s contents

    "

    "

     |s|

     s := WriteStream on:(String new).

     s nextPutAll:($a to:$f).

     s nextPutAll:'one '; 

       nextPutAll:'two ';

       nextPutAll:'three'.

     s contents

    "

!

nextPutAll:aCollection startingAt:first to:last

    "put the elements with index from first to last

     of the argument, aCollection onto the receiver"

    aCollection from:first to:last do:[:element |

	self nextPut:element

    ].

    ^ aCollection

    "

     |s|

     s := WriteStream on:#().

     s nextPutAll:#('one' 'two' 'three' 'four' 'five') startingAt:2 to:4.

     s contents

    "

!

endEntry

    "ignored here - for compatibility with Transcript"

    ^ self

!

show:aString

    "put all elements of the argument, aString onto the receiver;

     this makes streams somewhat compatible to TextCollectors and

     allows you to say: Smalltalk at:#Transcript put:Stdout"

    ^ self nextPutAll:aString printString

!

showCr:aString

    "put all elements of the argument, aString onto the receiver;

     and append a newline.

     For compatibility with TextCollectors"

    self show:aString.

    self cr

!

print:anObject

    "append a printed representation of anObject to the receiver.

     Same as anObject printOn:self; For ST-80 compatibility."

    anObject printOn:self

!

store:anObject

    "append a printed representation of anObject to the receiver,

     from which the receiver can be reconstructed.

     Same as anObject storeOn:self; For ST-80 compatibility."

    anObject storeOn:self

!

cr

    "append a carriage-return to the stream"

    self nextPut:(Character cr)

!

tab

    "append a tab-character to the stream"

    self nextPut:(Character tab)

!

crTab

    "append a carriage-return followed by a tab to the stream.

     Same as crtab for ST/X backward compatibility"

    self obsoleteMethodWarning:'use crTab'.

    self crtab

!

crtab:n

    "append a carriage-return followed by n tabs to the stream."

    self nextPut:(Character cr).

    self next:n put:(Character tab)

!

crtab

    "append a carriage-return followed by a tab to the stream."

    self crtab:1

!

space

    "append a space character to the receiver-stream"

    self nextPut:(Character space)

!

spaces:count

    "append count space-characters to the receiver-stream"

    self next:count put:(Character space)

!

ff

    "append a form-feed (new-pagee) to the receiver-stream"

    self nextPut:(Character ff)

! !

!Stream methodsFor:'non homogenous writing'!

nextPutWord:aNumber

    "write the argument, aNumber as a signed short (two bytes);

     write msb-first for compatibility with other smalltalks.

     The receiver must support writing of binary bytes.

     I dont know if it should be named nextPutWord: or nextWordPut:;

     one of them will vanish ..."

    ^ self nextPutShort:aNumber MSB:true

!

nextWordPut:aNumber

    "for ST-80 compatibility"

    ^ self nextPutShort:aNumber MSB:true

!