Command line handling specifications

This page details the supported features and expected behaviors of the command line parsers implemented in this project.

For a synthesis of what is currently supported in the different parsers, see the specification compliance page.

The words written in bold-monospace are keywords to identify a feature, a behavior or a parser message. These keywords are used as references in the specification compliance page and in unit tests.

Command line handling specifications

Options

Short option names

A short option name (son) is an option name of only one character. On the command line, it have to be prefixed by a single hyphen-minus character '-'

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					program_name -o
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																				

For single and multiple arguments options, the first option argument can be the next command line argument (son-arg-separated)

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					program_name -o "option argument"
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																				

or can be combined to the option letter (son-arg-combined)

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					program_name -oArgumentWithoutSpace
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						program_name -o"Argument With Space"

Several short option names can be combined as their associated options are switches (son-combined).
The last letter used may reference a single or multi argument option (son-combined-arg-at-last).

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						rsync -lprtve bash
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					

see man rsync

Long option names

A long option name (lon) is an option name of two or more characters. On the command line, it have to be prefixed by a double hyphen-minus character '--'

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						program_name --option
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					

For single and multiple arguments options, the first option argument can be the next command line argumen (lon-separated)t

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						program_name --option "option argument"
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					

or can be combined to the option name after a equal sign '=' (lon-combined)

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						program_name --option=ArgumentWithoutSpace
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program_name --option="Argument With Space"

Option name aliasing

The program interface definition XSD scheam requires the following rules:

Program-scope option names have to be unique
Subcommand-scope option names have to be unique in the subcommand

So, a subcommand option name may alias a program-scope option name (on-aliasing).

In this case, the option will be interpreted as the program-scope option if it appears before the subcommand name (on-aliasing-before-sc).

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program --aliased-option subcommand --subcommand-option value1 value2
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						

Or as the subcommand option if it appears after the subcommand name (on-aliasing-after-sc).

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program subcommand --aliased-option --subcommand-option value1 value2
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						

Switches

The switch option value is true if the switch appears at least once on the command line. Otherwise, the option value is false.
Combining an argument with a switch long option name is not authorized (Error 13)

Single argument option

The command line argument following an single argument option (sarg) name is always considered as the argument of this option unless
- it is the end-of-options (eoo) marker (double hyphen-minus character '--'). In this case, an error is emitted (Error 3).
- the option argument is combined to the option name (-aValue or --arg=Value).

Multiple arguments option

All arguments of a multiple argument option (marg) have the same type interpretation.
The command line argument following a multi argument option is always considered as an argument of this option unless
- it is the end-of-options (eoa) marker (double hyphen-minus character '--'). In this case, an error is emitted (Error 3).
- an argument is combined to the option name.
After the first argument, all subsequent command line arguments are considered as arguments of the current option until
- a new option name marker is found (marg-arg-stop-at-on)
- a end-of-options (eoo) marker (double hyphen-minus string '--') is found
- a end-of-arguments (eoa) marker (single hyphen-minus string '-') is found
- the maximum argument count of the option is reached (marg-max-rule)
If an argument does not validates against type or argument value rules, the argument is still counted as one of the option arguments but takes a null value (marg-invalid-arg-null). So, It will affect the maximum number of argument rule.
If a multiple argument option appears multiple times on the command line. The new arguments are appended (marg-arg-append)
Minimum and maximum argument count rules are checked after all command line arguments were parsed (marg-minmax-postproc)

Option group

A option group (grp) offers a way to group several related option. This kind of option does not have any particular meaning for a command line parser unless the group is set as a mutually exclusive option group (xgrp)

Option group may contains sub groups (grp-subgrp)
When an option is present (and valid) on the command line, all its parent groups are also present (grp-set-cascade).

Mutually exclusive option group

An option group defined as exclusive adds the following rules

Two options of the exclusive same group cannot appear at the same time on the command line (xgrp-mutex)
The same option, part of a mutually exclusive option group, may appears multiple time on the command line (xgrp-same-option).
If an option is rejected due to mutual exclusion rule, it will be parsed as it will be accepted but will not be marked as set and its possible argument(s) will finally be ignored (parse-unexpected-option).

Sub command

A sub command name must appear as the first positional argument of the command line (sc-name). Otherwise it will be considered as a positional argument of the program.
Parsers always reports the active sub command by its main name, even if it is one of the subcommand aliases that was used on the command line (sc-alias-name).

Markers

Markers are special command line arguments that change the parser behavior. They does not appear in positional argument (value) list nor in single/multiple argument option argument list.

'End-of-options' marker

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program subcommand -a --option arg1 -- value1 --even-this-is-a-value
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						

There is no exception to this behavior.

'End of arguments' marker

to stop considering the following command line arguments as arguments of the current multiple argument option.

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program subcommand --multiarg-option arg1 arg2 - value1 value2
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						

This marker has no particular meaning in another context (eoa-outofcontext) and should be considered as option argument or positional argument.
It will be ignored if it appears just after the multi-argument option name (eoa-firstarg-exception).

String literals

The program interface definition file is language-independent, so string literals specified in node such as <prg:documentation />, <prg:default /> and <prg:option/> will not be evaluated even if the language allow this feature.

For example, specifying <prg:default>$(pwd)</prg:default> as the default value of a single argument option will NOT be dynamically evaluated by a UNIX shell program.

Escaping and disambiguation

If a positional argument is not an option but starts with a hyphen-minus character, the positional argument will be misinterpreted as an option name.

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program subcommand --switch-option -positional_argument_which_is_not_an_option
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																						

To avoid this invalid behavior, the hyphen-minus character have to be escaped by the user using the backslash character (escape-markers).

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							program subcommand --switch-option \\-positional_argument_which_is_not_an_option
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																							
# or
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																								
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																									program subcommand --switch-option "\-positional_argument_which_is_not_an_option"

The following markers can be escaped

End-of-arguments (escape-eoa)
End-of-options (escape-eoo)
Short option names (escape-son)
Long option names (escape-lon)

The parser will have to unescape (escape-unescape) any command line argument starting with '\-" before storing it as an option argument or a positional argument. In the example above, the second argument of the command line will have to be interpreted as the positional argument '-positional_argument_which_is_not_an_option'

Argument validation

The parser always checks all arguments validation rules of the current option (parse-call-all-validators). So, a validation failure of one rule should not ends the validation process

Post processing phase

If a single argument option was not present on the command line and if it defines a default value and if setting this option does not break a mutual exclusion rule, then the option is set with the default value (postproc-sarg-default).
Check multiple argument option minimum and maximum argument count rules (postproc-marg-minmax)
Options which does not validate one of the post-processing rules above are reseted to their default state (postproc-unset-option)
The parser looks for missing required options (postproc-required) and report them as Error 4, Error 5 or Error 6 (depending on option type)
- except¹ if the required option is part of a exclusive group which is not set or set by another option of the group (postproc-required-in-xgrp)

Error handling

The general behavior of command line parsers is to go as far as they can to provide as much informations as possible to the user in case of error.