  
  [1m[4m[31m8. Examples of usage[0m
  
  For larger examples see the [1mexample[0m 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 [22m[32mFile[0m 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 [1m[34mIO_Popen2[0m ([1m4.4-4[0m).
  
  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
  [1mIO[0m package with the command [22m[32mLoadPackage("IO");[0m before trying these examples.
  
  
  [1m[4m[31m8.1 Writing and reading a file[0m
  
  The  following  sequence  of commands opens a file with name [1mguck[0m and writes
  some things to it:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> f := IO_File("guck","w");[0m
    [22m[35m<file fd=3 wbufsize=65536 wdata=0>[0m
    [22m[35mgap> IO_Write(f,"Hello world\n");[0m
    [22m[35m12[0m
    [22m[35mgap> IO_WriteLine(f,"Hello world2!");[0m
    [22m[35m14[0m
    [22m[35mgap> IO_Write(f,12345);[0m
    [22m[35m5[0m
    [22m[35mgap> IO_Flush(f);[0m
    [22m[35mtrue[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  There  is  nothing  special  about  this,  the  numbers are numbers of bytes
  written.  Note  that  only  after  the [1m[34mIO_Flush[0m ([1m4.2-10[0m) command the data is
  actually written to disk. Before that, it resides in the write buffer of the
  file. Note further, that the [1m[34mIO_Flush[0m ([1m4.2-10[0m) call here would not have been
  necessary, since the [1m[34mIO_Close[0m ([1m4.2-16[0m) call flushes the buffer anyway.
  
  The file can again be read with the following sequence of commands:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> f := IO_File("guck","r");[0m
    [22m[35m<file fd=3 rbufsize=65536 rpos=1 rdata=0>[0m
    [22m[35mgap> IO_Read(f,10);[0m
    [22m[35m"Hello worl"[0m
    [22m[35mgap> IO_ReadLine(f);[0m
    [22m[35m"d\n"[0m
    [22m[35mgap> IO_ReadLine(f);[0m
    [22m[35m"Hello world2!\n"[0m
    [22m[35mgap> IO_ReadLine(f);[0m
    [22m[35m"12345"[0m
    [22m[35mgap> IO_ReadLine(f);[0m
    [22m[35m""[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Note  here  that  reading  line-wise  can  only be done efficiently by using
  buffered  I/O.  You  can  mix  calls  to  [1m[34mIO_Read[0m ([1m4.2-6[0m) and to [1m[34mIO_ReadLine[0m
  ([1m4.2-3[0m).  The end of file is indicated by an empty string returned by one of
  the read functions.
  
  
  [1m[4m[31m8.2 Using filtering programs to read and write files[0m
  
  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:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> s := "";; for i in [1..10000] do Append(s,String(i)); od;;[0m
    [22m[35mgap> Length(s);[0m
    [22m[35m38894[0m
    [22m[35mgap> IO_FileFilterString("guck.gz",[["gzip",["-9c"]]],s);[0m
    [22m[35mtrue[0m
    [22m[35mgap> sgz := StringFile("guck.gz");;[0m
    [22m[35mgap> Length(sgz);[0m
    [22m[35m18541[0m
    [22m[35mgap> ss := IO_StringFilterFile([["gzip",["-dc"]]],"guck.gz");;[0m
    [22m[35mgap> s=ss;[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  This  sequence  of commands needs that the program [1mgzip[0m is installed on your
  system.
  
  
  [1m[4m[31m8.3 Using filters when reading or writing files sequentially[0m
  
  If  you  want  to process bigger amounts of data you might not want to store
  all  of  it  in a single [1mGAP[0m string. In that case you might want to access a
  file on disk sequentially through a filter:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> f := IO_FilteredFile([["gzip",["-9c"]]],"guck.gz","w");[0m
    [22m[35m<file fd=5 wbufsize=65536 wdata=0>[0m
    [22m[35mgap> IO_Write(f,"Hello world!\n");[0m
    [22m[35m13[0m
    [22m[35mgap> IO_Write(f,Elements(SymmetricGroup(5)),"\n");[0m
    [22m[35m1359[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
    [22m[35mgap> f := IO_FilteredFile([["gzip",["-dc"]]],"guck.gz","r");[0m
    [22m[35m<file fd=4 rbufsize=65536 rpos=1 rdata=0>[0m
    [22m[35mgap> IO_ReadLine(f);[0m
    [22m[35m"Hello world!\n"[0m
    [22m[35mgap> s := IO_ReadLine(f);; Length(s);[0m
    [22m[35m1359[0m
    [22m[35mgap> IO_Read(f,10);                  [0m
    [22m[35m""[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m8.4 Accessing a web page[0m
  
  The  [1mIO[0m package has an HTTP client implementation. Using this you can access
  web pages and other web downloads from within [1mGAP[0m. Here is an example:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> r := SingleHTTPRequest("www.math.rwth-aachen.de",80,"GET",[0m
    [22m[35m>              "/~Max.Neunhoeffer/index.html",rec(),false,false);;[0m
    [22m[35mgap> RecFields(r);[0m
    [22m[35m[ "protoversion", "statuscode", "status", "header", "body", "closed" ][0m
    [22m[35mgap> r.status;[0m
    [22m[35m"OK"[0m
    [22m[35mgap> r.statuscode;[0m
    [22m[35m200[0m
    [22m[35mgap> r.header;[0m
    [22m[35mrec( date := "Thu, 07 Dec 2006 22:08:22 GMT", [0m
    [22m[35m  server := "Apache/2.0.55 (Ubuntu)", [0m
    [22m[35m  last-modified := "Thu, 16 Nov 2006 00:21:44 GMT", [0m
    [22m[35m  etag := "\"2179cf-11a5-3c77f600\"", accept-ranges := "bytes", [0m
    [22m[35m  content-length := "4517", content-type := "text/html; charset=ISO-8859-1" )[0m
    [22m[35mgap> Length(r.body);[0m
    [22m[35m4517[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Of course, the time stamps and exact sizes of the answer may differ when you
  do this.
  
  
  [1m[4m[31m8.5 (Un-)Pickling[0m
  
  Assume  you  have  some  [1mGAP[0m  objects  you  want  to archive to disk grouped
  together. Then you might do the following:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> r := rec( a := 1, b := "Max", c := [1,2,3] );[0m
    [22m[35mrec( a := 1, b := "Max", c := [ 1, 2, 3 ] )[0m
    [22m[35mgap> r.c[4] := r;[0m
    [22m[35mrec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )[0m
    [22m[35mgap> f := IO_File("guck","w");[0m
    [22m[35m<file fd=3 wbufsize=65536 wdata=0>[0m
    [22m[35mgap> IO_Pickle(f,r);[0m
    [22m[35mIO_OK[0m
    [22m[35mgap> IO_Pickle(f,[(1,2,3,4),(3,4)]);[0m
    [22m[35mIO_OK[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Then, to read it in again, just do:
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> f := IO_File("guck");[0m
    [22m[35m<file fd=3 rbufsize=65536 rpos=1 rdata=0>[0m
    [22m[35mgap> IO_Unpickle(f);[0m
    [22m[35mrec( a := 1, b := "Max", c := [ 1, 2, 3, ~ ] )[0m
    [22m[35mgap> IO_Unpickle(f);[0m
    [22m[35m[ (1,2,3,4), (3,4) ][0m
    [22m[35mgap> IO_Unpickle(f);[0m
    [22m[35mIO_Nothing[0m
    [22m[35mgap> IO_Close(f);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  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 [1m5.3[0m. However, it works for
  lists and records and they may be arbitrarily self-referential.
  
