The unix-opts Reference Manual

Table of Contents

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

The unix-opts Reference Manual

This is the unix-opts Reference Manual, version 0.1.7, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:44:02 2018 GMT+0.


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

1 Introduction

Unix-style command line options parser

License MIT Build Status Quicklisp

This is a minimalistic parser of command line options. The main advantage of the library is the ability to concisely define command line options once and then use this definition for parsing and extraction of command line arguments, as well as printing description of command line options (you get --help for free). This way you don't need to repeat yourself. Also, unix-opts doesn't depend on anything and allows to precisely control behavior of the parser via Common Lisp restarts.

Inspired by Haskell's optparse-applicative and Python's argparse.

It is portable accross implementations.

Installation

Copy files of this library in any place where ASDF can find them. Then you can use it in system definitions and ASDF will take care of the rest.

Via Quicklisp (recommended):

(ql:quickload "unix-opts")

Now you can also use its shorter nickname opts.

Functions

option condition

Take a condition condition (unknown-option, missing-arg, or arg-parser-failed) and return a string representing the option in question.


raw-arg condition

Take a condition of type arg-parser-failed and return the raw argument string.


define-opts &rest descriptions

Define command line options. Arguments of this macro must be plists containing various parameters. Here we enumerate all allowed parameters:


argv

Return a list of the program's arguments, including the command used to execute the program as the first element of the list. Portable across implementations.


get-opts &optional options

Parse command line options. If options is given, it should be a list to parse. If it's not given, the function will use the argv function to get the list of command line arguments.

Returns two values:

If some option requires an argument, you can use getf to test the presence of the option and get its argument if the option is present.

The parser may signal various conditions. Let's list them all specifying which restarts are available for every condition, and what kind of information the programmer can extract from the conditions.

describe &key prefix suffix usage-of args stream

Return a string describing all the options of the program that were defined with the previous define-opts macro. You can supply prefix and suffix arguments that will be printed before and after the options respectively. If usage-of is supplied, it should be a string, the name of the program for an "Usage: " section. This section is only printed if this name is given. If your program takes arguments (apart from options), you can specify how to print them in "Usage: " section with an args option (should be a string designator). Output goes to stream (default value is *standard-output*).


exit &optional (status 0)

Exit the program returning status.

Example

Go to the example directory. Now, you can use example.lisp file to see if unix-opts is cool enough for you to use. SBCL users can use example.sh file.

Take a look at example.lisp and you will see that the library is pretty sexy! Basically, we have defined all the options just like this:

(opts:define-opts
  (:name :help
   :description "print this help text"
   :short #\h
   :long "help")
  (:name :verbose
   :description "verbose output"
   :short #\v
   :long "verbose")
  (:name :level
   :description "the program will run on LEVEL level"
   :short #\l
   :long "level"
   :required t
   :arg-parser #'parse-integer
   :meta-var "LEVEL")
  (:name :output
   :description "redirect output to file FILE"
   :short #\o
   :long "output"
   :arg-parser #'identity
   :meta-var "FILE"))

and we read them with (opts:get-opts) which returns two values, a list of parsed options and the remaining arguments, so:

(multiple-value-bind (options free-args)
    (opts:get-opts)
  (if (getf options :verbose)
      ...

See the example for helpers and how to handle malformed or incomplete arguments.

And here is some action:

$ sh example.sh --help
example—program to demonstrate unix-opts library

Usage: example.sh [-h|--help] [-v|--verbose] [-l|--level LEVEL]
                  [-o|--output FILE] [FREE-ARGS]

Available options:
  -h, --help               print this help text
  -v, --verbose            verbose output
  -l, --level LEVEL        the program will run on LEVEL level
  -o, --output FILE        redirect output to file FILE

so that's how it works…
free args:

$ sh example.sh --level 1 -v file1.txt file2.txt
OK, running in verbose mode…
I see you've supplied level option, you want 1 level!
free args: file1.txt, file2.txt

$ sh example.sh --level 10 --output foo.txt bar.txt
I see you've supplied level option, you want 10 level!
I see you want to output the stuff to "foo.txt"!
free args: bar.txt

$ sh example.sh --level kitty foo.txt
fatal: cannot parse "kitty" as argument of "--level"
free args:

$ sh example.sh --hoola-boola noola.txt
warning: "--hoola-boola" option is unknown!
fatal: missing required options: "--level"

$ sh example.sh -vgl=10
warning: "-g" option is unknown!
OK, running in verbose mode…
I see you've supplied level option, you want 10 level!
free args:

License

Copyright © 2015–2018 Mark Karpov

Distri


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

2 Systems

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


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

2.1 unix-opts

Author

Mark Karpov

License

MIT

Description

minimalistic parser of command line arguments

Version

0.1.7

Source

unix-opts.asd (file)

Component

unix-opts.lisp (file)


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

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

3.1.1 unix-opts.asd

Location

unix-opts.asd

Systems

unix-opts (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 unix-opts/unix-opts.lisp

Parent

unix-opts (system)

Location

unix-opts.lisp

Packages

unix-opts

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 unix-opts

Source

unix-opts.lisp (file)

Nickname

opts

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: define-opts &body DESCRIPTIONS

Define command line options. Arguments of this macro must be plists containing various parameters. Here we enumerate all allowed parameters:

:NAME—keyword that will be included in list returned by GET-OPTS function if actual option is supplied by user.

:DESCRIPTION—description of the option (it will be used in DESCRIBE function). This argument is optional, but it’s recommended to supply it.

:SHORT—single character, short variant of the option. You may omit this argument if you supply :LONG variant of option.

:LONG—string, long variant of option. You may omit this argument if you supply :SHORT variant of option.

:ARG-PARSER—if actual option must take an argument, supply this argument, it must be a function that takes a string and parses it.

:META-VAR—if actual option requires an argument, this is how it will be printed in option description.

Package

unix-opts

Source

unix-opts.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: argv ()

Return a list of program’s arguments, including command used to execute the program as first elements of the list. Portable across implementations.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: describe &key PREFIX SUFFIX USAGE-OF ARGS STREAM

Return string describing options of the program that were defined with ‘define-opts’ macro previously. You can supply PREFIX and SUFFIX arguments that will be printed before and after options respectively. If USAGE-OF is supplied, it should be a string, name of the program for "Usage: " section. This section is only printed if this name is given. If your program takes arguments (apart from options), you can specify how to print them in "Usage: " section with ARGS option (should be a string designator). Output goes to STREAM.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: exit &optional STATUS

Exit the program returning ‘status’.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: get-opts &optional OPTIONS

Parse command line options. If OPTIONS is given, it should be a list to parse. If it’s not given, the function will use ‘argv’ function to get list of command line arguments.

Return two values:

* a list that contains keywords associated with command line options with ‘define-opts’ macro, and
* a list of free arguments.

If some option requires an argument, you can use ‘getf’ to
test presence of the option and get its argument if the option is present.

The parser may signal various conditions. Let’s list them all specifying which restarts are available for every condition, and what kind of information the programmer can extract from the conditions.

‘unknown-option’ is thrown when parser encounters unknown (not previously defined with ‘define-opts’) option. Use the ‘option’ reader to get name of the option (string). Available restarts: ‘use-value’ (substitute the option and try again), ‘skip-option’ (ignore the option).

‘missing-arg’ is thrown when some option wants an argument, but there is no such argument given. Use the ‘option’ reader to get name of the
option (string). Available restarts: ‘use-value’ (supplied value will be used), ‘skip-option’ (ignore the option).

‘arg-parser-failed’ is thrown when some option wants an argument, it’s given but cannot be parsed by argument parser. Use the ‘option’ reader to get name of the option (string) and ‘raw-arg’ to get raw string representing the argument before parsing. Available restarts: ‘use-value’ (supplied value will be used), ‘skip-option’ (ignore the option), ‘reparse-arg’ (supplied string will be parsed instead).

‘missing-required-option’ is thrown when some option was required but was not given. Use the ‘missing-options’ reader to get the list of options that are missing. Available restarts: ‘use-value’ (supplied list of values will be used), ‘skip-option’ (ignore all these options, effectively binding them to ‘nil’)

Package

unix-opts

Source

unix-opts.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Generic functions

Generic Function: missing-options CONDITION
Package

unix-opts

Methods
Method: missing-options (CONDITION missing-required-option)
Source

unix-opts.lisp (file)

Generic Function: option CONDITION
Package

unix-opts

Methods
Method: option (CONDITION troublesome-option)
Source

unix-opts.lisp (file)

Generic Function: raw-arg CONDITION
Package

unix-opts

Methods
Method: raw-arg (CONDITION arg-parser-failed)
Source

unix-opts.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Conditions

Condition: arg-parser-failed ()

This condition is thrown when some option OPTION wants
an argument, it’s given but cannot be parsed by argument parser.

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

troublesome-option (condition)

Direct methods

raw-arg (method)

Direct slots
Slot: raw-arg
Initargs

:raw-arg

Readers

raw-arg (generic function)

Condition: missing-arg ()

This condition is thrown when some option OPTION wants an argument, but there is no such argument given.

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

troublesome-option (condition)

Condition: missing-required-option ()

This condition is thrown when required options are missing.

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

troublesome-option (condition)

Direct methods

missing-options (method)

Direct slots
Slot: missing-options
Initargs

:missing-options

Readers

missing-options (generic function)

Condition: unknown-option ()

This condition is thrown when parser encounters
unknown (not previously defined with ‘define-opts’) option.

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

troublesome-option (condition)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Classes

Class: option ()

representation of an option

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name

keyword that will be included in list returned by ‘get-opts’ function if this option is given by user

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: description

description of the option

Initargs

:description

Readers

description (generic function)

Writers

(setf description) (generic function)

Slot: short

NIL or single char - short variant of the option

Initargs

:short

Readers

short (generic function)

Writers

(setf short) (generic function)

Slot: long

NIL or string - long variant of the option

Initargs

:long

Readers

long (generic function)

Writers

(setf long) (generic function)

Slot: required

If not NIL this argument is required.

Initargs

:required

Readers

required (generic function)

Writers

(setf required) (generic function)

Slot: arg-parser

if not NIL, this option requires an argument, it will be parsed with this function

Initargs

:arg-parser

Readers

arg-parser (generic function)

Writers

(setf arg-parser) (generic function)

Slot: meta-var

if this option requires an argument, this is how it will be printed in option description

Initargs

:meta-var

Readers

meta-var (generic function)

Writers

(setf meta-var) (generic function)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *options*

List of all defined options.

Package

unix-opts

Source

unix-opts.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: add-option &rest ARGS

Register an option according to ARGS.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: add-text-padding STR &key PADDING NEWLINE

Add padding to text STR. Every line except for the first one, will be prefixed with PADDING spaces. If NEWLINE is non-NIL, newline character will be prepended to the text making it start on the next line with padding applied to every single line.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: argp STR

Check if string STR is an argument (not option).

Package

unix-opts

Source

unix-opts.lisp (file)

Function: find-option OPT

Find option OPT and return object that represents it or NIL.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: longp OPT

Predicate that checks if OPT is a long option.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: optionp STR

This predicate checks if string STR is an option.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: print-opts &optional STREAM

Print info about defined options to STREAM. Every option get its own line with description.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: print-opts* MARGIN

Return a string containing info about defined options. All options are displayed on one line, although this function tries to print it elegantly if it gets too long. MARGIN specifies margin.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: shortp OPT

Predicate that checks if OPT is a short option.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: split-on-= ARG

Split string ARG on "=", return value is list of strings.

Package

unix-opts

Source

unix-opts.lisp (file)

Function: split-short-opts ARG

Split short options, for example "-ab" will produce "-a" and "-b". ARG must be a string, return value is list of strings.

Package

unix-opts

Source

unix-opts.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: arg-parser OBJECT
Generic Function: (setf arg-parser) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: arg-parser (OPTION option)
Method: (setf arg-parser) NEW-VALUE (OPTION option)

if not NIL, this option requires an argument, it will be parsed with this function

Source

unix-opts.lisp (file)

Generic Function: description OBJECT
Generic Function: (setf description) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: description (OPTION option)
Method: (setf description) NEW-VALUE (OPTION option)

description of the option

Source

unix-opts.lisp (file)

Generic Function: long OBJECT
Generic Function: (setf long) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: long (OPTION option)
Method: (setf long) NEW-VALUE (OPTION option)

NIL or string - long variant of the option

Source

unix-opts.lisp (file)

Generic Function: meta-var OBJECT
Generic Function: (setf meta-var) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: meta-var (OPTION option)
Method: (setf meta-var) NEW-VALUE (OPTION option)

if this option requires an argument, this is how it will be printed in option description

Source

unix-opts.lisp (file)

Generic Function: name OBJECT
Generic Function: (setf name) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: name (OPTION option)
Method: (setf name) NEW-VALUE (OPTION option)

keyword that will be included in list returned by ‘get-opts’ function if this option is given by user

Source

unix-opts.lisp (file)

Generic Function: required OBJECT
Generic Function: (setf required) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: required (OPTION option)
Method: (setf required) NEW-VALUE (OPTION option)

If not NIL this argument is required.

Source

unix-opts.lisp (file)

Generic Function: short OBJECT
Generic Function: (setf short) NEW-VALUE OBJECT
Package

unix-opts

Methods
Method: short (OPTION option)
Method: (setf short) NEW-VALUE (OPTION option)

NIL or single char - short variant of the option

Source

unix-opts.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Conditions

Condition: troublesome-option ()

Generalization over conditions that have to do with some particular option.

Package

unix-opts

Source

unix-opts.lisp (file)

Direct superclasses

simple-error (condition)

Direct subclasses
Direct methods

option (method)

Direct slots
Slot: option
Initargs

:option

Readers

option (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   U  
Index Entry  Section

F
File, Lisp, unix-opts.asd: The unix-opts<dot>asd file
File, Lisp, unix-opts/unix-opts.lisp: The unix-opts/unix-opts<dot>lisp file

L
Lisp File, unix-opts.asd: The unix-opts<dot>asd file
Lisp File, unix-opts/unix-opts.lisp: The unix-opts/unix-opts<dot>lisp file

U
unix-opts.asd: The unix-opts<dot>asd file
unix-opts/unix-opts.lisp: The unix-opts/unix-opts<dot>lisp file

Jump to:   F   L   U  

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

A.2 Functions

Jump to:   (  
A   D   E   F   G   L   M   N   O   P   R   S  
Index Entry  Section

(
(setf arg-parser): Internal generic functions
(setf arg-parser): Internal generic functions
(setf description): Internal generic functions
(setf description): Internal generic functions
(setf long): Internal generic functions
(setf long): Internal generic functions
(setf meta-var): Internal generic functions
(setf meta-var): Internal generic functions
(setf name): Internal generic functions
(setf name): Internal generic functions
(setf required): Internal generic functions
(setf required): Internal generic functions
(setf short): Internal generic functions
(setf short): Internal generic functions

A
add-option: Internal functions
add-text-padding: Internal functions
arg-parser: Internal generic functions
arg-parser: Internal generic functions
argp: Internal functions
argv: Exported functions

D
define-opts: Exported macros
describe: Exported functions
description: Internal generic functions
description: Internal generic functions

E
exit: Exported functions

F
find-option: Internal functions
Function, add-option: Internal functions
Function, add-text-padding: Internal functions
Function, argp: Internal functions
Function, argv: Exported functions
Function, describe: Exported functions
Function, exit: Exported functions
Function, find-option: Internal functions
Function, get-opts: Exported functions
Function, longp: Internal functions
Function, optionp: Internal functions
Function, print-opts: Internal functions
Function, print-opts*: Internal functions
Function, shortp: Internal functions
Function, split-on-=: Internal functions
Function, split-short-opts: Internal functions

G
Generic Function, (setf arg-parser): Internal generic functions
Generic Function, (setf description): Internal generic functions
Generic Function, (setf long): Internal generic functions
Generic Function, (setf meta-var): Internal generic functions
Generic Function, (setf name): Internal generic functions
Generic Function, (setf required): Internal generic functions
Generic Function, (setf short): Internal generic functions
Generic Function, arg-parser: Internal generic functions
Generic Function, description: Internal generic functions
Generic Function, long: Internal generic functions
Generic Function, meta-var: Internal generic functions
Generic Function, missing-options: Exported generic functions
Generic Function, name: Internal generic functions
Generic Function, option: Exported generic functions
Generic Function, raw-arg: Exported generic functions
Generic Function, required: Internal generic functions
Generic Function, short: Internal generic functions
get-opts: Exported functions

L
long: Internal generic functions
long: Internal generic functions
longp: Internal functions

M
Macro, define-opts: Exported macros
meta-var: Internal generic functions
meta-var: Internal generic functions
Method, (setf arg-parser): Internal generic functions
Method, (setf description): Internal generic functions
Method, (setf long): Internal generic functions
Method, (setf meta-var): Internal generic functions
Method, (setf name): Internal generic functions
Method, (setf required): Internal generic functions
Method, (setf short): Internal generic functions
Method, arg-parser: Internal generic functions
Method, description: Internal generic functions
Method, long: Internal generic functions
Method, meta-var: Internal generic functions
Method, missing-options: Exported generic functions
Method, name: Internal generic functions
Method, option: Exported generic functions
Method, raw-arg: Exported generic functions
Method, required: Internal generic functions
Method, short: Internal generic functions
missing-options: Exported generic functions
missing-options: Exported generic functions

N
name: Internal generic functions
name: Internal generic functions

O
option: Exported generic functions
option: Exported generic functions
optionp: Internal functions

P
print-opts: Internal functions
print-opts*: Internal functions

R
raw-arg: Exported generic functions
raw-arg: Exported generic functions
required: Internal generic functions
required: Internal generic functions

S
short: Internal generic functions
short: Internal generic functions
shortp: Internal functions
split-on-=: Internal functions
split-short-opts: Internal functions

Jump to:   (  
A   D   E   F   G   L   M   N   O   P   R   S  

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

A.3 Variables

Jump to:   *  
A   D   L   M   N   O   R   S  
Index Entry  Section

*
*options*: Internal special variables

A
arg-parser: Exported classes

D
description: Exported classes

L
long: Exported classes

M
meta-var: Exported classes
missing-options: Exported conditions

N
name: Exported classes

O
option: Internal conditions

R
raw-arg: Exported conditions
required: Exported classes

S
short: Exported classes
Slot, arg-parser: Exported classes
Slot, description: Exported classes
Slot, long: Exported classes
Slot, meta-var: Exported classes
Slot, missing-options: Exported conditions
Slot, name: Exported classes
Slot, option: Internal conditions
Slot, raw-arg: Exported conditions
Slot, required: Exported classes
Slot, short: Exported classes
Special Variable, *options*: Internal special variables

Jump to:   *  
A   D   L   M   N   O   R   S  

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

A.4 Data types

Jump to:   A   C   M   O   P   S   T   U  
Index Entry  Section

A
arg-parser-failed: Exported conditions

C
Class, option: Exported classes
Condition, arg-parser-failed: Exported conditions
Condition, missing-arg: Exported conditions
Condition, missing-required-option: Exported conditions
Condition, troublesome-option: Internal conditions
Condition, unknown-option: Exported conditions

M
missing-arg: Exported conditions
missing-required-option: Exported conditions

O
option: Exported classes

P
Package, unix-opts: The unix-opts package

S
System, unix-opts: The unix-opts system

T
troublesome-option: Internal conditions

U
unix-opts: The unix-opts system
unix-opts: The unix-opts package
unknown-option: Exported conditions

Jump to:   A   C   M   O   P   S   T   U