Adopt

Usage

Adopt is a library for parsing UNIX-style command line arguments in Common Lisp. It was made because none of the other libraries did what I needed.

Package

All core Adopt functions are in the adopt package. Several of the symbols in adopt shadow those in the common-lisp package, so you should probably use namespaced adopt:… symbols instead of USEing the package.

Interfaces

To get started with Adopt you can create an interface object with adopt:make-interface. This returns an object representing the command line interface presented to your users.

Creating an Interface

Let's say you're developing a program to search the contents of files (because the world certainly needs another grep replacement). You might start with something like:

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help "Search the contents of each FILE for the regular expression PATTERN.  If no files are specified, searches standard input instead."))

make-interface takes several required arguments:

:name is the name of the program.
:summary is a concise one-line summary of what it does. By convention it should not be a full sentence, but just a snippet of text.
:usage is a UNIX-style the command line usage string.
:help is a longer description of the program.

You can now print some pretty help text for the CLI with adopt:print-help:

(adopt:print-help *ui*)
; =>
; search - search files for a regular expression
;
; USAGE: /path/to/binary [OPTIONS] PATTERN [FILE]...
;
; Search the contents of each FILE for the regular expression PATTERN.  If no
; files are specified, searches standard input instead.

Line Wrapping

Adopt will handle line-wrapping your help text, so you don't need to (and shouldn't) add extra line breaks when creating your interface.

If you want to line break the text in your source code to fit nicely in your text editor, remember that adopt:make-interface is just a function — you can use format (possibly with its ~Newline directive) to preprocess the help text argument:

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help (format nil "Search the contents of each FILE for ~
                       the regular expression PATTERN.  If ~
                       no files are specified, searches ~
                       standard input instead.")))

If you want to pull out the documentation string into its own variable to keep that make-interface call from getting too unwieldy, you can certainly do that:

(defparameter *help-text*
  (format nil "Search the contents of each FILE for the ~
               regular expression PATTERN.  If no files ~
               are specified, searches standard input ~
               instead."))

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help *help-text*))

The (defparameter … (format nil …)) pattern can be tedious to write, so Adopt provides a helper macro define-string that does exactly that:

(adopt:define-string *help-text*
  "Search the contents of each FILE for the regular ~
   expression PATTERN.  If no files are specified, ~
   searches standard input instead.")

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help *help-text*))

Adopt's line-wrapping library Bobbin will only ever add line breaks, never remove them, which means you can include breaks in the output if you want to have multiple paragraphs in your help text. Once again, format is your friend:

(adopt:define-string *help-text*
  "Search the contents of each FILE for the regular ~
   expression PATTERN.~@
   ~@
   If no files are specified (or if - is given as a ~
   file name), standard input will be searched instead.")

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help *help-text*))

If you want to control the width of the help text lines when they are printed, adopt:print-help takes a :width argument:

(adopt:print-help *ui* :width 50)
; =>
; search - search files for a regular expression
;
; USAGE: … [OPTIONS] PATTERN [FILE]...
;
; Search the contents of each FILE for the regular
; expression PATTERN.
;
; If no files are specified (or if - is given as a
; file name), standard input will be searched
; instead.

adopt:print-help takes a number of other options — see the API Reference for more information.

Adding Examples

Describing the CLI in detail is helpful, but users can often learn a lot more by seeing a few examples of its usage. make-interface can take an :examples argument, which should be an alist of (description . example) conses:

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help *help-text*
    :examples
    '(("Search foo.txt for the string 'hello':"
       . "search hello foo.txt")
      ("Search standard input for lines starting with x:"
       . "search '^x' -")
      ("Watch the file log.txt for lines containing the username steve.losh:"
       . "tail foo/bar/baz/log.txt | search --literal steve.losh -"))))

(adopt:print-help *ui* :width 50)
; =>
; search - search files for a regular expression
;
; USAGE: … [OPTIONS] PATTERN [FILE]...
;
; Search the contents of each FILE for the regular
; expression PATTERN.
;
; If no files are specified (or if - is given as a
; file name) standard input will be searched
; instead.
;
; Examples:
;
;   Search foo.txt for the string 'hello':
;
;       search hello foo.txt
;
;   Search standard input for lines starting with x:
;
;       search '^x' -
;
;   Watch the file log.txt for lines containing the
;   username steve.losh:
;
;       tail foo/bar/baz/log.txt | search --literal steve.losh -

