The adopt-subcommands Reference Manual

This is the adopt-subcommands Reference Manual, version 0.2.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 14:30:59 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 adopt-subcommands

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

Author

Eric Timmons <>

Home Page

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

Bug Tracker

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

License

MIT

Version

0.2.2

Dependencies
  • adopt (system).
  • bobbin (system).
  • split-sequence (system).
  • uiop (system).
Source

adopt-subcommands.asd.

Child 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/adopt-subcommands.asd

Source

adopt-subcommands.asd.

Parent Component

adopt-subcommands (system).

ASDF Systems

adopt-subcommands.


3.1.2 adopt-subcommands/adopt-subcommands.lisp

Source

adopt-subcommands.asd.

Parent Component

adopt-subcommands (system).

Packages

adopt-subcommands.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 adopt-subcommands

Source

adopt-subcommands.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: add-subcommand (folder subcommand)

Add a subcommand to a folder.

Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

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.

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.

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.


5.1.2 Generic functions

Generic Reader: folder-is-terminal-folder (condition)
Package

adopt-subcommands.

Methods
Reader Method: folder-is-terminal-folder ((condition folder-is-terminal))
Source

adopt-subcommands.lisp.

Target Slot

folder.

Generic Reader: folder-is-terminal-path (condition)
Package

adopt-subcommands.

Methods
Reader Method: folder-is-terminal-path ((condition folder-is-terminal))
Source

adopt-subcommands.lisp.

Target Slot

path.

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.

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.

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 Reader: unknown-subcommand-folder (condition)
Package

adopt-subcommands.

Methods
Reader Method: unknown-subcommand-folder ((condition unknown-subcommand))
Source

adopt-subcommands.lisp.

Target Slot

folder.

Generic Reader: unknown-subcommand-key (condition)
Package

adopt-subcommands.

Methods
Reader Method: unknown-subcommand-key ((condition unknown-subcommand))
Source

adopt-subcommands.lisp.

Target Slot

key.

Generic Reader: unknown-subcommand-path (condition)
Package

adopt-subcommands.

Methods
Reader Method: unknown-subcommand-path ((condition unknown-subcommand))
Source

adopt-subcommands.lisp.

Target Slot

path.


5.1.3 Conditions

Condition: folder-is-terminal

Signals that no terminal subcommand was found

Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct superclasses

subcommand-error.

Direct methods
Direct slots
Slot: folder
Initargs

:folder

Readers

folder-is-terminal-folder.

Writers

This slot is read-only.

Slot: path
Initargs

:path

Readers

folder-is-terminal-path.

Writers

This slot is read-only.

Condition: unknown-subcommand

Signals that a subcommand could not be found.

Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct superclasses

subcommand-error.

Direct methods
Direct slots
Slot: folder
Initargs

:folder

Readers

unknown-subcommand-folder.

Writers

This slot is read-only.

Slot: key
Initargs

:key

Readers

unknown-subcommand-key.

Writers

This slot is read-only.

Slot: path
Initargs

:path

Readers

unknown-subcommand-path.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Ordinary functions

Function: copy-hash-table (ht)

Copy a hash table

Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Function: extend-path (new-head path)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Function: hash-table-keys (ht)

Return a list of all keys in HT.

Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

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.

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.

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.

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.

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.

Function: signal-folder-is-terminal (folder path)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Function: signal-unknown-subcommand (folder path key)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Function: subcommand-folder-p (object)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Function: subcommand-terminal-p (object)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.


5.2.2 Generic functions

Generic Reader: %function (object)
Package

adopt-subcommands.

Methods
Reader Method: %function ((subcommand subcommand))

automatically generated reader method

Source

adopt-subcommands.lisp.

Target Slot

function.

Generic Writer: (setf %function) (object)
Package

adopt-subcommands.

Methods
Writer Method: (setf %function) ((subcommand subcommand))

automatically generated writer method

Source

adopt-subcommands.lisp.

Target Slot

function.

