Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the unix-options Reference Manual, version 0.3.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:44:00 2018 GMT+0.
| • Introduction: | What unix-options is all about | |
| • Systems: | The systems documentation | |
| • Files: | The files documentation | |
| • Packages: | The packages documentation | |
| • Definitions: | The symbols documentation | |
| • Indexes: | Concepts, functions, variables and data types |
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.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The unix-options system: |
Andrew Stine stine.drew@gmail.com
LLGPL
Easy to use command line option parser
0.3.1
unix-options.asd (file)
unix-options.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files: |
| • The unix-options.asd file: | ||
| • The unix-options/unix-options.lisp file: |
Next: The unix-options/unix-options<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
unix-options.asd
unix-options (system)
Previous: The unix-options<dot>asd file, Up: Lisp files [Contents][Index]
unix-options (system)
unix-options.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The unix-options package: |
unix-options.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions: | ||
| • Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables: | ||
| • Exported macros: | ||
| • Exported functions: | ||
| • Exported generic functions: | ||
| • Exported classes: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
unix-options.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
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}* [¶meters {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.
unix-options.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
list of tokens passed in at the cli
unix-options.lisp (file)
The command used to execute this program
unix-options.lisp (file)
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")
unix-options.lisp (file)
Creates an option-spec object
unix-options.lisp (file)
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’.
unix-options.lisp (file)
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
unix-options.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
A description of this option’s purpose and usage
unix-options.lisp (file)
A collection of all long tokens valid for this option
unix-options.lisp (file)
A boolean specifying whether this option takes a parameter.
Can be a string describing the parameter.
unix-options.lisp (file)
A collection of all short tokens valid for this option
unix-options.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
unix-options.lisp (file)
standard-object (class)
A collection of all short tokens valid for this option
:short-tokens
short-tokens (generic function)
(setf short-tokens) (generic function)
A collection of all long tokens valid for this option
:long-tokens
long-tokens (generic function)
(setf long-tokens) (generic function)
A boolean specifying whether this option takes a parameter.
Can be a string describing the parameter.
:parameter
parameter (generic function)
(setf parameter) (generic function)
A description of this option’s purpose and usage
:description
""
description (generic function)
(setf description) (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal macros: | ||
| • Internal functions: | ||
| • Internal generic functions: | ||
| • Internal conditions: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
Returns true if ’char’ is a letter of the English alphabet or a numerical digit.
unix-options.lisp (file)
unix-options.lisp (file)
Takes a list of option specifications and returns two lists
of tokens: one from boolean option specs and one from parameter
option specs
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
Filters a list removing all element for which function returns nil
unix-options.lisp (file)
unix-options.lisp (file)
unix-options.lisp (file)
Checks the tokens of new-spec against the tokens in option-specs and changes or removes them to avoid conflicts
unix-options.lisp (file)
Calculates the length of the string necessary to print all of the tokens in a standard fashion
unix-options.lisp (file)
Returns a human readable string describing the option spec.
unix-options.lisp (file)
unix-options.lisp (file)
Reverses the case of a character
unix-options.lisp (file)
Tests if token is in option spec
unix-options.lisp (file)
Returns all tokens of option-spec
unix-options.lisp (file)
Returns a lowercase name of symbol and the lowercase first letter of that name
unix-options.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
unix-options.lisp (file)
unix-options.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
unix-options.lisp (file)
warning (condition)
:option
option (generic function)
:details
details (generic function)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index: | ||
| • Function index: | ||
| • Variable index: | ||
| • Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L U |
|---|
| Jump to: | F L U |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A C D E F G L M O P S T W |
|---|
| Jump to: | (
A C D E F G L M O P S T W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
D L O P S |
|---|
| Jump to: | *
D L O P S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | B C O P S U |
|---|
| Jump to: | B C O P S U |
|---|