General: The streams read
operators deliver bytes from the stream and reposition the cursor for the next
read. The cursor is always left at the next byte to be read. This may be beyond
the end or before the beginning of the stream. In that case the appropriate BOS
(Begin of Stream) or EOS (End of Stream) is turned on. The read operations are
sensitive to the direction property of the stream. If direction is changed, the
cursor is repositioned to make the read in the reverse direction deliver the
result you would intuitively expect. This is a departure from how most stream
mechanisms operate. However, I think it is more natural and results in less and
simpler code.
At Position ( ?`@ ): In
these examples I will use the At Position (index) operator to show what has
happened to this stream property as a result of the operation.
Stream Properties( .props
): Among the properties of a stream are : P: Position; PP: Previous
Position; B: Begin of Stream Indicator; E: End of Stream Indicator; D: Last
read direction indicator; NE: Number of Elements. This .props method
of streams displays these properties as a mechanism for understanding stream
operations and troubleshooting. It would not likely be used in normal
programming.
Next Line ( ->>
) and Previous Line ( <<- ): These examples illustrate
reading through a stream by line. The line delimiter is taken as CRLF, CR, LF,
or LFCR. After the read, depending on the direction, the cursor is 1 after
(right) or 1 before (left) the delimiter. It marks the position of the next
character to be read if proceeding in the same direction. If the direction is
reversed, the previous position and current position are adjusted so as to
produce the effect of a previous line read in the new direction. Thus, the same
line is not reread when changing direction.
Next n Bytes (
->> n) and Previous n bytes ( <<- n):
You can stream a specific number of bytes in either direction with the dyadic
form of this operator. Notice, when the direction is reversed, the cursors are
repositioned so the line previously read is not read again. This makes it easy
to program for forward and backward browsing through lines or bytes in a
stream. You will only receive up to the number of bytes remaining in the
direction of your streaming. If ytous tream beyond the end of the stream in
either direction, the appropiate indicator is set.
Next any (
->>| 'delim') and Previous any ( <<-|
'delim') delimiter: Read to the next delimiter.
Next all (
->>& 'string') and Previous all (
<<-& 'string') string:
Read until matching the string. The Glee compare is used for
matching unless the operator is preceeded with the equal compare qualifier (
@== )