[MathJax off]

10 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.

10.1 Writing and reading a file

The following sequence of commands opens a file with name guck and writes some things to it:

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:

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.

10.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:

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.

10.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:

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

10.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:

gap> r := SingleHTTPRequest("www.math.rwth-aachen.de",80,"GET",
>              "/~Max.Neunhoeffer/index.html",rec(),false,false);;
gap> RecNames(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.

10.5 (Un-)Pickling

Assume you have some GAP objects you want to archive to disk grouped together. Then you might do the following:

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:

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.

generated by GAPDoc2HTML