8. Package for work with command line

To make easy process of command line, here abstract data `commline' is suggested. This abstract data implements features analogous to ones of public domain function `getopt'. The goal of the abstract data creation is to use more readable language of command line description and to use command line description as help output of program.

POSIX terminology concerning command line is used here. Command line is divided into command name and arguments. The arguments are subdivided into options, option-arguments and operands. Option starts with `-'. All arguments after first `--' in command line are treated as operands.

The description of command line is made up from two parts. Any part (or both) may be absent in the description. First part contains option-arguments names of options which are in the second part. option-arguments names are separated by white space. The second part starts with percents `%%' and contains any text in which description of options are placed. Any description of option starts with character ``' followed by character `-' and finishes by character `''. White spaces may precede option-argument name. It means that the corresponding option has obligatory separate option-argument. For example, the following may be a part of description of options of a pascal compiler command line.

dir xxx file
%%
command line:  pc [options] file ... 
                               Options:
`-0'      Pascal standard level 0    `-1'      Pascal standard Level 1.
`-29000'  Am29000 code generation    `-29050'* Am29050 code generation
`-c'      only object files creation `-el'     output of listing
`-g'      information for debuggers  `-Idir'   data task units directory
`-lxxx'   library                    `-Ldir'   libraries directory
`-o file' output file                `-O'      all optimizations
`-S'      only ass. code creation    `-v'      loaded processes indication
`-w'      no warnings generation
               Star * marks defaults

In this example options with names `-I', `-l', `-L' and `-o' have option-arguments but only option with name `-o' has separate option-argument, i.e. option-argument which is represented by separate argument after given option in command line.

The interface part of the abstract data is file `commline.h'. The package uses package `vlobject' which use package `allocate'. The implementation part is file `commline.c'. The interface contains the following external definitions:

Function

          `int start_command_line_processing
               (int argc, char **argv, const char *description)'
          

must be called before any work with abstract data. The function processes command line description given as string parameter and command line itself given as two parameter `argc' and `argv'. The function also initiates variables `argument_vector' and `argument_count' by parameters `argc' and `argv'. The function returns 0 if error in command line description is fixed, otherwise returns 1 (it means success).

Function `output_command_line_description'

          `void output_command_line_description (void)'
          

outputs the second part (without `%%') of description of options to stderr. This function should be called when it is necessary to show the program usage.

Function `next_operand'

          `int next_operand (int flag_of_first)'
          

returns command line argument number of next operand if the function parameter is nonzero. Otherwise the function returns number of the first operand in the command line. The function returns 0 if all operands are already processed. Returned number may be used as index of array `argument_vector' to access corresponding operand.

Function `number_of_operands'

          `int number_of_operands (void)'
          

returns number of operands in the command line.

Function `next_option'

          `int next_option (int flag_of_first)'
          

returns command line argument number of next option if the function parameter is nonzero. Otherwise the function returns number of the first option in the command line. The function returns 0 if all options are already processed. Returned number may be used as index of array `argument_vector' to access corresponding option.

Function `option_characteristics'

          `char *option_characteristics (int argument_number,
                                         int *option_has_argument)'
          

returns pointer to option name which describes the command line argument with number `argument_number' given as the first parameter of the function. The function returns NULL if the corresponding option in the command line description is not found or an option described as with option-argument has not option-argument in the command line. Remember that option name with option-argument differs from option in the command line (e.g. `-U' and `-Ufoo'). If the option in the command line description is found than the function sets up correspondingly the second function parameter `option_has_argument'. The case of returned NULL and `*option_has_argument' equals to TRUE means that given option must have option-argument but the option has not option-argument in the command line.

Function `last_option_place'

          `int last_option_place (const char *option_name)'
          

returns number of last option with given option name in the command line. The function returns 0 if the option is absent in the command line.

Function `option_argument'

          `char *option_argument (const char *option_name)'
          

returns pointer to argument of last option in the command line with given option name. The function returns NULL if the option is absent in the command line. The function must be called only for options which have argument separated by white spaces.

Variables `argument_count', `argument_vector'

have analogous values as parameters `argc' and `argv' of function `main'. See also description of `start_command_line_processing'.