A couple of functions declared in cmdline.h can be used to do all the necessary parsing of command lines and environment variables needed by virtual code applications.
The purpose of this function is to build most of the data structure used by parameter mode applications, as described in Input Data Structure, by parsing the command line according to Command Line Syntax. The parameters have these interpretations.
- argc
- is the number elements in the array referenced by argv
- argv
- is the address of an array of pointers to null terminated character strings holding command line arguments
- index
- is the position of the first element of argv to be considered. Those preceding it are ignored.
- extension
- is the address of a string that will be appended to input file names given in argv in an effort to find the associated files
- paths
- is the address of a null terminated character string containing a colon separated list of directory names that will be searched for input files
- default_to_stdin_mode
- is set to a non-zero value by the caller if the contents of standard input should be read in the absence of input files
- force_text_input_mode
- is set to a non-zero value by the caller to indicate that input files should be read as text, using
avm_load
(rather thanavm_preamble_and_contents
, which would allow them to be either text or data). The preamble field of the returned file specifications will always be empty when this flag is set.- file_ordinal
- is set to a pointer to an integer by the caller if only one file is to be loaded during each call. The value of the integer indicates the which one it will be.
The result returned by this function is a list whose
head
is a list of file specifications and whosetail
is a list of command line options intended for input to a virtual code application.The list of file specifications returned in the
head
of the result follows the same conventions as the data parameter to the functionavm_output_as_directed
, except that thehead
of thehead
of each item is a list representing the time stamp of the file as given byavm_date_representation
. If the file is standard input, then it holds the current system date and time.If the file_ordinal parameter is
NULL
, then all files on the command line are loaded, but if it points to an integer n, then only the nth file is loaded, and n is incremented. If there is no nth file, aNULL
value is returned as the entire result of the function. For a series of calls, the integer should be initialized to zero by the caller before the first call.If standard input is indicated as one of the files on the command line (by a dash), then it is also loaded regardless of the file_ordinal, but a cached copy of it is used on subsequent calls after the first, so that the function does not actually attempt to reread it. If standard input is to be loaded, it must be finite for this function to work properly.
The search strategy for files is described in Environment, and makes use of the extension and paths parameters.
In the list of command line options returned in the
tail
of the result, each item is a list with a non-emptyhead
andtail
, and is interpreted as follows.
- The
head
of thehead
is a list representing a natural number, as given byavm_natural
, indicating the position of the option on the command line relative to the initial value of the index parameter.- The
tail
of thehead
is a list which isNULL
in the case of a “short form” option, written with a single dash on the command line, but is a list whosehead
andtail
areNULL
in the case of a “long form” option, written with two dashes.- The
head
of thetail
is a list representing a character string for the keyword of an option, for example foo in the case of an option written --foo=bar,baz.- The
tail
of thetail
is a list of lists representing character strings, with one item for each parameter associated with the option, for example, bar and baz.If multiple calls to the function are made with differing values of
*
file_ordinal but other parameters unchanged, the same list of options will be returned each time, except insofar as the position numbers in thehead
of thehead
of each item are adjusted as explained in Input for Mapped Applications.Any of the i/o errors or fatal errors associated with other file input operations are possible with this function as well. This non-fatal warning message is also possible.
program-name: warning: search paths not supported
This error occurs if the library has been built on a platform that doesn't have the argz.h header file and the paths parameter is non-
NULL
.
This function takes the address of a null terminated array of pointers to null terminated character strings of the form
"variable=value"
. The result returned is a list of lists, with one item for each element of the array. Thehead
of each item is a representation of the left side of the corresponding string, and thetail
is a representation of the right.This function is therefore useful along with
avm_default_command_line
for building the remainder of the data structure described in Parameter Mode Interface. For example, a virtual machine emulator for non-interactive parameter mode applications with no bells and whistles could have the following form.int main(argc,argv,env) ... { FILE *virtual_code_file; ... avm_initialize_lists(); avm_initialize_apply(); avm_initialize_rawio(); avm_initialize_formout(); avm_initialize_cmdline(); virtual_code_file = fopen(argv[1],"rb"); operator = avm_received_list( virtual_code_file,argv[1]); fclose(virtual_code_file); command = avm_default_command_line(argc, argv,2,NULL,NULL,0,0,NULL); environs = avm_environment(env); operand = avm_join(command,environs); result = avm_apply(operator,operand); avm_output_as_directed(result,0,0); avm_dispose(result); ... }The
avm_environment
function could cause the program to abort due to a memory overflow. For security reasons, it will also abort with an error message if any non-printing characters are detected in its argument. (See Other Diagnostics and Warnings.)