The cl-argparse Reference Manual

Table of Contents

The cl-argparse Reference Manual

This is the cl-argparse Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:01:58 2020 GMT+0.

1 Introduction

cl-argparse

A common lisp cmd argument parser inspired by python argparse

Dependencies

None

API

create-main-parser (var &optional description) elements* => parser

Create a parser with the given name and the variable of name

• var: the variable name for the parser
• description: the description for this parser
• elements: the element forms that add parsing instructions to the parser

create-sub-parser (name &optional description) elements* => parser

Create a parser with the given name and the variable of name

• name: the variable name and the name for the parser
• description: the description for this parser
• elements: the element forms that add parsing instructions to the parser

add-flag parser &key short long help var

Add a flag to the current parser

• parser: the parser to which to add the flag
• short: the short form (i.e., one character) of the flag
• long: the long form of the flag
• help: the help message to be displayed for this flag
• var: the variable into which the truth value is stored

add-optional parser &key short long default help var

Add a parameter to the current parser

• parser: the parser to which to add the parameter
• short: the short form (i.e., one character) of the flag
• long: the long form of the flag
• default: the default value to be used in case the parameter is not used
• help: the help message to be displayed for this flag
• var: the variable into which the value is stored

add-positional parser &key name help

Add a positional argument to the parser

• parser: the parser to which to add the positional argument
• name: the name of the positional element which is also the variable name into which the value is stored
• help: the help message to be displayed for this flag

add-subparser parser subparser

adds a subparser to the parser

• parser: the parser to which to add the subparser
• subparser: the subparser to be added

add-generic-parser parser gen

adds the parsing elements of the gen parser to the given parser

• parser: the parser which is to be extended
• gen: the parser from which the parser is to be extended

add-default parser &key var default

adds a default value to the parser

• parser: the parser to which the default value is added
• var: the variable name to which the default value is bound
• default: the default value

get-value name parser

get the cmd provided variable value of name from parser

• name: the name of the variable the value is required
• parser: the parser from which to extract the value

parse parser argv

parse the stringlist argv using parser parser

• parser: the parser to be used
• argv: the arguments (i.e., list of strings) to be parsed

create-mockup-parser key-value-list*

create a parser simulating a parsing resulting in the given key-value-list

• key-value-list: a paired list of strings to create the parser from

Usage

You can either use the short example below to get started or the longer example provided as commented source code in ./src/examples/example.lisp.

Short Example

(in-package :cl-argparse)

(format t "~a~%"
        (parse
         (create-main-parser (main-parser "here comes the description of the program")
           (add-flag main-parser :short "g" :long "goo" :help "this is an example flag" :var "goo")
           (add-optional main-parser :short "t" :long "test" :help "this is an example optional argument" :var "test")
           (add-positional main-parser :name "pos" :help "this is an example for a positional")
           (add-subparser main-parser (create-sub-parser (sub "this is a sub action parser")
                                        (add-positional sub :name "action" :help "this is an example for a positional"))))
         (list "-g" "-t" "alle" "positional" "sub" "theaction")))

=> <PARSER
     goo -> T
     test -> alle
     pos -> positional
     action -> theaction
   >

2 Systems

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

2.1 cl-argparse

Maintainer

Simon Koch <projects@halcony.de>

Author

Simon Koch <projects@halcony.de>

License

MIT

Description

A python argparse inspired command line parser library

Source

cl-argparse.asd (file)

Components

• package.lisp (file)
• classes.lisp (file)
• methods.lisp (file)

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.asd

Location

cl-argparse.asd

Systems

cl-argparse (system)

3.1.2 cl-argparse/package.lisp

Parent

cl-argparse (system)

Location

package.lisp

Packages

de.halcony.argparse

3.1.3 cl-argparse/classes.lisp

Dependency

package.lisp (file)

Parent

cl-argparse (system)

Location

classes.lisp

Exported Definitions

• cancel-parsing-error (condition)
• parser (class)

Internal Definitions

• cmd-arg-error (condition)
• default (method)
• defaults (method)
• description (method)
• flag (class)
• flags (method)
• format-arguments (method)
• format-arguments (method)
• format-control (method)
• format-control (method)
• help-flag (class)
• help-flag-condition (condition)
• help-message (method)
• help-message (method)
• help-message (method)
• long (method)
• long (method)
• name (method)
• name (method)
• optional (class)
• optionals (method)
• positional (class)
• positionals (method)
• previous-parsers (method)
• short (method)
• short (method)
• subparsers (method)
• table (method)
• var (method)
• var (method)

3.1.4 cl-argparse/methods.lisp

Dependencies

• package.lisp (file)
• classes.lisp (file)

Parent

cl-argparse (system)

Location

methods.lisp

Exported Definitions

