3.3.4 Formatted Output

The following functions pertaining to the output of text files or data files with preambles are declared in the header file ‘formout.h’.

Function: void avm_output (FILE *repository, char *filename, list preamble, list contents, int trace_mode)

This function writes a either a text file or a data file in the format described in File Format. The parameters have these interpretations.

repository

is the address of a file opened for writing by the caller, that will be written from its current position.

filename

is the address of a null terminated character string set by the caller to be the name of the file that will be reported to the user in the event of an i/o error.

preamble

is NULL in the case of a text file, but a list of character string representations as per Character Table, in the case of a data file. If a data file has is to be written with an empty preamble, then this list should have a NULL head and a NULL tail.

contents

is either a list of character string representations in the case of a text file, or is an unconstrained list in the case of a data file.

trace_mode

may be set to a non-zero value by the caller to request that everything written to a text file should be echoed to standard output. It is ignored in the case of a data file.

The effect of calling this function is to write the preamble and contents to the file in the format indicated by the preamble. The file is left open when this function returns.

Line breaks are always written as character code 10, not as 13 10, regardless of the convention on the host system, so that files written by this function can be reliably read by other functions in the library.

Leading hashes are automatically added to the beginning of the lines in the preamble, except where they are unnecessary due to a continuation character on the previous line. This action enforces consistency with the file format, ensuring that anything written as a data file can be read back as one. The hashes are stripped automatically when the file is read by avm_preamble_and_contents.

Another feature of this function is that it will mark any output file as executable if it is a data format file with a prelude whose first character in the first line is an exclamation point. This feature makes it easier for a compiler implemented in virtual code to generate executable shell scripts directly.

A fatal error is reported if any of the data required to be a character representation is not listed in the Character Table. A fatal error can also be caused by a memory overflow. Possible error messages are the following.

• program-name: invalid output preamble format
• program-name: invalid text format
• program-name: can't write to filename

In the last case, the error message will be followed by an explanation furnished by the standard strerror function if available.

Function: void avm_output_as_directed (list data, int ask_to_overwrite_mode, int verbose_mode)

This function writes an ensemble of files at specified paths in either text or data format, optionally interacting with the user through standard input and output. The parameters have these interpretations.

data

is a list in which each item specifies a file to be written.

ask_to_overwrite_mode

may be set to a non-zero value by the calling program in order to have this function ask the user for permission to overwrite existing files.

verbose_mode

may be set to a non-zero value by the calling program to have this function print to standard output a list of the names of the files it writes.

A high level interface between virtual code applications and the file system is provided by this function. The data parameter format is compatible with the the data structure returned by an application complying with the conventions in Output From Non-interactive Applications.

Each item in the data list should be a non-empty list whose head and tail are also non-empty. The fields in each item have the following relevance to the file it specifies.

• The head of the head is NULL if the file is to be opened for appending, and non-NULL if it is to be overwritten.
• The tail of the head represents a path as a list of character string representations, in a form suitable as an argument to avm_path_name.
• The head of the tail represents the preamble of the file, as either NULL for a text file or a non-empty list of character string representations for a data file.
• The tail of the tail represents the contents of the file, either as a list of character string representations for a text file or as a list in an unconstrained format for a data file.

For each item in the list, the function performs the following steps.

1. It decides whether to open a file for overwriting or appending based on the head of the head.
2. It uses the tail of the head to find out the file name from avm_path_name, in order to open it.
3. If the ask_to_overwrite_mode flag is set and the file is found to exist already, the function will print one of the following messages to standard output, depending on whether the file is to be overwritten or appended.
   • program-name: overwrite filename? (y/n)
   • program-name: append to filename? (y/n)

   It will then insist on either y or n as an answer before continuing.

4. If the ask_to_overwrite flag has not been set, or the file did not previously exist, or the answer of y was given, the preamble and contents of the file are then written with avm_output.
5. If permission to write or append was denied, one of the following messages is reported to standard output, and the data that were to be written are lost.
   • program-name: not writing filename
   • program-name: not appending filename
6. If permission was granted to write or append to the file or the verbose_mode flag is set, one of the messages
   • program-name: writing filename
   • program-name: appending filename

   is sent to standard output.

If any files are to be written to standard output, which would be indicated by a NULL path, they are not written until all other files in the list are written. This feature is in the interest of security, as it makes it more difficult for malicious or inept virtual code to alter the appearance of the console through standard output until after the interactive dialogue has taken place. Permission is not solicited for writing to standard output, and it will not be closed.

Any of the fatal errors or i/o errors possible with avm_output or avm_path_name are also possible with this function, as well as the following additional ones.

• program-name: invalid file specification
• program-name: can't close filename
• program-name: can't write filename

The last two are non-fatal i/o errors that will be accompanied by an explanation from the strerror function if the host supports it. The other message is the result of a badly formatted data parameter.

Function: void avm_put_bytes (list bytes)

This function takes a list of character representations, converts them to characters, and sends them to standard output. There is no chance of a memory overflow, but the following other errors are possible.

• program-name: invalid text format (code nn)
• program-name: can't write to standard output

The latter is non-fatal, but the former causes the program to abort. It is caused when any member of the list bytes is not a character representation appearing in Character Table.

Function: void avm_initialize_formout ()

This function initializes some data structures used locally by the other functions in this section, and should be called at the beginning of a run before any of them is called.

Function: void avm_count_formout ()

This function doesn’t do anything in the current version of the library, but should be called after the last call to any of the other functions in this section. Future versions of the library might use this function for cleaning up some internal data structures, and client programs that call it will maintain compatibility with them.

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