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.

Data Structures
struct	StfData
	Structured text file. More...

Functions
int	StfClose (StfData *f)
	Close a Structured Text File. More...
StfData *	StfOpen (const char *name, int mode)
	Open a Structured Text File. More...
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. More...
int	StfEndEntry (StfData *f)
	End Entry. More...
int	StfWriteValue (StfData *f, const char *name, const char *value)
	Write a String. More...
int	StfWriteInt (StfData *f, const char *name, int value)
	Write an Integer. More...
int	StfWriteString (StfData *f, const char *name, const char *value)
	Write a String. More...
int	StfWriteVector (StfData *f, const char *name, int size, const int *value)
	Write a Vector. More...
int	StfReadLine (StfData *f)
	Read Next Line. More...
const char *	StfGetName (StfData *f)
	Get Entry Name. More...
int	StfGetInt (StfData *f, int *buf)
	Read an Integer. More...
int	StfGetString (StfData *f, char *buf, size_t bufsize)
	Read a string. More...
int	StfMatch (StfData *f, const char *pattern)
	Skip text. More...
int	StfGetVector (StfData *f, int *bufsize, int *buf)
	Read a vector. More...

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.