MeatAxe: Text File Handling

MeatAxe 2.4

- Main Page
- Related Pages
- Modules
- Data Structures

Functions
Text File Handling

## Detailed Description

The MeatAxe library provides functions for input and output of data in human-readable text format.

Files that are created with this set of functions have a defined structure, and are refered to as "structured text files" (STF). An examples for this type of files is the .cfinfo file which is used by the submodule lattice programs.

## File format

A structured text file is interpreted as a sequence of lines. While the STF input functions can read very long lines, the output functions try to limit the line length to 80 characters in order to make the file more readable. Each line is one of the following:

- Lines starting with a "#" in column 1 are comment lines and are ignored completely. Empty lines are ignored, too.
- A non-comment line with a non-blank character in column 1 marks the beginning of a new entry. Such a line has the format

       Name := Value

  Both Name and Value are arbitrary strings, except that they cannot contain leading or trailing blanks. In fact leading and trailing blanks as well as any blanks around the ":=" are removed on input.
- Lines starting with a whitspace character are interpreted as continuing lines. Obviously a continuing line may occur only after an entry has started. The contents of the continuing line, after leading lanks have been removed, are appended to Value.

## Data formats

Besides the removal of leading and trailing blanks there is no restriction on the format of

in an STF entry. There are, however, predefined functions that read and write integers and sequences of integers. An application should use these functions where possible. The format used by the integer i/o functions is most easily demonstrated in an example:

     Field := 7;
     Multiplicity := [1,1,1,2];
     Dimensions := [11,22,33,44,55];

The format has been chosen such that GAP can read the text file without modification.

## Functions
int | StfClose (StfData *f)
| Close a Structured Text File.
StfData * | StfOpen (const char *name, int mode)
| Open a Structured Text File.
int | StfReadLine (StfData *f)
| Read Next Line.
const char * | StfGetName (StfData *f)
| Get Entry Name.
int | StfGetInt (StfData *f, int *buf)
| Read an Integer.
int | StfGetString (StfData *f, char *buf, size_t bufsize)
| Read a string.
int | StfMatch (StfData *f, const char *pattern)
| Skip text.
int | StfGetVector (StfData *f, int *bufsize, int *buf)
| Read a vector.
int | StfPut (StfData *f, const char *text)
| Write a Raw Value.
int | StfPutInt (StfData *f, int value)
| Write an Integer.
int | StfPutString (StfData *f, const char *text)
| Write a String.
int | StfPutVector (StfData *f, int size, const int *value)
| Write a Vector.
int | StfBeginEntry (StfData *f, const char *name)
| Start a New Entry.
int | StfEndEntry (StfData *f)
| End Entry.
int | StfWriteValue (StfData *f, const char *name, const char *value)
| Write a String.
int | StfWriteString (StfData *f, const char *name, const char *value)
| Write a String.
int | StfWriteInt (StfData *f, const char *name, int value)
| Write an Integer.
int | StfWriteVector (StfData *f, const char *name, int size, const int *value)
| Write a Vector.

## Function Documentation

int StfBeginEntry | ( | StfData * | f,
|  | const char * | name
| ) |  |

Start a New Entry.

This function begins a new entry. Be sure to terminate any incomplete entries with StfEndEntry() before you start a new entry. If you don't, the incomplete entry may be lost, and the data file may become corrupted.

Before you use StfBeginEntry(), check if you can do the job with one of the StfWriteXXX() functions. In particular, there are functions to write integers and sequences of integers. If you have more complicated data to write, you may need to construct the output manually. Here is an example:

     StfBeginEntry(f,"Param");
     StfPut(f,"(");
     StfPutInt(f,11);
     StfPut(f,":");
     StfPutInt(f,22);
     StfPut(f,")");
     StfEndEntry(f);

This code produces the following line in the output file:

     Param := (11:22);

Parameters:

  f | Pointer to a structured text file (STF) object.
  name | Name of the entry.

Returns:
  0 on success, -1 on error.

int StfClose | ( | StfData * | f | ) |

Close a Structured Text File.

