getopt-long
¶Parse the command line given in args (which must be a list of strings) according to the option specification grammar.
The grammar argument is expected to be a list of this form:
((option (property value) …) …)
where each option is a symbol denoting the long option, but
without the two leading dashes (e.g. version
if the option is
called --version
).
For each option, there may be list of arbitrarily many property/value pairs. The order of the pairs is not important, but every property may only appear once in the property list. The following table lists the possible properties:
(single-char char)
Accept -char
as a single-character equivalent to
--option
. This is how to specify traditional Unix-style
flags.
(required? bool)
If bool is true, the option is required. getopt-long
will
raise an error if it is not found in args.
(value bool)
If bool is #t
, the option accepts a value; if it is
#f
, it does not; and if it is the symbol optional
, the
option may appear in args with or without a value.
(predicate func)
If the option accepts a value (i.e. you specified (value #t)
for
this option), then getopt-long
will apply func to the
value, and throw an exception if it returns #f
. func
should be a procedure which accepts a string and returns a boolean
value; you may need to use quasiquotes to get it into grammar.
The #:stop-at-first-non-option
keyword, if specified with any
true value, tells getopt-long
to stop when it gets to the first
non-option in the command line. That is, at the first word which is
neither an option itself, nor the value of an option. Everything in the
command line from that word onwards will be returned as non-option
arguments.
getopt-long
’s args parameter is expected to be a list of
strings like the one returned by command-line
, with the first
element being the name of the command. Therefore getopt-long
ignores the first element in args and starts argument
interpretation with the second element.
getopt-long
signals an error if any of the following conditions
hold.
--opt=value
syntax).
#:stop-at-first-non-option
is useful for command line invocations
like guild [--help | --version] [script [script-options]]
and cvs [general-options] command [command-options]
, where there
are options at two levels: some generic and understood by the outer
command, and some that are specific to the particular script or command
being invoked. To use getopt-long
in such cases, you would call
it twice: firstly with #:stop-at-first-non-option #t
, so as to
parse any generic options and identify the wanted script or sub-command;
secondly, and after trimming off the initial generic command words, with
a script- or sub-command-specific option grammar, so as to process those
specific options.