The command-line-arguments Reference Manual

This is the command-line-arguments Reference Manual, version 2.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:50:41 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 command-line-arguments

small library to deal with command-line arguments

Maintainer

Eric Schulte

Author

Francois-Rene Rideau

License

MIT

Long Description

A library to abstract away the parsing of Unix-style command-line arguments

Version

2.0.0

Source

command-line-arguments.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 command-line-arguments/command-line-arguments.asd

Source

command-line-arguments.asd.

Parent Component

command-line-arguments (system).

ASDF Systems

command-line-arguments.


3.1.2 command-line-arguments/pkgdcl.lisp

Source

command-line-arguments.asd.

Parent Component

command-line-arguments (system).

Packages

command-line-arguments.


3.1.3 command-line-arguments/argv.lisp

Dependency

pkgdcl.lisp (file).

Source

command-line-arguments.asd.

Parent Component

command-line-arguments (system).

Public Interface
Internals

3.1.4 command-line-arguments/parse.lisp

Dependency

pkgdcl.lisp (file).

Source

command-line-arguments.asd.

Parent Component

command-line-arguments (system).

Public Interface
Internals

3.1.5 command-line-arguments/help.lisp

Dependency

pkgdcl.lisp (file).

Source

command-line-arguments.asd.

Parent Component

command-line-arguments (system).

Public Interface

show-option-help (function).

Internals

split-sequence (function).


4 Packages

Packages are listed by definition order.


4.1 command-line-arguments

Source

pkgdcl.lisp.

Use List
  • common-lisp.
  • uiop/driver.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *command-line-option-specification*

the (prepared) specification for how to parse command-line options

Package

command-line-arguments.

Source

parse.lisp.

Special Variable: *command-line-options*

command-line options as parsed into a plist

Package

command-line-arguments.

Source

parse.lisp.


5.1.2 Macros

Macro: define-command (name args pre-help post-help &rest body)

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))

Package

command-line-arguments.

Source

parse.lisp.


5.1.3 Ordinary functions

Function: compute-and-process-command-line-options (specification)
Package

command-line-arguments.

Source

argv.lisp.

Function: get-command-line-arguments ()
Package

command-line-arguments.

Source

argv.lisp.

Function: handle-command-line (specification function &key positional-arity rest-arity name command-line)
Package

command-line-arguments.

Source

argv.lisp.

Function: process-command-line-options (specification &optional command-line)

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.

Package

command-line-arguments.

Source

parse.lisp.

Function: show-option-help (specification &key stream sort-names docstring)
Package

command-line-arguments.

Source

help.lisp.


5.1.4 Conditions

Condition: command-line-arity

Indicates the wrong number of arguments were given on the command line.

Package

command-line-arguments.

Source

argv.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: arguments
Initargs

:arguments

Readers

arguments.

Writers

This slot is read-only.

Slot: rest-arity
Initargs

:rest-arity

Readers

rest-arity.

Writers

This slot is read-only.

Slot: positional-arity
Initargs

:positional-arity

Readers

positional-arity.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Ordinary functions

Function: actual-action-from-spec (name &key action)
Package

command-line-arguments.

Source

parse.lisp.

Function: coerce-option-parameter (option string type)

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.

Package

command-line-arguments.

Source

parse.lisp.

Function: command-line-action (action &optional value)
Package

command-line-arguments.

Source

parse.lisp.

Function: command-line-option-specification (option)
Package

command-line-arguments.

Source

parse.lisp.

Function: decompose-long-option-string (string)
Package

command-line-arguments.

Source

parse.lisp.

Function: do-process-command-line-options ()

Remove all the options and values from *COMMAND-LINE-ARGUMENTS*. Process each option.

Package

command-line-arguments.

Source

parse.lisp.

Function: finalize-list (name symbol optional actual-action)
Package

command-line-arguments.

Source

parse.lisp.

Function: get-option-parameter (option type optional)
Package

command-line-arguments.

Source

parse.lisp.

Function: invoke-command-line-handler (function options arguments &key positional-arity rest-arity name)
Package

command-line-arguments.

Source

argv.lisp.

Function: long-option-p (arg)

ARG is a string. Is it like –XXX ?

Package

command-line-arguments.

Source

parse.lisp.

Function: make-negated-names (namelist &optional negation)
Package

command-line-arguments.

Source

parse.lisp.

Function: make-option-action (p name &key action list optional initial-value &allow-other-keys)

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.

Package

command-line-arguments.

Source

parse.lisp.

Function: negated-short-option-p (arg)

ARG is a string. Is it like +X ?

Package

command-line-arguments.

Source

parse.lisp.

Function: option-end-p (arg)
Package

command-line-arguments.

Source

parse.lisp.

Function: option-like-p (arg)
Package

command-line-arguments.

Source