Generic Function: dispatch-subcommand (interface &key arguments options print-help-and-exit path)
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

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 Reader: interface (object)
Package

adopt-subcommands.

Methods
Reader Method: interface ((subcommand subcommand))

automatically generated reader method

Source

adopt-subcommands.lisp.

Target Slot

interface.

Generic Writer: (setf interface) (object)
Package

adopt-subcommands.

Methods
Writer Method: (setf interface) ((subcommand subcommand))

automatically generated writer method

Source

adopt-subcommands.lisp.

Target Slot

interface.

Generic Reader: key (object)
Package

adopt-subcommands.

Methods
Reader Method: key ((subcommand subcommand))

automatically generated reader method

Source

adopt-subcommands.lisp.

Target Slot

key.

Generic Writer: (setf key) (object)
Package

adopt-subcommands.

Methods
Writer Method: (setf key) ((subcommand subcommand))

automatically generated writer method

Source

adopt-subcommands.lisp.

Target Slot

key.

Generic Reader: path (object)
Package

adopt-subcommands.

Methods
Reader Method: path ((subcommand-path subcommand-path))

automatically generated reader method

Source

adopt-subcommands.lisp.

Target Slot

path.

Generic Writer: (setf path) (object)
Package

adopt-subcommands.

Methods
Writer Method: (setf path) ((subcommand-path subcommand-path))

automatically generated writer method

Source

adopt-subcommands.lisp.

Target Slot

path.

Generic Reader: subcommands (object)
Package

adopt-subcommands.

Methods
Reader Method: subcommands ((subcommand-folder subcommand-folder))

automatically generated reader method

Source

adopt-subcommands.lisp.

Target Slot

subcommands.

Generic Writer: (setf subcommands) (object)
Package

adopt-subcommands.

Methods
Writer Method: (setf subcommands) ((subcommand-folder subcommand-folder))

automatically generated writer method

Source

adopt-subcommands.lisp.

Target Slot

subcommands.


5.2.3 Conditions

Condition: subcommand-error
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct superclasses

error.

Direct subclasses
Direct methods

print-help-and-exit.


5.2.4 Classes

Class: subcommand
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct subclasses
Direct methods
Direct slots
Slot: key
Initargs

:key

Readers

key.

Writers

(setf key).

Slot: function
Package

common-lisp.

Initargs

:function

Readers

%function.

Writers

(setf %function).

Slot: interface
Initargs

:interface

Readers

interface.

Writers

(setf interface).

Class: subcommand-folder
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct superclasses

subcommand.

Direct methods
Direct slots
Slot: subcommands
Initform

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

Readers

subcommands.

Writers

(setf subcommands).

Class: subcommand-path
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct methods
Direct slots
Slot: path
Initargs

:path

Readers

path.

Writers

(setf path).

Class: subcommand-terminal
Package

adopt-subcommands.

Source

adopt-subcommands.lisp.

Direct superclasses

subcommand.

Direct methods

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   C   D   E   F   G   H   I   K   M   P   S   U  
Index Entry  Section

%
%function: Private generic functions
%function: Private generic functions

