A.31.1 Notes and tips

• In the example we were mostly explicit about the types. Since the default is term, which subsumes integer, float, atom, it may be possible to get away cheaper (e.g., by only giving booleans). However, it is recommended practice to always specify types: parsing becomes more reliable and error messages will be easier to interpret.
• Note that -sbar is taken to mean -s bar, not -s -b -a -r, that is, there is no clustering of flags.
• -s=foo is disallowed. The rationale is that although some command-line parsers will silently interpret this as -s =foo, this is very seldom what you want. To have an option argument start with’=' (very un-recommended), say so explicitly.
• The example specifies the option depth twice: once as -d5 and once as --iters 7. The default when encountering duplicated flags is to keeplast (this behaviour can be controlled, by ParseOption duplicated_flags).
• The order of the options returned by the parsing functions is the same as given on the command line, with non-overridden defaults prepended and duplicates removed as in previous item. You should not rely on this, however.
• Unknown flags (not appearing in OptsSpec) will throw errors. This is usually a Good Thing. Sometimes, however, you may wish to pass along flags to an external program (say, one called by shell/2), and it means duplicated effort and a maintenance headache to have to specify all possible flags for the external program explicitly (if it even can be done). On the other hand, simply taking all unknown flags as valid makes error checking much less efficient and identification of positional arguments uncertain. A better solution is to collect all arguments intended for passing along to an indirectly called program as a single argument, probably as an atom (if you don't need to inspect them first) or as a prolog term (if you do).

[det]opt_arguments(+OptsSpec, -Opts, -PositionalArgs)

Extract commandline options according to a specification. Convenience predicate, assuming that command-line arguments can be accessed by current_prolog_flag/2 (as in swi-prolog). For other access mechanisms and/or more control, get the args and pass them as a list of atoms to opt_parse/4 or opt_parse/5 instead.

Opts is a list of parsed options in the form Key(Value). Dashed args not in OptsSpec are not permitted and will raise error (see tip on how to pass unknown flags in the module description). PositionalArgs are the remaining non-dashed args after each flag has taken its argument (filling in true or false for booleans). There are no restrictions on non-dashed arguments and they may go anywhere (although it is good practice to put them last). Any leading arguments for the runtime (up to and including’--') are discarded.

[det]opt_parse(+OptsSpec, +ApplArgs, -Opts, -PositionalArgs)

Equivalent to opt_parse(OptsSpec, ApplArgs, Opts, PositionalArgs, []).

[det]opt_parse(+OptsSpec, +ApplArgs, -Opts, -PositionalArgs, +ParseOptions)

Parse the arguments Args (as list of atoms) according to OptsSpec. Any runtime arguments (typically terminated by’--') are assumed to be removed already.

Opts is a list of parsed options in the form Key(Value), or (with the option functor(Func) given) in the form Func(Key, Value). Dashed args not in OptsSpec are not permitted and will raise error (see tip on how to pass unknown flags in the module description). PositionalArgs are the remaining non-dashed args after each flag has taken its argument (filling in true or false for booleans). There are no restrictions on non-dashed arguments and they may go anywhere (although it is good practice to put them last). ParseOptions are

output_functor(Func)

Set the functor Func of the returned options Func(Key,Value). Default is the special value’OPTION' (upper-case), which makes the returned options have form Key(Value).

duplicated_flags(Keep)

Controls how to handle options given more than once on the commad line. Keep is one of keepfirst, keeplast, keepall with the obvious meaning. Default is keeplast.

allow_empty_flag_spec(Bool)

If true (default), a flag specification is not required (it is allowed that both shortflags and longflags be either [] or absent). Flagless options cannot be manipulated from the command line and will not show up in the generated help. This is useful when you have (also) general configuration parameters in your OptsSpec, especially if you think they one day might need to be controlled externally. See example in the module overview. allow_empty_flag_spec(false) gives the more customary behaviour of raising error on empty flags.

[det]opt_help(+OptsSpec, -Help:atom)

True when Help is a help string synthesized from OptsSpec.

[semidet,multifile]parse_type(+Type, +Codes:list(code), -Result)

Hook to parse option text Codes to an object of type Type.