Notice how Adopt line wraps the prose explaining each example, but leaves the example itself untouched for easier copying and pasting. In general Adopt tries to do the right thing for your users (even when that means making a little more work for you in certain places).

Exiting

Adopt provides some helpful utility functions to exit out of your program with a UNIX exit code. These do what you think they do:

(adopt:exit)

(adopt:exit 1)

(adopt:print-help-and-exit *ui*)

(adopt:print-help-and-exit *ui*
  :stream *error-output*
  :exit-code 1)

(handler-case (assert (= 1 0))
  (error (err)
    (adopt:print-error-and-exit err)))

These functions are not implemented for every Lisp implementation. PRs are welcome, or you can just write the implementation-specific calls in your program yourself if you prefer.

Options

Now that you know how to create an interface, you can create some options to use inside it with adopt:make-option:

(defparameter *option-version*
  (adopt:make-option 'version
    :long "version"
    :help "Display version and exit."
    :reduce (constantly t)))

(defparameter *option-help*
  (adopt:make-option 'help
    :long "help"
    :short #\h
    :help "Display help and exit."
    :reduce (constantly t)))

(defparameter *option-literal*
  (adopt:make-option 'literal
    :long "literal"
    :short #\l
    :help "Treat PATTERN as a literal string instead of a regular expression."
    :reduce (constantly t)))

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :summary "search files for a regular expression"
    :usage "[OPTIONS] PATTERN [FILE]..."
    :help "Search the contents of …"
    :contents (list
                *option-version*
                *option-help*
                *option-literal*)))

Adopt will automatically add the options to the help text:

(adopt:print-help *ui*)
; =>
; search - search files for a regular expression
;
; USAGE: /usr/local/bin/sbcl [OPTIONS] PATTERN [FILE]...
;
; Search the contents of …
;
; Options:
;   --version             Display version and exit.
;   -h, --help            Display help and exit.
;   -l, --literal         Treat PATTERN as a literal string instead of a regular
;                         expression.

The first argument to make-option is the name of the option, which we'll see put to use shortly. At least one of :short and :long is required, and :help text must be specified. We'll talk more about :reduce in a little while, but it too is required.

When writing :help text I recommend using a full sentence, starting with a capital letter and ending with appropriate punctuation. If there's a default value or behavior for the option, mention it in the help text with something like Search at most N lines (default 100)..

I prefer to define each option as its own global variable to keep the call to make-interface from getting too large and unwieldy, but feel free to do something like this if you prefer to avoid cluttering your package:

