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