General:The stream
"at" operators advance the stream's cursor but do not read data. They
return the cursor position as it existed before the repositioning. The
programmer can capture this to return to the current position. Streams have
various states. Among these are the cursor position for the next operation; the
previous cursor postion; the direction of the last operation (i.e. L, R, or X
for neither); the Beginning of stream indicator; and the End of stream
indicator. These "at" operators affect all of these states. Depending
on the operator, calculation of the next position is a function of these
states.
Current Cursor Position (
?`@ ) Previous Cursor Position ( ?`@<<- ):
Glee streams maintain two cursors and a direction indicator. They
work together to support the various streaming contexts and operations. You
will notice that when direction changes at the end of this example, the prior
cursor position is actually changed. This is because the cursor points to the
next byte to be read. Thus, it is always one beyond the last byte read. And
this is a function of the direction of the reading. The mechanics are fairly
complicated. However, the feel is very natural. I prefer this over simple
mechanics and clumbsy feel. The computer is well suited for dealing with the
mechanical.
Begin of stream ( ?@<-
) End of stream ( ?@-> ): These operators return bits
indicating the current state of the cursor. They return 1 or true if the cursor
is at their respective ends of the stream. They are intended to be used to test
for completion of streaming.
Last read direction (
?>< ) : I don't expect this operator to be used very much
... if at all. But for testing it was important for me to see what was going on
so I have included it for you as well. "L" means the last read was to
the left; "R" means it was to the right. "X" means the
cursor was just set ... it didn't get to its position by a read or it is at the
beginning or end of the stream.
Stream properties ( .props
) : While debugging streams I found it convenient to dump the current state
of all the streaming properties. Since I had this facility I thought it might
be helpful to show you. Maybe it will help you in troubleshooting as well. The
elements of the output are D: Direction; PP: Prev Pos; B: Begin of stream; E:
End of stream; P: Current Pos; NE: Number of elements.
Position relative to start of
stream ( @<- or @<- n) : Set the current cursor
relative to the start of the stream. Monadically this is seek beginning.
Dyadically it is seek to an absolute position from the start. The origin
is 1. The operator returns the previous position.
Position relative to end of stream (
@-> or @-> n) : Set the current cursor relative to
the end of the stream. Monadically this is seek end of stream.
Dyadically it is seek to a position relative to the end of the stream..
The origin is 1. The operator returns the previous position.
At previous line or relative bytes
( @<<- and @<<- n) : The monadic form
positions at the beginning of the previous CRLF delimiter. The dyadic form
positions "n" bytes before the current position. I'm relying on the
example to provide most of the play-by-play here.
At next line or relative bytes (
@->> and @->> n ) : The monadic form
positions at the beginning of the next CRLF delimiter. The dyadic form
positions "n" bytes after the current position.
At previous any or
all ( @<<-| 'delim' and @<<-&
'string') : Position on any of the delimiter characters
presented in the string argument ( @<<-|) form. Position on
beginning of matching string argument (@<<-& ) form. In the
(&) all form a Glee compare is made. For
exact compare use @== preceeding the operator.
At next any or
all ( @->>| 'delim' and @->>&
'string') : This is essentially the same example given for the
previous case. Additionally it illustrates the use of @==
forcing an equal compare on "TH" and missing it because case
does not match.