Next: gauche.partcont
- Partial continuations, Previous: gauche.parameter
- Parameters (legacy), Up: Library modules - Gauche extensions [Contents][Index]
gauche.parseopt
- Parsing command-line optionsThis module defines a convenient way to parse command-line options. The interface is hinted by Perl, and conveniently handles long-format options with multiple option arguments.
Actually, you have a few choices to parse command-line
options in Gauche.
SRFI-37 (see srfi.37
- args-fold: a program argument processor) provides
functional interface to parse POSIX/GNU compatible argument syntax.
SLIB has getopt
-compatible utility.
Required features may differ from application to application,
so choose whichever fits your requirement.
{gauche.parseopt} This macro captures the most common pattern of argument processing. It takes a list of arguments, args, and scans it to find Unix-style command-line options and binds their values to local variables according to bind-spec, then executes body ….
Let’s look at a simple example first, which gives you a good idea of what this form does. (See the “Examples” section below for more examples).
(define (main args) (let-args (cdr args) ((verbose "v|verbose") (outfile "o|outfile=s") (debug-level "d|debug-level=i" 0) (help "h|help" => (cut show-help (car args))) . restargs ) ....)) (define (show-help progname) ...)
The local variable verbose will be bound to #t
if
a command-line argument -v
or --verbose
is given,
and to #f
otherwise.
The variable output is specified to take one option argument;
if the command-line arguments are given like -o out.txt
,
outfile receives
"out.txt"
. The debug-level one is similar, but the
option argument is coerced to an integer, and also it has default
value 0 when the option isn’t given. The help clause
invokes an action rather than merely binding the value.
(Note: Currently let-args
does not distinguish so-called
short and long options, e.g. -v
and --v
have the same
effect, so as -verbose
and --verbose
. In future we
may add an option to make it compatible with getopt_long(3)
.)
The final restargs variable after the dot receives a list of non-optional command-line arguments.
Let’s look at bind-spec in detail. It must be one of the following forms.
1. (var option-spec) 2. (var option-spec default) 3. (var option-spec => callback) 4. (var option-spec default => callback) 5. (else => handler) 6. (else formals body ...)
A list of command-line arguments passed to args are parsed according to option-specs. If the corresponding option is given, a variable var is bound to a value as follows:
(a) If the bind-spec is 1. or 2., then
(a1) If option-spec doesn't require an argument, then #t
:
(a2) If option-spec requires one argument, then the value of
the argument:
(a3) If option-spec requires more than one argument,
the list of the values of the arguments.
(b) If the bind-spec is 3. or 4., then callback is called with
the value(s) of arguments, and its return value.
We’ll explain the details of option-spec later.
As a special case, var can be #f
, in which case
the value is ignored. It is only useful for side effects in
callback.
If the corresponding option is not given in args,
var is bound to default if it is given, or
#f
otherwise.
The last bind-spec may be the form 5 or 6. in which case
the clause is selected when no other option-spec matches
a given command-line option.
In the form 5, handler will be called with three arguments;
the given option, a list of remaining command-line arguments,
and a continuation procedure. The handler
is supposed to handle the given option, and it may call the
continuation procedure with the remaining arguments to continue
processing, or it may return a list of arguments which will
be treated as non-optional command-line arguments.
The form 6 is a shorthand notion of
(else => (lambda formals body ...))
.
The bind-spec list can be an improper list, whose last cdr is a symbol. In which case, a list of the rest of the command-line arguments is bound to the variable named by the symbol.
Note that the default, callback, and forms in else
clause is evaluated outside of the scope of binding of vars
(as the name let-args
implies).
Unlike typical getopt
or getopt_long
implementation in C,
let-args
does not permute the given command-line arguments.
It stops parsing when it encounters a non-option argument (argument without
starting with a minus sign).
If the parser encounters an argument with only two minus signs ‘--
’,
it stops argument parsing and returns a list of arguments after ‘--
’.
After all the bindings is done, body … are evaluated. Body may began with internal define forms.
option-spec is a string that specifies the name of the option and
how the option takes the arguments. An alphanumeric characters, underscore,
plus and minus sign is allowed for option’s names, except that
minus sign can’t be the first character, i.e. the valid option name
matches a regexp #/[\w+][-\w+]*/
.
If the option takes argument(s), it can be specified by attaching equal character and a character (or characters) that represents the type of the argument(s) after the name. The option can take more than one arguments. The following characters are recognized as a type specifier of the option’s argument.
s
String.
n
Number.
f
Real number (coerced to flonum).
i
Exact integer.
e
S-expression.
y
Symbol (argument is converted by string->symbol
).
Let’s see some examples of option-spec:
"name"
Specifies option name, that doesn’t take any argument.
"name=s"
Option name takes one argument, and it is passed as a string.
"name=i"
Option name takes one argument, and it is passed as an exact integer.
"name=ss"
Option name takes two arguments, both string.
"name=iii"
Option name takes three integer arguments.
"name=sf"
Option name takes two arguments, the first is a string and the second is a number.
If the option has alternative names, they can be concatenated by "|".
For example, an option spec "h|help"
will match both
"h" and "help".
In the command line, the option may appear with preceding
single or double minus signs. The option’s argument may be combined
by the option itself with an equal sign. For example, all the following
command line arguments match an option spec "prefix=s"
.
-prefix /home/shiro -prefix=/home/shiro --prefix /home/shiro --prefix=/home/shiro
If the option consists of a single letter and takes arguments,
the first argument can follow immediately after the option letter
without a whitespace. If you have an option spec "I=s"
,
all the following command line arguments are recognized:
-I/foo -I /foo -I=/foo --I/foo --I /foo --I=/foo
If there’s an ambiguity between a long option and a single-letter
option plus an argument, the long option takes precedence.
If you have an option spec "long"
and "l=s"
, command
line arguments -long
is recognized as the former,
not -l
option with arguments ong
.
{gauche.parseopt}
When let-args
encounters an argument that cannot be
processed as specified by option specs, an error of condition type
<parseopt-error>
is raised. The cases include
when a mandatory option argument is missing, or when
an option argument has a wrong type.
(let-args '("-a" "foo") ((a "a=i")) ; option a requires integer
(list a))
⇒ parseopt-error
Note that this condition is about parsing the given args. If an invalid option-spec is given, an ordinary error is thrown.
This example is taken from gauche-install
script.
The mode option takes numbers in octal, so it
uses the callback procedure to convert it.
See also the else
clause how to handle unrecognized option.
(let-args (cdr args) ((#f "c") ;; ignore for historical reason (mkdir "d|directory") (mode "m|mode=s" #o755 => (cut string->number <> 8)) (owner "o|owner=s") (group "g|group=s") (srcdir "S|srcdir=s") (target "T|target=s") (utarget "U|uninstall=s") (shebang "shebang=s") (verb "v") (dry "n|dry-run") (#f "h|help" => usage) (else (opt . _) (print "Unknown option : " opt) (usage)) . args) ...)
The next example is a small test program to show the usage of
else
clause. It gathers all options into the variable r,
except that when it sees -c
it stops argument processing and
binds the rest of the arguments to restargs.
(use gauche.parseopt) (define (main args) (let1 r '() (let-args (cdr args) ((else (opt rest cont) (cond [(equal? opt "c") rest] [else (push! r opt) (cont rest)])) . restargs) (print "options: " (reverse r)) (print "restargs: " restargs) 0)))
Sample session of the above script (suppose it is saved as example).
$ ./example -a -b -c -d -e foo options: (a b) restargs: (-d -e foo) $ ./example -a -b -d -e foo options: (a b d e) restargs: (foo)
The followings are lower-level API used to build let-args
macro.
{gauche.parseopt}
args is an expression that contains a list of command-line arguments.
This macro scans the command-line options (an argument that begins with
‘-
’) and processes it as specified in option-clauses, then
returns the remaining arguments.
Each option-clause is consisted by a pair of option-spec and its action.
If a given command-line option matches one of option-spec, then the associated action is evaluated. An action can be one of the following forms.
bind-spec body …
bind-spec is a proper or dotted list of variables like lambda-list. The option’s arguments are bound to bind-spec, then then body … is evaluated.
=> proc
If a command-line option matches option-spec, calls a procedure proc with a list of the option’s arguments.
If a symbol else
is at the position of option-spec,
the clause is selected when no other option clause matches a given
command-line option. Three “arguments” are associated to
the clause; the unmatched option, the rest of arguments, and
a procedure that represents the option parser.
{gauche.parseopt}
This is a lower-level interface. option-clauses are the
same as parse-options
. This macro returns a procedure
that can be used later to parse the command line options.
The returned procedure takes one required argument and one
optional argument. The required argument is a list of strings,
for given command-line arguments. The optional argument may
be a procedure that takes more than three arguments, and if given,
the procedure is used as if it is the body of else
option clause.
Next: gauche.partcont
- Partial continuations, Previous: gauche.parameter
- Parameters (legacy), Up: Library modules - Gauche extensions [Contents][Index]