Common Lisp Package: UNIX-OPTIONS

README:

FUNCTION

Public

CLI-OPTIONS

list of tokens passed in at the cli

EXE-NAME

The command used to execute this program

GETOPT (CLI-OPTIONS SHORTOPTS LONGOPTS)

A traditional command-line option parser of a similar general format as getopt from the Unix cli. Return three values which are all lists: (1) parsed command-line arguments with "--" separating the valid options and free arguments, (2) only the valid options and (3) only the free arguments. For example: *cli-options* = '("-afgo.txt" "--alpha" "stay.txt" "--file" "return.txt" "loop.txt") (getopts *cli-options* "af:j" '("alpha" "file=") => ("a" "f" "go.txt" "alpha" "file" "return.txt" "--" "stay.txt" "loop.txt") ("a" "f" "go.txt" "alpha" "file" "return.txt") ("stay.txt" "loop.txt")

MAKE-OPTION-SPEC (TOKENS &OPTIONAL PARAMETER DESCRIPTION)

Creates an option-spec object

MAP-PARSED-OPTIONS (CLI-OPTIONS BOOL-OPTIONS PARAM-OPTIONS OPT-VAL-FUNC FREE-OPT-FUNC)

A macro that parses a list of command line tokens according to a set of conditions and allows the user to operate on them as a series of key/value pairs. -- cli-options: a tokenized command line with the executable name removed -- bool-options: a list of parameters that do not require values; these are either true or false depending on wether they were passed in on the cli. -- param-options: a list of parameters that do require values; these are either false, if not passed or the value of the next token in the list. -- opt-val-func: the code that operates on the key/value pairs; The code in this block is executed for every found option name and it associated value (always true for boolean parameters) bound to 'option' and 'value' respectively. -- free-opt-func: operates on free options not associated with any parameter 'map-parsed-options' is meant as a backend for convenient option parsing mechanisms such as 'with-cli-options' and 'getopts'.

Private

ALPHA-NUMERIC? (CHAR)

Returns true if 'char' is a letter of the English alphabet or a numerical digit.

DIVIDE-TOKENS (OPTION-SPECS)

Takes a list of option specifications and returns two lists of tokens: one from boolean option specs and one from parameter option specs

FILTER (FUNCTION LIST)

Filters a list removing all element for which function returns nil

MAKE-NORMALIZED-OPTION-SPEC (NEW-SPEC OPTION-SPECS)

Checks the tokens of new-spec against the tokens in option-specs and changes or removes them to avoid conflicts

OPTION-SPEC-LENGTH (OPTION-SPEC)

Calculates the length of the string necessary to print all of the tokens in a standard fashion

OPTION-SPEC-TO-STRING (OPTION-SPEC &OPTIONAL (DESC-OFFSET 50))

Returns a human readable string describing the option spec.

TOGGLE-CASE (CHAR)

Reverses the case of a character

TOKEN? (TOKEN OPTION-SPEC)

Tests if token is in option spec

TOKENS (OPTION-SPEC)

Returns all tokens of option-spec

TOKENS-FROM-SYMBOL (SYMBOL)

Returns a lowercase name of symbol and the lowercase first letter of that name

Undocumented

ADD-TOKEN (TOKEN OPTION)

ALL-LONG-TOKENS (OPTION-SPECS)

ALL-SHORT-TOKENS (OPTION-SPECS)

ALL-TOKENS (OPTION-SPECS)

CONCAT (&REST STRINGS)

ENSURE-LIST (VAL)

ENSURE-OPTION-SPEC (SPEC)

GREATER (X Y &OPTIONAL (TEST #'>))

GREATEST (LIST &OPTIONAL (TEST #'>))

SPLIT-STRING (CHAR STRING)

MACRO

Public

WITH-CLI-OPTIONS ((&OPTIONAL (CLI-OPTIONS '(CLI-OPTIONS)) ENABLE-USAGE-SUMMARY) OPTION-VARIABLES &BODY BODY)

The macro automatically binds passed in command line options to a set of user defined variable names, following the usual GNU conventions. OPTION-VARIABLES is a lambda list, similar to a macro lambda list, of the form: ({option-variable}* [&parameters {option-variable}*] [&free free-token]) Each OPTION-VARIABLE is either a symbol or a lambda list of the form: (symbol &optional option-spec) The variable SYMBOL specifies the name of a value to be bound to some value passed in on the cli. The symbol will be bound to the value of the parsed option, (either as a boolean representing whether the option was passed, or as a string, representing the parameter passed, if the option take parameters,) within the body of WITH-CLI-OPTIONS. OPTION-SPEC is either an optional option-spec object, which defines how the tokens should be interpreted to bind this value, or a list that defines one. If option spec is omitted, an option-spec object is generated internally for this value, using the variable name (SYMBOL) as a long-form token and the first letter as a short-form token. If the lowercase of the short-form token is already taken, then the capital version is used. If this is also taken, the option will have no default short-form token. Alternatively, one may pass a string as OPTION-SPEC, in which case, the optoin-spec object will still be generated from SYMBOL, but will use the string as the option description. Option-variables listed after the &PARAMETERS modifier will be set as options which take a parameter, unless overridden with an explicitly passed option-spec object. Lastly, if the &FREE modifier is specified, it should be followed by exactly one symbol, which will be used as the name of the variable to be bound to the list of free tokens encountered after all other options.

Private

Undocumented

ADD-OPTION-SPEC (NEW-SPEC OPTION-SPECS)

AIF (TEST &REST FORMS)

DEFRESTART (NAME)

DOSEQ ((VAR SEQUENCE) &BODY BODY)

WITH-GENSYMS (SYMBOLS &BODY BODY)

GENERIC-FUNCTION

Private

Undocumented

DETAILS (CONDITION)

OPTION (CONDITION)

SLOT-ACCESSOR

Public

DESCRIPTION (OBJECT)

A description of this option's purpose and usage

SETFDESCRIPTION (NEW-VALUE OBJECT)

A description of this option's purpose and usage

LONG-TOKENS (OBJECT)

A collection of all long tokens valid for this option

SETFLONG-TOKENS (NEW-VALUE OBJECT)

A collection of all long tokens valid for this option

PARAMETER (OBJECT)

A boolean specifiing whether this option takes a parameter. Can be a string describing the parameter.

SETFPARAMETER (NEW-VALUE OBJECT)

A boolean specifiing whether this option takes a parameter. Can be a string describing the parameter.

SHORT-TOKENS (OBJECT)

A collection of all short tokens valid for this option

SETFSHORT-TOKENS (NEW-VALUE OBJECT)

A collection of all short tokens valid for this option

VARIABLE

Public

Undocumented

*DEFAULT-USAGE-FORMAT-STRING*

CLASS

Public

Undocumented

OPTION-SPEC

CONDITION

Private

Undocumented

BAD-OPTION-WARNING