<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Categories for Streams and the StreamsFamily">
<Heading>Categories for Streams and the StreamsFamily</Heading>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations applicable to All Streams">
<Heading>Operations applicable to All Streams</Heading>
<Description>
makes the UNIX C-library function <C>select</C> 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
<Ref Oper="FileDescriptorOfStream"/> for streams
to local processes and to local files. The argument <A>timeoutsec</A> is a
timeout in seconds as in the <C>struct timeval</C> on the C level. The argument
<A>timeoutusec</A> 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 (<K>fail</K> is allowed for the timeout arguments).
<P/>
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 <K>fail</K> in this function. So
the lists are changed!
<P/>
This function is only available if your operating system has <C>select</C>,
which is detected during compilation of &GAP;.
</Description>
</ManSection>
</Section>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Input Streams">
<Heading>Operations for Input Streams</Heading>
Two operations normally used to read files: <Ref Oper="Read"/> and
<Ref Oper="ReadAsFunction"/> can also be used to read &GAP; input from a
stream. The input is immediately parsed and executed. When reading
from a stream <A>str</A>, the &GAP; kernel generates calls to
<C>ReadLine(<A>str</A>)</C> to supply text to the parser.
<P/>
Three further operations: <Ref Oper="ReadByte"/>, <Ref Oper="ReadLine"/>
and <Ref Oper="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;.
<P/>
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.
<P/>
<Description>
reads the input-text-stream as input until <C>end-of-stream</C> occurs. See
<Ref Sect="File Operations"/> for details.
</Description>
</ManSection>
<Description>
reads the input-text-stream as function and returns this function. See
<Ref Sect="File Operations"/> for details.
<Example><![CDATA[
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
]]></Example>
</Description>
</ManSection>
<Description>
These functions work like <Ref Func="Print"/>, except that the output is
appended to the output stream <A>output-stream</A>.
<P/>
<Example><![CDATA[
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)
]]></Example>
</Description>
</ManSection>
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 <K>fail</K> if an error occurred,
in this case <Ref Func="LastSystemError"/> can be used to get
information about the error.
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.
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.
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Handling of Streams in the Background">
<Heading>Handling of Streams in the Background</Heading>
This section describes a feature of the &GAP; kernel that can be used
to handle pending streams somehow <Q>in the background</Q>. This is
only available on operating systems that have <C>select</C>.
<P/>
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.
<P/>
This feature is used in the following way. One can install handler
functions for reading or writing streams via
<Ref Func="InstallCharReadHookFunc"/>.
Handlers can be removed via
<Ref Func="UnInstallCharReadHookFunc"/>
<P/>
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.
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.
<P/>
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).
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Opening files in the Operating System">
<Heading>Opening files in the Operating System</Heading>
In some situations it can be desirable to open a file outside of &GAP;,
for example HTML files, PDFs, or pictures.
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
