Class: FilteringStream

• Inheritance
• Description
• Class protocol
  • instance creation
• Instance protocol
  • access - pull-reading
  • access - push-writing
  • accessing
  • misc
  • obsolete positioning
  • queries
• Examples

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--FilteringStream
            |
            +--FilteringLineStream
            |
            +--LineNumberReadStream

Package:

stx:libbasic2

Category:

Streams-Misc

Version:

rev: 1.32 date: 2024/02/09 12:53:14

user: cg

file: FilteringStream.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

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

Similar, but not quite the same as SelectingReadStream / CollectingReadStream.

[instance variables:]
    inputStream     <Stream>  the stream from which elements are read
    outputStream    <Stream>  the stream to which elements are written
    filter          <Block>   the filter block;
    unbound         <Boolean> if true, the stream is unbound.

copyright
COPYRIGHT (c) 1996 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.

Class protocol:

 new

create and return a new filteringStream.
The resulting stream must be connected to some other stream,
before being used

 on: aStringOrStream

create and return a new filteringStream, which reads from
something (which must be convertable to a stream)

 readingFrom: aReadStream

create and return a new filteringStream, which reads from
another stream

 readingFrom: aReadStream writingTo: aWriteStream

create and return a new filteringStream, which reads from
aReadStream and writes to aWriteStream.

 writingTo: aWriteStream

create and return a new filteringStream, which writes to
another stream

Instance protocol:

 contents

(comment from inherited method)
return a collection of the elements up-to the end.
Return an empty collection, if the stream is already at the end.

 filterUpToEnd

pull input from inputStream up to the end,
push it filtered into the outputStream.

 next

pull input from inputStream and
push it filtered into the outputStream

 peek

peek ahead for the next character

 peekOrNil

peek ahead for the next character, or return nil

 nextPut: something

push something through the filter.
Answer the argument.

 filter

return the filter

 filter: aBlock

set the filter; a block which receives elements and can
return nil (so the element is ignored), or another element (for translation)

 inputStream

return the inputStream

 inputStream: something

set the inputStream

 outputStream

return the outputStream

 outputStream: something

set the outputStream

 clearEOF

 close

when I am closed, close my input - if any

 position0Based

return the receiver streams position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 position1Based

return the receiver streams position

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 atEnd

return true, if the receiver stream is at the end

 contentsSpecies

return the kind of collection I should return when asked
for multiple elements.

 isEmpty

(comment from inherited method)
return true, if the contents of the stream is empty

 isEncodedStream

(comment from inherited method)
true, iff this is an encoder/decoder stream

 isReadable

(comment from inherited method)
return true, if reading is supported by the receiver.
This has to be redefined in concrete subclasses.

 isWritable

return true, if writing is supported by the receiver.

 position

return the receiver streams position

 readStream

 size

not always correct, but probably better than 0.
Better use #isEmpty.

Usage example(s):

self error:'size of input is unknown (due to filtering)'

Examples:

  |in pusher|

  in := 'Make.proto' asFilename readStream.
  pusher := FilteringStream readingFrom:in writingTo:Transcript.
  pusher filterUpToEnd

  |in filter|

  in := Random new.

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

  20 timesRepeat:[
      Transcript showCR:(filter next printString).
  ]

  |filter|

  filter := FilteringStream 
              readingFrom:#(1 2 3 4 5 6 7 8 9 10) readStream
              writingTo:#() writeStream.
  filter filter:[:num | num * 2].
  filter contents inspect.

  |num generator primeFilter addFilter|

  num := 1.
  generator := Plug new.
  generator respondTo:#next
                 with:[num := num + 1. num].
  generator respondTo:#atEnd
                 with:[false].

  addFilter := [:prime | |newFilter|
      newFilter := FilteringStream basicNew.
      newFilter filter:[:num | (num \\ prime) == 0 ifTrue:[
                                  nil
                               ] ifFalse:[
                                  num
                               ]
                       ].
      newFilter inputStream:primeFilter.
      primeFilter := newFilter
  ].

  addFilter value:2.
  primeFilter inputStream:generator.

  1000 timesRepeat:[
      |nextPrime|

      nextPrime := primeFilter next.
      addFilter value:nextPrime.
      Transcript showCR:nextPrime.
  ]