This function closes a structured text file. Closing the file implies that the memory occupied by the StfData structure is freed. Thus, after return, f is invalid and must not be dereferenced.

Parameters:

  f | Pointer to an open structured text file (STF) object.

Returns:
  0 on success, non-zero on error.

int StfEndEntry | ( | StfData * | f | ) |

End Entry.

This function terminates the current entry and flushes the STF's line buffer. See StfBeginEntry() for an example.

Parameters:

  f | Pointer to a structured text file (STF) object.

Returns:
  0 on success, -1 on error.

int StfGetInt | ( | StfData * | f,
|  | int * | buf
| ) |  |

Read an Integer.

This function gets one integer from the current line and increments the read pointer accordingly. Before this function is called, a line must have been read with StfReadLine() and prepared with StfGetName().

Reading starts at the current position. Any leading blanks are skipped. On return, the new current position is the character following the last digit. If there is no integer to read, the current position is not changed, and the function returns -1.

Here is an example:

     StfFile *f = StfOpen("test","r");
     int dim, degree, result = 0;
     while (result == 0 && StfReadLine(f) == 0)
     {
         char *name = StfGetName(f);
         if (!strcmp(name,"Dimension"))
             result = StfGetInt(f,&dim);
         else if (!strcmp(name,"Degree"))
             result = StfGetInt(f,&degree);
     }

This code fragment opens a text file and reads two parameters, "Degree" and "Dimension", into the variables `degree` and `dim`, respectively.

Parameters:

  f | Pointer to a structured text file (STF) object.
  buf | Pointer to a buffer receiving the value.

Returns:
  0 on success, -1 on error.

const char* StfGetName | ( | StfData * | f | ) |

Get Entry Name.

This function extracts the name part of internal line buffer and prepares the buffer for further parsing with StfGetXXX() functions. On return, `f->GetPtr` points to the first non-space character after the ":=". StfGetName() can be called only after a line was successfully read with StfReadLine(). It must be called before any of the StfGetXXX() functions. See StfGetInt() for an example.

Parameters:

  f | Pointer to a structured text file (STF) object.

Returns:
  Name found in text line or |NULL| on error.

int StfGetString | ( | StfData * | f,
|  | char * | buf,
|  | size_t | bufsize
| ) |  |

Read a string.

This function gets a string from the current line and increments the read pointer accordingly. Before this function is called, a line must have been read with StfReadLine() and prepared with StfGetName(). The string is expected at the current position of the test file and must be in C syntax, i.e., enclosed in double quotation marks.

Parameters:

  f | Pointer to a structured text file (STF) object.
  buf | Pointer to a buffer receiving the value.
  bufsize | Buffer size in bytes.

Returns:
  0 on success, -1 on error.

int StfGetVector | ( | StfData * | f,
|  | int * | bufsize,
|  | int * | buf
| ) |  |

Read a vector.

This function reads a sequence of integers. The sequence must have been written with StfWriteVector() or at least in the same format.

Before using this function, a line must have been read with StfReadLine() and prepared with StfGetname(). Reading starts at the current position, i.e., at the first non-space character after the ":=", or at the first character that was not read by the previous StfGetXXX() or StfMatch().

The caller must supply two buffers, the data buffer (buf) and an integer buffer (bufsize). When StfGetVector() is called, the variable pointed to by bufsize must contain the maximal number of integers that can be stored in buf. On successful return, the variable contains the number of integers that were actually stored, which may be smaller than the original value. If the vector is to long to fit into the user-supplied buffer, the function reads as many entries as possible and returns -1.

Here is an example:

     char *name = StfGetName(f);
     if (!strcmp(name,"Vector"))
     {
         int vec[10];
         int vecsize = 10;
         StfGetVector(f,&vecsize,vec);
         printf("%d elements read\n",*vecsize);
     }

Parameters:

  f | Pointer to a structured text file (STF) object.
  bufsize | Pointer to a variable containing the buffer size. On return, the variable contains the number of elements actually read.
  buf | Pointer to a buffer receiving the data.

Returns:
  The function returns $0$ on success and $-1$ on error.

