2.5.1.1 Standard Input Representation

The representation for the standard input file used as the argument to the function depends both on the file format and on the command line options specified when the application is invoked. The ‘--unparameterized’ and ‘--raw-output’ options make no difference to the input representation, and the ‘--line-map’ and ‘--byte-transducer’ options are not relevant to this mode of operation. That leaves four possible combined settings of the ‘--choice-of-output’ and ‘--force-text-input’ options. If standard input conforms to the data file format specification File Format, the following effects are possible.

• If neither ‘--choice-of-output’ nor ‘--force-text-input’ is used, the argument to the function will be given directly by the tree encoded in the data section of the file. The preamble of the file will be ignored.
• If the ‘--choice-of-output’ option is used and the ‘--force-text-input’ option is not used, the argument to the function will be a pair (preamble,contents), where preamble is a list of character strings taken from the preamble of the file (with leading hashes stripped), and contents is the tree represented in the data section of the file.
• If the ‘--choice-of-output’ option is not used and the ‘--force-text-input’ option is used, the argument to the function will be the whole file as a list of character strings. I.e., both the preamble and the data sections are included, hashes are not stripped from the preamble, and the data section is not converted to the tree it represents.
• If the ‘--choice-of-output’ option is used and the ‘--force-text-input’ option is also used, the argument to the the function will be a pair (nil,contents), where the contents are the list of character strings as in the previous case.

If standard input does not conform to the data file format specification in File Format, then it is assumed to be a text file. The ‘--force-text-input’ option makes no difference, and there are only two possible effects, depending on whether ‘--choice-of-output’ is used. They correspond to the latter two cases above, where ‘--force-text-input’ is used.

The idea of the ‘--choice-of-output’ option is that it is used only for applications that are smart enough to be aware of the (preamble,contents) convention. A non-empty preamble implies a data file whose contents could be any type, but an empty preamble implies a text file whose contents can only be a list of character strings. (In the case of a data file with no preamble, the list of the empty string is used for the preamble to distinguish it from a text file.)

Dumb applications that never want to deal with anything but text files should be invoked with ‘--force-text-input’. Otherwise, they have to be prepared for either text or data as arguments.

The use of both options at once is unproductive as far as the input format is concerned, but may be justified when the output is to be a data file and the input is text only.

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