Commentary: Stream Read Operators

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 ( @== )