7.4.4 Reference Documentation for getopt-long

Scheme Procedure: getopt-long args grammar [#:stop-at-first-non-option #t]

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.

• The option grammar has an invalid syntax.
• One of the options in the argument list was not specified by the grammar.
• A required option is omitted.
• An option which requires an argument did not 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.

#: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.