Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the utility-arguments Reference Manual, version 0.161029, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:44:19 2018 GMT+0.
| • Introduction: | What utility-arguments is all about | |
| • Systems: | The systems documentation | |
| • Files: | The files documentation | |
| • Packages: | The packages documentation | |
| • Definitions: | The symbols documentation | |
| • Indexes: | Concepts, functions, variables and data types |
Utility Arguments is a Common Lisp software that handles command-line arguments. The adopted argument syntax is described in the POSIX and the GNU conventions.
Real notion of a usage, which allows Utility Arguments to automatically select a suitable usage for operands and options.
Robust in parsing command-line arguments. Utility Arguments doesn't trip on spaces in option specifications, and options are not required to appear before operands.
Lispy feel. Lambda lists describe the operands and options a usage binds — this idea was taken from Command Line Arguments.
No auto-generated documentation for operands, options, and usages; because it would be hard to produce a style which pleases all eyes.
Utility Arguments is hosted on Gitlab.com. The master branch points to the most recent release.
The easiest way to install Utility Arguments is through Quicklisp.
Alternatively, either download a tarball from the project's website or
clone the Git repository. Put the source code where ASDF can find it.
The system utility-arguments can then be loaded and compiled.
Utility arguments are formatted strings that conform to the POSIX and the GNU argument syntax conventions. To summarize it here: Option specifications start with one or two hyphens followed by alphanumeric characters. Everything that is not an option specification is an operand. A double hyphen terminates options, i.e., everything to the right of it is considered an operand.
Commonly, the utility arguments will be the arguments received on the
command-line. To retrieve the command-line arguments in a portable
way, use the function uiop:command-line-arguments.
A usage, which is defined with the macro defusage, can be thought of
as a Lisp function applicable to a set of utility arguments. Its
positional and keyword parameters receive the values of operands and
options. Type parsing can be requested through objects handed over to
the function apply-usage; otherwise, a string trimmed of white space
at both ends is passed as value.
Usages are applied to utility arguments with the function
apply-usage. Among other arguments, it receives two lists of
operand and option objects that complement the parameters on usage
lambda lists in providing additional type and syntactic information.
A usage is applicable to a set of utility arguments if there is a correlated parameter for each operand and option, and if all parameters are satisfied on the usage lambda list.
Symbols exported from the package utility-arguments comprise the API
and are documented by their docstrings. The examples below cover the
majority of the API.
In this example we create the outline for a hypothetical encryption utility to demonstrate how to use Utility Arguments.
We devise usages to encrypt and decrypt files. The usages are
implemented with the macro defusage. Positional parameters on the
first lambda list describe operands, and keyword parameters on the
second lambda list describe options. Parameters receive the values of
operands and options.
(defusage encrypt ((infile &optional outfile)
(&key encrypt (algorithm 'aes) (keysize 256)))
(declare (ignore encrypt))
;; code...
)
(defusage decrypt ((infile &optional outfile)
(&key decrypt algorithm keysize))
(declare (ignore decrypt))
;; code...
)
For the encryption usage we made algorithm and keysize optional
options by specifying an init-form for the keyword parameters.
We have no real use for the encrypt and decrypt parameters inside
the body of the usages; however, they are essential for the usages to
be distinguishable from each other.
We create operand objects that complement the positional parameters on the usage lambda lists. Correlation is established by option key and parameter name. For type we pass a function object instead of a Lisp type specifier, which gives us full control over the received argument.
(defun probe-infile (string designator)
(when (not (uiop:probe-file* string))
(warn "File ~s specified for ~a does not exist." string designator))
string)
(defun probe-outfile (string designator)
(when (uiop:probe-file* string)
(warn "File ~s specified for ~a does already exist." string designator))
string)
(defparameter *operands*
(list (make-operand :key 'infile :type #'probe-infile)
(make-operand :key 'outfile :type #'probe-outfile)))
We create option objects that complement the keyword parameters on the usage lambda lists. Correlation is established by option key and parameter name. Different kind of options are available. We specify key, short and long designators, and for options that receive an argument a Lisp type specifier. For type parsing, the Lisp reader is used.
(defparameter *options*
(list (make-option-flag
:key :encrypt :short #\e :long "encrypt")
(make-option-flag
:key :decrypt :short #\d :long "decrypt")
(make-option-with-argument
:key :algorithm :short #\a :long "algorithm" :type '(or (eql aes) (eql des)))
(make-option-with-argument
:key :keysize :short #\s :long "keysize" :type '(integer 128))))
We apply the usages to utility arguments with the function
apply-usage. The next two examples succeed.
(apply-usage '(encrypt decrypt) *operands* *options*
(list "--encrypt" "secret.txt" "secret.enc"))
(apply-usage '(encrypt decrypt) *operands* *options*
(list "--decrypt" "secret.enc" "-aAES" "--keysize=256"))
This example signals a utility-argument-error condition, because we
didn't make any provisions for an option --help.
(apply-usage '(encrypt decrypt) *operands* *options*
(list "--help"))
This example signals a usage-error condition, because we did not
devise such usage. We need at least an input-file operand for this to
succeed.
(apply-usage '(encrypt decrypt) *operands* *options*
(list "--encrypt"))
The reason defusage takes two lambda lists instead of one is to
allow for a rest parameter to be specified for operands and options
each, like in the next example.
(defusage foo ((&rest ints)
(&rest options &key x &allow-other-keys))
;; code...
)
To successfully apply the usage, we need to provide the option x.
Additionally any other option and integer operands are accepted.
(apply-usage '(foo)
(list (make-operand :key 'ints :type ' (integer * 0)))
(list (make-option-flag :key :x :short #\x)
(make-option-flag :key :y :short #\y))
(list "-xy" "--" "-3" "-7"))
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The utility-arguments system: |
Frank A. U.
ICS
Utility to handle command-line arguments.
0.161029
alexandria
utility-arguments.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
Next: The utility-arguments/packages<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
utility-arguments.asd
utility-arguments (system)
Next: The utility-arguments/utils<dot>lisp file, Previous: The utility-arguments<dot>asd file, Up: Lisp files [Contents][Index]
utility-arguments (system)
packages.lisp
Next: The utility-arguments/error<dot>lisp file, Previous: The utility-arguments/packages<dot>lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
utility-arguments (system)
utils.lisp
Next: The utility-arguments/option<dot>lisp file, Previous: The utility-arguments/utils<dot>lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
utility-arguments (system)
error.lisp
Next: The utility-arguments/parser<dot>lisp file, Previous: The utility-arguments/error<dot>lisp file, Up: Lisp files [Contents][Index]
error.lisp (file)
utility-arguments (system)
option.lisp
Next: The utility-arguments/operand<dot>lisp file, Previous: The utility-arguments/option<dot>lisp file, Up: Lisp files [Contents][Index]
option.lisp (file)
utility-arguments (system)
parser.lisp
*separator* (special variable)
Next: The utility-arguments/usage<dot>lisp file, Previous: The utility-arguments/parser<dot>lisp file, Up: Lisp files [Contents][Index]
parser.lisp (file)
utility-arguments (system)
operand.lisp
Previous: The utility-arguments/operand<dot>lisp file, Up: Lisp files [Contents][Index]
operand.lisp (file)
utility-arguments (system)
usage.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The utility-arguments package: |
packages.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions: | ||
| • Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables: | ||
| • Exported macros: | ||
| • Exported functions: | ||
| • Exported generic functions: | ||
| • Exported conditions: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Character that separates the arguments in a sequence. Setting it to nil, disables separation.
parser.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Define a new usage for operands and options.
NAME is a symbol and denotes the name of the usage.
OPERAND-LAMBDA-LIST describes operands. It resembles a lambda list
with required, optional, or rest parameter specifiers as the only
elements allowed. The parameters receive the operands’ values.
OPTION-LAMBDA-LIST describes options. It resembles a lambda list with
keyword and rest parameter specifiers as the only elements allowed.
The parameters receive the options’ values.
Optional and keyword parameter that specify an init-form make it
optional in this usage.
The forms of BODY are executed when the usage is applied.
usage.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Apply a usage to utility arguments.
USAGES is a list of symbols naming usages defined with defusage.
The lists OPERANDS and OPTIONS hold objects that complement the
parameters on usage lambda lists in providing additional type and
syntactic information. Correlation is established by object key and
parameter name.
UTILITY-ARGUMENTS is a list of strings that is parsed into operands
and options. The operand and options are matched against the usage
lambda lists to find a suitable usage which is then applied to the
operand’s and option’s values.
An error condition of utility-argument-error, no-such-usage, or usage-conflict may be signaled.
usage.lisp (file)
Find operand identifiable by KEY.
KEY is a symbol. OPERANDS is a list of operand objects.
operand.lisp (file)
Make a new operand.
KEY is a symbol that correlates the operand with a positional
parameter on a usage lambda list.
The parameter TYPE is documented in make-option-with-argument.
operand.lisp (file)
Make a new option flag.
Its number of appearances on a utility argument list is the assumed
value.
The parameters KEY, SHORT, and LONG are documented in make-option-with-argument.
option.lisp (file)
Make a new option that receives one argument.
KEY is a symbol that correlates the option with a keyword parameter on
a usage lambda list.
SHORT is a case-sensitive character. LONG is a case-insensitive but
case-preserving string. Both designators are equivalent and request
the option on a utility argument list. At least one of the two must
be specified.
TYPE is a Lisp type specifier the object must conform to the Lisp
reader builds from the received argument. The built object becomes
the assumed value.
TYPE is a function of two string arguments: the first of which is the received argument for the option, and the second the designator that requested the option. The object returned becomes the assumed value.
TYPE is nil, the received argument is the assumed value.
option.lisp (file)
Make a new option that optionally receives one argument.
If the option doesn’t receive an argument, nil is assumed.
The parameters KEY, SHORT, LONG, and TYPE are documented in make-option-with-argument.
option.lisp (file)
Make a new option that optionally receives a sequence of arguments.
If the option doesn’t receive an argument, nil is assumed. See also
make-option-with-sequence.
The parameters KEY, SHORT, LONG, and TYPE are documented in make-option-with-argument.
option.lisp (file)
Make a new option that receives a sequence of arguments.
Multiple arguments in a sequence are separated from each other by the
separator registered with *separator*.
Received arguments are subject to type parsing as described in
make-option-with-argument. The assumed values are collected into a
list by order of utility arguments.
The parameters KEY, SHORT, LONG, and TYPE are documented in make-option-with-argument.
option.lisp (file)
error.lisp (file)
error.lisp (file)
error.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
error.lisp (file)
Find option identifiable by ITEM.
ITEM is either a symbol, character, or a string. OPTIONS is a list of option objects.
option.lisp (file)
error.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Condition signaled if no suitable usage was found.
error.lisp (file)
usage-error (condition)
utility-arguments (method)
:utility-arguments
utility-arguments (generic function)
Condition signaled if more than one suitable usage was found.
error.lisp (file)
usage-error (condition)
conflicting-usages (method)
:usages
conflicting-usages (generic function)
Condition signaled for usage related errors.
error.lisp (file)
error (condition)
Condition signaled for utility argument related errors, such as bad syntax, unknown options, or type errors.
error.lisp (file)
error (condition)
utility-argument-error-text (method)
:text
utility-argument-error-text (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal functions: | ||
| • Internal generic functions: | ||
| • Internal classes: |
Next: Internal generic functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
utils.lisp (file)
utils.lisp (file)
usage.lisp (file)
parser.lisp (file)
parser.lisp (file)
error.lisp (file)
usage.lisp (file)
error.lisp (file)
error.lisp (file)
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
parser.lisp (file)
error.lisp (file)
error.lisp (file)
utils.lisp (file)
usage.lisp (file)
usage.lisp (file)
parser.lisp (file)
operand.lisp (file)
usage.lisp (file)
option.lisp (file)
parser.lisp (file)
parser.lisp (file)
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
parser.lisp (file)
utils.lisp (file)
parser.lisp (file)
error.lisp (file)
utils.lisp (file)
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
parser.lisp (file)
error.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
operand.lisp (file)
standard-object (class)
initialize-instance (method)
:key
:type
option.lisp (file)
standard-object (class)
initialize-instance (method)
:key
:short
:long
:type
option.lisp (file)
option (class)
parse-option (method)
option.lisp (file)
option (class)
parse-option (method)
option.lisp (file)
option (class)
parse-option (method)
option.lisp (file)
option (class)
parse-option (method)
option.lisp (file)
option (class)
parse-option (method)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index: | ||
| • Function index: | ||
| • Variable index: | ||
| • Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L U |
|---|
| Jump to: | F L U |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A B C D E F G I L M N O P S T U |
|---|
| Jump to: | A B C D E F G I L M N O P S T U |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
K L S T U |
|---|
| Jump to: | *
K L S T U |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C N O P S U |
|---|
| Jump to: | C N O P S U |
|---|