Streams
<#Include Label="[1]{streams}">

Categories for Streams and the StreamsFamily
<#Include Label="IsStream"> <#Include Label="IsClosedStream"> <#Include Label="IsInputStream"> <#Include Label="IsInputTextStream"> <#Include Label="IsInputTextNone"> <#Include Label="IsOutputStream"> <#Include Label="IsOutputTextStream"> <#Include Label="IsOutputTextNone"> <#Include Label="StreamsFamily">

Operations applicable to All Streams
<#Include Label="CloseStream"> <#Include Label="FileDescriptorOfStream">

makes the UNIX C-library function select accessible from &GAP; for streams. The functionality is as described in the man page (see

UNIX file descriptors (integers) for streams. They can be obtained via for streams to local processes and to local files. The argument timeoutsec is a timeout in seconds as in the struct timeval on the C level. The argument timeoutusec is analogously in microseconds. The total timeout is the sum of both. If one of those timeout arguments is not a small integer then no timeout is applicable (fail is allowed for the timeout arguments).

The return value is the number of streams that are ready, this may be 0 if a timeout was specified. All file descriptors in the three lists that are not yet ready are replaced by fail in this function. So the lists are changed!

This function is not available on the Macintosh architecture and is only available if your operating system has select, which is detected during compilation of &GAP;.
Operations for Input Streams

Three operations normally used to read files: , and 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: , and , 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.

reads the input-text-stream as input until end-of-stream occurs. See for details.
reads the input-text-stream as function and returns this function. See for details.

gap> # a 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 gap> # reading it via `Read' does gap> i := InputTextString( "a := 10;" );; gap> Read(i); gap> a; 10
reads the input-text-stream as test input until end-of-stream occurs. See for details.
<#Include Label="ReadByte"> <#Include Label="ReadLine"> <#Include Label="ReadAll"> <#Include Label="IsEndOfStream"> <#Include Label="PositionStream"> <#Include Label="RewindStream"> <#Include Label="SeekPositionStream">

Operations for Output Streams
<#Include Label="WriteByte"> <#Include Label="WriteLine"> <#Include Label="WriteAll">

PrintTo and AppendTo (for streams)
These functions work like , except that the output is appended to the output stream output-stream.

gap> str := "";; a := OutputTextString(str,true);; gap> AppendTo( a, (1,2,3), ":", Z(3) ); gap> CloseStream(a); gap> Print( str, "\n" ); (1,2,3):Z(3)
<#Include Label="LogTo"> <#Include Label="InputLogTo"> <#Include Label="OutputLogTo"> <#Include Label="SetPrintFormattingStatus">

File Streams

File streams are streams associated with files. An input file stream reads the characters it delivers from a file, an output file stream prints the characters it receives to a file. The following functions can be used to create such streams. They return fail if an error occurred, in this case can be used to get information about the error.

<#Include Label="InputTextFile"> <#Include Label="OutputTextFile">

User Streams

The commands described in this section create streams which accept characters from, or deliver characters to, the user, via the keyboard or the &GAP; session display.

<#Include Label="InputTextUser"> <#Include Label="OutputTextUser"> <#Include Label="InputFromUser">

String Streams

String streams are streams associated with strings. An input string stream reads the characters it delivers from a string, an output string stream appends the characters it receives to a string. The following functions can be used to create such streams.

<#Include Label="InputTextString"> <#Include Label="OutputTextString">

Input-Output Streams
<#Include Label="[2]{streams}"> <#Include Label="IsInputOutputStream"> <#Include Label="InputOutputLocalProcess"> <#Include Label="ReadAllLine">

Dummy Streams

The following two commands create dummy streams which will consume all characters and never deliver one.

<#Include Label="InputTextNone"> <#Include Label="OutputTextNone">

Handling of Streams in the Background

This section describes a feature of the &GAP; kernel that can be used to handle pending streams somehow in the background. This is currently not available on the Macintosh architecture and only on operating systems that have select.

Right before &GAP; reads a keypress from the keyboard it calls a little subroutine that can handle streams that are ready to be read or ready to be written. This means that &GAP; can handle these streams during user input on the command line. Note that this does not work when &GAP; is in the middle of some calculation.

This feature is used in the following way. One can install handler functions for reading or writing streams via . Handlers can be removed via

Note that handler functions must not return anything and get one integer argument, which refers to an index in one of the following arrays (according to whether the function was installed for input, output or exceptions on the stream). Handler functions usually should not output anything on the standard output because this ruins the command line during command line editing.

<#Include Label="InstallCharReadHookFunc"> <#Include Label="UnInstallCharReadHookFunc">

Comma separated files
Spreadsheet
Excel

In some situations it can be desirable to process data given in the form of a spreadsheet (such as Excel). &GAP; can do this using the CSV (comma separated values) format, which spreadsheet programs can usually read in or write out.

The first line of the spreadsheet is used as labels of record components, each subsequent line then corresponds to a record. Entries enclosed in double quotes are considered as strings and are permitted to contain the separation character (usually a comma).

<#Include Label="ReadCSV"> <#Include Label="PrintCSV">