chap10.txt

  
  10 Streams
  
  Streams  provide  flexible  access  to GAP's input and output processing. An
  input  stream  takes  characters  from  some source and delivers them to GAP
  which  reads  them  from  the stream. When an input stream has delivered all
  characters it is at end-of-stream. An output stream receives characters from
  GAP which writes them to the stream, and delivers them to some destination.
  
  A major use of streams is to provide efficient and flexible access to files.
  Files  can  be  read  and  written  using Read (9.7-1) and AppendTo (9.7-3),
  however  the  former only allows a complete file to be read as GAP input and
  the  latter  imposes  a high time penalty if many small pieces of output are
  written  to  a  large file. Streams allow input files in other formats to be
  read  and  processed, and files to be built up efficiently from small pieces
  of  output. Streams may also be used for other purposes, for example to read
  from and print to GAP strings, or to read input directly from the user.
  
  Any  stream  is  either  a  text  stream,  which  translates the end-of-line
  character  (\n) to or from the system's representation of end-of-line (e.g.,
  new-line  under  UNIX  and  carriage-return-new-line under DOS), or a binary
  stream,  which  does not translate the end-of-line character. The processing
  of other unprintable characters by text streams is undefined. Binary streams
  pass them unchanged.
  
  Whereas  it  is  cheap  to  append  to  a  stream, streams do consume system
  resources,  and  only a limited number can be open at any time, therefore it
  is  necessary  to  close  a  stream  as  soon  as possible using CloseStream
  (10.2-1).  If  creating  a stream failed then LastSystemError (9.1-1) can be
  used to get information about the failure.
  
  
  10.1 Categories for Streams and the StreamsFamily
  
  10.1-1 IsStream
  
  IsStream( obj )  Category
  
  Streams  are  GAP  objects  and  all  open  streams, input, output, text and
  binary, lie in this category.
  
  10.1-2 IsClosedStream
  
  IsClosedStream( obj )  Category
  
  When  a  stream  is  closed, its type changes to lie in IsClosedStream. This
  category is used to install methods that trap accesses to closed streams.
  
  10.1-3 IsInputStream
  
  IsInputStream( obj )  Category
  
  All input streams lie in this category, and support input operations such as
  ReadByte (10.3-3) (see 10.3)
  
  10.1-4 IsInputTextStream
  
  IsInputTextStream( obj )  Category
  
  All  text  input  streams  lie  in  this  category.  They translate new-line
  characters read.
  
  10.1-5 IsInputTextNone
  
  IsInputTextNone( obj )  Category
  
  It  is  convenient to use a category to distinguish dummy streams (see 10.9)
  from others. Other distinctions are usually made using representations
  
  10.1-6 IsOutputStream
  
  IsOutputStream( obj )  Category
  
  All output streams lie in this category and support basic operations such as
  WriteByte (10.4-1) (see Section 10.4).
  
  10.1-7 IsOutputTextStream
  
  IsOutputTextStream( obj )  Category
  
  All  text  output  streams  lie  in  this  category  and  translate new-line
  characters on output.
  
  10.1-8 IsOutputTextNone
  
  IsOutputTextNone( obj )  Category
  
  It  is  convenient to use a category to distinguish dummy streams (see 10.9)
  from others. Other distinctions are usually made using representations
  
  10.1-9 StreamsFamily
  
  StreamsFamily family
  
  All streams lie in the StreamsFamily.
  
  
  10.2 Operations applicable to All Streams
  
  10.2-1 CloseStream
  
  CloseStream( stream )  operation
  
  In  order  to  preserve  system  resources and to flush output streams every
  stream should be closed as soon as it is no longer used using CloseStream.
  
  It  is  an  error  to  try  to read characters from or write characters to a
  closed  stream.  Closing  a stream tells the GAP kernel and/or the operating
  system  kernel  that  the  file  is  no longer needed. This may be necessary
  because the GAP kernel and/or the operating system may impose a limit on how
  many streams may be open simultaneously.
  
  10.2-2 FileDescriptorOfStream
  
  FileDescriptorOfStream( stream )  operation
  
  returns  the  UNIX  file  descriptor  of the underlying file. This is mainly
  useful  for  the  UNIXSelect  (10.2-3) function call. This is as of now only
  available  on  UNIX-like  operating  systems  and  only for streams to local
  processes and local files.
  
  10.2-3 UNIXSelect
  
  UNIXSelect( inlist, outlist, exclist, timeoutsec, timeoutusec )  function
  
  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 FileDescriptorOfStream
  (10.2-2)  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.
  
  
  10.3 Operations for Input Streams
  
  Two  operations normally used to read files: Read (9.7-1) and ReadAsFunction
  (9.7-2)  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 (10.3-3), ReadLine (10.3-4) and ReadAll
  (10.3-5),  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.
  
  10.3-1 Read
  
  Read( input-text-stream )  operation
  
  reads the input-text-stream as input until end-of-stream occurs. See 9.7 for
  details.
  
  10.3-2 ReadAsFunction
  
  ReadAsFunction( input-text-stream )  operation
  
  reads  the  input-text-stream as function and returns this function. See 9.7
  for details.
  
    Example  
    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
  
  
  10.3-3 ReadByte
  
  ReadByte( input-stream )  operation
  
  ReadByte  returns  one character (returned as integer) from the input stream
  input-stream.  ReadByte  returns fail if there is no character available, in
  particular if it is at the end of a file.
  
  If  input-stream 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 which does not block, then all
  the  other  input stream operations will work (although possibly not at peak
  efficiency).
  
  ReadByte  will  wait  (block) until a byte is available. For instance if the
  stream  is  a connection to another process, it will wait for the process to
  output a byte.
  
  10.3-4 ReadLine
  
  ReadLine( input-stream )  operation
  
  ReadLine  returns  one  line  (returned as string with the newline) from the
  input  stream  input-stream.  ReadLine reads in the input until a newline is
  read or the end-of-stream is encountered.
  
  If  input-stream 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. It will always wait (block) for at least one byte to
  be  available,  but  will then return as much input as is available, up to a
  limit of one line
  
  A  default  method  is  supplied  for  ReadLine  which simply calls ReadByte
  (10.3-3)  repeatedly.  This  is only safe for streams that cannot block. The
  kernel  uses  calls  to  ReadLine to supply input to the parser when reading
  from a stream.
  
  10.3-5 ReadAll
  
  ReadAll( input-stream[, limit] )  operation
  
  ReadAll returns all characters as string from the input stream stream-in. It
  waits (blocks) until at least one character is available from the stream, or
  until  there  is  evidence  that no characters will ever be available again.
  This last indicates that the stream is at end-of-stream. Otherwise, it reads
  as much input as it can from the stream without blocking further and returns
  it  to  the  user. If the stream is already at end of file, so that no bytes
  are available, fail is returned. In the case of a file stream connected to a
  normal  file  (not  a  pseudo-tty  or  named pipe or similar), all the bytes
  should be immediately available and this function will read the remainder of
  the file.
  
  With  a  second argument, at most limit bytes will be returned. Depending on
  the  stream  a bounded number of additional bytes may have been read into an
  internal buffer.
  
  A  default  method  is  supplied  for  ReadAll  which  simply calls ReadLine
  (10.3-4)  repeatedly.  This  is  only  really  safe for streams which cannot
  block. Other streams should install a method for ReadAll
  
    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"
  
  
  10.3-6 IsEndOfStream
  
  IsEndOfStream( input-stream )  operation
  
  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 (10.3-3) fails.
  
  10.3-7 PositionStream
  
  PositionStream( input-stream )  operation
  
  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  (10.3-9)  and  RewindStream  (10.3-8).
  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
  
  10.3-8 RewindStream
  
  RewindStream( input-stream )  operation
  
  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 (10.3-9).
  
  10.3-9 SeekPositionStream
  
  SeekPositionStream( input-stream, pos )  operation
  
  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.
  
  
  10.4 Operations for Output Streams
  
  10.4-1 WriteByte
  
  WriteByte( output-stream, byte )  operation
  
  writes   the  next  character  (given  as  integer)  to  the  output  stream
  output-stream.  The  function  returns  true  if the write succeeds and fail
  otherwise.
  
  WriteByte  is  the basic operation for output streams. If a WriteByte method
  is  installed  for  a user-defined type of stream, then all the other output
  stream operations will work (although possibly not at peak efficiency).
  
  10.4-2 WriteLine
  
  WriteLine( output-stream, string )  operation
  
  appends  string  to  output-stream. A final newline is written. The function
  returns true if the write succeeds and fail otherwise.
  
  A  default  method is installed which implements WriteLine by repeated calls
  to WriteByte (10.4-1).
  
  10.4-3 WriteAll
  
  WriteAll( output-stream, string )  operation
  
  appends  string  to output-stream. No final newline is written. The function
  returns true if the write succeeds and fail otherwise. It will block as long
  as  necessary  for  the write operation to complete (for example for a child
  process to clear its input buffer )
  
  A default method is installed which implements WriteAll by repeated calls to
  WriteByte (10.4-1).
  
  When  printing  or appending to a stream (using PrintTo (9.7-3), or AppendTo
  (9.7-3)  or  when  logging  to  a  stream),  the  kernel generates a call to
  WriteAll for each line output.
  
    Example  
    gap> str := "";; a := OutputTextString(str,true);;
    gap> WriteByte(a,INT_CHAR('H'));
    true
    gap> WriteLine(a,"allo");
    true
    gap> WriteAll(a,"You\n");
    true
    gap> CloseStream(a);
    gap> Print(str);
    Hallo
    You
  
  
  
  10.4-4 PrintTo and AppendTo (for streams)
  
  PrintTo( output-stream, arg1, ... )  function
  AppendTo( output-stream, arg1, ... )  function
  
  These  functions work like Print (6.3-4), except that the output is appended
  to the output stream output-stream.
  
    Example  
    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)
  
  
  10.4-5 LogTo
  
  LogTo( stream )  operation
  
  causes  the subsequent interaction to be logged to the output stream stream.
  It works in precisely the same way as it does for files (see LogTo (9.7-4)).
  
  10.4-6 InputLogTo
  
  InputLogTo( stream )  operation
  
  causes  the  subsequent  input  to be logged to the output stream stream. It
  works just like it does for files (see InputLogTo (9.7-5)).
  
  10.4-7 OutputLogTo
  
  OutputLogTo( stream )  operation
  
  causes  the  subsequent  output to be logged to the output stream stream. It
  works just like it does for files (see OutputLogTo (9.7-6)).
  
  10.4-8 SetPrintFormattingStatus
  
  SetPrintFormattingStatus( stream, newstatus )  operation
  PrintFormattingStatus( stream )  operation
  
  When  text  is  being  sent  to  an  output text stream via PrintTo (9.7-3),
  AppendTo  (9.7-3),  LogTo (10.4-5), etc., it is by default formatted just as
  it  would  be  were  it being printed to the screen. Thus, it is broken into
  lines  of  reasonable  length  at  (where  possible)  sensible places, lines
  containing  elements of lists or records are indented, and so forth. This is
  appropriate  if  the  output  is  eventually  to  be  viewed by a human, and
  harmless if it to passed as input to GAP, but may be unhelpful if the output
  is to be passed as input to another program. It is possible to turn off this
  behaviour  for a stream using the SetPrintFormattingStatus operation, and to
  test whether it is on or off using PrintFormattingStatus.
  
  SetPrintFormattingStatus  sets  whether  output  sent  to  the output stream
  stream  via  PrintTo  (9.7-3), AppendTo (9.7-3), etc. will be formatted with
  line  breaks  and indentation. If the second argument newstatus is true then
  output will be so formatted, and if false then it will not. If the stream is
  not a text stream, only false is allowed.
  
  PrintFormattingStatus  returns true if output sent to the output text stream
  stream  via  PrintTo  (9.7-3), AppendTo (9.7-3), etc. will be formatted with
  line  breaks  and indentation, and false otherwise. For non-text streams, it
  returns  false.  If as argument stream the string "*stdout*" is given, these
  functions  refer to the formatting status of the standard output (so usually
  the users terminal screen).
  
  These  functions  do  not influence the behaviour of the low level functions
  WriteByte  (10.4-1),  WriteLine  (10.4-2)  or WriteAll (10.4-3) which always
  write without formatting.
  
    Example  
    gap> s := "";; str := OutputTextString(s,false);;
    gap> PrintTo(str,Primes{[1..30]});
    gap> s;
    "[ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,\
     \n  67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113 ]"
    gap> Print(s,"\n");
    [ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 
      67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113 ]
    gap> SetPrintFormattingStatus(str, false);
    gap> PrintTo(str,Primes{[1..30]});
    gap> s;
    "[ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,\
     \n  67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113 ][ 2, 3, 5, 7\
    , 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, \
    79, 83, 89, 97, 101, 103, 107, 109, 113 ]"
    gap> Print(s,"\n");
    [ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 
      67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113 ][ 2, 3, 5, 7, 1\
    1, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79,\
     83, 89, 97, 101, 103, 107, 109, 113 ]
  
  
  
  10.5 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
  LastSystemError (9.1-1) can be used to get information about the error.
  
  10.5-1 InputTextFile
  
  InputTextFile( filename )  operation
  
  InputTextFile(   filename   )  returns  an  input  stream  in  the  category
  IsInputTextStream  (10.1-4)  that  delivers  the  characters  from  the file
  filename.
  
  10.5-2 OutputTextFile
  
  OutputTextFile( filename, append )  operation
  
  OutputTextFile(  filename, append ) returns an output stream in the category
  IsOutputTextFile  that  writes  received characters to the file filename. If
  append  is  false,  then  the  file  is  emptied  first,  otherwise received
  characters are added at the end of the file.
  
    Example  
    gap> # use a temporary directory
    gap> name := Filename( DirectoryTemporary(), "test" );;
    gap> # create an output stream, append output, and close again
    gap> output := OutputTextFile( name, true );;
    gap> AppendTo( output, "Hallo\n", "You\n" );
    gap> CloseStream(output);
    gap> # create an input, print complete contents of file, and close
    gap> input := InputTextFile(name);;
    gap> Print( ReadAll(input) );
    Hallo
    You
    gap> CloseStream(input);
    gap> # append a single line
    gap> output := OutputTextFile( name, true );;
    gap> AppendTo( output, "AppendLine\n" );
    gap> # close output stream to flush the output
    gap> CloseStream(output);
    gap> # create an input, print complete contents of file, and close
    gap> input := InputTextFile(name);;
    gap> Print( ReadAll(input) );
    Hallo
    You
    AppendLine
    gap> CloseStream(input);
  
  
  
  10.6 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.
  
  10.6-1 InputTextUser
  
  InputTextUser(  )  function
  
  returns an input text stream which delivers characters typed by the user (or
  from  the  standard  input  device  if  it  has  been redirected). In normal
  circumstances,  characters  are  delivered  one  by  one  as they are typed,
  without waiting until the end of a line. No prompts are printed.
  
  10.6-2 OutputTextUser
  
  OutputTextUser(  )  function
  
  returns an output stream which delivers characters to the user's display (or
  the  standard  output  device  if it has been redirected). Each character is
  delivered  immediately  it  is  written,  without waiting for a full line of
  output.  Text  written  in  this  way is not written to the session log (see
  LogTo (9.7-4)).
  
  10.6-3 InputFromUser
  
  InputFromUser( arg )  function
  
  prints the arg as a prompt, then waits until a text is typed by the user (or
  from the standard input device if it has been redirected). This text must be
  a  single  expression,  followed  by  one  enter.  This  is  evaluated  (see
  EvalString (27.9-3)) and the result is returned.
  
  
  10.7 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.
  
  10.7-1 InputTextString
  
  InputTextString( string )  operation
  
  InputTextString(  string  )  returns  an  input  stream  that  delivers  the
  characters  from  the  string string. The string is not changed when reading
  characters from it and changing the string after the call to InputTextString
  has no influence on the input stream.
  
  10.7-2 OutputTextString
  
  OutputTextString( list, append )  operation
  
  returns  an  output  stream  that puts all received characters into the list
  list. If append is false, then the list is emptied first, otherwise received
  characters are added at the end of the list.
  
    Example  
    gap> # read input from a string
    gap> input := InputTextString( "Hallo\nYou\n" );;
    gap> ReadLine(input);
    "Hallo\n"
    gap> ReadLine(input);
    "You\n"
    gap> # print to a string
    gap> str := "";;
    gap> out := OutputTextString( str, true );;
    gap> PrintTo( out, 1, "\n", (1,2,3,4)(5,6), "\n" );
    gap> CloseStream(out);
    gap> Print( str );
    1
    (1,2,3,4)(5,6)
  
  
  
  10.8 Input-Output Streams
  
  Input-output  streams  capture  bidirectional communications between GAP and
  another process, either locally or (@as yet unimplemented@) remotely.
  
  Such  streams support the basic operations of both input and output streams.
  They  should  provide  some buffering, allowing output data to be written to
  the  stream,  even  when input data is waiting to be read, but the amount of
  this  buffering is operating system dependent, and the user should take care
  not  to  get too far ahead in writing, or behind in reading, or deadlock may
  occur.
  
  At  present  the  only  type  of  Input-Output  streams that are implemented
  provide communication with a local child process, using a pseudo-tty.
  
  Like  other  streams,  write  operations  are blocking, read operations will
  block to get the first character, but not thereafter.
  
  As far as possible, no translation is done on characters written to, or read
  from  the  stream,  and  no control characters have special effects, but the
  details of particular pseudo-tty implementations may effect this.
  
  10.8-1 IsInputOutputStream
  
  IsInputOutputStream( obj )  Category
  
  IsInputOutputStream is the Category of Input-Output Streams; it returns true
  if the obj is an input-output stream and false otherwise.
  
  10.8-2 InputOutputLocalProcess
  
  InputOutputLocalProcess( dir, executable, args )  function
  
  starts up a slave process, whose executable file is executable, with command
  line  arguments  args  in  the  directory dir. (Suitable choices for dir are
  DirectoryCurrent()     or     DirectoryTemporary()     (see    Section 9.3);
  DirectoryTemporary()  may  be a good choice when executable generates output
  files  that  it  doesn't  itself remove afterwards.) InputOutputLocalProcess
  returns  an  InputOutputStream  object.  Bytes  written  to  this stream are
  received  by  the slave process as if typed at a terminal on standard input.
  Bytes  written  to standard output by the slave process can be read from the
  stream.
  
  When  the  stream  is  closed,  the signal SIGTERM is delivered to the child
  process, which is expected to exit.
  
    Example  
    gap> d := DirectoryCurrent();
    dir("./")
    gap> f := Filename(DirectoriesSystemPrograms(), "rev");
    "/usr/bin/rev"
    gap> s := InputOutputLocalProcess(d,f,[]);
    < input/output stream to rev >
    gap> WriteLine(s,"The cat sat on the mat");
    true
    gap> Print(ReadLine(s));
    tam eht no tas tac ehT
    gap> x := ListWithIdenticalEntries(10000,'x');;
    gap> ConvertToStringRep(x);
    gap> WriteLine(s,x);
    true
    gap> WriteByte(s,INT_CHAR('\n'));
    true
    gap> y := ReadAll(s);;
    gap> Length(y);
    4095
    gap> CloseStream(s);
    gap> s;
    < closed input/output stream to rev >
  
  
  10.8-3 ReadAllLine
  
  ReadAllLine( iostream[, nofail][, IsAllLine] )  operation
  
  For  an  input/output  stream  iostream  ReadAllLine  reads  until a newline
  character  if  any  input  is  found  or  returns fail if no input is found,
  i.e. if any input is found ReadAllLine is non-blocking.
  
  If  the  argument nofail (which must be false or true) is provided and it is
  set  to  true  then ReadAllLine will wait, if necessary, for input and never
  return fail.
  
  If  the  argument  IsAllLine  (which  must be a function that takes a string
  argument and returns either true or false) then it is used to determine what
  constitutes a whole line. The default behaviour is equivalent to passing the
  function
  
    Example  
    line -> 0 < Length(line) and line[Length(line)] = '\n'
  
  
  for  the  IsAllLine  argument.  The  purpose of the IsAllLine argument is to
  cater  for  the  case where the input being read is from an external process
  that writes a prompt for data that does not terminate with a newline.
  
  If the first argument is an input stream but not an input/output stream then
  ReadAllLine  behaves  as if ReadLine (10.3-4) was called with just the first
  argument and any additional arguments are ignored.
  
  
  10.9 Dummy Streams
  
  The  following  two  commands  create  dummy  streams which will consume all
  characters and never deliver one.
  
  10.9-1 InputTextNone
  
  InputTextNone(  )  function
  
  returns a dummy input text stream, which delivers no characters, i.e., it is
  always  at end of stream. Its main use is for calls to Process (11.1-1) when
  the started program does not read anything.
  
  10.9-2 OutputTextNone
  
  OutputTextNone(  )  function
  
  returns  a  dummy output stream, which discards all received characters. Its
  main  use is for calls to Process (11.1-1) when the started program does not
  write anything.
  
  
  10.10 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  InstallCharReadHookFunc  (10.10-1).
  Handlers can be removed via UnInstallCharReadHookFunc (10.10-2)
  
  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.
  
  10.10-1 InstallCharReadHookFunc
  
  InstallCharReadHookFunc( stream, mode, func )  function
  
  installs  the function func as a handler function for the stream stream. The
  argument  mode  decides,  for what operations on the stream this function is
  installed.  mode  must  be a string, in which a letter r means read, w means
  write  and  x  means exception, according to the select function call in the
  UNIX  C-library  (see  man  select  and  UNIXSelect (10.2-3)). More than one
  letter  is  allowed  in mode. As described above the function is called in a
  situation  when  GAP  is  reading  a  character  from  the keyboard. Handler
  functions should not use much time to complete.
  
  This  functionality  does  not  work  on the Macintosh architecture and only
  works if the operating system has a select function.
  
  10.10-2 UnInstallCharReadHookFunc
  
  UnInstallCharReadHookFunc( stream, func )  function
  
  uninstalls  the  function  func as a handler function for the stream stream.
  All  instances  are  deinstalled, regardless of the mode of operation (read,
  write, exception).
  
  This  functionality  does  not  work  on the Macintosh architecture and only
  works if the operating system has a select function.
  
  
  10.11 Comma separated files
  
  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).
  
  10.11-1 ReadCSV
  
  ReadCSV( filename[, nohead][, separator] )  function
  
  This  function  reads in a spreadsheet, saved in CSV format (comma separated
  values)  and  returns  its  entries as a list of records. The entries of the
  first  line  of  the  spreadsheet are used to denote the names of the record
  components.  Blanks  will  be  translated into underscore characters. If the
  parameter  nohead  is  given  as true, instead the record components will be
  called  fieldn.  Each  subsequent  line  will  create  one record. If given,
  separator is the character used to separate fields. Otherwise it defaults to
  a comma.
  
  10.11-2 PrintCSV
  
  PrintCSV( filename, list[, fields] )  function
  
  This function prints a list of records as a spreadsheet in CSV format (which
  can  be  read in for example into Excel). The names of the record components
  will  be  printed  as  entries  in the first line. If the argument fields is
  given  only  the  record fields listed in this list will be printed and they
  will be printed in the same arrangement as given in this list. If the option
  noheader  is  set  to  true the line with the record field names will not be
  printed.