This is the adopt Reference Manual, version 1.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 14:30:56 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
adoptSimple, flexible, UNIX-style option parsing.
Steve Losh <steve@stevelosh.com>
MIT
1.2.0
bobbin (system).
split-sequence (system).
src (module).
Modules are listed depth-first from the system components tree.
adopt/srcadopt (system).
package.lisp (file).
main.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
adopt/src/main.lisppackage.lisp (file).
src (module).
argv (function).
collect (function).
define-string (macro).
defparameters (macro).
discard-option (function).
exit (function).
first (function).
flip (function).
last (function).
make-boolean-options (function).
make-group (function).
make-interface (function).
make-option (function).
parse-options (function).
parse-options-or-exit (function).
print-error-and-exit (function).
print-help (function).
print-help-and-exit (function).
print-manual (function).
print-object (method).
print-object (method).
print-object (method).
problematic-option (reader method).
(setf problematic-option) (writer method).
supply-new-value (function).
treat-as-argument (function).
unrecognized-option (condition).
check-types (macro).
defclass* (macro).
escape (function).
examples (reader method).
(setf examples) (writer method).
finalize-results (function).
finally (reader method).
(setf finally) (writer method).
funcall% (function).
funcallf (macro).
group (class).
groupp (function).
groups (reader method).
(setf groups) (writer method).
help (reader method).
help (reader method).
help (reader method).
(setf help) (writer method).
(setf help) (writer method).
(setf help) (writer method).
initial-value (reader method).
(setf initial-value) (writer method).
initialize-results (function).
interface (class).
key (reader method).
(setf key) (writer method).
long (reader method).
(setf long) (writer method).
long-options (reader method).
(setf long-options) (writer method).
longp (function).
make-default-group (function).
manual (reader method).
manual (reader method).
manual (reader method).
(setf manual) (writer method).
(setf manual) (writer method).
(setf manual) (writer method).
name (reader method).
name (reader method).
name (reader method).
(setf name) (writer method).
(setf name) (writer method).
(setf name) (writer method).
option (class).
option-string (function).
option-troff (function).
optionp (function).
options (reader method).
options (reader method).
(setf options) (writer method).
(setf options) (writer method).
parameter (reader method).
(setf parameter) (writer method).
parse-long (function).
parse-short (function).
print-option-help (function).
quit-on-ctrl-c (macro).
reduce (reader method).
(setf reduce) (writer method).
result-key (reader method).
(setf result-key) (writer method).
short (reader method).
(setf short) (writer method).
short-options (reader method).
(setf short-options) (writer method).
shortp (function).
split-paragraphs (function).
summary (reader method).
(setf summary) (writer method).
terminatorp (function).
title (reader method).
(setf title) (writer method).
unrecognized-option-p (function).
usage (reader method).
(setf usage) (writer method).
Packages are listed by definition order.
adoptcommon-lisp.
argv (function).
collect (function).
define-string (macro).
defparameters (macro).
discard-option (function).
exit (function).
first (function).
flip (function).
last (function).
make-boolean-options (function).
make-group (function).
make-interface (function).
make-option (function).
parse-options (function).
parse-options-or-exit (function).
print-error-and-exit (function).
print-help (function).
print-help-and-exit (function).
print-manual (function).
problematic-option (generic reader).
(setf problematic-option) (generic writer).
supply-new-value (function).
treat-as-argument (function).
unrecognized-option (condition).
check-types (macro).
defclass* (macro).
escape (function).
examples (generic reader).
(setf examples) (generic writer).
finalize-results (function).
finally (generic reader).
(setf finally) (generic writer).
funcall% (function).
funcallf (macro).
group (class).
groupp (function).
groups (generic reader).
(setf groups) (generic writer).
help (generic reader).
(setf help) (generic writer).
initial-value (generic reader).
(setf initial-value) (generic writer).
initialize-results (function).
interface (class).
key (generic reader).
(setf key) (generic writer).
long (generic reader).
(setf long) (generic writer).
long-options (generic reader).
(setf long-options) (generic writer).
longp (function).
make-default-group (function).
manual (generic reader).
(setf manual) (generic writer).
name (generic reader).
(setf name) (generic writer).
option (class).
option-string (function).
option-troff (function).
optionp (function).
options (generic reader).
(setf options) (generic writer).
parameter (generic reader).
(setf parameter) (generic writer).
parse-long (function).
parse-short (function).
print-option-help (function).
quit-on-ctrl-c (macro).
reduce (generic reader).
(setf reduce) (generic writer).
result-key (generic reader).
(setf result-key) (generic writer).
short (generic reader).
(setf short) (generic writer).
short-options (generic reader).
(setf short-options) (generic writer).
shortp (function).
split-paragraphs (function).
summary (generic reader).
(setf summary) (generic writer).
terminatorp (function).
title (generic reader).
(setf title) (generic writer).
unrecognized-option-p (function).
usage (generic reader).
(setf usage) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Convenience macro for ‘(defparameter ,var (format nil ,string ,@args))‘.
Convenience macro for ‘defparameter‘ing multiple variables at once.
‘parameters‘ must be a list of special variable names suitable for giving to
‘defparameter‘.
‘values-form‘ must be an expression that returns as many values as parameters in the parameter list. Each parameter will be set to the corresponding value.
This can be handy when using ‘make-boolean-options‘ to create two ‘option‘s at
once and assign them to special variables.
Examples:
(defparameters (*a* *b*) (truncate 100 3))
(list *a* *b*)
; =>
; (33 1)
(defparameters (*option-foo* *option-no-foo*)
(make-boolean-options ’foo
:help "Foo the widgets during the run."
:help-no "Do not foo the widgets during the run (the default)."
:long "foo"
:short #f))
Return a list of the program name and command line arguments.
This is not implemented for every Common Lisp implementation. You can pass
your own values to ‘parse-options‘ and ‘print-help‘ if it’s not implemented
for your particular Lisp.
Append element ‘el‘ to the end of ‘list‘.
It is useful as a ‘:reduce‘ function when you want to collect all values given
for an option.
This is implemented as ‘(append list (list el))‘. It is not particularly fast. If you can live with reversed output consider ‘(flip #’cons)‘ instead.
Invoke the ‘discard-option‘ restart properly.
Example:
(handler-bind ((unrecognized-option ’discard-option))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
Exit the program with status ‘code‘.
This is not implemented for every Common Lisp implementation. You can write your own version of it and pass it to ‘print-help-and-exit‘ and ‘print-error-and-exit‘ if it’s not implemented for your particular Lisp.
Return ‘new‘ if ‘old‘ is ‘nil‘, otherwise return ‘old‘.
It is useful as a ‘:reduce‘ function when you want to just keep the
first-given value for an option.
Return a function of two arguments X and Y that calls ‘function‘ with Y and X.
Useful for wrapping existing functions that expect their arguments in the
opposite order.
Examples:
(funcall #’cons 1 2) ; => (1 . 2)
(funcall (flip #’cons) 1 2) ; => (2 . 1)
(reduce (flip #’cons) ’(1 2 3) :initial-value nil)
; => (3 2 1)
Return ‘new‘.
It is useful as a ‘:reduce‘ function when you want to just keep the last-given
value for an option.
Create and return a pair of boolean options, suitable for use in an interface.
This function reduces some of the boilerplate when creating two ‘option‘s for
boolean values, e.g. ‘–foo‘ and ‘–no-foo‘. It will try to guess at an
appropriate name, long option, short option, and result key, but you can
override them with the ‘…-no‘ keyword options as needed.
The two options will be returned as two separate values — you can use
‘defparameters‘ to conveniently bind them to two separate variables if
desired.
Example:
(defparameters (*option-debug* *option-no-debug*)
(make-boolean-options ’debug
:long "debug"
:short #d
:help "Enable the Lisp debugger."
:help-no "Disable the Lisp debugger (the default)."))
;; is roughly equivalent to:
(defparameter *option-debug*
(make-option ’debug
:long "debug"
:short #d
:help "Enable the Lisp debugger."
:initial-value nil
:reduce (constantly t))
(defparameter *option-no-debug*
(make-option ’no-debug
:long "no-debug"
:short #D
:help "Disable the Lisp debugger (the default)."
:reduce (constantly nil))
Create and return an option group, suitable for use in an interface.
This function takes a number of arguments that define how the group is
presented to the user:
* ‘name‘ (**required**): a symbol naming the group.
* ‘title‘ (optional): a title for the group for use in the help text.
* ‘help‘ (optional): a short summary of this group of options for use in the help text.
* ‘manual‘ (optional): used in place of ‘help‘ when rendering a man page.
* ‘options‘ (**required**): the options to include in the group.
See the full documentation for more information.
Create and return a command line interface.
This function takes a number of arguments that define how the interface is
presented to the user:
* ‘name‘ (**required**): a symbol naming the interface.
* ‘summary‘ (**required**): a string of a concise, one-line summary of what the program does.
* ‘usage‘ (**required**): a string of a UNIX-style usage summary, e.g. ‘"[OPTIONS] PATTERN [FILE...]"‘.
* ‘help‘ (**required**): a string of a longer description of the program.
* ‘manual‘ (optional): a string to use in place of ‘help‘ when rendering a man page.
* ‘examples‘ (optional): an alist of ‘(prose . command)‘ conses to render as a list of examples.
* ‘contents‘ (optional): a list of options and groups. Ungrouped options will be collected into a single top-level group.
See the full documentation for more information.
Create and return an option, suitable for use in an interface.
This function takes a number of arguments, some required, that define how the
option interacts with the user.
* ‘name‘ (**required**): a symbol naming the option.
* ‘help‘ (**required**): a short string describing what the option does.
* ‘result-key‘ (optional): a symbol to use as the key for this option in the hash table of results.
* ‘long‘ (optional): a string for the long form of the option (e.g. ‘–foo‘).
* ‘short‘ (optional): a character for the short form of the option (e.g. ‘-f‘). At least one of ‘short‘ and ‘long‘ must be given.
* ‘manual‘ (optional): a string to use in place of ‘help‘ when rendering a man page.
* ‘parameter‘ (optional): a string. If given, it will turn this option into a parameter-taking option (e.g. ‘–foo=bar‘) and will be used as a placeholder
in the help text.
* ‘reduce‘ (**required**): a function designator that will be called every time the option is specified by the user.
* ‘initial-value‘ (optional): a value to use as the initial value of the option.
* ‘key‘ (optional): a function designator, only allowed for parameter-taking options, to be called on the values given by the user before they are passed along to the reducing function. It will not be called on the initial value.
* ‘finally‘ (optional): a function designator to be called on the final result after all parsing is complete.
The manner in which the reducer is called depends on whether the option takes a parameter:
* For options that don’t take parameters, it will be called with the old value.
* For options that take parameters, it will be called with the old value and the value given by the user.
See the full documentation for more information.
Parse ‘arguments‘ according to ‘interface‘.
Two values are returned:
1. A fresh list of top-level, unaccounted-for arguments that don’t correspond
to any options defined in ‘interface‘.
2. An ‘EQL‘ hash table of option keys to values.
See the full documentation for more information.
Parse ‘arguments‘ according to ‘interface‘, exiting if any error occurs.
Two values are returned:
1. A fresh list of top-level, unaccounted-for arguments that don’t correspond
to any options defined in ‘interface‘.
2. An ‘EQL‘ hash table of option keys to values.
If an error occurs while parsing the arguments, exits immediately as if with
‘adopt:print-error-and-exit‘.
See the full documentation for more information.
Print ‘prefix‘ and ‘error‘ to ‘stream‘ and exit.
Example:
(handler-case
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options))
(unrecognized-option (c)
(print-error-and-exit c)))
Print a pretty help document for ‘interface‘ to ‘stream‘.
‘width‘ should be the total width (in characters) for line-wrapping purposes.
Care will be taken to ensure lines are no longer than this, though some edge
cases (extremely long short/long option names and parameters) may slip
through.
‘option-width‘ should be the width of the column of short/long options (in
characters). If the short/long option help is shorter than this, the option’s
help string will start on the same line. Otherwise the option’s help string
will start on the next line.
The result will look something like:
(print-help *program-interface* :width 60 :option-width 15)
; =>
; foo - do some things and meow
;
; USAGE: /bin/foo [options] FILES
;
; Foo is a program to frobulate some files, meowing as it
; happens.
;
; Options:
; -v, –verbose Output extra information.
; -q, –quiet Shut up.
; –ignore FILE Ignore FILE. May be specified multiple
; times.
; -n NAME, –name NAME
; Your name. May be specified many times,
; last one wins.
; -m, –meow Meow.
; 0.........1.... option-width
; 0........1.........2.........3.........4.........5.........6
Print a pretty help document for ‘interface‘ to ‘stream‘ and exit.
Handy for easily providing –help:
(multiple-value-bind (arguments options) (parse-options *ui*)
(when (gethash ’help options)
(print-help-and-exit *ui*))
(run arguments options))
Print a troff-formatted man page for ‘interface‘ to ‘stream‘.
Example:
(with-open-file (manual "man/man1/foo.1"
:direction :output
:if-exists :supersede)
(print-manual *ui* manual))
Invoke the ‘supply-new-value‘ restart properly.
Example:
(handler-bind
((unrecognized-option (alexandria:rcurry ’supply-new-value "–foo"))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
Invoke the ‘treat-as-argument‘ restart properly.
Example:
(handler-bind ((unrecognized-option ’treat-as-argument))
(multiple-value-bind (arguments options) (parse-options *ui*)
(run arguments options)))
unrecognized-option)) ¶unrecognized-option)) ¶Print ‘option‘’s help to ‘stream‘, indented/wrapped properly.
Assumes the last thing printed to ‘stream‘ was a newline.
The option string will start at ‘option-column‘. The help will start at
‘doc-column‘ and be line-wrapped to ‘doc-width‘.
:summary
:examples
:options
:groups
:short-options
:long-options
:usage
:manual
:result-key
:manual
:short
:parameter
:initial-value
:finally
:reduce
| Jump to: | (
A C D E F G H I K L M N O P Q R S T U |
|---|
| Jump to: | (
A C D E F G H I K L M N O P Q R S T U |
|---|
| Jump to: | E F G H I K L M N O P R S T U |
|---|
| Jump to: | E F G H I K L M N O P R S T U |
|---|
| Jump to: | A C F G I M O P S U |
|---|
| Jump to: | A C F G I M O P S U |
|---|