Skip to content

Specifications

Jump to bottom Edit New page
Renaud Guillard edited this page Jul 3, 2013 · 9 revisions

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](#Command line handling specifications)
    • Options
      • [Short option names](#Short option names)
      • [Long option names](#Long option names)
      • [Option name aliasing](#Option name aliasing)
      • Switches
      • [Single argument option](#Single argument option)
      • [Multiple arguments option](#Multiple arguments option)
      • [Option group](#Option group)
      • [Mutually exclusive option group](#Mutually exclusive option group)
    • [Sub command](#Sub command)
    • Markers
      • ['End-of-options' marker](#'End-of-options' marker)
      • ['End of arguments' marker](#'End of arguments' marker)
    • [Escaping and disambiguation](#Escaping and disambiguation)
      • [Argument validation](#Argument validation)
      • [Post processing phase](#Post processing phase)
    • [Error handling](#Error handling)
    • [See also](#See also)

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

#!bash
program_name -o

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

#!bash
program_name -o "option argument"

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

#!bash
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).

    #!bash 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 '--'

#!bash
program_name --option

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

#!bash
program_name --option "option argument"

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

#!bash
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).

#!bash
program --aliased-option subcommand --subcommand-option value1 value2

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

#!bash
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

eoo: A double hyphen-minus string '--' (without any other character) indicates that all subsequent command line arguments are positional arguments (values).

#!bash
program subcommand -a --option arg1 -- value1 --even-this-is-a-value

There is no exception to this behavior.

'End of arguments' marker

eoa: A single hyphen-minus character '-' (without any other character) tells the parser to stop considering the following command line arguments as arguments of the current multiple argument option.

#!bash
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).

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.

#!bash
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).

#!bash
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

  • The parser looks for missing required options (postproc-required) and report them as Error 6
  • 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)

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.

See also

  • (1): Not yet implemented in Shell and Python parser

The program interface definition framework

Add a custom footer
Add a custom sidebar
Clone this wiki locally