• add-default (method)
• add-flag (method)
• add-generic-parser (method)
• add-help (method)
• add-optional (method)
• add-positional (method)
• add-subparser (method)
• create-main-parser (macro)
• create-sub-parser (macro)
• get-key-value-pairs (method)
• get-value (method)
• parse (method)

Internal Definitions

• aif (macro)
• create-mockup-parser (macro)
• merge-tables (function)
• parse-flag (method)
• parse-flag (method)
• parse-optional (method)
• parse-optionals (method)
• parse-positional (method)
• parse-positionals (method)
• parse-subparsers (method)
• print-help (method)
• sync-parser (method)

4 Packages

Packages are listed by definition order.

4.1 de.halcony.argparse

Source

package.lisp (file)

Nickname

cl-argparse

Use List

• common-lisp
• common-lisp-user

Exported Definitions

• add-default (generic function)
• add-default (method)
• add-flag (generic function)
• add-flag (method)
• add-generic-parser (generic function)
• add-generic-parser (method)
• add-help (generic function)
• add-help (method)
• add-optional (generic function)
• add-optional (method)
• add-positional (generic function)
• add-positional (method)
• add-subparser (generic function)
• add-subparser (method)
• cancel-parsing-error (condition)
• create-main-parser (macro)
• create-sub-parser (macro)
• get-key-value-pairs (generic function)
• get-key-value-pairs (method)
• get-value (generic function)
• get-value (method)
• parse (generic function)
• parse (method)
• parser (class)

Internal Definitions

• aif (macro)
• cmd-arg-error (condition)
• create-mockup-parser (macro)
• default (generic function)
• default (method)
• defaults (generic function)
• defaults (method)
• description (generic function)
• description (method)
• flag (class)
• flags (generic function)
• flags (method)
• format-arguments (generic function)
• format-arguments (method)
• format-arguments (method)
• format-control (generic function)
• format-control (method)
• format-control (method)
• help-flag (class)
• help-flag-condition (condition)
• help-message (generic function)
• help-message (method)
• help-message (method)
• help-message (method)
• long (generic function)
• long (method)
• long (method)
• merge-tables (function)
• name (generic function)
• name (method)
• name (method)
• optional (class)
• optionals (generic function)
• optionals (method)
• parse-flag (generic function)
• parse-flag (method)
• parse-flag (method)
• parse-optional (generic function)
• parse-optional (method)
• parse-optionals (generic function)
• parse-optionals (method)
• parse-positional (generic function)
• parse-positional (method)
• parse-positionals (generic function)
• parse-positionals (method)
• parse-subparsers (generic function)
• parse-subparsers (method)
• positional (class)
• positionals (generic function)
• positionals (method)
• previous-parsers (generic function)
• previous-parsers (method)
• print-help (generic function)
• print-help (method)
• short (generic function)
• short (method)
• short (method)
• subparsers (generic function)
• subparsers (method)
• sync-parser (generic function)
• sync-parser (method)
• table (generic function)
• table (method)
• var (generic function)
• var (method)
• var (method)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: create-main-parser (VAR &optional DESCRIPTION) &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 (file)

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

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

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

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

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

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

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

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

Generic Function: get-key-value-pairs PARSER

Package

de.halcony.argparse

Methods

Method: get-key-value-pairs (PARSER parser)

Source

methods.lisp (file)

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

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

5.1.3 Conditions

Condition: cancel-parsing-error ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

simple-error (condition)

Direct methods

• print-object (method)
• format-arguments (method)
• format-control (method)

Direct slots

Slot: format-control

Initargs

:format-control

Initform

(quote "")

Readers

format-control (generic function)

Slot: format-arguments

Initargs

:format-arguments

Initform

(quote (list))

Readers

format-arguments (generic function)

5.1.4 Classes

Class: parser ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• get-key-value-pairs (method)
• print-help (method)
• get-value (method)
• add-default (method)
• add-generic-parser (method)
• sync-parser (method)
• add-subparser (method)
• add-positional (method)
• add-optional (method)
• add-help (method)
• add-flag (method)
• parse (method)
• parse-subparsers (method)
• parse-positionals (method)
• parse-optionals (method)
• print-object (method)
• table (method)
• defaults (method)
• subparsers (method)
• positionals (method)
• optionals (method)
• flags (method)
• name (method)
• previous-parsers (method)
• description (method)

Direct slots

Slot: description

Initargs

:description

Initform

"no description"

Readers

description (generic function)

Slot: previous-parsers

Initform

(list)

Readers

previous-parsers (generic function)

Slot: name

Initargs

:name

Initform

""

Readers

name (generic function)

Slot: flags

Initform

(list)

Readers

flags (generic function)

Slot: optionals

Initform

(list)

Readers

optionals (generic function)

Slot: positionals

Initform

(list)

Readers

positionals (generic function)

Slot: subparsers

Initform

(list)

Readers

subparsers (generic function)

Slot: defaults

Initform

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

Readers

defaults (generic function)

