8. Examples of usage
  
  For larger examples see the example directory of the package. You find there
  a  small  server  using  the  TCP/IP protocol and a corresponding client and
  another small server using the UDP protocol and a corresponding client.
  
  Further,  there  is an example for the usage of File objects, that read from
  or write to strings.
  
  Another  example  there  shows  starting up a child process and piping a few
  megabytes through it using IO_Popen2 (4.4-4).
  
  In  the following, we present a few explicit, interactive short examples for
  the  usage  of the functions in this package. Note that you have to load the
  IO package with the command LoadPackage("IO"); before trying these examples.
  
  
  8.1 Writing and reading a file
  
  The  following  sequence  of commands opens a file with name guck and writes
  some things to it:
  
  -----------------------------  Log  ------------------------------
    gap> f := IO_File("guck","w");
    <file fd=3 wbufsize=65536 wdata=0>
    gap> IO_Write(f,"Hello world\n");
    12
    gap> IO_WriteLine(f,"Hello world2!");
    14
    gap> IO_Write(f,12345);
    5
    gap> IO_Flush(f);
    true
    gap> IO_Close(f);
    true
  ------------------------------------------------------------------
  
  There  is  nothing  special  about  this,  the  numbers are numbers of bytes
  written.  Note  that  only  after  the IO_Flush (4.2-10) command the data is
  actually written to disk. Before that, it resides in the write buffer of the
  file. Note further, that the IO_Flush (4.2-10) call here would not have been
  necessary, since the IO_Close (4.2-16) call flushes the buffer anyway.
  
  The file can again be read with the following sequence of commands:
  
  -----------------------------  Log  ------------------------------
    gap> f := IO_File("guck","r");
    <file fd=3 rbufsize=65536 rpos=1 rdata=0>
    gap> IO_Read(f,10);
    "Hello worl"
    gap> IO_ReadLine(f);
    "d\n"
    gap> IO_ReadLine(f);
    "Hello world2!\n"
    gap> IO_ReadLine(f);
    "12345"
    gap> IO_ReadLine(f);
    ""
    gap> IO_Close(f);
    true
  ------------------------------------------------------------------
  
  Note  here  that  reading  line-wise  can  only be done efficiently by using
  buffered  I/O.  You  can  mix  calls  to  IO_Read (4.2-6) and to IO_ReadLine
  (4.2-3).  The end of file is indicated by an empty string returned by one of
  the read functions.
  
  
  8.2 Using filtering programs to read and write files
  
  If you want to write a big amount of data to file you might want to compress
  it  on  the fly without using much disk space. This can be achieved with the
  following command:
  
  -----------------------------  Log  ------------------------------
    gap> s := "";; for i in [1..10000] do Append(s,String(i)); od;;
    gap> Length(s);
    38894
    gap> IO_FileFilterString("guck.gz",[["gzip",["-9c"]]],s);
    true
    gap> sgz := StringFile("guck.gz");;
    gap> Length(sgz);
    18541
    gap> ss := IO_StringFilterFile([["gzip",["-dc"]]],"guck.gz");;
    gap> s=ss;
    true
  ------------------------------------------------------------------
  
  This  sequence  of commands needs that the program gzip is installed on your
  system.
  
  
  8.3 Using filters when reading or writing files sequentially
  
  If  you  want  to process bigger amounts of data you might not want to store
  all  of  it  in a single GAP string. In that case you might want to access a
  file on disk sequentially through a filter:
  
  -----------------------------  Log  ------------------------------
    gap> f := IO_FilteredFile([["gzip",["-9c"]]],"guck.gz","w");
    <file fd=5 wbufsize=65536 wdata=0>
    gap> IO_Write(f,"Hello world!\n");
    13
    gap> IO_Write(f,Elements(SymmetricGroup(5)),"\n");
    1359
    gap> IO_Close(f);
    true
    gap> f := IO_FilteredFile([["gzip",["-dc"]]],"guck.gz","r");
    <file fd=4 rbufsize=65536 rpos=1 rdata=0>
    gap> IO_ReadLine(f);
    "Hello world!\n"
    gap> s := IO_ReadLine(f);; Length(s);
    1359
    gap> IO_Read(f,10);                  
    ""
    gap> IO_Close(f);
    true
  ------------------------------------------------------------------
  
  
  8.4 Accessing a web page
  
  The  IO package has an HTTP client implementation. Using this you can access
  web pages and other web downloads from within GAP. Here is an example:
  
  -----------------------------  Log  ------------------------------
    gap> r := SingleHTTPRequest("www.math.rwth-aachen.de",80,"GET",
    >              "/~Max.Neunhoeffer/index.html",rec(),false,false);;
    gap> RecFields(r);
    [ "protoversion", "statuscode", "status", "header", "body", "closed" ]
    gap> r.status;
    "OK"
    gap> r.statuscode;
    200
    gap> r.header;
    rec( date := "Thu, 07 Dec 2006 22:08:22 GMT", 
      server := "Apache/2.0.55 (Ubuntu)", 
      last-modified := "Thu, 16 Nov 2006 00:21:44 GMT", 
      etag := "\"2179cf-11a5-3c77f600\"", accept-ranges := "bytes", 
      content-length := "4517", content-type := "text/html; charset=ISO-8859-1" )
    gap> Length(r.body);
    4517
  ------------------------------------------------------------------
  
  Of course, the time stamps and exact sizes of the answer may differ when you
  do this.
  
  
  8.5 (Un-)Pickling
  
  Assume  you  have  some  GAP  objects  you  want  to archive to disk grouped
  together. Then you might do the following:
  
  -----------------------------  Log  ------------------------------
    gap> r := rec( a := 1, b := "Max", c := [1,2,3] );
    rec( a := 1, b := "Max", c := [ 1, 2, 3 ] )
    gap> r.c[4] := r;
    rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
    gap> f := IO_File("guck","w");
    <file fd=3 wbufsize=65536 wdata=0>
    gap> IO_Pickle(f,r);
    IO_OK
    gap> IO_Pickle(f,[(1,2,3,4),(3,4)]);
    IO_OK
    gap> IO_Close(f);
    true
  ------------------------------------------------------------------
  
  Then, to read it in again, just do:
  
  -----------------------------  Log  ------------------------------
    gap> f := IO_File("guck");
    <file fd=3 rbufsize=65536 rpos=1 rdata=0>
    gap> IO_Unpickle(f);
    rec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )
    gap> IO_Unpickle(f);
    [ (1,2,3,4), (3,4) ]
    gap> IO_Unpickle(f);
    IO_Nothing
    gap> IO_Close(f);
    true
  ------------------------------------------------------------------
  
  Note that this works for a certain amount of builtin objects. If you want to
  archive  your  own  objects  or  more  sophisticated objects you have to use
  extend  the functionality as explained in Section 5.3. However, it works for
  lists and records and they may be arbitrarily self-referential.