• If the calling module defines opt_type/3, full featured parsing with long and short options, type conversion and help is provided.
• If opt_type/3 is not defined, only unguided transformation using long options is supported. See argv_untyped_options/3 for details.

When guided, three predicates are called in the calling module. opt_type/3 must be defined, the others need not. Note that these three predicates may be defined as multifile to allow multiple modules contributing to the provided commandline options. Defining them as discontiguous allows for creating blocks that describe a group of related options.

opt_type(Opt, Name, Type)

Defines Opt to add an option Name(Value), where Value statisfies Type. Opt does not include the leading -. A single character implies a short option, multiple a long option. Long options use _ as word separator, user options may use either _ or -. Type is one of:

A | B

Disjunctive type.

boolean(Default)

boolean

Boolean options are special. They do not take a value except for when using the long --opt=value notation. This explicit value specification converts true, True, TRUE, on, On, ON, 1 and the obvious false equivalents to Prolog true or false. If the option is specified, Default is used. If --no-opt or --noopt is used, the inverse of Default is used.

integer

Argument is converted to an integer

float

Argument is converted to a float. User may specify an integer

nonneg

As integer. Requires value >= 0.

natural

As integer. Requires value >= 1.

number

Any number (integer, float, rational).

between(Low, High)

If both one of Low and High is a float, convert as float, else convert as integer. Then check the range.

atom

No conversion

oneof(List)

As atom, but requires the value to be a member of List (enum type).

string

Convert to a SWI-Prolog string

file

Convert to a file name in Prolog canonical notation using prolog_to_os_filename/2.

file(Access)

As file, and check access using access_file/2. A value - is not checked for access, assuming the application handles this as standard input or output.

term

Parse option value to a Prolog term.

term(+Options)

As term, but passes Options to term_string/3. If the option variable_names(Bindings) is given the option value is set to the pair Term-Bindings.

opt_help(Name, HelpString)

Help string used by argv_usage/1.

opt_meta(Name, Meta)

If a typed argument is required this defines the placeholder in the help message. The default is the uppercase version of the type functor name. This produces the FILE in e.g. -f FILE.

By default, -h, -? and --help are bound to help. If opt_type(Opt, help, boolean) is true for some Opt, the default help binding and help message are disabled and the normal user rules apply. In particular, the user should also provide a rule for opt_help(help, String).