3.3.3 Formatted Input

Some functions relating to the input of text files or data files with preambles are declared in the header file ‘formin.h’. The usage of these functions is as follows.

Function: list avm_preamble_and_contents (FILE *source, char *filename)

This function loads a file of either text or data format into memory.

source

should be initialized by the caller as the address of a file already open for reading that will be read from its current position.

filename

should be set by the caller to the address of a null terminated character string giving the name of the file that will be used if an i/o error message needs to be written about it. If it is a NULL pointer, standard input is assumed.

The result returned by the function will be a list whose head represents the preamble of the file and whose tail represents the contents. As a side effect, the input file will be closed, unless the filename parameter is NULL.

If the file conforms to the format described in File Format, the preamble is a list of character strings. In the result returned by the function, the head field will be a list with one item for each line in the file, and each item will be a list of character representations as in Character Table, but with the leading hashes stripped. The tail will be the list specified by remainder of the file according to Concrete Syntax. If the file has an empty preamble but is nevertheless a data file, the head will be a list whose head and tail are both NULL.

If the file does not conform to the format in File Format, then the head of the result will be NULL, and the tail will be a list of lists of character representations, with one for each line.

Whether or not the file conforms to the format is determined on the fly, so this function is useful for situations in which the format is not known in advance. The conventions regarding the preamble and contents maintained by this function are the same as those used by virtual code applications as described in Standard Output Representation and Input Data Structure.

The characters used for line breaks are not explicitly represented in the result. Depending on the host system, line breaks in text files may be represented either by the character code 10, or by the sequence 13 10. However, in order for the library to deal with binary files in a portable way, a line break always corresponds to a 10 as far as this function is concerned regardless of the host, and a 13 is treated like any other character. Hence, if this function were used on binary files that happened to have some 10s in them, the exact contents of a file could be reconstructed easily by appending a 10 to all but the last line and flattening the list.

A considerable amount of memory may need to be allocated by this function in order to store the file as a list. If not enough memory is available, the function prints an error message to standard error and aborts rather than returning to the caller. However, i/o errors are not fatal, and will cause the function to print a warning but attempt to continue.

Function: list avm_load (FILE *source, char *filename, int raw)

Similarly to avm_preamble_and_contents, this function also loads a file into memory, but the format is specified in advance.

source

should be set by the caller to the address of an already open file for reading, which will be read from its current position.

filename

should be initialized by the caller as a pointer to a null terminated string containing the name of the file that will be reported to the user in the event of an error reading from it. If it is a NULL pointer, standard input is assumed.

raw

is set to a non-zero value by the caller to indicate that the file is expected to conform to the format in File Format. If the file is an ordinary text file, then it should be set to zero.

In the case of a data file, which is when raw is non-zero, the result returned by this function will be a list representing the data section of the file and ignoring the preamble. In the case of a text file, the result will be a list of lists of character representations as per Character Table, with one such list for each line in the file. Similar comments about line breaks to those mentioned under avm_preamble_and_contents are applicable.

As a side effect of this function, the source file will be closed, unless the filename is a NULL pointer.

This function is useful when the type of file is known in advance. If a data file is indicated by the raw parameter but the format is incorrect, an error message is reported and the process terminates. The error message will be of the form

program-name: invalid raw file format in filename

Alternatively, if a text file is indicated by the raw parameter, then no attempt is made to test whether it could be interpreted as data, even if it could be. This behavior differs from that of avm_preamble_and_contents, where a bad data file format causes the file to be treated as text, and a valid data file format, even in a “text” file, causes it to be treated as data.

Memory requirements for this function are significant and will cause the process to abort with an error message in the event of insufficient free memory. Messages pertaining to i/o errors are also possible and are not fatal.

Function: void avm_initialize_formin ()

This function should be called before either of the other functions in this section is called, as it initializes some necessary static data structures. Results of the other functions are undefined if this one is not called first.

Function: void avm_count_formin ()

This function should be called after the last call to any of the other functions in this section, as it is necessary for cleaning up and reclaiming some internal data. If any storage remains unreclaimed due to memory leaks in these functions or to misuse of them, a warning message is written to standard error. If the function avm_count_lists is also being used by the client program, it should be called after this one.

This document was generated on December 10, 2012 using texi2html 1.82.