- 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. Disjunction can be used create long options with
optional values. For example, using the type
nonneg|boolean
, for an optionhttp
handles--http
ashttp(true)
,--no-http
ashttp(false)
,--http=3000
and--http 3000
ashttp(3000)
. With an optional boolean an option is considered boolean if it is the last or the next argument starts with a hyphen (-
). - 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 convertstrue
,True
,TRUE
,on
,On
,ON
,1
and the obvious false equivalents to Prologtrue
orfalse
. 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 asinteger
. 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.
- directory
- Convert to a file name in Prolog canonical notation using prolog_to_os_filename/2.
No checking is done and thus this type is the same as
file
- 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. - directory(Access)
- As
directory
, and check access. Access is one ofread
write
orcreate
. In the latter case the parent directory must exist and have write access. - term
- Parse option value to a Prolog term.
- term(+Options)
- As
term
, but passes Options to term_string/3. If the optionvariable_names(Bindings)
is given the option value is set to the pairTerm-Bindings
.
- A
- 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)
.