This library is intended for supporting PrologScript on Unix using the
#! magic sequence for scripts using commandline options. The entry
point main/0 calls the user-supplied predicate main/1 passing a list of
commandline options. Below is a simle
echo implementation in Prolog.
#!/usr/bin/env swipl :- initialization(main, main). main(Argv) :- echo(Argv). echo() :- nl. echo([Last]) :- !, write(Last), nl. echo([H|T]) :- write(H), write(' '), echo(T).
- Call main/1 using the passed command-line arguments. Before calling
main/1 this predicate installs a signal handler for
SIGINT(Control-C) that terminates the process with status 1.
When main/0 is called interactively it simply calls main/1 with the arguments. This allows for debugging scripts as follows:
$ swipl -l script.pl -- arg ... ?- gspy(suspect/1). % setup debugging ?- main. % run program
- We received an interrupt. This handler is installed using on_signal/3.
- argv_options(:Argv, -Positional, -Options) is det
- Parse command line arguments. This predicate acts in one of two
- 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
-. Type is one of:
- A | B
- Disjunctive type.
- Boolean options are special. They do not take a value except
for when using the long
--opt=valuenotation. This explicit value specification converts
1and the obvious false equivalents to Prolog
false. If the option is specified, Default is used. If
--nooptis used, the inverse of Default is used.
- Argument is converted to an integer
- Argument is converted to a float. User may specify an integer
integer. Requires value >= 0.
integer. Requires value >= 1.
- 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.
- No conversion
atom, but requires the value to be a member of List (enum type).
- Convert to a SWI-Prolog string
- Convert to a file name in Prolog canonical notation using prolog_to_os_filename/2.
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.
- Parse option value to a Prolog term.
term, but passes Options to term_string/3. If the option
variable_names(Bindings)is given the option value is set to the pair
- 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
--helpare 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
- argv_options(:Argv, -Positional, -Options, +ParseOptions) is det
- As argv_options/3 in guided mode, Currently this version allows
parsing argument options throwing an exception rather than calling
halt/1 by passing an empty list to ParseOptions. ParseOptions:
- If Goal is
halt(Code), exit with Code. Other goals are currently not supported.
true), stop parsing after the first positional argument, returning options that follow this argument as positional arguments. E.g,
-x file -yresults in positional arguments
- argv_untyped_options(+Argv, -RestArgv, -Options) is det[private]
- Generic transformation of long commandline arguments to options.
--Name=Valueis mapped to Name(Value). Each plain name is mapped to Name(true), unless Name starts with
no-, in which case the option is mapped to Name(false). Numeric option values are mapped to Prolog numbers.
- opt_parse(:Argv, -Positional, -Options, +POptions) is det[private]
- Rules follow those of Python optparse:
- Short options must be boolean, except for the last.
- The value of a short option can be connected or the next argument
- Long options can have "=value" or have the value in the next argument.
- opt_value(+Type, +Opt, +VAtom, -Value) is det[private]
- opt_convert(+Type, +VAtom, -Value) is semidet[private]
- argv_usage(:Level) is det
- Use print_message/2 to print a usage message at Level. To print the
message as plain text indefault color, use
debug. Other meaningful options are
warning. The help page consists of four sections, two of which are optional:
- The header is created from
opt_help(help(header), String). It is optional.
- The usage is added by default. The part behind
Usage: <command>is by default
[options]and can be overruled using
- The actual option descriptions. The options are presented in the order they are defined in opt_type/3. Subsequent options for the same destination (option name) are joined with the first.
- The footer_ is created from
opt_help(help(footer), String). It is optional.
The help provided by
help(footer)are either a simple string or a list of elements as defined by print_message_lines/3. In the latter case, the construct
\Callablecan be used to call a DCG rule in the module from which the user calls argv_options/3. For example, we can add a bold title using
opt_help(help(header), [ansi(bold, '~w', ['My title'])]).
- The header is created from
- usage_text(:Which)// is det[private]
- Emit a user element. This may use elements as defined by print_message_lines/3 or can be a simple string.
- Find the defined options and display help on them. Uses opt_type/3 to find the options and their type, opt_help/2 to find the option help comment and opt_meta/2 for meta types.
- wrap_text(+Width, +Text, -Wrapped)[private]
- Simple text wrapper. Breaks Text into words and creates lines with minimally one word and as many additional words as fit in Width. Wrapped is a list of strings.
- options(+Type, +ShortOpt, +LongOpts, +Meta)//[private]
- Emit a line with options.
- options_width(+Opt, -Width) is det[private]
- Compute the width of the column we need for the options.
- get_option(+Module, -Opt) is multi[private]
- Get a description for a single option. Opt is a term
opt(Name, Type, ShortFlags, Longflags, Help, Meta).
- As call/1, but fails silently if there is no predicate that implements Goal.
- cli_parse_debug_options(+OptionsIn, -Options) is det
- Parse certain commandline options for debugging and development
purposes. Options processed are below. Note that the option
argument is an atom such that these options may be activated as
- Re-enable the development environment. Currently re-enables xpce if
this was loaded, but not initialised and causes the interactive
toplevel to be re-enabled.
This predicate may be called from main/1 to enter the Prolog toplevel rather than terminating the application after main/1 completes.