Getopt-like parser for command-line options and arguments

cl-just-getopt-parser

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)
             (exit-program :code 1)))
         (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: [6965F03973F0D4CA22B9410F0F2CAE0E07608462][PGP]

License: [Creative Commons CC0][CC0] (public domain dedication)

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

[PGP]: http://www.iki.fi/tlikonen/pgp-key.asc
[CC0]: https://creativecommons.org/publicdomain/zero/1.0/legalcode


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: `invalid-option-specification`

`getopt` function signals this condition if its
`option-specification` argument is invalid. Function `error-string` can
be used to read error string 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
option. 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 `option-specification` argument is not in correct form an error of
type `invalid-option-specification` is signaled.

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.




cl-just-getopt-parser

Upstream URL

Author

License

just-getopt-parser

License:

Authors:

Dependencies:

Dependencies (0)

Dependents (0)