The adopt-subcommands Reference Manual

Table of Contents

The adopt-subcommands Reference Manual

This is the adopt-subcommands Reference Manual, version 0.2.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 08:51:57 2021 GMT+0.

1 Introduction

#+TITLE: Adopt Subcommands
#+AUTHOR: Eric Timmons 

This library is an extension of Steve Losh's [[https://docs.stevelosh.com/adopt/][Adopt]] library (hands down my
favorite CLI options parser for CL) to support arbitrarily nested
subcommands. Not all features of Adopt are nicely supported yet (like producing
man pages for subcommands), but the basic functionality is there.

Subcommands are organized into folders and terminals. Both folders and
terminals can have options associated with them. Folders can additionally
contain other folders and terminals. Terminals *must* have a function
associated with them that will be called when a CLI command is dispatched. This
function must accept three arguments: a list of arguments (strings), an =EQL=
hash table of processed arguments, and a path object denoting all the folders
and terminal traversed.

Folders *may* have a function associated with them that is called before
attempting to further process the remaining arguments. This is useful to bind
dynamic variables or munge the options passed down to the later levels. This
function, if provided, must take four arguments: a list of arguments (strings),
an =EQL= hash table of options, a path object denoting all the folders and
traversed so far, and a thunk that must be called to continue processing.

This library tries to follow the same aesthetic as Adopt (such as interfaces
encouraged to be defined with =defparameter= and errors signaled with some
restarts provided) with two primary exceptions:

1. Any function you provide for terminals or folders is called with the results
   of processing the command line. You do not need to call
   =adopt:parse-options= or similar yourself.
2. Printing help and exiting is a common enough operation that this library
   provides native support for it, so you do not need to duplicate the checks
   for your program's help option everywhere.