parse.lisp.

Function: option-name (option-designator)
Package

command-line-arguments.

Source

parse.lisp.

Function: prepare-command-line-options-specification (specification)

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.

Package

command-line-arguments.

Source

parse.lisp.

Function: process-long-option (s)
Package

command-line-arguments.

Source

parse.lisp.

Function: process-option (option validp action parameter type optional)
Package

command-line-arguments.

Source

parse.lisp.

Function: process-short-option (c &key negated)
Package

command-line-arguments.

Source

parse.lisp.

Function: short-option-p (arg)

ARG is a string. Is it like -X, but not – ?

Package

command-line-arguments.

Source

parse.lisp.

Function: split-sequence (sequence delimiter)
Package

command-line-arguments.

Source

help.lisp.


5.2.2 Generic functions

Generic Reader: arguments (condition)
Package

command-line-arguments.

Methods
Reader Method: arguments ((condition command-line-arity))
Source

argv.lisp.

Target Slot

arguments.

Generic Reader: name (condition)
Package

command-line-arguments.

Methods
Reader Method: name ((condition command-line-arity))
Source

argv.lisp.

Target Slot

name.

Generic Reader: positional-arity (condition)
Package

command-line-arguments.

Methods
Reader Method: positional-arity ((condition command-line-arity))
Source

argv.lisp.

Target Slot

positional-arity.

Generic Reader: rest-arity (condition)
Package

command-line-arguments.

Methods
Reader Method: rest-arity ((condition command-line-arity))
Source

argv.lisp.

Target Slot

rest-arity.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   F   G   H   I   L   M   N   O   P   R   S  
Index Entry  Section

A
actual-action-from-spec: Private ordinary functions
arguments: Private generic functions
arguments: Private generic functions

C
coerce-option-parameter: Private ordinary functions
command-line-action: Private ordinary functions
command-line-option-specification: Private ordinary functions
compute-and-process-command-line-options: Public ordinary functions

D
decompose-long-option-string: Private ordinary functions
define-command: Public macros
do-process-command-line-options: Private ordinary functions

F
finalize-list: Private ordinary functions
Function, actual-action-from-spec: Private ordinary functions
Function, coerce-option-parameter: Private ordinary functions
Function, command-line-action: Private ordinary functions
Function, command-line-option-specification: Private ordinary functions
Function, compute-and-process-command-line-options: Public ordinary functions
Function, decompose-long-option-string: Private ordinary functions
Function, do-process-command-line-options: Private ordinary functions
Function, finalize-list: Private ordinary functions
Function, get-command-line-arguments: Public ordinary functions
Function, get-option-parameter: Private ordinary functions
Function, handle-command-line: Public ordinary functions
Function, invoke-command-line-handler: Private ordinary functions
Function, long-option-p: Private ordinary functions
Function, make-negated-names: Private ordinary functions
Function, make-option-action: Private ordinary functions
Function, negated-short-option-p: Private ordinary functions
Function, option-end-p: Private ordinary functions
Function, option-like-p: Private ordinary functions
Function, option-name: Private ordinary functions
Function, prepare-command-line-options-specification: Private ordinary functions
Function, process-command-line-options: Public ordinary functions
Function, process-long-option: Private ordinary functions
Function, process-option: Private ordinary functions
Function, process-short-option: Private ordinary functions
Function, short-option-p: Private ordinary functions
Function, show-option-help: Public ordinary functions
Function, split-sequence: Private ordinary functions

G
Generic Function, arguments: Private generic functions
Generic Function, name: Private generic functions
Generic Function, positional-arity: Private generic functions
Generic Function, rest-arity: Private generic functions
get-command-line-arguments: Public ordinary functions
get-option-parameter: Private ordinary functions

H
handle-command-line: Public ordinary functions

I
invoke-command-line-handler: Private ordinary functions

L
long-option-p: Private ordinary functions

M
Macro, define-command: Public macros
make-negated-names: Private ordinary functions
make-option-action: Private ordinary functions
Method, arguments: Private generic functions
Method, name: Private generic functions
Method, positional-arity: Private generic functions
Method, rest-arity: Private generic functions

N
name: Private generic functions
name: Private generic functions
negated-short-option-p: Private ordinary functions

O
option-end-p: Private ordinary functions
option-like-p: Private ordinary functions
option-name: Private ordinary functions

P
positional-arity: Private generic functions
positional-arity: Private generic functions
prepare-command-line-options-specification: Private ordinary functions
process-command-line-options: Public ordinary functions
process-long-option: Private ordinary functions
process-option: Private ordinary functions
process-short-option: Private ordinary functions

R
rest-arity: Private generic functions
rest-arity: Private generic functions

S
short-option-p: Private ordinary functions
show-option-help: Public ordinary functions
split-sequence: Private ordinary functions