This is the unix-opts Reference Manual, version 0.1.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 18:12:00 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
unix-optsminimalistic parser of command line arguments
Mark Karpov
MIT
0.1.7
unix-opts.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
unix-opts/unix-opts.lispunix-opts (system).
arg-parser-failed (condition).
argv (function).
define-opts (macro).
describe (function).
exit (function).
get-opts (function).
make-options (function).
missing-arg (condition).
missing-options (reader method).
missing-required-option (condition).
option (reader method).
option (class).
raw-arg (reader method).
troublesome-option (condition).
unknown-option (condition).
unknown-option-provided (condition).
*options* (special variable).
add-text-padding (function).
arg-parser (reader method).
(setf arg-parser) (writer method).
argp (function).
default (reader method).
(setf default) (writer method).
description (reader method).
(setf description) (writer method).
find-option (function).
long (reader method).
(setf long) (writer method).
longp (function).
make-option (function).
map-options-to-hash-table (function).
maybe-funcall (function).
meta-var (reader method).
(setf meta-var) (writer method).
name (reader method).
(setf name) (writer method).
optionp (function).
print-opts (function).
print-opts* (function).
required (reader method).
(setf required) (writer method).
short (reader method).
(setf short) (writer method).
shortp (function).
split-on-= (function).
split-short-opts (function).
Packages are listed by definition order.
unix-optsopts
common-lisp.
arg-parser-failed (condition).
argv (function).
define-opts (macro).
describe (function).
exit (function).
get-opts (function).
make-options (function).
missing-arg (condition).
missing-options (generic reader).
missing-required-option (condition).
option (generic reader).
option (class).
raw-arg (generic reader).
troublesome-option (condition).
unknown-option (condition).
unknown-option-provided (condition).
*options* (special variable).
add-text-padding (function).
arg-parser (generic reader).
(setf arg-parser) (generic writer).
argp (function).
default (generic reader).
(setf default) (generic writer).
description (generic reader).
(setf description) (generic writer).
find-option (function).
long (generic reader).
(setf long) (generic writer).
longp (function).
make-option (function).
map-options-to-hash-table (function).
maybe-funcall (function).
meta-var (generic reader).
(setf meta-var) (generic writer).
name (generic reader).
(setf name) (generic writer).
optionp (function).
print-opts (function).
print-opts* (function).
required (generic reader).
(setf required) (generic writer).
short (generic reader).
(setf short) (generic writer).
shortp (function).
split-on-= (function).
split-short-opts (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Define command line options. Arguments of this macro must be plists containing various parameters. Here we enumerate all allowed parameters:
:NAME—keyword that will be included in list returned by GET-OPTS function if
actual option is supplied by user.
:DESCRIPTION—description of the option (it will be used in DESCRIBE function). This argument is optional, but it’s recommended to supply it.
:SHORT—single character, short variant of the option. You may omit this
argument if you supply :LONG variant of option.
:LONG—string, long variant of option. You may omit this argument if you
supply :SHORT variant of option.
:ARG-PARSER—if actual option must take an argument, supply this argument, it
must be a function that takes a string and parses it.
:META-VAR—if actual option requires an argument, this is how it will be
printed in option description.
:REQUIRED—whether the option is required. This only makes sense if the
option takes an argument.
:DEFAULT—the default value used if the option was not found. This can either be a function (which will be called to generate the default value) or a literal value. This option cannot be combined with :REQUIRED. The default value will not be provided to the :ARG-PARSER.
Return a list of program’s arguments, including command used to execute the program as first elements of the list. Portable across implementations.
Return string describing options of the program that were defined with
‘define-opts’ macro previously. You can supply PREFIX and SUFFIX arguments
that will be printed before and after options respectively. If USAGE-OF is
supplied, it should be a string, name of the program for "Usage: "
section. This section is only printed if this name is given.
If your program takes arguments (apart from options), you can specify how to
print them in ’usage’ section with ARGS option (should be a string
designator).
For the ’available options’ block: if the text that describes how to pass the
option is wider than ARGUMENT-BLOCK-WIDTH a newline is printed before the
description of that option.
The ’usage’ section will be prefixed with the value of the key
argument ‘usage-of-label‘ (default value: "Usage"), and the
’available options’ block will starts with the value of the key
argument ‘available-options-label’
(default value: "Available options")
on a single line
If USAGE-OF is provided and BRIEF is non-NIL, the ’available options’
block will be omitted from the output.
The output goes to STREAM.
Exit the program returning ‘status’.
Parse command line options. If OPTIONS is given, it should be a list to
parse. If it’s not given, the function will use ‘argv’ function to get list
of command line arguments.
Return two values:
* a list that contains keywords associated with command line options with
‘define-opts’ macro, and
* a list of free arguments.
If some option requires an argument, you can use ‘getf’ to
test presence of the option and get its argument if the option is present.
The parser may signal various conditions. Let’s list them all specifying
which restarts are available for every condition, and what kind of
information the programmer can extract from the conditions.
‘unknown-option’ is thrown when parser encounters unknown (not previously
defined with ‘define-opts’) option. Use the ‘option’ reader to get name of
the option (string). Available restarts: ‘use-value’ (substitute the option
and try again), ‘skip-option’ (ignore the option).
‘missing-arg’ is thrown when some option wants an argument, but there is no
such argument given. Use the ‘option’ reader to get name of the
option (string). Available restarts: ‘use-value’ (supplied value will be
used), ‘skip-option’ (ignore the option).
‘arg-parser-failed’ is thrown when some option wants an argument, it’s given
but cannot be parsed by argument parser. Use the ‘option’ reader to get name
of the option (string) and ‘raw-arg’ to get raw string representing the
argument before parsing. Available restarts: ‘use-value’ (supplied value
will be used), ‘skip-option’ (ignore the option), ‘reparse-arg’ (supplied
string will be parsed instead).
‘missing-required-option’ is thrown when some option was required but was not given. Use the ‘missing-options’ reader to get the list of options that are missing. Available restarts: ‘use-value’ (supplied list of values will be used), ‘skip-option’ (ignore all these options, effectively binding them to ‘nil’)
missing-required-option)) ¶troublesome-option)) ¶arg-parser-failed)) ¶This condition is thrown when some option OPTION wants
an argument, it’s given but cannot be parsed by argument parser.
This condition is thrown when some option OPTION wants an argument, but there is no such argument given.
This condition is thrown when required options are missing.
:missing-options
This slot is read-only.
Generalization over conditions that have to do with some particular option.
simple-error.
This condition is thrown when parser encounters
unknown (not previously defined with ‘define-opts’) option.
This condition is signaled when the restart ‘USE-VALUE’ is called with an undefined option.
representation of an option
keyword that will be included in list returned by ‘get-opts’ function if this option is given by user
:name
name.
description of the option
:description
NIL or single char - short variant of the option
:short
If not NIL this argument is required.
:required
if not NIL, this option requires an argument, it will be parsed with this function
:arg-parser
if this option requires an argument, this is how it will be printed in option description
:meta-var
if the option is not passed this value will be used, cannot be used in combination with REQUIRED
:default
Add padding to text STR. Every line except for the first one, will be prefixed with PADDING spaces. If NEWLINE is non-NIL, newline character will be prepended to the text making it start on the next line with padding applied to every single line.
Check if string STR is an argument (not option).
Find option OPT and return object that represents it or NIL.
Predicate that checks if OPT is a long option.
Register an option according to ARGS.
This predicate checks if string STR is an option.
Print info about defined options to STREAM. Every option get its own line with description. A newline is printed after the options if this part of the text is wider than ARGUMENT-BLOCK-WIDTH.
Return a string containing info about defined options. All options are displayed on one line, although this function tries to print it elegantly if it gets too long. MARGIN specifies margin.
Predicate that checks if OPT is a short option.
Split string ARG on "=", return value is list of strings.
Split short options, for example "-ab" will produce "-a" and "-b". ARG must be a string, return value is list of strings.
| Jump to: | (
A D E F G L M N O P R S |
|---|
| Jump to: | (
A D E F G L M N O P R S |
|---|
| Jump to: | *
A D L M N O R S |
|---|
| Jump to: | *
A D L M N O R S |
|---|
| Jump to: | A C F M O P S T U |
|---|
| Jump to: | A C F M O P S T U |
|---|