The just-getopt-parser Reference Manual

Table of Contents

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

The just-getopt-parser Reference Manual

This is the just-getopt-parser Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Fri May 24 08:12:45 2019 GMT+0.


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

1 Introduction

Just Getopt Parser

Getopt-like command-line parser for the Common Lisp language

Introduction

Just Getopt Parser is a Common Lisp package that implements Unix Getopt command-line parser. The intention is to be just that: the parser functionality with clear Lisp programming interface and nothing more. Package's main interface is getopt function which parses the command line options and organizes them to valid options, other arguments and unknown arguments. There are also optional Lisp conditions for error situations. For full documentation on package's programming interface see section The Programming Interface below.

Examples

Example command line:

$ some-program -d3 -f one --file=two -xyz foo --none bar -v -- -v

That command line could be parsed with the following function call:

(getopt '("-d3" "-f" "one" "--file=two" "-xyz" "foo"
          "--none" "bar" "-v" "--" "-v")
        '((:debug #\d :optional)
          (:file #\f :required)
          (:file "file" :required)
          (:verbose #\v))
        :options-everywhere t)

The function returns three values: (1) valid options and their arguments, (2) other arguments and (3) unknown options:

((:DEBUG . "3") (:FILE . "one") (:FILE . "two") (:VERBOSE))
("foo" "bar" "-v")
(#\x #\y #\z "none")

In programs it is probably convenient to call this function through cl:multiple-value-bind so that the return values are bound to different variables:

(multiple-value-bind (options other unknown)
    (getopt COMMAND-LINE-ARGUMENTS '(...))

  ...
  )

In practice there is probably also cl:handler-bind macro which handles error conditions by printing error messages, invoking skip-option restarts or transferring the program control elsewhere. Here is more thorough example:

(handler-bind
    ((ambiguous-option
       (lambda (condition)
         (format *error-output* "~A~%" condition)
         (invoke-restart 'skip-option)))
     (unknown-option
       (lambda (condition)
         (format *error-output* "~A~%" condition)
         (invoke-restart 'skip-option)))
     (required-argument-missing
       (lambda (condition)
         (format *error-output* "~A~%" condition)
         (exit-program :code 1)))
     (argument-not-allowed
       (lambda (condition)
         (format *error-output* "~A~%" condition)
         (exit-program :code 1))))

  (multiple-value-bind (options other unknown)
      (getopt COMMAND-LINE-ARGUMENTS '(...)
              :prefix-match-long-options t
              :error-on-ambiguous-option t
              :error-on-unknown-option t
              :error-on-argument-missing t
              :error-on-argument-not-allowed t)

    ...
    ))

License and Source Code

Author: Teemu Likonen <tlikonen@iki.fi>

OpenPGP key: 4E10 55DC 84E9 DFF6 13D7 8557 719D 69D3 2453 9450

License: Creative Commons CC0 (public domain dedication)

The source code repository: https://github.com/tlikonen/cl-just-getopt-parser

The Programming Interface

Condition: ambiguous-option

getopt function may signal this condition when it parses a partially-written option name that matches to two or more long option names. Function option-name can be used to read option's name from the condition object. Function option-matches will return the matching options.

Condition: argument-not-allowed

getopt function may signal this condition when it parses an option that does not allow an argument but one is given with "--foo=...". Function option-name can be used to read option's name from the condition object.

Condition: required-argument-missing

getopt function may signal this condition when it parses an option that required an argument but there is none. Function option-name can be used to read option's name from the condition object.

Condition: unknown-option

getopt function may signal this condition when it finds an unknown condition. Function option-name can be used to read option's name from the condition object.

Function: getopt

The lambda list:

 (arguments option-specification &key options-everywhere
  prefix-match-long-options error-on-ambiguous-option
  error-on-unknown-option error-on-argument-missing
  error-on-argument-not-allowed)

Parse command-line arguments like getopt.

The arguments is a list of strings and contains the command-line arguments that typically come from program's user.

option-specification argument is the specification of valid command-line options. It is a list that contains lists of the following format (in lambda list format):

(symbol option-name &optional option-argument)

The first element symbol is any symbol which identifies this command-line option (for example keyword symbol :help). The identifier is used in function's return value to identify that this particular option was present in the command line.

The second element option-name is either

  1. a character specifying a short option name (for example #\h, entered as -h in command line)

  2. a string specifying a long option (for example "help", entered as --help in command line). The string must be at least two characters long.

The third element option-argument is optional but if it is non-nil it must be one of the following keyword symbols: :required means that this option requires an argument; :optional means that this option has an optional argument. Example value for this function's option-specification argument:

((:help #\h)     ; short option -h for help (no option argument)
 (:help "help")  ; long option --help (no option argument)
 (:file "file" :required) ; --file option which requires argument
 (:debug #\d :optional))  ; -d option with optional argument

Note that several options may have the same identifier symbol. This makes sense when short and long option represent the same meaning. See the :help keyword symbol above. All options must have unique option-name though.

If function's key argument options-everywhere is nil (the default) the option parsing stops when the first non-option argument is found. Rest of the command line is parsed as non-options. If options-everywhere is non-nil then options can be found anywhere in the command line, even after non-option arguments. In all cases the option parsing stops when the pseudo-option -- is found in the command line. Then all remaining arguments are parsed as non-option arguments.

If key argument prefix-match-long-options is non-nil then long options don't need to be written in full in the command line. They can be shortened as long as there are enough characters to find unique prefix match. If there are more than one match the option is classified as unknown. If also key argument error-on-ambiguous-option is non-nil the function will signal error condition ambiguous-option. The condition object contains the option's name and it can be read with function call (option-name condition). Function call (option-matches condition) returns a list of option matches (strings). Also, the condition object can be printed as an error message for user. There is skip-option restart available. When it is invoked the ambiguous option is skipped and the function will continue parsing the command line. Ambiguous options are always also unknown options: if ambiguous-option condition is not signaled then the condition for unknown option can be signaled. See the next paragraph.

If function's key argument error-on-unknown-option is non-nil and the function finds an unknown option on the command line the function signals error condition unknown-option. The condition object includes the name of the unknown option which can be read with function (option-name condition). The return value is of type character or string for short or long options respectively. You can also just print the condition object: it gives a reasonable error message. There is active skip-option restart. The invoked restart skips the unknown option and continues parsing the command line.

Function's key argument error-on-argument-missing (if non-nil) causes the function to signal error condition required-argument-missing if it sees an option which requires argument (keyword :required) but there is none. The condition object contains the name of the option which can be read with function call (option-name condition). You can also just print the condition object for user. It is an error message. There are two restarts available: give-argument restart can be invoked with an optional argument (string or nil) which will be passed as a new argument for the option; restart skip-option will just skip this option and continue parsing.

Key argument error-on-argument-not-allowed (if non-nil) makes this function to signal error condition argument-not-allowed if there is an argument for a long option which does not allow argument (--foo=...). Such option is always listed as unknown option with name "foo=" in function's return value. The condition object can be printed to user as error message. The object also contains the name of the option which can be read with (option-name condition) function call. There is skip-option restart available. When the restart is invoked the function continues parsing the command line.

Return values

The function returns three values:

  1. List of parsed options. List's items are cons cells: the CAR part of the cons cell is the identifier symbol for the option; the CDR part of the cons cell is either nil (if there is no argument for this option) or a string containing option's argument.

  2. List of non-option arguments (strings).

  3. List of unknown options. List's items are either characters or strings which represent unknown short or long command-line options which were not defined in the option-specification.

In all three return values the list's items are in the same order as they were given in the function's arguments argument.

Parsing rules for short options

Short options in the command line start with the - character and the option character follows (-c).

If option requires an argument (keyword :required) the argument must be entered either directly after the option character (-cARG) or as the next command-line argument (-c ARG). In the latter case anything that follows -c will be parsed as option's argument.

If option has optional argument (keyword :optional) it must always be entered directly after the option character (-cARG). Otherwise there is no argument for this option.

Several short options can be entered together after one - character (-abc) but then only the last option in the series may have required or optional argument.

Parsing rules for long options

Long options start with -- characters and the option name comes directly after it (--foo).

If option requires an argument (keyword :required) it must be entered either directly after the option name and = character (--foo=ARG) or as the next command-line argument (--foo ARG). In the latter case anything that follows --foo will be parsed as its argument.

If option has optional argument (keyword :optional) the argument must always be entered directly after the option name and = character (--foo=ARG). Otherwise (like in --foo) there is no argument for this option.

Option --foo= is valid format when the option requires argument or accepts optional argument. It means that the argument is empty string.


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 just-getopt-parser

Author

Teemu Likonen <tlikonen@iki.fi>

License

Creative Commons CC0 (public domain dedication)

Description

Getopt-like parser for command-line options and arguments

Source

just-getopt-parser.asd (file)

Component

just-getopt-parser.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 just-getopt-parser.asd

Location

just-getopt-parser.asd

Systems

just-getopt-parser (system)


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

3.1.2 just-getopt-parser/just-getopt-parser.lisp

Parent

just-getopt-parser (system)

Location

just-getopt-parser.lisp

Packages

just-getopt-parser

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 just-getopt-parser

Source

just-getopt-parser.lisp (file)

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 Functions

Function: getopt ARGUMENTS OPTION-SPECIFICATION &key OPTIONS-EVERYWHERE PREFIX-MATCH-LONG-OPTIONS ERROR-ON-AMBIGUOUS-OPTION ERROR-ON-UNKNOWN-OPTION ERROR-ON-ARGUMENT-MISSING ERROR-ON-ARGUMENT-NOT-ALLOWED

Parse command-line arguments like getopt.

The ‘arguments‘ is a list of strings and contains the command-line arguments that typically come from program’s user.

‘option-specification‘ argument is the specification of valid command-line options. It is a list that contains lists of the following format (in lambda list format):

(symbol option-name &optional option-argument)

The first element ‘symbol‘ is any symbol which identifies this command-line option (for example keyword symbol ‘:help‘). The identifier is used in function’s return value to identify that this particular option was present in the command line.

The second element ‘option-name‘ is either

1. a character specifying a short option name (for example ‘#\h‘, entered as ‘-h‘ in command line)

2. a string specifying a long option (for example ‘"help"‘, entered as ‘–help‘ in command line). The string must be at least two characters long.

The third element ‘option-argument‘ is optional but if it is non-nil it must be one of the following keyword symbols: ‘:required‘ means that this option requires an argument; ‘:optional‘ means that this option has an optional argument. Example value for this function’s ‘option-specification‘ argument:

((:help #\h) ; short option -h for help (no option argument) (:help "help") ; long option –help (no option argument) (:file "file" :required) ; –file option which requires argument (:debug #\d :optional)) ; -d option with optional argument

Note that several options may have the same identifier ‘symbol‘. This makes sense when short and long option represent the same meaning. See the ‘:help‘ keyword symbol above. All options must have unique ‘option-name‘ though.

If function’s key argument ‘options-everywhere‘ is nil (the default) the option parsing stops when the first non-option argument is found. Rest of the command line is parsed as non-options. If ‘options-everywhere‘ is non-nil then options can be found anywhere in the command line, even after non-option arguments. In all cases the option parsing stops when the pseudo-option ‘–‘ is found in the command line. Then all remaining arguments are parsed as non-option arguments.

If key argument ‘prefix-match-long-options‘ is non-nil then long options don’t need to be written in full in the command line. They can be shortened as long as there are enough characters to find unique prefix match. If there are more than one match the option is classified as unknown. If also key argument ‘error-on-ambiguous-option‘ is non-nil the function will signal error condition ‘ambiguous-option‘. The condition object contains the option’s name and it can be read with function call ‘(option-name condition)‘. Function call ‘(option-matches condition)‘ returns a list of option matches (strings). Also, the condition object can be printed as an error message for user. There is ‘skip-option‘ restart available. When it is invoked the ambiguous option is skipped and the function will continue parsing the command line. Ambiguous options are always also unknown options: if ‘ambiguous-option‘ condition is not signaled then the condition for unknown option can be signaled. See the next paragraph.

If function’s key argument ‘error-on-unknown-option‘ is non-nil and the function finds an unknown option on the command line the function signals error condition ‘unknown-option‘. The condition object includes the name of the unknown option which can be read with
function ‘(option-name condition)‘. The return value is of type character or string for short or long options respectively. You can also just print the condition object: it gives a reasonable error message. There is active ‘skip-option‘ restart. The invoked restart skips the unknown option and continues parsing the command line.

Function’s key argument ‘error-on-argument-missing‘ (if non-nil) causes the function to signal error condition ‘required-argument-missing‘ if it sees an option which requires argument (keyword ‘:required‘) but there is none. The condition object contains the name of the option which can be read with function call ‘(option-name condition)‘. You can also just print the condition object for user. It is an error message. There are two restarts available: ‘give-argument‘ restart can be invoked with an optional argument (string or nil) which will be passed as a new argument for the option; restart ‘skip-option‘ will just skip this option and continue parsing.

Key argument ‘error-on-argument-not-allowed‘ (if non-nil) makes this function to signal error condition ‘argument-not-allowed‘ if there is an argument for a long option which does not allow argument (‘–foo=...‘). Such option is always listed as unknown option with name ‘"foo="‘ in function’s return value. The condition object can be printed to user as error message. The object also contains the name of the option which can be read with ‘(option-name condition)‘ function call. There is ‘skip-option‘ restart available. When the restart is invoked the function continues parsing the command line.

#### Return values

The function returns three values:

1. List of parsed options. List’s items are cons cells: the CAR part of the cons cell is the identifier symbol for the option; the CDR part of the cons cell is either nil (if there is no argument for this option) or a string containing option’s argument.

2. List of non-option arguments (strings).

3. List of unknown options. List’s items are either characters or strings which represent unknown short or long command-line options which were not defined in the ‘option-specification‘.

In all three return values the list’s items are in the same order as they were given in the function’s ‘arguments‘ argument.

#### Parsing rules for short options

Short options in the command line start with the ‘-‘ character and the option character follows (‘-c‘).

If option requires an argument (keyword ‘:required‘) the argument must be entered either directly after the option character (‘-cARG‘) or as the next command-line argument (‘-c ARG‘). In the latter case anything that follows ‘-c‘ will be parsed as option’s argument.

If option has optional argument (keyword ‘:optional‘) it must always be entered directly after the option character (‘-cARG‘). Otherwise there is no argument for this option.

Several short options can be entered together after one ‘-‘ character (‘-abc‘) but then only the last option in the series may have required or optional argument.

#### Parsing rules for long options

Long options start with ‘–‘ characters and the option name comes directly after it (‘–foo‘).

If option requires an argument (keyword ‘:required‘) it must be entered either directly after the option name and ‘=‘ character (‘–foo=ARG‘) or as the next command-line argument (‘–foo ARG‘). In the latter case anything that follows ‘–foo‘ will be parsed as its argument.

If option has optional argument (keyword ‘:optional‘) the argument must always be entered directly after the option name and ‘=‘
character (‘–foo=ARG‘). Otherwise (like in ‘–foo‘) there is no argument for this option.

Option ‘–foo=‘ is valid format when the option requires argument or accepts optional argument. It means that the argument is empty string.

Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)


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

5.1.2 Generic functions

Generic Function: option-matches CONDITION
Package

just-getopt-parser

Methods
Method: option-matches (CONDITION ambiguous-option)
Source

just-getopt-parser.lisp (file)

Generic Function: option-name CONDITION
Package

just-getopt-parser

Methods
Method: option-name (CONDITION argument-error)
Source

just-getopt-parser.lisp (file)


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

5.1.3 Conditions

Condition: ambiguous-option ()

‘getopt‘ function may signal this condition when it parses a partially-written option name that matches to two or more long option names. Function ‘option-name‘ can be used to read option’s name from the condition object. Function ‘option-matches‘ will return the matching options.

Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Direct superclasses

argument-error (condition)

Direct methods

option-matches (method)

Direct slots
Slot: matches
Initargs

:matches

Readers

option-matches (generic function)

Condition: argument-not-allowed ()

‘getopt‘ function may signal this condition when it parses an option that does not allow an argument but one is given with "–foo=...". Function ‘option-name‘ can be used to read option’s name from the condition object.

Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Direct superclasses

argument-error (condition)

Condition: required-argument-missing ()

‘getopt‘ function may signal this condition when it parses an option that required an argument but there is none. Function ‘option-name‘ can be used to read option’s name from the condition object.

Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Direct superclasses

argument-error (condition)

Condition: unknown-option ()

‘getopt‘ function may signal this condition when it finds an unknown condition. Function ‘option-name‘ can be used to read option’s name from the condition object.

Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Direct superclasses

argument-error (condition)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: check-duplicate-names SPECIFICATION
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-long-option-string STRING
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-option-argument FIELD
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-option-identifier IDENTIFIER
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-option-name NAME
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-option-specification SPECIFICATION
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: check-short-option-character NAME
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: format-option-name NAME
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Function: match-long-option NAME SPECIFICATION &key PREFIX
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)


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

5.2.2 Conditions

Condition: argument-error ()
Package

just-getopt-parser

Source

just-getopt-parser.lisp (file)

Direct superclasses

error (condition)

Direct subclasses
Direct methods

option-name (method)

Direct slots
Slot: option
Initargs

:option

Readers

option-name (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   J   L  
Index Entry  Section

F
File, Lisp, just-getopt-parser.asd: The just-getopt-parser<dot>asd file
File, Lisp, just-getopt-parser/just-getopt-parser.lisp: The just-getopt-parser/just-getopt-parser<dot>lisp file

J
just-getopt-parser.asd: The just-getopt-parser<dot>asd file
just-getopt-parser/just-getopt-parser.lisp: The just-getopt-parser/just-getopt-parser<dot>lisp file

L
Lisp File, just-getopt-parser.asd: The just-getopt-parser<dot>asd file
Lisp File, just-getopt-parser/just-getopt-parser.lisp: The just-getopt-parser/just-getopt-parser<dot>lisp file

Jump to:   F   J   L  

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

A.2 Functions

Jump to:   C   F   G   M   O  
Index Entry  Section

C
check-duplicate-names: Internal functions
check-long-option-string: Internal functions
check-option-argument: Internal functions
check-option-identifier: Internal functions
check-option-name: Internal functions
check-option-specification: Internal functions
check-short-option-character: Internal functions

F
format-option-name: Internal functions
Function, check-duplicate-names: Internal functions
Function, check-long-option-string: Internal functions
Function, check-option-argument: Internal functions
Function, check-option-identifier: Internal functions
Function, check-option-name: Internal functions
Function, check-option-specification: Internal functions
Function, check-short-option-character: Internal functions
Function, format-option-name: Internal functions
Function, getopt: Exported functions
Function, match-long-option: Internal functions

G
Generic Function, option-matches: Exported generic functions
Generic Function, option-name: Exported generic functions
getopt: Exported functions

M
match-long-option: Internal functions
Method, option-matches: Exported generic functions
Method, option-name: Exported generic functions

O
option-matches: Exported generic functions
option-matches: Exported generic functions
option-name: Exported generic functions
option-name: Exported generic functions

Jump to:   C   F   G   M   O  

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

A.3 Variables

Jump to:   M   O   S  
Index Entry  Section

M
matches: Exported conditions

O
option: Internal conditions

S
Slot, matches: Exported conditions
Slot, option: Internal conditions

Jump to:   M   O   S  

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

A.4 Data types

Jump to:   A   C   J   P   R   S   U  
Index Entry  Section

A
ambiguous-option: Exported conditions
argument-error: Internal conditions
argument-not-allowed: Exported conditions

C
Condition, ambiguous-option: Exported conditions
Condition, argument-error: Internal conditions
Condition, argument-not-allowed: Exported conditions
Condition, required-argument-missing: Exported conditions
Condition, unknown-option: Exported conditions

J
just-getopt-parser: The just-getopt-parser system
just-getopt-parser: The just-getopt-parser package

P
Package, just-getopt-parser: The just-getopt-parser package

R
required-argument-missing: Exported conditions

S
System, just-getopt-parser: The just-getopt-parser system

U
unknown-option: Exported conditions

Jump to:   A   C   J   P   R   S   U