"

 COPYRIGHT (c) 1996 by Claus Gittinger

 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.

"

Stream subclass:#FilteringStream

	instanceVariableNames:'inputStream outputStream filter readAhead'

	classVariableNames:''

	poolDictionaries:''

	category:'Streams-Misc'

!

!FilteringStream class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1996 by Claus Gittinger

 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

"

    A FilteringStream can be connected to some input

    (from which elements are read via the ReadStream protocol),

    and/or to some output (to which elements are written via

    the WriteStream protocol.

    The FilteringStream itself performs filtering/processing

    on the elements as they arrive, optionally suppressing

    elements.

    A FilteringStream can be operated in pull-mode, by asking

    it for the next element; it will then ask its inputStream for

    and element, process it and return it.

    Or, in pushMode, by having someone else writing elements via

    nextPut:; it will then process the element, and send it to its 

    output stream.

    Mixing modes does not make sense, since if pulled, data will not

    be written to the outputStream (unless the puller does it).

    The connected streams need not be real streams; anything which

    responds to the basic Stream protocol can be connected

    (a Transcript, a RandomNumber generator or even a Plug will do as well).

    [instance variables:]

    [author:]

    [See also:]

"

!

examples

"

  pushing the contents of a stream onto another stream

  (here, the Transcript) without a need to read everyting into a

  buffer or to reinvent the read-loop:

  (notice, a FilteringLineStream does this with less overhead,

   due to the byte-wise reading done here)

    |in pusher|

    in := 'Makefile' asFilename readStream.

    pusher := FilteringStream readingFrom:in writingTo:Transcript.

    pusher filterUpToEnd

  filter random numbers:

    |in filter|

    in := Random new.

    filter := FilteringLineStream readingFrom:in.

    filter filter:[:num | ((num >= 0.5) and:[num <= 0.6]) ifTrue:[num] ifFalse:[nil]].

    20 timesRepeat:[

    ]

  filtering prime numbers:

    |num generator primeFilter addFilter|

    num := 1.

    generator := Plug new.

    generator respondTo:#next

    generator respondTo:#atEnd

    addFilter := [:prime | |newFilter|

    ].

    addFilter value:2.

    primeFilter inputStream:generator.

    10000 timesRepeat:[

    ]

"

! !

!FilteringStream class methodsFor:'instance creation'!

new

    "create and return a new filteringStream.

     The resulting stream must be connected to some other stream,

     before being used"

    ^ self basicNew initialize.

    "Created: 11.1.1997 / 15:31:30 / cg"

    "Modified: 11.1.1997 / 15:33:13 / cg"

!

on:something

    "create and return a new filteringStream, which reads from

     something (which must be convertable to a stream)"

    ^ self readingFrom:something readStream

    "Created: 11.1.1997 / 19:19:34 / cg"

!

readingFrom:aReadStream

    "create and return a new filteringStream, which reads from

     another stream"

    ^ self basicNew initialize inputStream:aReadStream.

    "Created: 11.1.1997 / 15:32:15 / cg"

!

readingFrom:aReadStream writingTo:aWriteStream

    "create and return a new filteringStream, which reads from

     aReadStream and writes to aWriteStream."

    |newStream|

    newStream := self basicNew initialize.

    newStream inputStream:aReadStream.

    newStream outputStream:aWriteStream.

    ^ newStream

    "Created: 11.1.1997 / 15:32:28 / cg"

!

writingTo:aWriteStream

    "create and return a new filteringStream, which writes to

     another stream"

    ^ self basicNew initialize outputStream:aWriteStream.

    "Created: 11.1.1997 / 15:32:36 / cg"

! !

!FilteringStream methodsFor:'access - pull-reading'!

filterUpToEnd

    "pull input from inputStream up to the end,

     push it filtered into the outputStream."

    [inputStream atEnd] whileFalse:[

    ].

    "Created: 2.7.1996 / 21:06:42 / cg"

    "Modified: 11.1.1997 / 16:08:35 / cg"

!

next

    "pull input from inputStream and

     push it filtered into the outputStream"

    |input output|

    "/ readAhead input has already been filtered

    "/ (see #atEnd)

    readAhead notNil ifTrue:[

    ].

    [inputStream atEnd] whileFalse:[

    ].

    ^ nil

    "Created: 2.7.1996 / 21:09:58 / cg"

    "Modified: 11.1.1997 / 17:17:27 / cg"

! !

!FilteringStream methodsFor:'access - push-writing'!

nextPut:something

    "push something through the filter"

    |output|

    "/ filter it

    filter isNil ifTrue:[

    ] ifFalse:[

    ]

    "Modified: 11.1.1997 / 16:12:52 / cg"

! !

!FilteringStream methodsFor:'accessing'!

filter

    "return the filter"

    ^ filter

    "Modified: 2.7.1996 / 21:03:36 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

!

filter:something

    "set the filter"

    filter := something.

    "Modified: 2.7.1996 / 21:03:40 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

!

inputStream

    "return the inputStream"

    ^ inputStream

    "Modified: 2.7.1996 / 21:03:43 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

!

inputStream:something

    "set the inputStream"

    inputStream := something.

    "Modified: 2.7.1996 / 21:03:46 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

!

outputStream

    "return the outputStream"

    ^ outputStream

    "Modified: 2.7.1996 / 21:03:49 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

!

outputStream:something

    "set the outputStream"

    outputStream := something.

    "Modified: 2.7.1996 / 21:03:52 / cg"

    "Created: 2.7.1996 / 21:06:42 / cg"

! !

!FilteringStream methodsFor:'misc'!

close

    "when I am closed, close my input - if any"

    inputStream notNil ifTrue:[

    ]

    "Created: 11.1.1997 / 15:27:17 / cg"

! !

!FilteringStream methodsFor:'queries'!

atEnd

    "return true, if the receiver stream is at the end"

    |nextElement|

    readAhead notNil ifTrue:[^ false].

    filter isNil ifTrue:[

    ].

    "/ with a filter, things are more complicated, 

    "/ since we cannot tell, without asking the filter ...

    [inputStream atEnd] whileFalse:[

    ].

    ^ true

    "Modified: 11.1.1997 / 17:16:45 / cg"

!

contentsSpecies

    "return the kind of collection I should return when asked

     for multiple elements."

    ^ inputStream contentsSpecies

    "Created: 11.1.1997 / 16:23:22 / cg"

! !

!FilteringStream class methodsFor:'documentation'!

version

! !