The cl-argparse Reference Manual

This is the cl-argparse Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 14:57:56 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-argparse

A python argparse inspired command line parser library

Maintainer

Simon Koch <>

Author

Simon Koch <>

License

MIT

Source

cl-argparse.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 cl-argparse/cl-argparse.asd

Source

cl-argparse.asd.

Parent Component

cl-argparse (system).

ASDF Systems

cl-argparse.


3.1.2 cl-argparse/package.lisp

Source

cl-argparse.asd.

Parent Component

cl-argparse (system).

Packages

de.halcony.argparse.


3.1.3 cl-argparse/classes.lisp

Dependency

package.lisp (file).

Source

cl-argparse.asd.

Parent Component

cl-argparse (system).

Public Interface
Internals

3.1.4 cl-argparse/methods.lisp

Dependencies
Source

cl-argparse.asd.

Parent Component

cl-argparse (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 de.halcony.argparse

Source

package.lisp.

Nickname

cl-argparse

Use List
  • common-lisp.
  • common-lisp-user.
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 Macros

Macro: create-main-parser ((var &optional description program-name) &body elements)

Macro for creating the main parser. Always names the parser main-parser (required for parsing
to work) and adds the help flag. Allows to add further parameters to the parser. Returns the parser at the end

Package

de.halcony.argparse.

Source

methods.lisp.

Macro: create-sub-parser ((name &optional description) &body elements)

Macro for creating a sub parser, provides name as the subparser name to the help message, adds a help flag and allows to add further parameters to the parser. Returns the parser at the end.

Package

de.halcony.argparse.

Source

methods.lisp.


5.1.2 Generic functions

Generic Function: add-default (parser &key var default)
Package

de.halcony.argparse.

Methods
Method: add-default ((parser parser) &key var default)

Adds a default value to the parser value table. I.e., allows to define sub parser specific default values that cannot be set via the cmd

Source

methods.lisp.

Generic Function: add-flag (parser &key short long help var)
Package

de.halcony.argparse.

Methods
Method: add-flag ((parser parser) &key short long help var)

Adds a flag to the given parser using short as the short value of the flag (has to be lead with a single - in the argument list. The var determines the name under which it is stored in the parser value table. long determines the long version of the flag (lead with two -) and help is the help string used to generate the help message

Source

methods.lisp.

Generic Function: add-generic-parser (parser gen)
Package

de.halcony.argparse.

Methods
Method: add-generic-parser ((parser parser) (gen parser))

Adds a generic parser to the given parser. Basically merges the generic parser into the given parser, adding all the flags, optional, and positional utilities. Subparsers are ignored.

Source

methods.lisp.

Generic Function: add-help (parser)
Package

de.halcony.argparse.

Methods
Method: add-help ((parser parser))

Adds the help flag to the parser

Source

methods.lisp.

Generic Function: add-optional (parser &key short long default help var)
Package

de.halcony.argparse.

Methods
Method: add-optional ((parser parser) &key short long default help var)

Adds an optional value to the given parser. short is the to be used parameter name (with a single leading -). Var is the name under which to store the value in the parser table. long is the long version of the name (lead with two –). Default determines the default value and help is the help message string to be used in the auto generated help message

Source

methods.lisp.

Generic Function: add-positional (parser &key name help)
Package

de.halcony.argparse.

Methods
Method: add-positional ((parser parser) &key name help)

Adds a positional argument to the given parser. Name is both the name of the positional used in the help message as well as the name under which the value is stored. Help defines the string to be used in the auto generated help message

Source

methods.lisp.

Generic Function: add-subparser (parser subparser)
Package

de.halcony.argparse.

Methods
Method: add-subparser ((parser parser) (subparser parser))

Adds the given sub parser to the given parser.

Source

methods.lisp.

Generic Function: get-key-value-pairs (parser)
Package

de.halcony.argparse.

Methods
Method: get-key-value-pairs ((parser parser))
Source

methods.lisp.

Generic Function: get-value (name parser)
Package

de.halcony.argparse.

Methods
Method: get-value (name (parser parser))

Get the stored value for name from the given parser.

Source

methods.lisp.

Generic Function: parse (parser argv)
Package

de.halcony.argparse.

Methods
Method: parse ((parser parser) argv)

This is the main parsing method and providing a parser and a string of arguments it extracts and enters all provided parameters into the parser

Source

methods.lisp.


5.1.3 Standalone methods

Method: print-object ((cancel-parsing-error cancel-parsing-error) stream)
Source

classes.lisp.

Method: print-object ((parser parser) stream)
Source

classes.lisp.

Method: print-object ((optional optional) stream)
Source

classes.lisp.

Method: print-object ((positional positional) stream)
Source

classes.lisp.

Method: print-object ((cmd-arg-error cmd-arg-error) stream)
Source

classes.lisp.

Method: print-object ((flag flag) stream)
Source

classes.lisp.


5.1.4 Conditions

Condition: cancel-parsing-error
Package

de.halcony.argparse.

Source

classes.lisp.

Direct superclasses

simple-error.

Direct methods
Direct slots
Slot: format-control
Initform

(quote "")

Initargs

:format-control

Readers

format-control.

Writers

This slot is read-only.

Slot: format-arguments
Initform

(quote (list))

Initargs

:format-arguments

Readers

format-arguments.

Writers

This slot is read-only.


5.1.5 Classes

Class: parser
Package

de.halcony.argparse.

Source

classes.lisp.

Direct methods
Direct slots
Slot: description
Initform

"no description"

Initargs

:description

Readers

description.

Writers

This slot is read-only.

Slot: program-name
Initform

"program.lisp"

Initargs

:program-name

Readers

program-name.

Writers

This slot is read-only.

Slot: previous-parsers
Initform

(list)

Readers

previous-parsers.

Writers

This slot is read-only.

Slot: name
Initform

""

Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: flags
Initform

(list)

Readers

flags.

Writers

This slot is read-only.

Slot: optionals
Initform

(list)

Readers

optionals.

Writers

This slot is read-only.

Slot: positionals
Initform

(list)

Readers

positionals.

Writers

This slot is read-only.

Slot: subparsers
Initform

(list)

Readers

subparsers.

Writers

This slot is read-only.

Slot: defaults
Initform

(make-hash-table :test (quote equalp))

Readers

defaults.

Writers

This slot is read-only.

Slot: table
Initform

(make-hash-table :test (quote equalp))

Readers

table.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Macros

Macro: aif (condition if then)
Package

de.halcony.argparse.

Source

methods.lisp.

Macro: create-mockup-parser (&rest key-value-list)

allows for the creation of a mockup parser to enable creating a parser without actually parsing command line parameters

Package

de.halcony.argparse.

Source

methods.lisp.


5.2.2 Ordinary functions

Function: merge-tables (table-a table-b)

merges table-b into table-a

Package

de.halcony.argparse.

Source

methods.lisp.


5.2.3 Generic functions

Generic Reader: default (object)
Package

de.halcony.argparse.

Methods
Reader Method: default ((optional optional))

automatically generated reader method

Source

classes.lisp.

Target Slot

default.

Generic Reader: defaults (object)
Package

de.halcony.argparse.

Methods
Reader Method: defaults ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

defaults.

Generic Reader: description (object)
Package

de.halcony.argparse.

Methods
Reader Method: description ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

description.

Generic Reader: flags (object)
Package

de.halcony.argparse.

Methods
Reader Method: flags ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

flags.

Generic Reader: format-arguments (condition)
Package

de.halcony.argparse.

Methods
Reader Method: format-arguments ((condition cancel-parsing-error))
Source

classes.lisp.

Target Slot

format-arguments.

Reader Method: format-arguments ((condition cmd-arg-error))
Source

classes.lisp.

Target Slot

format-arguments.

Generic Reader: format-control (condition)
Package

de.halcony.argparse.

Methods
Reader Method: format-control ((condition cancel-parsing-error))
Source

classes.lisp.

Target Slot

format-control.

Reader Method: format-control ((condition cmd-arg-error))
Source

classes.lisp.

Target Slot

format-control.

Generic Reader: help-message (object)
Package

de.halcony.argparse.

Methods
Reader Method: help-message ((positional positional))

automatically generated reader method

Source

classes.lisp.

Target Slot

help-message.

Reader Method: help-message ((optional optional))

automatically generated reader method

Source

classes.lisp.

Target Slot

help-message.

Reader Method: help-message ((flag flag))

automatically generated reader method

Source

classes.lisp.

Target Slot

help-message.

Generic Reader: long (object)
Package

de.halcony.argparse.

Methods
Reader Method: long ((optional optional))

automatically generated reader method

Source

classes.lisp.

Target Slot

long.

Reader Method: long ((flag flag))

automatically generated reader method

Source

classes.lisp.

Target Slot

long.

Generic Reader: name (object)
Package

de.halcony.argparse.

Methods
Reader Method: name ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

name.

Reader Method: name ((positional positional))

automatically generated reader method

Source

classes.lisp.

Target Slot

name.

Generic Reader: optionals (object)
Package

de.halcony.argparse.

Methods
Reader Method: optionals ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

optionals.

Generic Function: parse-flag (flag argv table)
Package

de.halcony.argparse.

Methods
Method: parse-flag ((help-flag help-flag) argv table)

Tries to parse (car argv) using the passed flag (i.e., help flag). If the flag is successfully parsed the help-flag-condition is signaled, else argv and nil is returned.

Source

methods.lisp.

Method: parse-flag ((flag flag) argv table)

This method tries to match the given (car argv) with the flag. If this succeeds the flag is entered into the parser value table and (cdr argv) and T is returned. If there is no match argv and nil is returned

Source

methods.lisp.

Generic Function: parse-optional (optional argv table)
Package

de.halcony.argparse.

Methods
Method: parse-optional ((optional optional) argv table)

Tries to parse (car argv) using the given optional. If the optional matches the defined table value is set to (cadr argv) and (cddr argv) and T are returned. Else argv and nil are returned

Source

methods.lisp.

Generic Function: parse-optionals (parser argv)
Package

de.halcony.argparse.

Methods
Method: parse-optionals ((parser parser) argv)

Given a parser and a list of strings this method extracts the provided flags and optional parameters and enters them into the parser table.
It returns the remaining list. The parsing either stops if all optionals or flags of the parser a filled or if the currently viewed list element does not match either an optional or flag.

Source

methods.lisp.

Generic Function: parse-positional (positional argv table)
Package

de.halcony.argparse.

Methods
Method: parse-positional ((positional positional) argv table)

Parses a positional argument, i.e., (car argv) and stores it in the given table. Throws an error in case no value is contained in argv. Returns (cdr argv) as it either always works or has to throw an error.

Source

methods.lisp.

Generic Function: parse-positionals (parser initial-argv)
Package

de.halcony.argparse.

Methods
Method: parse-positionals ((parser parser) initial-argv)

Given a parser and a list of strings this method extracts the provided positional parameters and enters them into the parser table. It returns the remaining list

Source

methods.lisp.

Generic Function: parse-subparsers (parser argv)
Package

de.halcony.argparse.

Methods
Method: parse-subparsers ((parser parser) argv)

Given a parser and a list of strings this method extracts the subparser from which the parsing continues and continues the parsing with this parser

Source

methods.lisp.

Generic Reader: positionals (object)
Package

de.halcony.argparse.

Methods
Reader Method: positionals ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

positionals.

Generic Reader: previous-parsers (object)
Package

de.halcony.argparse.

Methods
Reader Method: previous-parsers ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

previous-parsers.

Generic Function: print-help (parser)
Package

de.halcony.argparse.

Methods
Method: print-help ((parser parser))

Functionality to print the correct help message for the given parser

Source

methods.lisp.

Generic Reader: program-name (object)
Package

de.halcony.argparse.

Methods
Reader Method: program-name ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

program-name.

Generic Reader: short (object)
Package

de.halcony.argparse.

Methods
Reader Method: short ((optional optional))

automatically generated reader method

Source

classes.lisp.

Target Slot

short.

Reader Method: short ((flag flag))

automatically generated reader method

Source

classes.lisp.

Target Slot

short.

Generic Reader: subparsers (object)
Package

de.halcony.argparse.

Methods
Reader Method: subparsers ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

subparsers.

Generic Function: sync-parser (parser)
Package

de.halcony.argparse.

Methods
Method: sync-parser ((parser parser))

Syncs the current parser, i.e., merges the value table (for defaults) as well as append the list of previous parsers to the sub parser for generating the help message

Source

methods.lisp.

Generic Reader: table (object)
Package

de.halcony.argparse.

Methods
Reader Method: table ((parser parser))

automatically generated reader method

Source

classes.lisp.

Target Slot

table.

Generic Reader: var (object)
Package

de.halcony.argparse.

Methods
Reader Method: var ((optional optional))

automatically generated reader method

Source

classes.lisp.

Target Slot

var.

Reader Method: var ((flag flag))

automatically generated reader method

Source

classes.lisp.

Target Slot

var.


5.2.4 Conditions

Condition: cmd-arg-error
Package

de.halcony.argparse.

Source

classes.lisp.

Direct superclasses

simple-error.

Direct methods
Direct slots
Slot: format-control
Initform

(quote "")

Initargs

:format-control

Readers

format-control.

Writers

This slot is read-only.

Slot: format-arguments
Initform

(quote (list))

Initargs

:format-arguments

Readers

format-arguments.

Writers

This slot is read-only.

Condition: help-flag-condition
Package

de.halcony.argparse.

Source

classes.lisp.

Direct superclasses

simple-error.


5.2.5 Classes

Class: flag
Package

de.halcony.argparse.

Source

classes.lisp.

Direct subclasses

help-flag.

Direct methods
Direct slots
Slot: short
Initargs

:short

Readers

short.

Writers

This slot is read-only.

Slot: long
Initargs

:long

Readers

long.

Writers

This slot is read-only.

Slot: var
Initargs

:var

Readers

var.

Writers

This slot is read-only.

Slot: help-message
Initargs

:help-message

Readers

help-message.

Writers

This slot is read-only.

Class: help-flag
Package

de.halcony.argparse.

Source

classes.lisp.

Direct superclasses

flag.

Direct methods

parse-flag.

Direct slots
Slot: short
Initform

"h"

Slot: long
Initform

"help"

Slot: help-message
Initform

"displays this help message"

Class: optional
Package

de.halcony.argparse.

Source

classes.lisp.

Direct methods
Direct slots
Slot: short
Initargs

:short

Readers

short.

Writers

This slot is read-only.

Slot: long
Initargs

:long

Readers

long.

Writers

This slot is read-only.

Slot: var
Initargs

:var

Readers

var.

Writers

This slot is read-only.

Slot: default
Initargs

:default

Readers

default.

Writers

This slot is read-only.

Slot: help-message
Initargs

:help-message

Readers

help-message.

Writers

This slot is read-only.

Class: positional
Package

de.halcony.argparse.

Source

classes.lisp.

Direct methods
Direct slots
Slot: name
Initargs

:name

Readers

name.

Writers

This slot is read-only.

Slot: help-message
Initargs

:help-message

Readers

help-message.

Writers

This slot is read-only.


Appendix A Indexes


A.1 Concepts


A.2 Functions

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

A
add-default: Public generic functions
add-default: Public generic functions
add-flag: Public generic functions
add-flag: Public generic functions
add-generic-parser: Public generic functions
add-generic-parser: Public generic functions
add-help: Public generic functions
add-help: Public generic functions
add-optional: Public generic functions
add-optional: Public generic functions
add-positional: Public generic functions
add-positional: Public generic functions
add-subparser: Public generic functions
add-subparser: Public generic functions
aif: Private macros

C
create-main-parser: Public macros
create-mockup-parser: Private macros
create-sub-parser: Public macros

D
default: Private generic functions
default: Private generic functions
defaults: Private generic functions
defaults: Private generic functions
description: Private generic functions
description: Private generic functions

F
flags: Private generic functions
flags: Private generic functions
format-arguments: Private generic functions
format-arguments: Private generic functions
format-arguments: Private generic functions
format-control: Private generic functions
format-control: Private generic functions
format-control: Private generic functions
Function, merge-tables: Private ordinary functions

G
Generic Function, add-default: Public generic functions
Generic Function, add-flag: Public generic functions
Generic Function, add-generic-parser: Public generic functions
Generic Function, add-help: Public generic functions
Generic Function, add-optional: Public generic functions
Generic Function, add-positional: Public generic functions
Generic Function, add-subparser: Public generic functions
Generic Function, default: Private generic functions
Generic Function, defaults: Private generic functions
Generic Function, description: Private generic functions
Generic Function, flags: Private generic functions
Generic Function, format-arguments: Private generic functions
Generic Function, format-control: Private generic functions
Generic Function, get-key-value-pairs: Public generic functions
Generic Function, get-value: Public generic functions
Generic Function, help-message: Private generic functions
Generic Function, long: Private generic functions
Generic Function, name: Private generic functions
Generic Function, optionals: Private generic functions
Generic Function, parse: Public generic functions
Generic Function, parse-flag: Private generic functions
Generic Function, parse-optional: Private generic functions
Generic Function, parse-optionals: Private generic functions
Generic Function, parse-positional: Private generic functions
Generic Function, parse-positionals: Private generic functions
Generic Function, parse-subparsers: Private generic functions
Generic Function, positionals: Private generic functions
Generic Function, previous-parsers: Private generic functions
Generic Function, print-help: Private generic functions
Generic Function, program-name: Private generic functions
Generic Function, short: Private generic functions
Generic Function, subparsers: Private generic functions
Generic Function, sync-parser: Private generic functions
Generic Function, table: Private generic functions
Generic Function, var: Private generic functions
get-key-value-pairs: Public generic functions
get-key-value-pairs: Public generic functions
get-value: Public generic functions
get-value: Public generic functions

H
help-message: Private generic functions
help-message: Private generic functions
help-message: Private generic functions
help-message: Private generic functions

L
long: Private generic functions
long: Private generic functions
long: Private generic functions

M
Macro, aif: Private macros
Macro, create-main-parser: Public macros
Macro, create-mockup-parser: Private macros
Macro, create-sub-parser: Public macros
merge-tables: Private ordinary functions
Method, add-default: Public generic functions
Method, add-flag: Public generic functions
Method, add-generic-parser: Public generic functions
Method, add-help: Public generic functions
Method, add-optional: Public generic functions
Method, add-positional: Public generic functions
Method, add-subparser: Public generic functions
Method, default: Private generic functions
Method, defaults: Private generic functions
Method, description: Private generic functions
Method, flags: Private generic functions
Method, format-arguments: Private generic functions
Method, format-arguments: Private generic functions
Method, format-control: Private generic functions
Method, format-control: Private generic functions
Method, get-key-value-pairs: Public generic functions
Method, get-value: Public generic functions
Method, help-message: Private generic functions
Method, help-message: Private generic functions
Method, help-message: Private generic functions
Method, long: Private generic functions
Method, long: Private generic functions
Method, name: Private generic functions
Method, name: Private generic functions
Method, optionals: Private generic functions
Method, parse: Public generic functions
Method, parse-flag: Private generic functions
Method, parse-flag: Private generic functions
Method, parse-optional: Private generic functions
Method, parse-optionals: Private generic functions
Method, parse-positional: Private generic functions
Method, parse-positionals: Private generic functions
Method, parse-subparsers: Private generic functions
Method, positionals: Private generic functions
Method, previous-parsers: Private generic functions
Method, print-help: Private generic functions
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods
Method, program-name: Private generic functions
Method, short: Private generic functions
Method, short: Private generic functions
Method, subparsers: Private generic functions
Method, sync-parser: Private generic functions
Method, table: Private generic functions
Method, var: Private generic functions
Method, var: Private generic functions

N
name: Private generic functions
name: Private generic functions
name: Private generic functions

O
optionals: Private generic functions
optionals: Private generic functions

P
parse: Public generic functions
parse: Public generic functions
parse-flag: Private generic functions
parse-flag: Private generic functions
parse-flag: Private generic functions
parse-optional: Private generic functions
parse-optional: Private generic functions
parse-optionals: Private generic functions
parse-optionals: Private generic functions
parse-positional: Private generic functions
parse-positional: Private generic functions
parse-positionals: Private generic functions
parse-positionals: Private generic functions
parse-subparsers: Private generic functions
parse-subparsers: Private generic functions
positionals: Private generic functions
positionals: Private generic functions
previous-parsers: Private generic functions
previous-parsers: Private generic functions
print-help: Private generic functions
print-help: Private generic functions
print-object: Public standalone methods
print-object: Public standalone methods
print-object: Public standalone methods
print-object: Public standalone methods
print-object: Public standalone methods
print-object: Public standalone methods
program-name: Private generic functions
program-name: Private generic functions

S
short: Private generic functions
short: Private generic functions
short: Private generic functions
subparsers: Private generic functions
subparsers: Private generic functions
sync-parser: Private generic functions
sync-parser: Private generic functions

T
table: Private generic functions
table: Private generic functions

V
var: Private generic functions
var: Private generic functions
var: Private generic functions


A.3 Variables

Jump to:   D   F   H   L   N   O   P   S   T   V  
Index Entry  Section

D
default: Private classes
defaults: Public classes
description: Public classes

F
flags: Public classes
format-arguments: Public conditions
format-arguments: Private conditions
format-control: Public conditions
format-control: Private conditions

H
help-message: Private classes
help-message: Private classes
help-message: Private classes
help-message: Private classes

L
long: Private classes
long: Private classes
long: Private classes

N
name: Public classes
name: Private classes

O
optionals: Public classes

P
positionals: Public classes
previous-parsers: Public classes
program-name: Public classes

S
short: Private classes
short: Private classes
short: Private classes
Slot, default: Private classes
Slot, defaults: Public classes
Slot, description: Public classes
Slot, flags: Public classes
Slot, format-arguments: Public conditions
Slot, format-arguments: Private conditions
Slot, format-control: Public conditions
Slot, format-control: Private conditions
Slot, help-message: Private classes
Slot, help-message: Private classes
Slot, help-message: Private classes
Slot, help-message: Private classes
Slot, long: Private classes
Slot, long: Private classes
Slot, long: Private classes
Slot, name: Public classes
Slot, name: Private classes
Slot, optionals: Public classes
Slot, positionals: Public classes
Slot, previous-parsers: Public classes
Slot, program-name: Public classes
Slot, short: Private classes
Slot, short: Private classes
Slot, short: Private classes
Slot, subparsers: Public classes
Slot, table: Public classes
Slot, var: Private classes
Slot, var: Private classes
subparsers: Public classes

T
table: Public classes

V
var: Private classes
var: Private classes