Command line parser generator (gargs) v1.2

Abstract

This document describes utility which may be used to automatically generate command line parser.

Contents

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

1. Introduction

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.

2. Command line

Syntax:

gargs [options] [file(s)]

Options:

-folog all messages in the file "gargs.out"
-helpshow the help information
-nologosuppress 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 *.atf
would process all description files with the mask *.atf, log all messages in the "gargs.out" and not display the program logo.

3. Parsing rules

3.1. General issues

The command line of an application is treated as a sequence of arguments separated by one or more spaces. An argument may denote:

  1. an option, if it starts with "-" or "/"
  2. a responce file, if it starts with "@"
  3. a file name, otherwise

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.

3.2. Options types

Three types of options are available:

  1. toggle (e.g., "-nologo")
  2. list (e.g., "-libs:math.lib,matrix.lib -libs=test.lib")
  3. single value (e.g., "-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.

3.3. Syntax summary

<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>'''

4. Options description

4.1. General issues

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> }

4.2. File names processing

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

4.3. Options types

As it was stated above, several types of command line options are supported. In the description it is designated by an option type:

  1. SIMPLE_SWITCH - toggle
  2. LIST_SWITCH [<value_type>] - list
  3. ONCE_SWITCH [<value_type>] - single value

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.

4.4. Option specification

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

5. Output Eiffel class

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.

5.1. Predefined features

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

5.2. Option features

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

6. Building user application

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.

7. Errors of the generator

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

8. Examples

See "Utility Arg_Msg" for details.


Copyright © Object Tools -- info@object-tools.com
Last updated: 2005/02/02 11:51:35