The unix-options Reference Manual

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

The unix-options Reference Manual

This is the unix-options Reference Manual, version 0.3.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 06:06:57 2022 GMT+0.

Table of Contents


1 Introduction

unix-options (C) 2009-2010 Andrew Stine

This software is distributed under the terms of the Lisp Lesser GNU 
Public License (http://opensource.franz.com/preamble.html), also 
known as the LLGPL. 

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

----------------------------------------------------------------------

Unix-options is a small Common Lisp library for parsing unix-style 
command line options. 

This library is very new and not widely tested so suggestions, 
bug-reports and patches (including changes to this document) are
welcome.

Please send any feedback to: unix dot options (at) librelist dot com

----------------------------------------------------------------------
Usage:
 
The library can be loaded through ASDF and used through the package 
'unix-options.'

Exported symbols are:

=| cli-options      - variable
=| ¶meters        - symbol
=| &free              - symbol
=| free               - symbol
=| map-parsed-options - function
=| getopt             - function
=| with-cli-options   - macro

An example of usage:

(with-cli-options ()
    (print ¶meters in-file out-file)
  (when print
    (with-open-file (in in-file :direction :input)
      (with-open-file (out out-file :direction :output)
        (while (peek-char in)
          (write-char (read-char in) out))))))

$ sample-program -p -i input.txt -o output.txt
=> write input.txt to output.txt

---------------------------------------------------------------------
API:

getopt - An imitation of the Unix 'getopt' command line program

    prototype: (getopt cli-options shortopts longopts)

    details: Getopt accepts three arguments: a list of tokens passed
             in on the CLI, a string detailing available short-form
             options and a list detailing long-form options. Getopt
             breaks the tokens up and sorts them so that they can be
             handled by the calling program more easily.
 
             Cli-options can be any list of strings. Each string
             beginning with a single '-' is interpreted as a series of
             short options and any beginning with '--' is interpreted
             as a long option. Others are either free tokens or
             parameters. Any tokens appearing after a token that is
             soley a '--', are interpreted as free tokens.

             Shortopts takes the form: "abf:" where each letter is the
             name of a permissable short option and a ':' following a
             letter signifies that it takes a parameter.

             Longopts takes the form: '("option1" "file=") where each
             string is the name of a long option and a '=' signifies
             that the option takes a parameter.

	     Return three values which are all lists: (1) parsed command
	     line arguments with "--" separating valid options and free
	     arguments, (2) only the valid options and (3) only the free
	     arguments.

    example: (getopt '("-ab" "--file" "file.txt" "free")
                     "ab"
                     '("file="))
             => ("a" "b" "file" "file.txt" "--" "free")
                ("a" "b" "file" "file.txt")
                ("free")

make-option-spec - A function which create an option-spec object

    prototype: (make-option-spec tokens &optional parameter description)
    
    details: Make-option-spec generates an option-spec object from the
             the details provided. Tokens can either be a symbol, or a
             list of characters, strings, and symbols. Parameter is either
             nil, t, or a string. Description is always a string.

             An option spec contains a list of short-tokens, as characters
             and a list of long-tokens as strings. Short-tokens are drawn
             from any characters passed under tokens and the first
             letter of the name of any symbols passed. Long-tokens are
             drawn from any strings passed likewise and from the complete
             names of any symbols passed.

             Parameter signifies whether an option takes a parameter. If
             parameter is nil, then the option does not. Otherwise, the
             option does. The parameter can be described briefly by passing
             a string as parameter rather than simply t. 

             Description is a description of the option and it's purpose in
             general.
     
             Option-specs are used as parameters to several functions in
             unix-options. Generally, anywhere an option-spec is required,
             one may substitute a list of the parameters one would pass to 
             make-option-spec. Thus one might be able to type:
             (function '(foo nil "foo option")) instead of:
             (function (make-option-spec 'foo nil "foo option"))
    
    example: (make-option-spec '(#\A foo) "integer" "A number to be passed in")
             => 
             

with-cli-options - A macro that binds values passed in from the command
                   line to local variables

    prototype: (with-cli-options (&optional (cli-options '(cli-options))
                                             enable-usage-summary)
                                  option-variables &body body)
                                  
    details: With-cli-options takes a list of symbols and attempts to
             bind values passed in on the command line to them according
             to a set of rules. For every symbol named in 
             option-variables, with-cli-options creates a variable to 
             which it binds any long option of the same name. 
             With-cli-options also take the first letter of any symbol
             and bind short options of that letter to that symbol. If
             multiple symbols begin with the same letter, only the first
             in option-variables is bound the short option of the same
             letter; the second is bound to the uppercase version and any
             more must use a long option.
             
             Optionally, each entry in option-variables can be a short
             list. The first item is symbol to be used. The second is
             either a documentation string, or a full option-spec allowing 
             greater detail as to how that particular entry is to be
             formed.

             In addition, symbols in option-variables are boolean by 
             default; that is, they are bound to either t or nil depending on
             whether they are passed in on the CLI. Symbols listed after
             ¶meters, if it is present, are considered parameter
             options, that is, they are bound to the next token on the CLI
             if they are long options or the same or the rest of the
             current short option group, if they are short options. If
             nothing is passed for this options (ie. if it is the last
             token) it is bound to nil.
             
             Any tokens that aren't options or parameters to options are
             saved into a list of free tokens. This list is bound to 'free'
             unless a different symbol is provided in option-variables
             after &free.
             
             If enable-usage-summary is set, then with-cli-options will be
             able to print out a usage summary (using print-usage-summary)
             based on the options bound in option-varibles. The summary
             will be printed either when an invalid option is specified or
             when the user uses '-h' or '--help' as an option. If
             enable-usage-summary is set to a string, that string is passed
             as control string to print-usage-summary. Else, a generic
             string is used.

   example: (with-cli-options ('("-pi" "in" "--out-file" "out" "another"))
                (print ¶meters in-file out-file)
              (print print)
              (print in-file)
              (print out-file)
              (print free))
            T
            "in"
            "out"
            ("another")
            => NIL
            
cli-options - returns the list of whitespace separated tokens passed
                on the command line.
                
print-usage-summary - Prints a usage description of the current program

    prototype: (print-usage-summary description option-specs)

    details: Print-usage-summary prints a summary of options specified
             by options-specs.

             The function takes each option-spec and generates a string
             describing each option in detail. The resulting strings are
             passed as arguments to a call to format. Description is used
             as the control string. The option-spec descriptions are auto-
             aligned.

    example: (print-usage-summary "Usage:~%~@{~A~%~}~%end summary"
                                  '(((#\a "alpha") nil "A simple option")
                                    ((#\f "file") "FILENAME" "A filename")
                                    ((#\b #\d "beta") nil "Another option")))
             Usage:
               -a, --alpha          A simple option
               -f, --file=FILENAME  A filename
               -b, -d, --beta       Another option

             end summary
             =>NIL

map-parsed-options - Function that does the actual parsing of CLI tokens

    prototype: (map-parsed-options cli-options bool-options param-options
                                   opt-val-func free-val-func)

    details: Map-parsed-options is the backend function that does most
             of the actual work in parsing CLI functions. It is exposed
             to allow more front ends in addition to getopt and
             with-cli-options. Map-parsed-options receives a list of CLI
             tokens, as well as two list of options, boolean options and
             options with parameters, respectively. The final two
             arguments are functions, one to handle found options and
             there values, and one to handle free tokens.

    example: (map-parsed-options '("-ab" "value" "free") '("a") '("b")
                                 (lambda (option value)
                                    (format t "option: ~A; value: ~A~%"
                                            option value))
                                 (lambda (free-val)
                                    (format t "free: ~A~%" free-val)))
             option: a; value T
             option: b; value value 
             free: free
             => NIL

With thanks to folks who've reported bugs and provided patches.


2 Systems

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


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

2.1 unix-options

Easy to use command line option parser

Author

<Andrew Stine stine.drew@gmail.com>

License

LLGPL

Version

0.3.1

Source

unix-options.asd.

Child Component

unix-options.lisp (file).


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   [Contents][Index]

3.1.1 unix-options/unix-options.asd

Source

unix-options.asd.

Parent Component

unix-options (system).

ASDF Systems

unix-options.


3.1.2 unix-options/unix-options.lisp

Source

unix-options.asd.

Parent Component

unix-options (system).

Packages

unix-options.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


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

4.1 unix-options

Source

unix-options.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *default-usage-format-string*
Package

unix-options.

Source

unix-options.lisp.


5.1.2 Macros

Macro: with-cli-options ((&optional 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.

Package

unix-options.

Source

unix-options.lisp.


5.1.3 Ordinary functions

Function: cli-options ()

list of tokens passed in at the cli

Package

unix-options.

Source

unix-options.lisp.

Function: exe-name ()

The command used to execute this program

Package

unix-options.

Source

unix-options.lisp.

Function: 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")

Package

unix-options.

Source

unix-options.lisp.

Function: make-option-spec (tokens &optional parameter description)

Creates an option-spec object

Package

unix-options.

Source

unix-options.lisp.

Function: 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’.

Package

unix-options.

Source

unix-options.lisp.

Function: print-usage-summary (description option-specs)

Given a description (a control string) and a list of specs for options descriptions prints a usage summary. ’Description’ is a format control string, which is run against a list of strings generated from the specs in ’option-specs’ each spec takes the form of a list containing the following values in order:
short-opts - a string contain characters used as short options for this option long-opt - either a single string, or a list of strings naming long options parameter - If true, specifies that this option takes a parameter; parameter type or description can be specified as a string
description - A short description of this option

Package

unix-options.

Source

unix-options.lisp.


5.1.4 Generic functions

Generic Reader: description (object)
Generic Writer: (setf description) (object)
Package

unix-options.

Methods
Reader Method: description ((option-spec option-spec))
Writer Method: (setf description) ((option-spec option-spec))

A description of this option’s purpose and usage

Source

unix-options.lisp.

Target Slot

description.

Generic Reader: long-tokens (object)
Generic Writer: (setf long-tokens) (object)
Package

unix-options.

Methods
Reader Method: long-tokens ((option-spec option-spec))
Writer Method: (setf long-tokens) ((option-spec option-spec))

A collection of all long tokens valid for this option

Source

unix-options.lisp.

Target Slot

long-tokens.

Generic Reader: parameter (object)
Generic Writer: (setf parameter) (object)
Package

unix-options.

Methods
Reader Method: parameter ((option-spec option-spec))
Writer Method: (setf parameter) ((option-spec option-spec))

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

Source

unix-options.lisp.

Target Slot

parameter.

Generic Reader: short-tokens (object)
Generic Writer: (setf short-tokens) (object)
Package

unix-options.

Methods
Reader Method: short-tokens ((option-spec option-spec))
Writer Method: (setf short-tokens) ((option-spec option-spec))

A collection of all short tokens valid for this option

Source

unix-options.lisp.

Target Slot

short-tokens.


5.1.5 Standalone methods

Method: make-load-form ((option-spec option-spec) &optional environment)
Source

unix-options.lisp.


5.1.6 Classes

Class: option-spec
Package

unix-options.

Source

unix-options.lisp.

Direct methods
Direct slots
Slot: short-tokens

A collection of all short tokens valid for this option

Initargs

:short-tokens

Readers

short-tokens.

Writers

(setf short-tokens).

Slot: long-tokens

A collection of all long tokens valid for this option

Initargs

:long-tokens

Readers

long-tokens.

Writers

(setf long-tokens).

Slot: parameter

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

Initargs

:parameter

Readers

parameter.

Writers

(setf parameter).

Slot: description

A description of this option’s purpose and usage

Initform

""

Initargs

:description

Readers

description.

Writers

(setf description).


5.2 Internals


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

5.2.1 Macros

Macro: add-option-spec (new-spec option-specs)
Package

unix-options.

Source

unix-options.lisp.

Macro: aif (test &rest forms)
Package

unix-options.

Source

unix-options.lisp.

Macro: defrestart (name)
Package

unix-options.

Source

unix-options.lisp.

Macro: doseq ((var sequence) &body body)
Package

unix-options.

Source

unix-options.lisp.

Macro: with-gensyms (symbols &body body)
Package

unix-options.

Source

unix-options.lisp.


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

5.2.2 Ordinary functions

Function: add-token (token option)
Package

unix-options.

Source

unix-options.lisp.

Function: all-long-tokens (option-specs)
Package

unix-options.

Source

unix-options.lisp.

Function: all-short-tokens (option-specs)
Package

unix-options.

Source

unix-options.lisp.

Function: all-tokens (option-specs)
Package

unix-options.

Source

unix-options.lisp.

Function: alpha-numeric? (char)

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

Package

unix-options.

Source

unix-options.lisp.

Function: concat (&rest strings)
Package

unix-options.

Source

unix-options.lisp.

Function: 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

Package

unix-options.

Source

unix-options.lisp.

Function: ensure-list (val)
Package

unix-options.

Source

unix-options.lisp.

Function: ensure-option-spec (spec)
Package

unix-options.

Source

unix-options.lisp.

Function: filter (function list)

Filters a list removing all element for which function returns nil

Package

unix-options.

Source

unix-options.lisp.

Function: greater (x y &optional test)
Package

unix-options.

Source

unix-options.lisp.

Function: greatest (list &optional test)
Package

unix-options.

Source

unix-options.lisp.

Function: 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

Package

unix-options.

Source

unix-options.lisp.

Function: option-spec-length (option-spec)

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

Package

unix-options.

Source

unix-options.lisp.

Function: option-spec-to-string (option-spec &optional desc-offset)

Returns a human readable string describing the option spec.

Package

unix-options.

Source

unix-options.lisp.

Function: split-string (char string)
Package

unix-options.

Source

unix-options.lisp.

Function: toggle-case (char)

Reverses the case of a character

Package

unix-options.

Source

unix-options.lisp.

Function: token? (token option-spec)

Tests if token is in option spec

Package

unix-options.

Source

unix-options.lisp.

Function: tokens (option-spec)

Returns all tokens of option-spec

Package

unix-options.

Source

unix-options.lisp.

Function: tokens-from-symbol (symbol)

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

Package

unix-options.

Source

unix-options.lisp.


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

5.2.3 Generic functions

Generic Reader: details (condition)
Package

unix-options.

Methods
Reader Method: details ((condition bad-option-warning))
Source

unix-options.lisp.

Target Slot

details.

Generic Reader: option (condition)
Package

unix-options.

Methods
Reader Method: option ((condition bad-option-warning))
Source

unix-options.lisp.

Target Slot

option.


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

5.2.4 Conditions

Condition: bad-option-warning
Package

unix-options.

Source

unix-options.lisp.

Direct superclasses

warning.

Direct methods
Direct slots
Slot: option
Initargs

:option

Readers

option.

Writers

This slot is read-only.

Slot: details
Initargs

:details

Readers

details.

Writers

This slot is read-only.


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   L   M   O   P   S   T   W  
Index Entry  Section

(
(setf description): Public generic functions
(setf description): Public generic functions
(setf long-tokens): Public generic functions
(setf long-tokens): Public generic functions
(setf parameter): Public generic functions
(setf parameter): Public generic functions
(setf short-tokens): Public generic functions
(setf short-tokens): Public generic functions

A
add-option-spec: Private macros
add-token: Private ordinary functions
aif: Private macros
all-long-tokens: Private ordinary functions
all-short-tokens: Private ordinary functions
all-tokens: Private ordinary functions
alpha-numeric?: Private ordinary functions

C
cli-options: Public ordinary functions
concat: Private ordinary functions

D
defrestart: Private macros
description: Public generic functions
description: Public generic functions
details: Private generic functions
details: Private generic functions
divide-tokens: Private ordinary functions
doseq: Private macros

E
ensure-list: Private ordinary functions
ensure-option-spec: Private ordinary functions
exe-name: Public ordinary functions

F
filter: Private ordinary functions
Function, add-token: Private ordinary functions
Function, all-long-tokens: Private ordinary functions
Function, all-short-tokens: Private ordinary functions
Function, all-tokens: Private ordinary functions
Function, alpha-numeric?: Private ordinary functions
Function, cli-options: Public ordinary functions
Function, concat: Private ordinary functions
Function, divide-tokens: Private ordinary functions
Function, ensure-list: Private ordinary functions
Function, ensure-option-spec: Private ordinary functions
Function, exe-name: Public ordinary functions
Function, filter: Private ordinary functions
Function, getopt: Public ordinary functions
Function, greater: Private ordinary functions
Function, greatest: Private ordinary functions
Function, make-normalized-option-spec: Private ordinary functions
Function, make-option-spec: Public ordinary functions
Function, map-parsed-options: Public ordinary functions
Function, option-spec-length: Private ordinary functions
Function, option-spec-to-string: Private ordinary functions
Function, print-usage-summary: Public ordinary functions
Function, split-string: Private ordinary functions
Function, toggle-case: Private ordinary functions
Function, token?: Private ordinary functions
Function, tokens: Private ordinary functions
Function, tokens-from-symbol: Private ordinary functions

G
Generic Function, (setf description): Public generic functions
Generic Function, (setf long-tokens): Public generic functions
Generic Function, (setf parameter): Public generic functions
Generic Function, (setf short-tokens): Public generic functions
Generic Function, description: Public generic functions
Generic Function, details: Private generic functions
Generic Function, long-tokens: Public generic functions
Generic Function, option: Private generic functions
Generic Function, parameter: Public generic functions
Generic Function, short-tokens: Public generic functions
getopt: Public ordinary functions
greater: Private ordinary functions
greatest: Private ordinary functions

L
long-tokens: Public generic functions
long-tokens: Public generic functions

M
Macro, add-option-spec: Private macros
Macro, aif: Private macros
Macro, defrestart: Private macros
Macro, doseq: Private macros
Macro, with-cli-options: Public macros
Macro, with-gensyms: Private macros
make-load-form: Public standalone methods
make-normalized-option-spec: Private ordinary functions
make-option-spec: Public ordinary functions
map-parsed-options: Public ordinary functions
Method, (setf description): Public generic functions
Method, (setf long-tokens): Public generic functions
Method, (setf parameter): Public generic functions
Method, (setf short-tokens): Public generic functions
Method, description: Public generic functions
Method, details: Private generic functions
Method, long-tokens: Public generic functions
Method, make-load-form: Public standalone methods
Method, option: Private generic functions
Method, parameter: Public generic functions
Method, short-tokens: Public generic functions

O
option: Private generic functions
option: Private generic functions
option-spec-length: Private ordinary functions
option-spec-to-string: Private ordinary functions

P
parameter: Public generic functions
parameter: Public generic functions
print-usage-summary: Public ordinary functions

S
short-tokens: Public generic functions
short-tokens: Public generic functions
split-string: Private ordinary functions

T
toggle-case: Private ordinary functions
token?: Private ordinary functions
tokens: Private ordinary functions
tokens-from-symbol: Private ordinary functions

W
with-cli-options: Public macros
with-gensyms: Private macros

Jump to:   (  
A   C   D   E   F   G   L   M   O   P   S   T   W