7.4.3 Expected Command Line Format

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.