The command-line-arguments Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The command-line-arguments Reference Manual

This is the command-line-arguments Reference Manual, version 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Dec 02 10:02:51 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

command-line-arguments

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.

Usage

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

Examples

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.

Homepage

http://common-lisp.net/project/qitab/

See also

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: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 command-line-arguments

Maintainer

Eric Schulte

Author

Francois-Rene Rideau

License

MIT

Description

small library to deal with command-line arguments

Long Description

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

Version

2.0.0

Source

command-line-arguments.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 command-line-arguments.asd

Location

command-line-arguments.asd

Systems

command-line-arguments (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 command-line-arguments/pkgdcl.lisp

Parent

command-line-arguments (system)

Location

pkgdcl.lisp

Packages

command-line-arguments


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 command-line-arguments/argv.lisp

Dependency

pkgdcl.lisp (file)

Parent

command-line-arguments (system)

Location

argv.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 command-line-arguments/parse.lisp

Dependency

pkgdcl.lisp (file)

Parent

command-line-arguments (system)

Location

parse.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 command-line-arguments/help.lisp

Dependency

pkgdcl.lisp (file)

Parent

command-line-arguments (system)

Location

help.lisp

Exported Definitions

show-option-help (function)

Internal Definitions

split-sequence (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 command-line-arguments

Source

pkgdcl.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

Special Variable: *command-line-options*

command-line options as parsed into a plist

Package

command-line-arguments

Source

parse.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: compute-and-process-command-line-options SPECIFICATION
Package

command-line-arguments

Source

argv.lisp (file)

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

command-line-arguments

Source

argv.lisp (file)

Function: handle-command-line SPECIFICATION FUNCTION &key POSITIONAL-ARITY REST-ARITY NAME COMMAND-LINE
Package

command-line-arguments

Source

argv.lisp (file)

Function: process-command-line-options SPECIFICATION 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 (file)

Function: show-option-help SPECIFICATION &key STREAM SORT-NAMES DOCSTRING
Package

command-line-arguments

Source

help.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

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

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

name (generic function)

Slot: arguments
Initargs

:arguments

Readers

arguments (generic function)

Slot: rest-arity
Initargs

:rest-arity

Readers

rest-arity (generic function)

Slot: positional-arity
Initargs

:positional-arity

Readers

positional-arity (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: actual-action-from-spec NAME &key ACTION
Package

command-line-arguments

Source

parse.lisp (file)

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

Function: command-line-action ACTION &optional VALUE
Package

command-line-arguments

Source

parse.lisp (file)

Function: command-line-option-specification OPTION
Package

command-line-arguments

Source

parse.lisp (file)

Function: decompose-long-option-string STRING
Package

command-line-arguments

Source

parse.lisp (file)

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

Function: finalize-list NAME SYMBOL OPTIONAL ACTUAL-ACTION
Package

command-line-arguments

Source

parse.lisp (file)

Function: get-option-parameter OPTION TYPE OPTIONAL
Package

command-line-arguments

Source

parse.lisp (file)

Function: invoke-command-line-handler FUNCTION OPTIONS ARGUMENTS &key POSITIONAL-ARITY REST-ARITY NAME
Package

command-line-arguments

Source

argv.lisp (file)

Function: long-option-p ARG

ARG is a string. Is it like –XXX ?

Package

command-line-arguments

Source

parse.lisp (file)

Function: make-negated-names NAMELIST &optional NEGATION
Package

command-line-arguments

Source

parse.lisp (file)

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

Function: negated-short-option-p ARG

ARG is a string. Is it like +X ?

Package

command-line-arguments

Source

parse.lisp (file)

Function: option-end-p ARG
Package

command-line-arguments

Source

parse.lisp (file)

Function: option-like-p ARG
Package

command-line-arguments

Source

parse.lisp (file)

Function: option-name OPTION-DESIGNATOR
Package

command-line-arguments

Source

parse.lisp (file)

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

Function: process-long-option S
Package

command-line-arguments

Source

parse.lisp (file)

Function: process-option OPTION VALIDP ACTION PARAMETER TYPE OPTIONAL
Package

command-line-arguments

Source

parse.lisp (file)

Function: process-short-option C &key NEGATED
Package

command-line-arguments

Source

parse.lisp (file)

Function: short-option-p ARG

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

Package

command-line-arguments

Source

parse.lisp (file)

Function: split-sequence SEQUENCE DELIMITER
Package

command-line-arguments

Source

help.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: arguments CONDITION
Package

command-line-arguments

Methods
Method: arguments (CONDITION command-line-arity)
Source

argv.lisp (file)

Generic Function: name CONDITION
Package

command-line-arguments

Methods
Method: name (CONDITION command-line-arity)
Source

argv.lisp (file)

Generic Function: positional-arity CONDITION
Package

command-line-arguments

Methods
Method: positional-arity (CONDITION command-line-arity)
Source

argv.lisp (file)

Generic Function: rest-arity CONDITION
Package

command-line-arguments

Methods
Method: rest-arity (CONDITION command-line-arity)
Source

argv.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
command-line-arguments.asd: The command-line-arguments․asd file
command-line-arguments/argv.lisp: The command-line-arguments/argv․lisp file
command-line-arguments/help.lisp: The command-line-arguments/help․lisp file
command-line-arguments/parse.lisp: The command-line-arguments/parse․lisp file
command-line-arguments/pkgdcl.lisp: The command-line-arguments/pkgdcl․lisp file

F
File, Lisp, command-line-arguments.asd: The command-line-arguments․asd file
File, Lisp, command-line-arguments/argv.lisp: The command-line-arguments/argv․lisp file
File, Lisp, command-line-arguments/help.lisp: The command-line-arguments/help․lisp file
File, Lisp, command-line-arguments/parse.lisp: The command-line-arguments/parse․lisp file
File, Lisp, command-line-arguments/pkgdcl.lisp: The command-line-arguments/pkgdcl․lisp file

L
Lisp File, command-line-arguments.asd: The command-line-arguments․asd file
Lisp File, command-line-arguments/argv.lisp: The command-line-arguments/argv․lisp file
Lisp File, command-line-arguments/help.lisp: The command-line-arguments/help․lisp file
Lisp File, command-line-arguments/parse.lisp: The command-line-arguments/parse․lisp file
Lisp File, command-line-arguments/pkgdcl.lisp: The command-line-arguments/pkgdcl․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

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: Internal functions
arguments: Internal generic functions
arguments: Internal generic functions

C
coerce-option-parameter: Internal functions
command-line-action: Internal functions
command-line-option-specification: Internal functions
compute-and-process-command-line-options: Exported functions

D
decompose-long-option-string: Internal functions
define-command: Exported macros
do-process-command-line-options: Internal functions

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

G
Generic Function, arguments: Internal generic functions
Generic Function, name: Internal generic functions
Generic Function, positional-arity: Internal generic functions
Generic Function, rest-arity: Internal generic functions
get-command-line-arguments: Exported functions
get-option-parameter: Internal functions

H
handle-command-line: Exported functions

I
invoke-command-line-handler: Internal functions

L
long-option-p: Internal functions

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

N
name: Internal generic functions
name: Internal generic functions
negated-short-option-p: Internal functions

O
option-end-p: Internal functions
option-like-p: Internal functions
option-name: Internal functions

P
positional-arity: Internal generic functions
positional-arity: Internal generic functions
prepare-command-line-options-specification: Internal functions
process-command-line-options: Exported functions
process-long-option: Internal functions
process-option: Internal functions
process-short-option: Internal functions

R
rest-arity: Internal generic functions
rest-arity: Internal generic functions

S
short-option-p: Internal functions
show-option-help: Exported functions
split-sequence: Internal functions

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   N   P   R   S  
Index Entry  Section

*
*command-line-option-specification*: Exported special variables
*command-line-options*: Exported special variables

A
arguments: Exported conditions

N
name: Exported conditions

P
positional-arity: Exported conditions

R
rest-arity: Exported conditions

S
Slot, arguments: Exported conditions
Slot, name: Exported conditions
Slot, positional-arity: Exported conditions
Slot, rest-arity: Exported conditions
Special Variable, *command-line-option-specification*: Exported special variables
Special Variable, *command-line-options*: Exported special variables

Jump to:   *  
A   N   P   R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
command-line-arguments: The command-line-arguments system
command-line-arguments: The command-line-arguments package
command-line-arity: Exported conditions
Condition, command-line-arity: Exported conditions

P
Package, command-line-arguments: The command-line-arguments package

S
System, command-line-arguments: The command-line-arguments system

Jump to:   C   P   S