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.
:- initialization(main, main).
echo() :- nl.
echo([Last]) :- !,
write(H), write(' '),
- See also
- - library(prolog_stack) to force backtraces in case of an
- - XPCE users should have a look at library(pce_main), which
starts the GUI and processes events until all windows have gone.
- Call main/1 using the passed command-line arguments. Before calling
main/1 this predicate installs a signal handler for
(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
- 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
- If opt_type/3 is not defined, only unguided transformation
using long options is supported. See argv_untyped_options/3
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
_ 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=value notation. This
explicit value specification converts
1 and the obvious
false equivalents to Prolog
false. If the
option is specified, Default is used. If
--noopt is 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
else convert as
integer. Then check the range.
- No conversion
atom, but requires the value to be a member of List
- Convert to a SWI-Prolog string
- Convert to a file name in Prolog canonical notation
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
- 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.
--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
- 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 -y
results in positional arguments
- argv_untyped_options(+Argv, -RestArgv, -Options) is det[private]
- Generic transformation of long commandline arguments to options.
--Name=Value is 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
- Long options can have "=value" or have the value in the
- 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
warning. The help page consists of
four sections, two of which are optional:
- The header is created from
It is optional.
- The usage is added by default. The part behind
Usage: <command> is by default
[options] and can be
- 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
It is optional.
The help provided by
either a simple string or a list of elements as defined by
print_message_lines/3. In the latter case, the construct
can 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'])]).
- 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
- 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
debug(Topic). See debug/1 and debug/3.
- spy Predicate
- Place a spy-point on Predicate.
- As spy using the graphical debugger. See tspy/1.
- Start the Prolog toplevel after main/1 completes.
- 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