2.6.2 Input for Mapped Applications

Applications invoked using the --map-to-each-file option benefit from a slightly different interface than the one described above. As the purpose of this option is to save memory by loading only one file at a time, the application does not have access to all input files named on the command line simultaneously within the same data structure. Although the data structure is of the type already described, the files field is not a list of arbitrary length. Instead, it is a list containing exactly one item for an input file. If - is used as a command line parameter, indicating standard input, then files will have another item pertaining to standard input. In no event will it have other than one or two items.

The mapped application is expected to work by being applied individually to each of any number of separately constructed data structures, doing the same in each case as it would if that case were the only one. To make that possible, copies of the environment variables, the contents of standard input, and the list of application specific options are contained in the data structure used for every invocation.

The position numbers in the options are adjusted for each invocation to reflect the position of the particular input file associated with it. For example, in the following command

     avram --map-to-each-file mapster.avm fa.txt --data fb.dat --code fc.o

the function in the virtual code file mapster.avm would be applied to each of three data structures, corresponding to the commands

     avram mapster.avm fa.txt --data --code
     avram mapster.avm --data fb.dat --code
     avram mapster.avm --data --code fc.o

If the relative positions of the options and filenames were important to the application, they could be reliably inferred from the position numbers. In the first case, they would be 1 and 2, implying that the file is in position 0. In the second case they would be 0 and 2, implying that the file is in position 1, and in the third case they would be 0 and 1, implying that the file is in position 2. (Of course, nothing compels an application to concern itself with the positions of its parameters, and the alternative might be preferable.)

For the most part, any application that can operate on one file at a time without needing information from any others can be executed more economically with the --map-to-each-file option and few if any changes to the code. The effect will normally be analogous to the above example, subject to a few possible differences.

• If an application is supposed to do something by default when there are no file parameters or only standard input, it won't work as a mapped application, because if there are no file parameters it won't be executed at all.
• If a mapped application causes any output files to be generated, they may be written before other input files are read, possibly causing the input files to be overwritten if they have the same names, and causing subsequent invocations to use the overwritten versions. This behavior differs from that of loading all input files at the outset, which ensures the application seeing all of the original versions. The latter may be more convenient for maintaining a group of files in some sort of consistent state.
• If an application causes standard output to be written along with output files, normally standard output is written last as a security measure against malicious code altering the --ask-to-overwrite prompts by subtly clobbering the console. In a mapped application, standard output isn't always last because there may be more invocations to come.