Slot: table

Initform

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

Readers

table (generic function)

5.2 Internal definitions

5.2.1 Macros

Macro: aif CONDITION IF THEN

Package

de.halcony.argparse

Source

methods.lisp (file)

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

5.2.2 Functions

Function: merge-tables TABLE-A TABLE-B

merges table-b into table-a

Package

de.halcony.argparse

Source

methods.lisp (file)

5.2.3 Generic functions

Generic Function: default OBJECT

Package

de.halcony.argparse

Methods

Method: default (OPTIONAL optional)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: defaults OBJECT

Package

de.halcony.argparse

Methods

Method: defaults (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: description OBJECT

Package

de.halcony.argparse

Methods

Method: description (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: flags OBJECT

Package

de.halcony.argparse

Methods

Method: flags (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: format-arguments CONDITION

Package

de.halcony.argparse

Methods

Method: format-arguments (CONDITION cancel-parsing-error)

Source

classes.lisp (file)

Method: format-arguments (CONDITION cmd-arg-error)

Source

classes.lisp (file)

Generic Function: format-control CONDITION

Package

de.halcony.argparse

Methods

Method: format-control (CONDITION cancel-parsing-error)

Source

classes.lisp (file)

Method: format-control (CONDITION cmd-arg-error)

Source

classes.lisp (file)

Generic Function: help-message OBJECT

Package

de.halcony.argparse

Methods

Method: help-message (POSITIONAL positional)

automatically generated reader method

Source

classes.lisp (file)

Method: help-message (OPTIONAL optional)

automatically generated reader method

Source

classes.lisp (file)

Method: help-message (FLAG flag)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: long OBJECT

Package

de.halcony.argparse

Methods

Method: long (OPTIONAL optional)

automatically generated reader method

Source

classes.lisp (file)

Method: long (FLAG flag)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: name OBJECT

Package

de.halcony.argparse

Methods

Method: name (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Method: name (POSITIONAL positional)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: optionals OBJECT

Package

de.halcony.argparse

Methods

Method: optionals (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

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

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

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

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

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

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

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

Generic Function: positionals OBJECT

Package

de.halcony.argparse

Methods

Method: positionals (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: previous-parsers OBJECT

Package

de.halcony.argparse

Methods

Method: previous-parsers (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

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

Generic Function: short OBJECT

Package

de.halcony.argparse

Methods

Method: short (OPTIONAL optional)

automatically generated reader method

Source

classes.lisp (file)

Method: short (FLAG flag)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: subparsers OBJECT

Package

de.halcony.argparse

Methods

Method: subparsers (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

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

Generic Function: table OBJECT

Package

de.halcony.argparse

Methods

Method: table (PARSER parser)

automatically generated reader method

Source

classes.lisp (file)

Generic Function: var OBJECT

Package

de.halcony.argparse

Methods

Method: var (OPTIONAL optional)

automatically generated reader method

Source

classes.lisp (file)

Method: var (FLAG flag)

automatically generated reader method

Source

classes.lisp (file)

5.2.4 Conditions

Condition: cmd-arg-error ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

simple-error (condition)

Direct methods

• print-object (method)
• format-arguments (method)
• format-control (method)

Direct slots

Slot: format-control

Initargs

:format-control

Initform

(quote "")

Readers

format-control (generic function)

Slot: format-arguments

Initargs

:format-arguments

Initform

(quote (list))

Readers

format-arguments (generic function)

Condition: help-flag-condition ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

simple-error (condition)

5.2.5 Classes

Class: flag ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

help-flag (class)

Direct methods

• parse-flag (method)
• print-object (method)
• help-message (method)
• var (method)
• long (method)
• short (method)

Direct slots

Slot: short

Initargs

:short

Readers

short (generic function)

Slot: long

Initargs

:long

Readers

long (generic function)

Slot: var

Initargs

:var

Readers

var (generic function)

Slot: help-message

Initargs

:help-message

Readers

help-message (generic function)

Class: help-flag ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

flag (class)

Direct methods

parse-flag (method)

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

Direct superclasses

standard-object (class)

Direct methods

• parse-optional (method)
• print-object (method)
• help-message (method)
• default (method)
• var (method)
• long (method)
• short (method)

Direct slots

Slot: short

Initargs

:short

Readers

short (generic function)

Slot: long

Initargs

:long

Readers

long (generic function)

Slot: var

Initargs

:var

Readers

var (generic function)

Slot: default

Initargs

:default

Readers

default (generic function)

Slot: help-message

Initargs

:help-message

Readers

help-message (generic function)

Class: positional ()

Package

de.halcony.argparse

Source

classes.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• parse-positional (method)
• print-object (method)
• help-message (method)
• name (method)

Direct slots

Slot: name

Initargs

:name

Readers

name (generic function)

Slot: help-message

Initargs

:help-message

Readers

help-message (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types