This document describes utility which may be used to automatically generate command line parser.
1. Introduction
2. Command line
3. Parsing rules
3.1. General issues
3.2. Options types
3.3. Syntax summary
4. Options description
4.1. General issues
4.2. File names processing
4.3. Options types
4.4. Option specification
5. Output Eiffel class
5.1. Predefined features
5.2. Option features
6. Building user application
7. Errors of the generator
8. Examples
The utility generates command line parser (in Eiffel) using the file which describes possible command line options and their values. The resulting Eiffel code (class OPTIONS_SERVER) is saved in the file "opt_ser.e". This class may be included into the Eiffel project and then used to process command line and to access to the specified options' values.
The GUI version of the program is also provided: dm_gargs.
Syntax:
gargs [options] [file(s)]
Options:
-fo | log all messages in the file "gargs.out" |
-help | show the help information |
-nologo | suppress logo |
File(s) - name(s) of the command line arguments description file(s). The multiple file names are allowed as well as wildcards in the file names.
Example.
The following command
gargs -nologo -fo *.atfwould process all description files with the mask
*.atf
,
log all messages in the "gargs.out" and not display the program logo.
The command line of an application is treated as a sequence of arguments separated by one or more spaces. An argument may denote:
-
" or "/
"@
"The option names may be considered to be case insensitive ("-A
" and
"-a
" denote the same option) or case sensitive ("-A
"
and "-a
" denote different options). This depends on the options
description.
Long file names and option values should be enclosed in double quotes to avoid
ambiguity. Quotes inside such literals should be written in the form \"
and \'
.
Responce file (if any) should be in the text form and it is used to specify options and files in the file in addition to command line. One option or file should be specified per one line of the responce file from the first position. Nested responce files are not allowed.
Three types of options are available:
-nologo
")-libs:math.lib,matrix.lib -libs=test.lib
")-target:console
", "-target=windows
")The toggle option, if specified, switches from default value "off" (False) to the value "on" (True).
The list option allows to specify multiple values by enumerating them in a list or by setting its value several times.
The single value option allows to specify not more than one value at a time.
<command_line> ::= { <option> | <responce_file> | <file_name> } <option> ::= <switch><option_spec> <switch> ::= '-' | '/' <option_spec> ::= <toggle_option> | <list_option> | <single_option> <toggle_option> ::= <option_name> <list_option> ::= <option_name><assignment><value>[','<value>] <single_option> ::= <option_name><assignment><value> <assignment> ::= ':' | '=' <option_name> ::= <string_literal> <value> ::= <string_literal> | <integer_literal> | <real_literal> | <char_literal> <responce_file> ::= '@'<file_name> <file_name> ::= <string_literal> <string_literal> ::= <string> | '"'<string>'"' <char_literal> ::= '''<character>'''
An option description file consists of two parts. The first part is optional. It starts with the word "options" and describes the way how the file names specified in the command line will be processed. The options should be delimited by at least one white space. The possible options are listed in section "File names processing".
The second part starts with the word "arguments" and serves to describe each option. One option description just follows another.
Thus the format of option description file is:
[ "options" <option> { <option> } ] "arguments" <argument_definition> { <argument_definition> }
The processing of the specified file names is controled by the following options:
expand_wildcards | allows to expand wildcards |
recursive_find | allows to search files in subdirectories |
name_with_directory | allows to use a file path instead of a file name |
include_directory | allows to include directories in the file list |
file_access | allows to leave in the list only existing files |
As it was stated above, several types of command line options are supported. In the description it is designated by an option type:
The possible type of option values is specified by <value_type> modifier:
<value_type> | option type | example |
---|---|---|
STRING | string | console, "win 32" |
INTEGER | integer | 1234, 0 |
CHARACTER | single character | 'Y', 'n' |
REAL | real number | 123.4, 1e2 |
FILE | file name | doc.txt, *.c, "long file name" |
The parser automatically checks whether the specified value of the option has a proper type and registers type violation as an error in the command line.
An option is specified in the description file as follows:
<option_name_in_program> ':' <option_type> '"'<option_name_in_command_line>'"' [ '{' <possible_value> { ',' <possible_value> } '}' ] [ '=' '(' <default_value> { ',' <default_value> } ')' ] [ '<' <option_modifier> { ',' <option_modifier> } '>' ]
where
<option_name_in_program> | indentifier of the option in the generated Eiffel program |
---|---|
<option_type> | type of the option (see "Option types" for details) |
<option_name_in_command_line> | literal representation of the option in the command line |
<possible_value> | possible value of the option argument (for LIST_SWITCH and ONCE_SWITCH); if at least one <possible_value> is specified, option value in the command line should be equal to the one of them |
<default_value> | the value of the option which it gets by default (i.e., when this option was not specified in the command line) |
<option_modifier> | one of the modifiers described in "File names processing" (affects only behaviour of options with FILE values) or "case_sensitive" which says that option name should be treated exactly as it is spelled |
If the generation completes without errors then the output file "opt_ser.e" with the Eiffel source code is produced. The name of the class is OPTIONS_SERVER.
Class OPTIONS_SERVER always provides the following features:
make -- creation routine, it initializes all -- attributes of the object has_error: BOOLEAN -- True if there is an error while -- processing command line, the feature -- "last_error" may be used to get -- the detailed information about the error last_error: ARG_ERROR -- contains a detailed description of the -- error -- feature "code" of this object -- returns the following error codes -- (declared in ARG_ERROR): -- unknown_swith_code - -- unknown option was specified in the command line -- invalid_value_code - -- specified option value does not correspond -- to the possible values of the option -- invalid_parameter_code - -- specified option value type does not correspond -- to the option type -- invalid_param_cnt_code - -- number of specified option values is wrong -- feature "name" returns name of the invalid option; -- feature "type" returns its type; -- feature "param" returns the number of the invalid parameter -- feature "out" returns printable error description file_list: ARRAY [STRING] -- list of file names specified in the command line files ( expand_wildcards: BOOLEAN; recursive_find: BOOLEAN; include_directory: BOOLEAN; name_with_directory: BOOLEAN; file_access: BOOLEAN ): ARRAY [STRING] -- returns a list of file names specified in the command line -- which was rebuilt accordingly to the new -- "File names processing" specification
Class OPTIONS_SERVER will have attributes with names <option_name_in_program> as it described above. These attributes will get the value corresponding to the option values specified in the command line. Type of the attribute depends on the option type:
SIMPLE_SWITCH | BOOLEAN |
LIST_SWITCH [<value_type>] | ARRAY [<value_type_spec>] |
ONCE_SWITCH [<value_type>] | <value_type_spec> |
The correspondance between <value_type> and <value_type_spec> is shown below:
<value_type> | <value_type_spec> |
---|---|
STRING | STRING |
INTEGER | INTEGER |
CHARACTER | CHARACTER |
REAL | REAL |
FILE | STRING |
In order use the generated command line parser, it's necessary to put the generated file "opt_ser.e" into the directory which contains a cluster from your project.
The generator may produce the following errors:
GA1 | Can not open file '<file_name>' |
---|---|
GA2 | Expected symbol '<symbol>' at position ['<line>':'<pos>'] |
GA3 | Option identifier is not consistent with the rules for Eiffel identifiers |
GA4 | Invalid option type |
GA5 | Option identifier is repeated twice or more |
GA6 | Option name is repeated twice or more |
GA7 | Invalid option value type specified for the given option type |
GA8 | This word cannot be used as an option identifier because it is reserved |
GA9 | Possible values list contains invalid value which is not appropriate for the given option type |
GA10 | Default values list contains invalid value which is not appropriate for the given option type, does not correspond to specified possible values or has several entries for option of ONCE_SWITCH type |
GA11 | Description file is empty |
GA12 | Option name is expected at that position |
GA13 | Option modifiers list contains an invalid entry (unknown or not appropriate for the given option type) |
GAU01 | Invalid command line arguments for the program are specified |
GAU02 | No files were specified for processing |
See "Utility Arg_Msg" for details.