* How to use

  In this section, we describe how to use the library, partially illustrated by
  examples from [[file:simple-demo.lisp][=simple-demo.lisp=]] (see the History section for more details on
  the provenance of this file).

  First, you must define your program's hierarchy. Terminals are defined using
  =make-subcommand-terminal=. It accepts the same arguments as
  =adopt:make-interface=, with the addition of the mandatory =:function= and
  optional =:key= keywords.

  The provided function will be called once we dispatch based on the command
  line arguments.

  The key is used if you want to specify the name of the subcommand; it is
  normally not required as it is derived from =:name=.

  For example:

  #+begin_src common-lisp
    (defparameter *ui/foo*
      (adopt-subcommands:make-subcommand-terminal
        :name "subex foo"
        :usage "foo [-a|-b]"
        :summary "foo some things"
        :help "foo some things"
        :contents (list *o/foo/a* *o/foo/b*)
        :function 'run/foo))
  #+end_src

  Folders are defined using =make-subcommand-folder=. It accepts the same
  arguments as =adopt:make-interface=, with the addition of the optional
  =:function= and =:key= keywords.

  If provided, the function will be called once we dispatch based on the
  command line arguments, before continuing to process the remainder of the
  arguments. It can be used to establish dynamic bindings or otherwise munge
  the arguments before continuing to process them.

  The key is used if you want to specify the name of the folder; it is normally
  not required as it is derived from =:name=.

  Additionally, the =:contents= of a folder can include other folders or
  terminals. For example:

  #+begin_src common-lisp
    (defparameter *ui*
      (adopt-subcommands:make-subcommand-folder
        :name "subex"
        :usage "[subcommand] [options]"
        :help "subcommand example program"
        :summary "an example program that uses subcommands"
        :contents (list *o/help* *o/version* *ui/foo* *ui/bar*)
        :function 'run/global))
  #+end_src

  Next, you must actually process the arguments and call the desired
  functions. This is accomplished using the =dispatch= function. It requires a
  folder as an argument. It can additionally be provided the list of
  arguments. Last, if =print-help-and-exit= is non-NIL, it should name our
  program's help option. If provided, this library processes as much of the
  command line as it can. Then, if the help option is non-NIL, prints the help
  and exits the program.

  For example:

  #+begin_src common-lisp
    (defun toplevel ()
      (handler-bind ((adopt-subcommands:folder-is-terminal 'adopt-subcommands:print-help-and-exit))
        (adopt-subcommands:dispatch *ui* :print-help-and-exit 'help)))
  #+end_src

* History

  This work was largely inspired by Steve Losh's [[https://old.reddit.com/r/Common_Lisp/comments/m7gjno/writing_small_cli_programs_in_common_lisp_steve/grdqq1j/][Reddit comment]] on a quick and
  dirty method to implement subcommands using Adopt. For a while, I had my own
  way of doing this (that also supported arbitrarily nested subcommands), but it
  was very nasty because I had somehow missed the existence of the
  =adopt:treat-as-argument= restart (d'oh). So after seeing that, I cleaned up my
  code and packaged it up as a library for others to use.

  For reference, the file =simple-demo.lisp= shows how to implement Steve's
  Reddit example using this library.

* Deficiencies

  These are the current deficiencies that I would like to fix some day:

  1. We reach into Adopt's internals a bit. Need to reach out to Steve and
     figure out if he's amenable to exporting the accessors we need and/or
     refactoring the help/man page generation to be more modular (and export
     the new components).

  2. Man page generation is not yet supported.

  3. Options need to come after the subcommand that defines them. For example,
     if =-a= is defined as part of =foo='s interface, the following will not
     work:

     #+begin_src shell
       my-program -a foo
     #+end_src

     But this will:

     #+begin_src shell
       my-program foo -a
     #+end_src

     This could be easily fixed for parameterless options. It could also be
     easily fixed for options with parameters, so long as the argument list has
     the parameter in the same token as the option (e.g. =--foo=5= instead of
     =--foo 5=). But a general purpose solution is harder and it is not obvious
     it's worth it.

2 Systems

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

2.1 adopt-subcommands

Author

Eric Timmons <eric@timmons.dev>

Home Page

https://gitlab.com/daewok/adopt-subcommands

Bug Tracker

https://gitlab.com/daewok/adopt-subcommands/-/issues

License

MIT

Description

Extend the Adopt command line processing library to handle nested subcommands.

Version

0.2.2

Dependencies

• adopt
• bobbin
• split-sequence
• uiop

Source

adopt-subcommands.asd (file)

Component

adopt-subcommands.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 adopt-subcommands.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/adopt-subcommands-v0.2.2/adopt-subcommands.asd

Systems

adopt-subcommands (system)

3.1.2 adopt-subcommands/adopt-subcommands.lisp

Parent

adopt-subcommands (system)

Location

adopt-subcommands.lisp

Packages

adopt-subcommands

Exported Definitions

• add-subcommand (function)
• dispatch (function)
• folder-is-terminal (condition)
• folder-is-terminal-folder (method)
• folder-is-terminal-path (method)
• make-subcommand-folder (function)
• make-subcommand-terminal (function)
• print-help (generic function)
• print-help (method)
• print-help (method)
• print-help (method)
• print-help (method)
• print-help-and-exit (generic function)
• print-help-and-exit (method)
• print-help-and-exit (method)
• unknown-subcommand (condition)
• unknown-subcommand-folder (method)
• unknown-subcommand-key (method)
• unknown-subcommand-path (method)

Internal Definitions

• %function (method)
• (setf %function) (method)
• copy-hash-table (function)
• dispatch-subcommand (generic function)
• dispatch-subcommand (method)
• dispatch-subcommand (method)
• extend-path (function)
• hash-table-keys (function)
• interface (method)
• (setf interface) (method)
• key (method)
• (setf key) (method)
• key-from-name (function)
• merge-hts (function)
• path (method)
• (setf path) (method)
• plist-remove-keys (function)
• print-entry-options (function)
• print-path-help (function)
• signal-folder-is-terminal (function)
• signal-unknown-subcommand (function)
• subcommand (class)
• subcommand-error (condition)
• subcommand-folder (class)
• subcommand-folder-p (function)
• subcommand-path (class)
• subcommand-terminal (class)
• subcommand-terminal-p (function)
• subcommands (method)
• (setf subcommands) (method)

4 Packages

Packages are listed by definition order.

4.1 adopt-subcommands

Source

adopt-subcommands.lisp (file)

Use List

common-lisp

Exported Definitions

• add-subcommand (function)
• dispatch (function)
• folder-is-terminal (condition)
• folder-is-terminal-folder (generic function)
• folder-is-terminal-folder (method)
• folder-is-terminal-path (generic function)
• folder-is-terminal-path (method)
• make-subcommand-folder (function)
• make-subcommand-terminal (function)
• print-help (generic function)
• print-help (method)
• print-help (method)
• print-help (method)
• print-help (method)
• print-help-and-exit (generic function)
• print-help-and-exit (method)
• print-help-and-exit (method)
• unknown-subcommand (condition)
• unknown-subcommand-folder (generic function)
• unknown-subcommand-folder (method)
• unknown-subcommand-key (generic function)
• unknown-subcommand-key (method)
• unknown-subcommand-path (generic function)
• unknown-subcommand-path (method)

Internal Definitions

• %function (generic function)
• %function (method)
• (setf %function) (method)
• (setf %function) (generic function)
• copy-hash-table (function)
• dispatch-subcommand (generic function)
• dispatch-subcommand (method)
• dispatch-subcommand (method)
• extend-path (function)
• hash-table-keys (function)
• interface (generic function)
• interface (method)
• (setf interface) (method)
• (setf interface) (generic function)
• key (generic function)
• key (method)
• (setf key) (method)
• (setf key) (generic function)
• key-from-name (function)
• merge-hts (function)
• path (generic function)
• path (method)
• (setf path) (method)
• (setf path) (generic function)
• plist-remove-keys (function)
• print-entry-options (function)
• print-path-help (function)
• signal-folder-is-terminal (function)
• signal-unknown-subcommand (function)
• subcommand (class)
• subcommand-error (condition)
• subcommand-folder (class)
• subcommand-folder-p (function)
• subcommand-path (class)
• subcommand-terminal (class)
• subcommand-terminal-p (function)
• subcommands (generic function)
• subcommands (method)
• (setf subcommands) (method)
• (setf subcommands) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: add-subcommand FOLDER SUBCOMMAND

Add a subcommand to a folder.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: dispatch INTERFACE &key ARGUMENTS PRINT-HELP-AND-EXIT

Given a subcommand UI (as returned by MAKE-SUBCOMMAND-FOLDER), dispatch based on the provided ARGUMENTS.

If PRINT-HELP-AND-EXIT is provided, it must be a symbol denoting the option corresponding to your UI’s help flag. If provided and the help option is present in the command line, the help will be printed and the program will exit when a terminal node is reached.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: make-subcommand-folder &rest KEYS &key NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS KEY FUNCTION

Create and return a subcommand folder.

If this is placed into another folder, that folder uses ‘key‘ to determine when to dispatch to this interface. If ‘key‘ is not specified, one is determined automatically by splitting ‘name‘ on space characters and taking the last entry.

When this subcommand is dispatched, ‘function‘ is called with a list of remaining arguments, an ‘eql‘ hash table containing all the parsed options, a path object representing all folders traversed (the path is currently only useful for passing to the PRINT-HELP), and a thunk that continues processing the subcommands when called. If not provided, the thunk is simply called.

The remaining arguments are passed directly to ‘adopt:make-interface‘.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: make-subcommand-terminal &rest KEYS &key NAME SUMMARY USAGE HELP MANUAL EXAMPLES CONTENTS FUNCTION KEY

Create and return a terminal subcommand interface.

The subcommand folder into which this is placed uses ‘key‘ to determine when to dispatch to this interface. If ‘key‘ is not specified, one is determined automatically by splitting ‘name‘ on space characters and taking the last entry.

When this subcommand is dispatched, ‘function‘ is called with a list of remaining arguments, an ‘eql‘ hash table containing all the parsed options, and a path object representing all folders and terminal traversed (the path is currently only useful for passing to the PRINT-HELP). ‘function‘ is required.

The remaining arguments are passed directly to ‘adopt:make-interface‘.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

5.1.2 Generic functions

Generic Function: folder-is-terminal-folder CONDITION

Package

adopt-subcommands

Methods

Method: folder-is-terminal-folder (CONDITION folder-is-terminal)

Source

adopt-subcommands.lisp (file)

Generic Function: folder-is-terminal-path CONDITION

Package

adopt-subcommands

Methods

Method: folder-is-terminal-path (CONDITION folder-is-terminal)

Source

adopt-subcommands.lisp (file)

Generic Function: print-help OBJECT &key STREAM PROGRAM-NAME WIDTH OPTION-WIDTH INCLUDE-EXAMPLES

A GF version of ADOPT:PRINT-HELP that additionally dispatches for the objects defined by this library.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Methods

Method: print-help UI &rest ARGS

Method: print-help (UI subcommand-terminal) &rest ARGS

Method: print-help (UI subcommand-folder) &rest ARGS

Method: print-help (OBJECT subcommand-path) &rest ARGS

Generic Function: print-help-and-exit OBJECT &key EXIT-CODE STREAM PROGRAM-NAME WIDTH OPTION-WIDTH INCLUDE-EXAMPLES &allow-other-keys

A GF version of ADOPT:PRINT-HELP-AND-EXIT that additionally dispatches for the objects defined by this library.

Additionally, we use UIOP:QUIT since that works on more implementations than ADOPT:EXIT.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Methods

Method: print-help-and-exit (C subcommand-error) &rest KEYS

Method: print-help-and-exit OBJECT &rest KEYS &key EXIT-CODE &allow-other-keys

Generic Function: unknown-subcommand-folder CONDITION

Package

adopt-subcommands

Methods

Method: unknown-subcommand-folder (CONDITION unknown-subcommand)

Source

adopt-subcommands.lisp (file)

Generic Function: unknown-subcommand-key CONDITION

Package

adopt-subcommands

Methods

Method: unknown-subcommand-key (CONDITION unknown-subcommand)

Source

adopt-subcommands.lisp (file)

Generic Function: unknown-subcommand-path CONDITION

Package

adopt-subcommands

Methods

Method: unknown-subcommand-path (CONDITION unknown-subcommand)

Source

adopt-subcommands.lisp (file)

5.1.3 Conditions

Condition: folder-is-terminal ()

Signals that no terminal subcommand was found

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

subcommand-error (condition)

Direct methods

• folder-is-terminal-path (method)
• folder-is-terminal-folder (method)

Direct slots

Slot: folder

Initargs

:folder

Readers

folder-is-terminal-folder (generic function)

Slot: path

Initargs

:path

Readers

folder-is-terminal-path (generic function)

Condition: unknown-subcommand ()

Signals that a subcommand could not be found.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

subcommand-error (condition)

Direct methods

• unknown-subcommand-path (method)
• unknown-subcommand-key (method)
• unknown-subcommand-folder (method)

Direct slots

Slot: folder

Initargs

:folder

Readers

unknown-subcommand-folder (generic function)

Slot: key

Initargs

:key

Readers

unknown-subcommand-key (generic function)

Slot: path

Initargs

:path

Readers

unknown-subcommand-path (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: copy-hash-table HT

Copy a hash table

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: extend-path NEW-HEAD PATH

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: hash-table-keys HT

Return a list of all keys in HT.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: key-from-name NAME

Generate a key from NAME by splitting on space and returning the last element.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: merge-hts EXISTING-HT NEW-HT

Return a copy of EXISTING-HT with all key/value pairs from NEW-HT inserted into it.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: plist-remove-keys PLIST &rest KEYS

Return a new plist that contains all keys and values from PLIST, excepting any key in KEYS.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: print-entry-options ENTRY STREAM WIDTH OPTION-WIDTH

Print the options for an interface in a path.

This code is mostly copied from Adopt. See LICENSE for more information.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: print-path-help PATH &key STREAM PROGRAM-NAME WIDTH OPTION-WIDTH INCLUDE-EXAMPLES

Print the help for PATH. Prints the examples and usage information for the most specific interface on the path. Prints the options for all interfaces on the path.

This code is mostly copied from Adopt. See LICENSE for more information.

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: signal-folder-is-terminal FOLDER PATH

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: signal-unknown-subcommand FOLDER PATH KEY

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: subcommand-folder-p OBJECT

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Function: subcommand-terminal-p OBJECT

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

5.2.2 Generic functions

Generic Function: %function OBJECT

Generic Function: (setf %function) NEW-VALUE OBJECT

Package

adopt-subcommands

Methods

Method: %function (SUBCOMMAND subcommand)

automatically generated reader method

Source

adopt-subcommands.lisp (file)

Method: (setf %function) NEW-VALUE (SUBCOMMAND subcommand)

automatically generated writer method

Source

adopt-subcommands.lisp (file)

Generic Function: dispatch-subcommand INTERFACE &key ARGUMENTS OPTIONS PRINT-HELP-AND-EXIT PATH

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Methods

Method: dispatch-subcommand (FOLDER subcommand-folder) &key ARGUMENTS OPTIONS PATH PRINT-HELP-AND-EXIT

Method: dispatch-subcommand (TERMINAL subcommand-terminal) &key ARGUMENTS OPTIONS PATH PRINT-HELP-AND-EXIT

Generic Function: interface OBJECT

Generic Function: (setf interface) NEW-VALUE OBJECT

Package

adopt-subcommands

Methods

Method: interface (SUBCOMMAND subcommand)

automatically generated reader method

Source

adopt-subcommands.lisp (file)

Method: (setf interface) NEW-VALUE (SUBCOMMAND subcommand)

automatically generated writer method

Source

adopt-subcommands.lisp (file)

Generic Function: key OBJECT

Generic Function: (setf key) NEW-VALUE OBJECT

Package

adopt-subcommands

Methods

Method: key (SUBCOMMAND subcommand)

automatically generated reader method

Source

adopt-subcommands.lisp (file)

Method: (setf key) NEW-VALUE (SUBCOMMAND subcommand)

automatically generated writer method

Source

adopt-subcommands.lisp (file)

Generic Function: path OBJECT

Generic Function: (setf path) NEW-VALUE OBJECT

Package

adopt-subcommands

Methods

Method: path (SUBCOMMAND-PATH subcommand-path)

automatically generated reader method

Source

adopt-subcommands.lisp (file)

Method: (setf path) NEW-VALUE (SUBCOMMAND-PATH subcommand-path)

automatically generated writer method

Source

adopt-subcommands.lisp (file)

Generic Function: subcommands OBJECT

Generic Function: (setf subcommands) NEW-VALUE OBJECT

Package

adopt-subcommands

Methods

Method: subcommands (SUBCOMMAND-FOLDER subcommand-folder)

automatically generated reader method

Source

adopt-subcommands.lisp (file)

Method: (setf subcommands) NEW-VALUE (SUBCOMMAND-FOLDER subcommand-folder)

automatically generated writer method

Source

adopt-subcommands.lisp (file)

5.2.3 Conditions

Condition: subcommand-error ()

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• unknown-subcommand (condition)
• folder-is-terminal (condition)

Direct methods

print-help-and-exit (method)

5.2.4 Classes

Class: subcommand ()

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• subcommand-terminal (class)
• subcommand-folder (class)

Direct methods

• interface (method)
• interface (method)
• %function (method)
• %function (method)
• key (method)
• key (method)

Direct slots

Slot: key

Initargs

:key

Readers

key (generic function)

Writers

(setf key) (generic function)

Slot: function

Initargs

:function

Readers

%function (generic function)

Writers

(setf %function) (generic function)

Slot: interface

Initargs

:interface

Readers

interface (generic function)

Writers

(setf interface) (generic function)

Class: subcommand-folder ()

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

subcommand (class)

Direct methods

• dispatch-subcommand (method)
• print-help (method)
• subcommands (method)
• subcommands (method)

Direct slots

Slot: subcommands

Initform

(make-hash-table :test (quote equal))

Readers

subcommands (generic function)

Writers

(setf subcommands) (generic function)

Class: subcommand-path ()

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• print-help (method)
• path (method)
• path (method)

Direct slots

Slot: path

Initargs

:path

Readers

path (generic function)

Writers

(setf path) (generic function)

Class: subcommand-terminal ()

Package

adopt-subcommands

Source

adopt-subcommands.lisp (file)

Direct superclasses

subcommand (class)

Direct methods

• dispatch-subcommand (method)
• print-help (method)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types