This is the just-getopt-parser Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:22:07 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
just-getopt-parserGetopt-like parser for command-line options and arguments
Teemu Likonen <tlikonen@iki.fi>
Creative Commons CC0 (public domain dedication)
just-getopt-parser.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
just-getopt-parser/just-getopt-parser.asdjust-getopt-parser (system).
just-getopt-parser/just-getopt-parser.lispjust-getopt-parser (system).
ambiguous-option (condition).
argument-not-allowed (condition).
error-string (reader method).
getopt (function).
invalid-option-specification (condition).
option-matches (reader method).
option-name (reader method).
required-argument-missing (condition).
unknown-option (condition).
argument-error (condition).
check-duplicate-names (function).
check-long-option-string (function).
check-option-argument (function).
check-option-identifier (function).
check-option-name (function).
check-option-specification (function).
check-short-option-character (function).
format-option-name (function).
match-long-option (function).
Packages are listed by definition order.
just-getopt-parsercommon-lisp.
ambiguous-option (condition).
argument-not-allowed (condition).
error-string (generic reader).
getopt (function).
invalid-option-specification (condition).
option-matches (generic reader).
option-name (generic reader).
required-argument-missing (condition).
unknown-option (condition).
argument-error (condition).
check-duplicate-names (function).
check-long-option-string (function).
check-option-argument (function).
check-option-identifier (function).
check-option-name (function).
check-option-specification (function).
check-short-option-character (function).
format-option-name (function).
match-long-option (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Parse command-line arguments like getopt.
The ‘arguments‘ is a list of strings and contains the command-line
arguments that typically come from program’s user.
‘option-specification‘ argument is the specification of valid
command-line options. It is a list that contains lists of the following
format (in lambda list format):
(symbol option-name &optional option-argument)
The first element ‘symbol‘ is any symbol which identifies this
command-line option (for example keyword symbol ‘:help‘). The identifier
is used in function’s return value to identify that this particular
option was present in the command line.
The second element ‘option-name‘ is either
1. a character specifying a short option name (for example ‘#\h‘,
entered as ‘-h‘ in command line)
2. a string specifying a long option (for example ‘"help"‘, entered
as ‘–help‘ in command line). The string must be at least two
characters long.
The third element ‘option-argument‘ is optional but if it is non-nil it
must be one of the following keyword symbols: ‘:required‘ means that
this option requires an argument; ‘:optional‘ means that this option has
an optional argument. Example value for this function’s
‘option-specification‘ argument:
((:help #\h) ; short option -h for help (no option argument)
(:help "help") ; long option –help (no option argument)
(:file "file" :required) ; –file option which requires argument
(:debug #\d :optional)) ; -d option with optional argument
Note that several options may have the same identifier ‘symbol‘. This
makes sense when short and long option represent the same meaning. See
the ‘:help‘ keyword symbol above. All options must have unique
‘option-name‘ though.
If ‘option-specification‘ argument is not in correct form an error of
type ‘invalid-option-specification‘ is signaled.
If function’s key argument ‘options-everywhere‘ is nil (the default) the
option parsing stops when the first non-option argument is found. Rest
of the command line is parsed as non-options. If ‘options-everywhere‘ is
non-nil then options can be found anywhere in the command line, even
after non-option arguments. In all cases the option parsing stops when
the pseudo-option ‘–‘ is found in the command line. Then all remaining
arguments are parsed as non-option arguments.
If key argument ‘prefix-match-long-options‘ is non-nil then long options
don’t need to be written in full in the command line. They can be
shortened as long as there are enough characters to find unique prefix
match. If there are more than one match the option is classified as
unknown. If also key argument ‘error-on-ambiguous-option‘ is non-nil the
function will signal error condition ‘ambiguous-option‘. The condition
object contains the option’s name and it can be read with function
call ‘(option-name condition)‘. Function call ‘(option-matches
condition)‘ returns a list of option matches (strings). Also, the
condition object can be printed as an error message for user. There is
‘skip-option‘ restart available. When it is invoked the ambiguous option
is skipped and the function will continue parsing the command line.
Ambiguous options are always also unknown options: if ‘ambiguous-option‘
condition is not signaled then the condition for unknown option can be
signaled. See the next paragraph.
If function’s key argument ‘error-on-unknown-option‘ is non-nil and the
function finds an unknown option on the command line the function
signals error condition ‘unknown-option‘. The condition object includes
the name of the unknown option which can be read with
function ‘(option-name condition)‘. The return value is of type
character or string for short or long options respectively. You can also
just print the condition object: it gives a reasonable error message.
There is active ‘skip-option‘ restart. The invoked restart skips the
unknown option and continues parsing the command line.
Function’s key argument ‘error-on-argument-missing‘ (if non-nil) causes
the function to signal error condition ‘required-argument-missing‘ if it
sees an option which requires argument (keyword ‘:required‘) but there
is none. The condition object contains the name of the option which can
be read with function call ‘(option-name condition)‘. You can also just
print the condition object for user. It is an error message. There are
two restarts available: ‘give-argument‘ restart can be invoked with an
optional argument (string or nil) which will be passed as a new argument
for the option; restart ‘skip-option‘ will just skip this option and
continue parsing.
Key argument ‘error-on-argument-not-allowed‘ (if non-nil) makes this
function to signal error condition ‘argument-not-allowed‘ if there is an
argument for a long option which does not allow argument (‘–foo=...‘).
Such option is always listed as unknown option with name ‘"foo="‘ in
function’s return value. The condition object can be printed to user as
error message. The object also contains the name of the option which can
be read with ‘(option-name condition)‘ function call. There is
‘skip-option‘ restart available. When the restart is invoked the
function continues parsing the command line.
#### Return values
The function returns three values:
1. List of parsed options. List’s items are cons cells: the CAR part of
the cons cell is the identifier symbol for the option; the CDR part
of the cons cell is either nil (if there is no argument for this
option) or a string containing option’s argument.
2. List of non-option arguments (strings).
3. List of unknown options. List’s items are either characters or
strings which represent unknown short or long command-line options
which were not defined in the ‘option-specification‘.
In all three return values the list’s items are in the same order as
they were given in the function’s ‘arguments‘ argument.
#### Parsing rules for short options
Short options in the command line start with the ‘-‘ character and the
option character follows (‘-c‘).
If option requires an argument (keyword ‘:required‘) the argument must
be entered either directly after the option character (‘-cARG‘) or as
the next command-line argument (‘-c ARG‘). In the latter case anything
that follows ‘-c‘ will be parsed as option’s argument.
If option has optional argument (keyword ‘:optional‘) it must always be
entered directly after the option character (‘-cARG‘). Otherwise there
is no argument for this option.
Several short options can be entered together after one ‘-‘
character (‘-abc‘) but then only the last option in the series may have
required or optional argument.
#### Parsing rules for long options
Long options start with ‘–‘ characters and the option name comes
directly after it (‘–foo‘).
If option requires an argument (keyword ‘:required‘) it must be entered
either directly after the option name and ‘=‘ character (‘–foo=ARG‘) or
as the next command-line argument (‘–foo ARG‘). In the latter case
anything that follows ‘–foo‘ will be parsed as its argument.
If option has optional argument (keyword ‘:optional‘) the argument must
always be entered directly after the option name and ‘=‘
character (‘–foo=ARG‘). Otherwise (like in ‘–foo‘) there is no
argument for this option.
Option ‘–foo=‘ is valid format when the option requires argument or accepts optional argument. It means that the argument is empty string.
invalid-option-specification)) ¶ambiguous-option)) ¶argument-error)) ¶‘getopt‘ function may signal this condition when it parses a partially-written option name that matches to two or more long option names. Function ‘option-name‘ can be used to read option’s name from the condition object. Function ‘option-matches‘ will return the matching options.
:matches
This slot is read-only.
‘getopt‘ function may signal this condition when it parses an option that does not allow an argument but one is given with "–foo=...". Function ‘option-name‘ can be used to read option’s name from the condition object.
‘getopt‘ function signals this condition if its ‘option-specification‘ argument is invalid. Function ‘error-string‘ can be used to read error string from the condition object.
error.
common-lisp.
:string
This slot is read-only.
‘getopt‘ function may signal this condition when it parses an option that required an argument but there is none. Function ‘option-name‘ can be used to read option’s name from the condition object.
‘getopt‘ function may signal this condition when it finds an unknown option. Function ‘option-name‘ can be used to read option’s name from the condition object.
| Jump to: | C E F G M O |
|---|
| Jump to: | C E F G M O |
|---|
| Jump to: | M O S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| M | |||
matches: | Public conditions | ||
| | |||
| O | |||
option: | Private conditions | ||
| | |||
| S | |||
Slot, matches: | Public conditions | ||
Slot, option: | Private conditions | ||
Slot, string: | Public conditions | ||
string: | Public conditions | ||
| | |||
| Jump to: | M O S |
|---|
| Jump to: | A C F I J P R S U |
|---|
| Jump to: | A C F I J P R S U |
|---|