(defparameter *ui*
  (adopt:make-interface
    …
    :contents
    (list (adopt:make-option 'foo …)
          (adopt:make-option 'bar …)
          …)))

Parsing

At this point we've got an interface with some options, so we can use it to parse a list of strings we've received as command line arguments with adopt:parse-options:

(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
; =>
; ("foo.*" "a.txt" "b.txt")
; #<HASH-TABLE :TEST EQL :COUNT 3 {10103142A3}>

From now on I'll use a special pretty printer for hash tables to make it easier to see what's inside them:

(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
; =>
; ("foo.*" "a.txt" "b.txt")
; {LITERAL: T, VERSION: NIL, HELP: NIL}

parse-options returns two values:

A list of non-option arguments.
An eql hash table of the option keys and values.

We'll talk about how the option values are determined soon. The keys of the hash table are (by default) the option names given as the first argument to make-option. You can specify a different key for a particular option with the :result-key argument to make-option:

(defparameter *option-literal*
  (adopt:make-option 'literal
    :result-key 'pattern-is-literal
    :long "literal"
    :short #\l
    :help "Treat PATTERN as a literal string instead of a regular expression."
    :reduce (constantly t)))

;; …

(adopt:parse-options *ui* '("foo.*" "--literal" "a.txt" "b.txt"))
; =>
; ("foo.*" "a.txt" "b.txt")
; {PATTERN-IS-LITERAL: T, VERSION: NIL, HELP: NIL}

This can come in useful if you want multiple options that affect the same result (e.g. --verbose and --silent flags that toggle extra log output on and off).

Option Formats

Adopt tries to support the most common styles of long and short UNIX options.

Long options must be given with two dashes (--foo). If a long option takes a parameter it can be given as the next argument (--foo meow) or mashed together into the same argument using an equals sign (--foo=meow).

Short options must be given with a single dash (-f). If several short options do not take any parameters, they can be mashed together and given all at once (-xzvf). If a short option takes a parameter it can be given as the next argument (-n foo) or mashed together with the option -nfoo.

The special string -- signals that all remaining arguments are normal text arguments, and should not be parsed as options.

Top-Level Structure

We'll look at how the option values are computed shortly, but first let's see the overall structure of the programs you'll typically create with Adopt:

(defun run (pattern files &key literal)
  ;; Actually do something here.
  )

(defun toplevel ()
  (handler-case
      (multiple-value-bind (arguments options) (adopt:parse-options *ui*)
        (when (gethash 'help options)
          (adopt:print-help-and-exit *ui*))
        (when (gethash 'version options)
          (format t "1.0.0~%")
          (adopt:exit))
        (destructuring-bind (pattern . files) arguments
          (run pattern
               files
               :literal (gethash 'literal options))))
    (error (c)
      (adopt:print-error-and-exit c))))

(defun build ()
  (sb-ext:save-lisp-and-die "search" :executable t :toplevel #'toplevel))

This is a typical way to use Adopt. There are three important functions here:

The toplevel function takes care of parsing arguments and exiting with an appropriate status code if necessary.
The run function takes parsed, Lispy arguments and actually does something. When developing (in SLIME, VLIME, etc) you'll call run, because you don't want the program to exit when you're developing interactively.
The build function dumps an executable binary. For more complicated programs you might use something fancier, like ASDF or Shinmera's Deploy library instead.

In this example the toplevel function first uses a handler-case to trap all errors. If any error occurs it will print the error message and exit, to avoid confusing users by dropping them into a Lisp debugger REPL (which they probably won't understand). If you're developing a program just for yourself, you might want to omit this part and let yourself land in the debugger as usual.

Next it uses adopt:parse-options to parse the command line arguments and options. It them does some initial checks to see if the user wants --help or --version information. If so, it prints the requested information and exits.

Otherwise it destructures the arguments into the expected items and calls run with all the information it needs to do its job. If the destructuring-bind fails an error will be signaled, and the handler-case will print it and exit. If you want to be a nice person you could check that the arguments have the correct shape first, and return a friendlier error message to your users if they don't.

Computing Values with Reduce

So far we've talked about how to define an interface, print help text, parse a list of options, and the overall structure of the program you'll create with Adopt. Now we need to talk about how the options the user specifies are parsed and turned into the resulting hash table.

Not all command-line options are the same. There are several common types of options in the UNIX world:

Simple options that are either given or not, like --help or --version.
Boolean options, like git's -p/--paginate and --no-pager, where both options affect a single boolean flag.
Counted options, where the number of times they are given has an effect, like SSH's -v option (more -v's means more verbosity).
Options that take a single parameter, like Mercurial's --repository /path/to/repo option, which specifies the path to a repository to work on.
Options that collect all parameters they are given, like rsync's --exclude PATTERN, which you can pass multiple times to add several exclusions.

An option-parsing library needs to give you the tools to handle all of these cases (and more). Python's argparse library, for example, has a number of different "actions" to account to handle these various use cases. Adopt works differently: it uses an interface similar to reduce to let you do whatever you need.

First: before any options are parsed, all entries in the options hash table have their values set to the :initial-value given to make-option (or nil if none was specified).

Next: When you create an option you must specify a :reduce function that takes the current value (and, for options that take a parameter, the given parameter) and produces a new value each time the option is given.

You may also specify a :finally function that will be called on the final value after all parsing is done.

For convenience, if an option takes a parameter you may also specify a :key function, which will be called on the given string before it is passed to the :reduce function. For example: you might use this for an option that takes integers as arguments with something like :key #'parse-integer.

The combination of these four pieces will let you do just about anything you might want. Let's look at how to do some common option parsing tasks using these as our building blocks.

Simple Options

To define an option that just tracks whether it's ever been given, you can do something like:

(defparameter *option-help*
  (adopt:make-option 'help
    :long "help"
    :short #\h
    :help "Display help and exit."
    :initial-value nil
    :reduce (lambda (current-value)
              (declare (ignore current-value))
              t)))

But since nil is the default initial value and Common Lisp provides the handy constantly function, you can do this more concisely:

(defparameter *option-help*
  (adopt:make-option 'help
    :long "help"
    :short #\h
    :help "Display help and exit."
    :reduce (constantly t)))

Boolean Options

If you want to have multiple options that both affect the same key in the results, you can use :result-key to do this:

(defparameter *option-paginate*
  (adopt:make-option 'paginate
    :long "paginate"
    :short #\p
    :help "Turn pagination on."
    :reduce (constantly t)))

(defparameter *option-no-paginate*
  (adopt:make-option 'no-paginate
    :result-key 'paginate
    :long "no-paginate"
    :short #\P
    :help "Turn pagination off (the default)."
    :reduce (constantly nil)))

The way we've written this, if the user gives multiple options the last-given one will take precedence. This is generally what you want, because it allows someone to add a shell alias with these options like this:

alias g='git --paginate --color=always'

but still lets them override an option at runtime for a single invocation:

g --no-paginate log
# expands to: git --paginate --color=always --no-paginate log

If the last-given option didn't take precedence, they'd have to fall back to the non-alias version of the command, and type out all the options they do want by hand. This is annoying, so it's usually better to let the last one win.

Making two separate options by hand can be tedious if you have a lot of boolean options, so Adopt provides a make-boolean-options function that will do some of the boilerplate for you:

(adopt:make-boolean-options 'paginate
  :long "paginate"
  :short #\p
  :help "Turn pagination on."
  :help-no "Turn pagination off (the default).")
;; =>
#<ADOPT::OPTION PAGINATE p/paginate>
#<ADOPT::OPTION NO-PAGINATE P/no-paginate>

make-boolean-options will try to guess at sensible values to reduce the boilerplate you need to type:

If :long is "foo" for the true option, the false option will be "no-foo" unless overridden by :long-no.
If :short is #\f for the true option, the false option will be (char-upcase #\f) unless overridden by :short-no.
The given option name (e.g. foo) will be used for the true option, and a symbol with no- prepended (e.g. no-foo) will be used for the false option unless overridden by :name-no.
:initial-value will be nil for the pair if not given.

The two options are returned as separate values. Adopt also provides a defparameters convenience macro to create special variables for them more easily:

(defparameters (*option-paginate* *option-no-paginate*)
  (adopt:make-boolean-options 'paginate
    :long "paginate"
    :short #\p
    :help "Turn pagination on."
    :help-no "Turn pagination off (the default)."))

Counting Options

To define an option that counts how many times it's been given, like SSH's -v, you can use something like this:

(defparameter *option-verbosity*
  (adopt:make-option 'verbosity
    :short #\v
    :help "Output more verbose logs."
    :initial-value 0
    :reduce #'1+))

Single-Parameter Options

To define an option that takes a parameter and only keeps the last one given, you can do something like:

(defparameter *option-repository*
  (adopt:make-option 'repository
    :parameter "PATTERN"
    :long "repository"
    :short #\R
    :help "Path to the repository (default .)."
    :initial-value "."
    :reduce (lambda (prev new)
              (declare (ignore prev))
              new)))

Specifying the :parameter argument makes this option a parameter-taking option, which means the :reduce function will be called with the current value and the given parameter each time.

Writing that lambda out by hand every time would be tedious. Adopt provides a function called last (as in "keep the last parameter given") that does exactly that:

(defparameter *option-repository*
  (adopt:make-option 'repository
    :long "repository"
    :short #\R
    :help "Path to the repository (default .)."
    :initial-value "."
    :reduce #'adopt:last))

Multiple-Parameter Options

Collecting every parameter given can be done in a number of different ways. One strategy could be:

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN (may be given multiple times)."
    :initial-value nil
    :reduce (lambda (patterns new)
              (cons new patterns))))

You might notice that the :reduce function here is just cons with its arguments flipped. Common Lisp doesn't have a function like Haskell's flip, so Adopt provides it:

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN (may be given multiple times)."
    :initial-value nil
    :reduce (adopt:flip #'cons)))

Note that the result of this will be a fresh list of all the given parameters, but their order will be reversed because cons adds each new parameter to the front of the list. If the order doesn't matter for what you're going to do with it, you're all set. Otherwise, there are several ways to get around this problem. The first is to add the parameter to the end of the list in the :reduce function:

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN (may be given multiple times)."
    :initial-value nil
    :reduce (lambda (patterns new)
              (append patterns (list new)))))

This is tedious and inefficient if you have a lot of arguments. If you don't care much about argument parsing speed, Adopt provides a function called collect that does exactly this, so you don't have to type out that lambda yourself (and nil is the default initial value, so you don't need that either):

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN (may be given multiple times)."
    :reduce #'adopt:collect))

A more efficient (though slightly uglier) solution would be to use nreverse at the end:

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN (may be given multiple times)."
    :reduce (adopt:flip #'cons)
    :finally #'nreverse))

If you really need maximum efficiency when parsing command line options (you probably don't) you could use a queue library, or use a vector and vector-push-extend, or anything else you might dream up. The combination of :reduce, :initial-value, and :finally will let you do just about anything.

Required Options

Adopt doesn't have a concept of a required option. Not only is "required option" an oxymoron, but it's almost never what you want — if a user types foo --help they shouldn't get an error about a missing required option.

In cases where you really do need to require an option (perhaps only if some other one is also given) you can check it yourself:

(defun toplevel ()
  (handler-case
      (multiple-value-bind (arguments options) (adopt:parse-options *ui*)
        (when (gethash 'help options)
          (adopt:print-help-and-exit *ui*))
        (unless (gethash 'some-required-option options)
          (error "Required option foo is missing."))
        (run …))
    (error (c)
      (adopt:print-error-and-exit c))))

Option Groups

Related options can be grouped together in the help text to make them easier for users to understand. Groups can have their own name, title, and help text.

Here's a example of how this works. It's fairly long, but shows how Adopt can help you make a command line interface with all the fixins:

(defparameter *option-help*
  (adopt:make-option 'help
    :help "Display help and exit."
    :long "help"
    :short #\h
    :reduce (constantly t)))

(defparameter *option-literal*
  (adopt:make-option 'literal
    :help "Treat PATTERN as a literal string instead of a regex."
    :long "literal"
    :short #\l
    :reduce (constantly t)))

(defparameter *option-no-literal*
  (adopt:make-option 'no-literal
    :result-key 'literal
    :help "Treat PATTERN as a regex (the default)."
    :long "no-literal"
    :short #\L
    :reduce (constantly nil)))

(defparameter *option-case-sensitive*
  (adopt:make-option 'case-sensitive
    :help "Match case-sensitively (the default)."
    :long "case-sensitive"
    :short #\c
    :initial-value t
    :reduce (constantly t)))

(defparameter *option-case-insensitive*
  (adopt:make-option 'case-insensitive
    :help "Ignore case when matching."
    :long "case-insensitive"
    :short #\C
    :result-key 'case-sensitive
    :reduce (constantly nil)))

(defparameter *option-color*
  (adopt:make-option 'color
    :help "Highlight matches with color."
    :long "color"
    :reduce (constantly t)))

(defparameter *option-no-color*
  (adopt:make-option 'no-color
    :help "Don't highlight matches (the default)."
    :long "no-color"
    :result-key 'color
    :reduce (constantly nil)))

(defparameter *option-context*
  (adopt:make-option 'context
    :parameter "N"
    :help "Show N lines of context (default 0)."
    :long "context"
    :short #\U
    :initial-value 0
    :reduce #'adopt:last
    :key #'parse-integer))


(defparameter *group-matching*
  (adopt:make-group 'matching-options
    :title "Matching Options"
    :options (list *option-literal*
                   *option-no-literal*
                   *option-case-sensitive*
                   *option-case-insensitive*)))

(defparameter *group-output*
  (adopt:make-group 'output-options
    :title "Output Options"
    :help "These options affect how matching lines are printed.  The defaults are ideal for piping into other programs."
    :options (list *option-color*
                   *option-no-color*
                   *option-context*)))


(adopt:define-string *help-text*
  "Search FILEs for lines that match the regular expression ~
   PATTERN and print them to standard out.  Several options ~
   are available to control how the matching lines are printed.~@
   ~@
   If no files are given (or if - is given as a filename) ~
   standard input will be searched.")

(defparameter *ui*
  (adopt:make-interface
    :name "search"
    :usage "PATTERN [FILE...]"
    :summary "print lines that match a regular expression"
    :help *help-text*
    :contents (list *option-help*
                    *group-matching*
                    *group-output*)))

And with all that out of the way, you've got some nicely-organized help text for your users:

(adopt:print-help *ui* :width 60 :option-width 16)
; =>
; search - print lines that match a regular expression
;
; USAGE: /usr/local/bin/sbcl PATTERN [FILE...]
;
; Search FILEs for lines that match the regular expression
; PATTERN and print them to standard out.  Several options are
; available to control how the matching lines are printed.
;
; If no files are given (or if - is given as a filename)
; standard input will be searched.
;
; Options:
;   -h, --help        display help and exit
;
; Matching Options:
;   -l, --literal     treat PATTERN as a literal string
;                     instead of a regex
;   -L, --no-literal  treat PATTERN as a regex (the default)
;   -c, --case-sensitive
;                     match case-sensitively (the default)
;   -C, --case-insensitive
;                     ignore case when matching
;
; Output Options:
;
;   These options affect how matching lines are printed.  The
;   defaults are ideal for piping into other programs.
;
;   --color           highlight matches with color
;   --no-color        don't highlight matches (the default)
;   -u N, --context N show N lines of context (default 0)

Error Handling

For the most part Adopt doesn't try to be too smart about error handling and leaves it up to you.

However, when Adopt is parsing the command line options it will signal an error of type adopt:unrecognized-option if the user passes a command line option that wasn't defined in the interface:

(defparameter *ui*
  (adopt:make-interface
    :name "meow"
    :summary "say meow"
    :usage "[OPTIONS]"
    :help "Say meow.  Like a cat."
    :contents (list (make-option 'times
                      :parameter "N"
                      :long "times"
                      :initial-value 1
                      :help "Say meow N times (default 1)."
                      :reduce #'adopt:last
                      :key #'parse-integer))))

(adopt:parse-options *ui* '("--times" "5"))
; =>
; NIL
; {TIMES: 5}

(adopt:parse-options *ui* '("--bark"))
; =>
; No such option "--bark".
;    [Condition of type UNRECOGNIZED-OPTION]
;
; Restarts:
;   R 0.  DISCARD-OPTION    - Discard the unrecognized option.
;   R 1.  TREAT-AS-ARGUMENT - Treat the unrecognized option as a plain argument.
;   R 2.  SUPPLY-NEW-VALUE  - Supply a new value to parse.
;   R 3.  RETRY             - Retry SLIME REPL evaluation request.
;   R 4. *ABORT             - Return to SLIME's top level.
;   R 5.  ABORT             - abort thread (#<THREAD "repl-thread" RUNNING {100AF48413}>)

Adopt provides three possible restarts for this condition as seen above. Adopt also provides functions with the same names that invoke the restarts properly, to make it easier to use them programatically with handler-bind. For example:

(handler-bind
    ((adopt:unrecognized-option 'adopt:discard-option))
  (adopt:parse-options *ui* '("--bark")))
; =>
; NIL
; {TIMES: 1}

(handler-bind
    ((adopt:unrecognized-option 'adopt:treat-as-argument))
  (adopt:parse-options *ui* '("--bark")))
; =>
; ("--bark")
; {TIMES: 1}

(handler-bind
    ((adopt:unrecognized-option
       (alexandria:rcurry 'adopt:supply-new-value "--times")))
  (adopt:parse-options *ui* '("--bark" "5")))
; =>
; NIL
; {TIMES: 5}

Generating Man Pages

We've already seen that Adopt can print a pretty help document, but it can also render man pages for you:

(with-open-file (out "man/man1/search.1"
                  :direction :output
                  :if-exists :supersede)
  (adopt:print-manual *ui* :stream out))

The generated man page will contain the same information as the help text by default. If you want to override this (e.g. to provide a short summary of an option in the help text, but elaborate more in the manual), you can use the :manual argument to make-interface and make-option:

(defparameter *option-exclude*
  (adopt:make-option 'exclude
    :long "exclude"
    :parameter "PATTERN"
    :help "Exclude PATTERN."
    :manual "Exclude lines that match PATTERN (a PERL-compatible regular expression) from the search results.  Multiple PATTERNs can be specified by giving this option multiple times."
    :reduce (adopt:flip #'cons)))

In order for man to find the pages, they need to be in the correct place. By default man is usually smart enough to look next to every directory in your $PATH to find a directory called man. So if you put your binaries in /home/me/bin/ you can put your man pages in /home/me/man/ under the appropriate subdirectories and it should all Just Work™. Consult the man documentation for more information.

Implementation Specifics

TODO: talk about Lisp runtime options vs program options.

SBCL

You'll want to use :save-runtime-options t in the call to sb-ext:save-lisp-and-die.

ClozureCL

See https://github.com/Clozure/ccl/issues/177.