For tools evaluating a command without sub commands the most general form of invocation is:
tool [OPTION]… [ARG]…
The tool automatically reponds to the
--help option by printing the help. If a version string is provided in the command information, it also automatically responds to the
--version option by printing this string on standard output.
Command line arguments are either optional or positional. Both can be freely interleaved but since
Cmdliner accepts many optional forms this may result in ambiguities. The special token
-- can be used to resolve them; anything that follows it is treated as a positional argument.
Tools evaluating commands with sub commands have this form of invocation
tool [COMMAND]… [OPTION]… [ARG]…
Commands automatically respond to the
--help option by printing their help. The sequence of
COMMAND strings must be the first strings following the tool name – as soon as an optional argument is seen the search for a sub command stops. Command names may be specified by a prefixe as long as they are not ambiguous.
An optional argument is specified on the command line by a name possibly followed by a value.
The name of an option can be short or long.
More than one name may refer to the same optional argument. For example in a given program the names
--silent may all stand for the same boolean argument indicating the program to be quiet. Long names can be specified by any non ambiguous prefix.
The value of an option can be specified in three different ways.
Glued forms are especially useful if the value itself starts with a dash as is the case for negative numbers,
Short flags can be grouped together to share a single dash and the group can end with a short option. For example assuming
-x are flags and
-f is a short option:
-vx will be parsed as
-vxfopt will be parsed as
-v -x -fopt.
-vxf opt will be parsed as
-v -x -fopt.
-fvx will be parsed as
Positional arguments are tokens on the command line that are not option names and are not the value of an optional argument. They are numbered from left to right starting with zero.
Since positional arguments may be mistaken as the optional value of an optional argument or they may need to look like option names, anything that follows the special token
"--" on the command line is considered to be a positional argument:
tool --option -- we -are --all positional --argu=ments
Non-required command line arguments can be backed up by an environment variable. If the argument is absent from the command line and that the environment variable is defined, its value is parsed using the argument converter and defines the value of the argument.
Using the cmdliner library puts the following constraints o
--cmdliner is reserved by the library.
--version if you specify a version string) is reserved by the library. Using it as a term or option name may result in undefined behaviour.