An option specification is an association list (see Association Lists) with one list element for each supported option. The key of each list element is a symbol that names the option, while the value is a list of option properties:
OPTION-SPEC ::= '( (OPT-NAME1 (PROP-NAME PROP-VALUE) ...)
(OPT-NAME2 (PROP-NAME PROP-VALUE) ...)
(OPT-NAME3 (PROP-NAME PROP-VALUE) ...)
...
)
Each opt-name specifies the long option name for that option. For
example, a list element with opt-name background specifies
an option that can be specified on the command line using the long
option --background. Further information about the option —
whether it takes a value, whether it is required to be present in the
command line, and so on — is specified by the option properties.
In the example of the preceding section, we already saw that a long
option name can have a equivalent short option character. The
equivalent short option character can be set for an option by specifying
a single-char property in that option’s property list. For
example, a list element like '(output (single-char #\o) …)
specifies an option with long name --output that can also be
specified by the equivalent short name -o.
The value property specifies whether an option requires or
accepts a value. If the value property is set to #t, the
option requires a value: getopt-long will signal an error if the
option name is present without a corresponding value. If set to
#f, the option does not take a value; in this case, a non-option
word that follows the option name in the command line will be treated as
a non-option argument. If set to the symbol optional, the option
accepts a value but does not require one: a non-option word that follows
the option name in the command line will be interpreted as that option’s
value. If the option name for an option with '(value optional)
is immediately followed in the command line by another option
name, the value for the first option is implicitly #t.
The required? property indicates whether an option is required to
be present in the command line. If the required? property is
set to #t, getopt-long will signal an error if the option
is not specified.
Finally, the predicate property can be used to constrain the
possible values of an option. If used, the predicate property
should be set to a procedure that takes one argument — the proposed
option value as a string — and returns either #t or #f
according as the proposed value is or is not acceptable. If the
predicate procedure returns #f, getopt-long will signal an
error.
By default, options do not have single-character equivalents, are not
required, and do not take values. Where the list element for an option
includes a value property but no predicate property, the
option values are unconstrained.