Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the command-line-arguments Reference Manual, version 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:09:41 2020 GMT+0.
| • Introduction | What command-line-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 |
A library for parsing command-line arguments.
Use it in conjunction with asdf:program-op or cl-launch for portable processing of command-line arguments.
This library is woefully under-documented. See the examples below, and read the source code for details. Here is what a prototypical use looks like:
(defparameter +command-line-spec+
'(((#\b) :type boolean :optional t :documentation "what optional -b flag does")
(("check" #\c) :type string :optional t :documentation "a --check or -c flag that takes a string")
(("verbose") :type boolean :optional t :documentation "only a verbose --verbose is accepted")
(("warn" "warning" #\w) :type boolean :optional t :documentation "multiple spellings possible")
(("help" #\h #\?) :type boolean :optional t :documentation "--help -h -?, good practice to have")
(("version" #\V) :type boolean :optional t :documentation "--version or -V, you get the idea")))
;; for the positional arguments, see below :positional-arity and :rest-arity
(defun my-program-function (arg1 arg2 rest-args &key b check verbose warn help version)
(when help (show-option-help +command-line-spec+ :sort-names t) (uiop:quit))
(when version (show-version) (uiop:quit))
...)
(defun main (args)
(handle-command-line
;; the spec as above, or prepared with prepare-command-line-options-specification
+command-line-spec+
;; the function to call with the arguments as parsed
'my-program-function
;; the arguments to parse
:command-line args
;; the program name to use in case of an error message
:name "my-program"
;; the number of mandatory positional arguments for this command (default: 0)
:positional-arity 2
;; What to do with the rest of the positional arguments.
;; T means pass the list of the rest of the command-line-arguments as one lisp argument.
;; NIL means ignore it. A keyword means pass this rest as a keyword argument.
:rest-arity t))
The define-command macro may be used to simultaneously define the
following three functions which are useful for defining a function
which may be invoked from the command line. For example, the
following invocation of define-command on FOO results in:
(define-command foo (noun verb &spec +command-line-spec+ &aux scratch)
"Usage: foo NOUN VERB [OPTIONS...]
Do VERB to NOUN according to OPTIONS."
#.(format nil "~%Built with ~a version ~a.~%"
(lisp-implementation-type)
(lisp-implementation-version))
(declare (verbose))
(when help (show-help-for-foo))
#|...implementation...|#)
show-help-for-FOO
: Prints help and option information for FOO to STDOUT and then
exits with uiop:quit.
The docstring passed to `define-command` becomes the help text
printed before options. A second docstring passed as the fourth
argument to `define-command` is printed after the options.
run-FOO
: Similar to the main example above this function is meant to be
used as a defsystem :entry-point. It runs FOO on the command
line arguments by invoking handle-command-line.
FOO
: The &body passed to define-command becomes the body of the FOO
function. The positional required command line arguments become
named arguments to FOO and the command line options passed in
behind the &spec keyword in the argument list become keyword
arguments to FOO. When supplied :initial-value properties of
command lines become defaults of the corresponding keyword
arguments. When supplied :action properties of command line
arguments have calls to their actions prepended to the body of the
function. Actions are only called when the keyword argument has a
non-nil value.
The macro-expanded prototype for FOO in this example would be the
following.
(DEFUN FOO (NOUN VERB &KEY B CHECK VERBOSE WARN HELP VERSION &AUX SCRATCH))
For very simple examples of actual uses, see my tthsum clone in Lisp or my workout-timer.
For a much more elaborate use, see xcvb — unhappily, XCVB has gone mostly unmaintained since 2012, so the example might not be usefully runnable.
http://common-lisp.net/project/qitab/
For a fancier take on the same general idea, see Didier Verna's CLON:
http://www.lrde.epita.fr/~didier/software/lisp/clon.php
CLON has much more features than this library, but is much more complex and slighly less portable
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The command-line-arguments system |
Eric Schulte
Francois-Rene Rideau
MIT
small library to deal with command-line arguments
A library to abstract away the parsing of Unix-style command-line arguments
2.0.0
command-line-arguments.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The command-line-arguments/pkgdcl․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
command-line-arguments.asd
command-line-arguments (system)
Next: The command-line-arguments/argv․lisp file, Previous: The command-line-arguments․asd file, Up: Lisp files [Contents][Index]
command-line-arguments (system)
pkgdcl.lisp
Next: The command-line-arguments/parse․lisp file, Previous: The command-line-arguments/pkgdcl․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
command-line-arguments (system)
argv.lisp
Next: The command-line-arguments/help․lisp file, Previous: The command-line-arguments/argv․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
command-line-arguments (system)
parse.lisp
Previous: The command-line-arguments/parse․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
command-line-arguments (system)
help.lisp
show-option-help (function)
split-sequence (function)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The command-line-arguments package |
pkgdcl.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 conditions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
the (prepared) specification for how to parse command-line options
parse.lisp (file)
command-line options as parsed into a plist
parse.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Defines show-help-for-NAME, run-NAME, and NAME functions.
The ‘define-command’ macro may be used to simultaneously define the
following three functions which are useful for defining a function
which may be invoked from the command line. For example, the
following invocation of ‘define-command’ on FOO results in:
(define-command foo (noun verb &spec +command-line-spec+ &aux scratch)
"Usage: foo NOUN VERB [OPTIONS...]
Do VERB to NOUN according to OPTIONS."
#.(format nil "~%Built with ~a version ~a.~%"
(lisp-implementation-type)
(lisp-implementation-version))
(declare (verbose))
(when help (show-help-for-foo))
#|...implementation...|#)
show-help-for-FOO
: Prints help and option information for FOO to STDOUT.
The docstring passed to ‘define-command’ becomes the help text
printed before options. A second docstring passed as the fourth
argument to ‘define-command’ is printed after the options.
run-FOO
: This function is meant to be used as a ‘defsystem’ :ENTRY-POINT.
It runs FOO on the command line arguments by invoking
‘handle-command-line’.
FOO
: The &BODY passed to ‘define-command’ becomes the body of the FOO
function. The positional required command line arguments become
named arguments to FOO and the command line options passed in
behind the &SPEC keyword in the argument list become keyword
arguments to FOO.
The macro-expanded prototype for FOO in this example would be the
following (where all keyword arguments are option names from
+command-line-spec+).
(DEFUN FOO (NOUN VERB &KEY B CHECK VERBOSE WARN HELP VERSION &AUX SCRATCH))
parse.lisp (file)
Next: Exported conditions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
argv.lisp (file)
argv.lisp (file)
argv.lisp (file)
SPECIFICATION is a list as described above.
COMMAND-LINE is the list of tokens to be parsed.
Return two values:
a list of alternating actions and values, and
a list of the arguments remaining after the various specified options.
parse.lisp (file)
help.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
Indicates the wrong number of arguments were given on the command line.
argv.lisp (file)
error (condition)
:name
name (generic function)
:arguments
arguments (generic function)
:rest-arity
rest-arity (generic function)
:positional-arity
positional-arity (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal functions | ||
| • Internal generic functions |
Next: Internal generic functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
parse.lisp (file)
Given a STRING option argument and a TYPE of argument,
return the argument value as a Lisp object.
OPTION is the name of the option to which the argument is to be passed,
for the sake of error messages.
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
Remove all the options and values from *COMMAND-LINE-ARGUMENTS*. Process each option.
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
argv.lisp (file)
ARG is a string. Is it like –XXX ?
parse.lisp (file)
parse.lisp (file)
This is called for each option specification when preparing for parsing, and
computes the action function to call (with optional value if provided)
when the option is found on a command-line.
P is the hash-table of actions.
NAME is the first name of this option, a string or a character.
The keywords are option options for this option specification.
parse.lisp (file)
ARG is a string. Is it like +X ?
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
Given a SPECIFICATION, return a hash-table mapping
option names to a vector of
the action function to call when encountering the option,
the type of option arguments accepted, and
whether the option is optional.
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
parse.lisp (file)
ARG is a string. Is it like -X, but not – ?
parse.lisp (file)
help.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
argv.lisp (file)
argv.lisp (file)
argv.lisp (file)
argv.lisp (file)
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: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A C D F G H I L M N O P R S |
|---|
| Jump to: | A C D F G H I L M N O P R S |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
A N P R S |
|---|
| Jump to: | *
A N P R S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C P S |
|---|
| Jump to: | C P S |
|---|