[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.13 gauche.parseopt - Parsing command-line options

Module: gauche.parseopt
This module defines a convenient way to parse command-line options. The interface is hinted by Perl, and conveniently handles long-format options with mutiple option arguments.

Note that you can also use the standard getopt interface by SLIB, if you prefer.

Macro: parse-options args (option-clause ...)
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.

Unlike typical getopt or getopt_long implementation in C, parse-options 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 `--'.

Each option-clause is consisted by a pair of option-spec and its action.

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 the type of the argument after the name. The option can take more than one arguments.

"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. If the given argument is not valid string for an exact integer, an error is signalled.

"name=f"
Option name takes one argument, and it is passed as a real number. If the given argument is not valid string for a real number, an error is signalled.

"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.

In the command line, the option may appear with preceding single or double minus signs. The option's argument may be comibined 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 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.

Examples:
 
(parse-options '("-file" "foo")
  (("file=s" (file)
     (format #t "file is ~s\n" file))))
 => ;``file is "foo"'' is printed

(parse-options '("-scale" "1.5" "2.2")
  (("scale=ff" (xscale yscale)
     (format #t "scale is ~sx~s\n" xscale yscale))))
 => ;``scale is 1.5x2.2'' is printed

(parse-options '("-scale" "1.5" "2.2")
  (("scale=ff" scales
     (format #t "scale is ~s\n" scales))))
 => ;``scale is (1.5 2.2)'' is printed

(define (scales x y)
  (format #t "scale is ~sx~s\n" x y))

(parse-options '("-scale" "1.5" "2.2")
  (("scale=ff" => scales)))
 => ;``scale is 1.5x2.2'' is printed

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.

 
(parse-options args
  (("file=s" => process-file)
   (else (option . _)  (error "unrecognized option:" option))))

Unlike other clause, the else clause returns to the caller of parse-options, without looping further. In order to continue looping, you have to call the third argument of the else clause with the remaining arguments. This can be used to implement your own sub-parser. The following example just skips unrecognized option, with printing a warning, and continues parsing:

 
(parse-options args
  (("file=s" => process-file)
   (else (option args continue)
     (format #t "warning: ignoring unrecognized option: ~a" option)
     (continue args))))

Macro: make-option-parser (option-clause ...)
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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html