(
(setf %function): Private generic functions
(setf %function): Private generic functions
(setf interface): Private generic functions
(setf interface): Private generic functions
(setf key): Private generic functions
(setf key): Private generic functions
(setf path): Private generic functions
(setf path): Private generic functions
(setf subcommands): Private generic functions
(setf subcommands): Private generic functions

A
add-subcommand: Public ordinary functions

C
copy-hash-table: Private ordinary functions

D
dispatch: Public ordinary functions
dispatch-subcommand: Private generic functions
dispatch-subcommand: Private generic functions
dispatch-subcommand: Private generic functions

E
extend-path: Private ordinary functions

F
folder-is-terminal-folder: Public generic functions
folder-is-terminal-folder: Public generic functions
folder-is-terminal-path: Public generic functions
folder-is-terminal-path: Public generic functions
Function, add-subcommand: Public ordinary functions
Function, copy-hash-table: Private ordinary functions
Function, dispatch: Public ordinary functions
Function, extend-path: Private ordinary functions
Function, hash-table-keys: Private ordinary functions
Function, key-from-name: Private ordinary functions
Function, make-subcommand-folder: Public ordinary functions
Function, make-subcommand-terminal: Public ordinary functions
Function, merge-hts: Private ordinary functions
Function, plist-remove-keys: Private ordinary functions
Function, print-entry-options: Private ordinary functions
Function, print-path-help: Private ordinary functions
Function, signal-folder-is-terminal: Private ordinary functions
Function, signal-unknown-subcommand: Private ordinary functions
Function, subcommand-folder-p: Private ordinary functions
Function, subcommand-terminal-p: Private ordinary functions

G
Generic Function, %function: Private generic functions
Generic Function, (setf %function): Private generic functions
Generic Function, (setf interface): Private generic functions
Generic Function, (setf key): Private generic functions
Generic Function, (setf path): Private generic functions
Generic Function, (setf subcommands): Private generic functions
Generic Function, dispatch-subcommand: Private generic functions
Generic Function, folder-is-terminal-folder: Public generic functions
Generic Function, folder-is-terminal-path: Public generic functions
Generic Function, interface: Private generic functions
Generic Function, key: Private generic functions
Generic Function, path: Private generic functions
Generic Function, print-help: Public generic functions
Generic Function, print-help-and-exit: Public generic functions
Generic Function, subcommands: Private generic functions
Generic Function, unknown-subcommand-folder: Public generic functions
Generic Function, unknown-subcommand-key: Public generic functions
Generic Function, unknown-subcommand-path: Public generic functions

H
hash-table-keys: Private ordinary functions

I
interface: Private generic functions
interface: Private generic functions

K
key: Private generic functions
key: Private generic functions
key-from-name: Private ordinary functions

M
make-subcommand-folder: Public ordinary functions
make-subcommand-terminal: Public ordinary functions
merge-hts: Private ordinary functions
Method, %function: Private generic functions
Method, (setf %function): Private generic functions
Method, (setf interface): Private generic functions
Method, (setf key): Private generic functions
Method, (setf path): Private generic functions
Method, (setf subcommands): Private generic functions
Method, dispatch-subcommand: Private generic functions
Method, dispatch-subcommand: Private generic functions
Method, folder-is-terminal-folder: Public generic functions
Method, folder-is-terminal-path: Public generic functions
Method, interface: Private generic functions
Method, key: Private generic functions
Method, path: Private generic functions
Method, print-help: Public generic functions
Method, print-help: Public generic functions
Method, print-help: Public generic functions
Method, print-help: Public generic functions
Method, print-help-and-exit: Public generic functions
Method, print-help-and-exit: Public generic functions
Method, subcommands: Private generic functions
Method, unknown-subcommand-folder: Public generic functions
Method, unknown-subcommand-key: Public generic functions
Method, unknown-subcommand-path: Public generic functions

P
path: Private generic functions
path: Private generic functions
plist-remove-keys: Private ordinary functions
print-entry-options: Private ordinary functions
print-help: Public generic functions
print-help: Public generic functions
print-help: Public generic functions
print-help: Public generic functions
print-help: Public generic functions
print-help-and-exit: Public generic functions
print-help-and-exit: Public generic functions
print-help-and-exit: Public generic functions
print-path-help: Private ordinary functions

S
signal-folder-is-terminal: Private ordinary functions
signal-unknown-subcommand: Private ordinary functions
subcommand-folder-p: Private ordinary functions
subcommand-terminal-p: Private ordinary functions
subcommands: Private generic functions
subcommands: Private generic functions

U
unknown-subcommand-folder: Public generic functions
unknown-subcommand-folder: Public generic functions
unknown-subcommand-key: Public generic functions
unknown-subcommand-key: Public generic functions
unknown-subcommand-path: Public generic functions
unknown-subcommand-path: Public generic functions