In order for getopt-long to correctly parse a command line, that
command line must conform to a standard set of rules for how command
line options are specified. This section explains what those rules
are.
getopt-long splits a given command line into several pieces. All
elements of the argument list are classified to be either options or
normal arguments. Options consist of two dashes and an option name
(so-called long options), or of one dash followed by a single
letter (short options).
Options can behave as switches, when they are given without a value, or they can be used to pass a value to the program. The value for an option may be specified using an equals sign, or else is simply the next word in the command line, so the following two invocations are equivalent:
$ ./foo.scm --output=bar.txt $ ./foo.scm --output bar.txt
Short options can be used instead of their long equivalents and can be grouped together after a single dash. For example, the following commands are equivalent.
$ ./foo.scm --version --help $ ./foo.scm -v --help $ ./foo.scm -vh
If an option requires a value, it can only be grouped together with other short options if it is the last option in the group; the value is the next argument. So, for example, with the following option specification —
((apples (single-char #\a)) (blimps (single-char #\b) (value #t)) (catalexis (single-char #\c) (value #t)))
— the following command lines would all be acceptable:
$ ./foo.scm -a -b bang -c couth $ ./foo.scm -ab bang -c couth $ ./foo.scm -ac couth -b bang
But the next command line is an error, because -b is not the last
option in its combination, and because a group of short options cannot
include two options that both require values:
$ ./foo.scm -abc couth bang
If an option’s value is optional, getopt-long decides whether the
option has a value by looking at what follows it in the argument list.
If the next element is a string, and it does not appear to be an option
itself, then that string is the option’s value.
If the option -- appears in the argument list, argument parsing
stops there and subsequent arguments are returned as ordinary arguments,
even if they resemble options. So, with the command line
$ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear
getopt-long will recognize the --apples option as having
the value "Granny Smith", but will not treat --blimp as an
option. The strings --blimp and Goodyear will be returned
as ordinary argument strings.