10.3 Operations for Input Streams

Three operations normally used to read files: Read, ReadAsFunction and ReadTest can also be used to read GAP input from a stream. The input is immediately parsed and executed. When reading from a stream str, the GAP kernel generates calls to ReadLine(str) to supply text to the parser.

Three further operations: ReadByte, ReadLine and ReadAll, support reading characters from an input stream without parsing them. This can be used to read data in any format and process it in GAP.

Additional operations for input streams support detection of end of stream, and (for those streams for which it is appropriate) random access to the data.

  • Read( input-text-stream )

    reads the input-text-stream as input until end-of-stream occurs. See File Operations for details.

  • ReadAsFunction( input-text-stream )

    reads the input-text-stream as function and returns this function. See File Operations for details.

  • ReadTest( input-text-stream )

    reads the input-text-stream as test input until end-of-stream occurs. See File Operations for details.

    Example 

    # as function with local `a' does not change the global one
gap> a := 1;;
gap> i := InputTextString( "local a; a := 10; return a*10;" );;
gap> ReadAsFunction(i)();
100
gap> a;
1

# reading it via `Read' does
gap> i := InputTextString( "a := 10;" );;                      
gap> Read(i);
gap> a;
10

  • ReadByte( input-stream ) O

    ReadByte returns one character (returned as integer) from the input stream stream-in. ReadByte returns fail if there is no character available, in particular if it is at the end of a file.

    If stream-in is the input stream of a input/output process, ReadByte may also return fail if no byte is currently available.

    ReadByte is the basic operation for input streams. If a ReadByte method is installed for a user-defined type of stream, then all the other input stream operations will work (although possibly not at peak efficiency).

  • ReadLine( input-stream ) O

    ReadLine returns one line (returned as string with the newline) from the input stream stream-in. ReadLine reads in the input until a newline is read or the end-of-stream. is encountered.

    If stream-in is the input stream of a input/output process, ReadLine may also return fail or return an incomplete line if the other process has not yet written any more.

    A default method is supplied for ReadLine which simply calls ReadByte repeatedly. The kernel uses calls to ReadLine to supply input to the parser when reading from a stream.

  • ReadAll( input-stream ) O

    ReadAll returns all characters as string from the input stream stream-in. It reads in the input until the stream is at end-of-stream, it returns fail if the input-text-stream is already at the end-of-stream.

    If stream-in is the input stream of a input/output process, ReadAll reads all the input currently available.

    A default method is supplied for ReadAll which simply calls ReadByte repeatedly.

    Example 

    gap> i := InputTextString( "1Hallo\nYou\n1" );;
gap> ReadByte(i);
49
gap> CHAR_INT(last);
'1'
gap> ReadLine(i);
"Hallo\n"
gap> ReadLine(i);
"You\n"
gap> ReadLine(i);
"1"
gap> ReadLine(i);
fail
gap> ReadAll(i);
""
gap> RewindStream(i);;
gap> ReadAll(i);     
"1Hallo\nYou\n1"

  • IsEndOfStream( input-stream ) O

    IsEndOfStream returns true if the input stream is at end-of-stream, and false otherwise. Note that IsEndOfStream might return false even if the next ReadByte fails.

  • PositionStream( input-stream ) O

    Some input streams, such as string streams and file streams attached to disk files, support a form of random access by way of the operations PositionStream, SeekPositionStream and RewindStream. PositionStream returns a non-negative integer denoting the current position in the stream (usually the number of characters before the next one to be read.

    If this is not possible, for example for an input stream attached to standard input (normally the keyboard), then fail is returned

  • RewindStream( input-stream ) O

    RewindStream attempts to return an input stream to its starting condition, so that all the same characters can be read again. It returns true if the rewind succeeds and fail otherwise

    A default method implements RewindStream using SeekPositionStream.

  • SeekPositionStream( input-stream, pos ) O

    SeekPositionStream attempts to rewind or wind forward an input stream to the specified position. This is not possible for all streams. It returns true if the seek is successful and fail otherwise.

    [Top] [Previous] [Up] [Next] [Index]

    GAP 4 manual
    February 2000