blimp.sp Specification of the blimp module.
Version 2.4 - PE Holmes and RA Parker  21.08.07

General
-------

The blimp module provides functions for reading and writing groups for
the STLP system.  A file consists of a list of integers representing a
list of finitely presented groups as specified in ffmt.sp.  This module
provides for the reading and writing of one group at a time into memory,
and for the insertion and deletion of "blimps".  A blimp is a part of
a group definition contain a particular type of information.  See
ffmt.sp for further information.

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx

1.   blimp shall provide a header file blimp.h that shall

1.1  #define GRPSIZ to be the number of ints to be malloc'd to hold a
     string for a group.  The calling routine must allocate an area
     of this size to hold all the ints of a single group.  The area of
     this size is the parameter int *g in the routines below.

1.2  Prototypes or macros for all the routines listed in section 2 

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx

2.   blimp shall provide the source code to implement all of the
     following functions.

2.1  int ReadGroup(int *g, FILE *f) 
     Reads the group from the file and puts the data into g.  This
     function shall ensure that the group fits into GRPSIZ ints, and 
     shall print an error and exit the program if not.  If there are 
     no further groups in the file, the function shall return -1,
     otherwise 0 shall be returned.  It is the caller's resonsibility
     to open fhe file f for reading.

2.2  void WriteGroup(int *g, FILE *f)
     Writes the data in g to the file f.  It is the caller's
     responsibility to open the file f for writing.

2.3  int ListBlimps(int *g, int *t)
     returns the number of blimps in the list and puts the types into t. 

2.4  void InsertBlimp(int *g, int *b)
     The blimp pointed to by t shall be inserted into the string for g.
     If this would not fit into GRPSIZ ints, the function shall print an
     error message and exit the program.  If the blimp type is already
     in the group g, it shall first be deleted.  

2.5  void DeleteBlimp(int *g, int t)
     The blimp of type t shall be deleted from the group g.

2.6  void ExtractBlimp(int *g, int t, int *b)
     The blimp of type t shall be copied from the group g into the area
     b.  The group g shall remain unchanged.  It is the caller's 
     responsibility to ensure that b is large enough to hold the blimp,
     and this is normally done by having a work area for b of size
     GRPSIZ.  The whole blimp, including the type and length, is 
     extracted.  If there is no blimp of type t, the program exits with
     an error message; hence it is the caller's responsibility to check
     that the blimp is there if this is not the required action.

2.7  void WriteEOF(FILE * f) to write the end-of-file marker (blimp type
     zero) to the file f.  The file is not closed, however.

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx
end of blimp.sp.