chickadee » getopt-long » getopt-long

Parse the arguments ARGS according to the argument list grammar GRAMMAR.

ARGS should be a list of strings containing the arguments that were passed to the program on the command line. The command-line-arguments procedure returns a list of this form.

In ARGS, single-character options may be combined, in the usual Unix fashion: ("-x" "-y") is equivalent to ("-xy"). If an option accepts values, then it must be the last option in the combination; the value is the next argument. So, for example, using the following grammar:

    ((apples    (single-char #\a))
     (blimps    (single-char #\b) (value #t))
     (catalexis (single-char #\c) (value #t)))

the following argument lists would be acceptable:

  ("-a" "-b" "bang" "-c" "couth")     ("bang" and "couth" are the values
                                       for "blimps" and "catalexis")
  ("-ab" "bang" "-c" "couth")         (same)
  ("-ac" "couth" "-b" "bang")         (same)
  ("-abc" "couth" "bang")             (an error, since `-b' is not the
                                       last option in its combination)

If an option's value is optional, then getopt-long decides whether it has a value by looking at what follows it in ARGS. If the next element is does not appear to be an option itself, then that element is the option's value.

The value of a long option can can only follow the option name, separated by an `=' character.

If the option "--" appears in ARGS, argument parsing stops there; subsequent arguments are returned as ordinary arguments, even if they resemble options. So, in the argument list:

       ("--apples" "Granny Smith" "--" "--blimps" "Goodyear")

getopt-long will recognize the `apples' option as having the value "Granny Smith", but it will not recognize the `blimp' option; it will return the strings "--blimps" and "Goodyear" as ordinary argument strings.

The getopt-long function returns an association list in which the key is an option name --- one of the symbols from GRAMMAR --- and each key is associated either with a single value (if the named option has been given once), or with a list of values (if the option was given multiple times). Options that were not given are not present.

There is a special item in the returned alist with a key '@: this is the list of arguments that are not options or option values.

Optional keyword argument UNKNOWN-OPTION-HANDLER is a procedure that receives as an argument a list of all options that were given as input but were unrecognized by the grammar. The default unknown option handler raises an error.

Optional keyword argument LONG-OPTION-VALUE-CSET is a SRFI-14 character set that specifies all valid characters in an option value. This argument defaults to:

 (char-set-union char-set:letter+digit 
                   char-set:punctuation
                  (char-set #\_ #\^ #\$ #\= #\space))

By default, getopt-long throws an exception if:

• it finds an unrecognized property in GRAMMAR
• it finds an unrecognized option in ARGS
• a required option is omitted
• an option that requires an argument doesn't get one
• an option that doesn't accept an argument does get one (this can only happen using the long option --opt=value syntax)
• an option predicate fails