int StfMatch | ( | StfData * | f,
|  | const char * | pattern
| ) |  |

Skip text.

This function reads (and skips) the text given by pattern. Before using this function, a line must have been read with StfReadLine() and prepared with StfGetname(). Reading starts at the current position, i.e., at the first non-space character after the ":=", or at the first character that was not read by the previous StfGetXXX() or StfMatch(). A space in pattern matches any number (including 0) of spaces or tabs. Any other characters in pattern are matched one-to-one against the input line. If pattern is matched completely, the current position is updated to the character after the last matched character. Otherwise, the current position is not changed and the function returns -1.

Parameters:

  f | Pointer to a structured text file (STF) object.
  pattern | The text to be skipped.

Returns:
  0, if the complete text in pattern has beed skipped. -1 otherwise.

StfData* StfOpen | ( | const char * | name,
|  | int | mode
| ) |  |

Open a Structured Text File.

This function opens a structured text file. It returns to a StfData structure which can be used with StfXXX() functions. name and mode have the same semantics as with SysFopen(). If the mode contains `FM_CREATE`, a new file is created and opened for writing, for example with StfWriteInt(). If a file with the specified name already exists, it is truncated to length zero. Otherwise, a new file is created.

The mode FM_READ opens the file for reading. If the file does not exist the function fails. FM_TEXT is always added implicitely to the mode.

Parameters:

  name | File name.
  mode | Open mode (see description).

Returns:
  StfData structure or 0 on error.

int StfReadLine | ( | StfData * | f | ) |

Read Next Line.

This function reads a single text line into the STF object's internal line buffer and prepares the text for parsing with StfGetXXX() functions. StfReadLine() strips comments and assembles multi-line texts into a single line. Thus, the application need not handle comments and multi-line texts.

Parameters:

  f | Pointer to a structured text file (STF) object.

Returns:
  0 on success, -1 on end-of-file or error.

int StfWriteInt | ( | StfData * | f,
|  | const char * | name,
|  | int | value
| ) |  |

Write an Integer.

This function writes an integer to a structured text file. For example, the statement

     StfWriteInt(f,"Dimension",42);

produces the following output line:

     Dimension := 42;

Parameters:

  f | Pointer to a structured text file (STF) object.
  name | Name of the entry.
  value | Value of the entry.

Returns:
  0 on success, -1 on error.

int StfWriteString | ( | StfData * | f,
|  | const char * | name,
|  | const char * | value
| ) |  |

Write a String.

Parameters:

  f | Pointer to a structured text file (STF) object.
  name | Name of the entry.
  value | String to write.

Returns:
  0 on success, -1 on error. This function writes an arbitrary string to a structured text file. For example, the statement

       StfWriteValue(f,"Title","This is a test ");

  produces the following output line:

       Title := "This is a test ";

  Unlike StrWriteValue() this function preserves leading and trailing spaces.

int StfWriteValue | ( | StfData * | f,
|  | const char * | name,
|  | const char * | value
| ) |  |

Write a String.

This function writes an arbitrary text to a structured text file. For example, the statement

     StfWriteValue(f,"Note","This is a note");

produces the following output line:

     Note := This is a note;

Note that any leading spaces in the value will be stripped off when reading the file.

Parameters:

  f | Pointer to a structured text file (STF) object.
  name | Name of the entry.
  value | Value of the entry.

Returns:
  0 on success, -1 on error.

int StfWriteVector | ( | StfData * | f,
|  | const char * | name,
|  | int | size,
|  | const int * | value
| ) |  |

Write a Vector.

This function writes a sequence of integers to a structured text file. For example, the statement

     int dims[5] = {11,22,33,44,55};
     StfWriteVector(f,"Dimensions",dims,5);

produces the following output line:

     Dimensions := [11,22,33,44,55];

Parameters:

  f | Pointer to a structured text file (STF) object.
  name | Name of the entry.
  size | Size of the vector (number of entries, not bytes).
  value | Pointer to the vector.

Returns:
  The function returns $0$ on success and $-1$ on error.