net.lewisship.cli-tools — io.github.hlship/cli-tools v0.4

Utilities for create CLIs around functions, and creating tools with multiple sub-commands.

defcommand clj macro

(defcommand command-name docstring interface & body)

Defines a command.

A command's interface identifies how to parse command options and positional arguments, mapping them to local symbols.

Commands must always have a docstring; this is part of the -h / --help summary.

The returned function takes is variadic, accepting a number of strings, much like a -main function. For testing purposes, it may instead by passed a single map, a command map, which bypasses parsing of the arguments.

Finally, the body inside a let that destructures the options and positional arguments into local symbols.

dispatch clj

(dispatch options)

Locates commands in namespaces, finds the current command (as identified by the first command line argument) and processes CLI options and arguments.

options:

• :tool-name (required, string) - used in command summary and errors
• :tool-doc (options, string) - used in help summary
• :arguments - command line arguments to parse (defaults to command-line-args)
• :namespaces - symbols identifying namespaces to search for commands

The default for :tool-doc is the docstring of the first namespace.

dispatch will load any namespaces specified, then scan those namespaces to identify commands. It also adds a help command from this namespace.

If option and argument parsing is unsuccessful, then a command usage summary is printed, along with errors, and the program exits with error code 1.

dispatch simply loads and scans the namespaces, adds the help command, then calls dispatch*.

Returns nil.

dispatch* clj

(dispatch* options)

Invoked by dispatch after namespace and command resolution.

This can be used, for example, to avoid including the builtin help command (or when providing an override).

options:

• :tool-name - used in command summary and errors
• :tool-doc - used in command summary
• :arguments - seq of strings; first is name of command, rest passed to command
• :commands - map from string command name to a var defined via defcommand

Returns nil.

help clj

(help & args)

List available commands

locate-commands clj

(locate-commands namespace-symbols)

Passed a seq of symbols identifying loaded namespaces, this function locates commands, functions defined by defcommand.

Normally, this is called from dispatch and is only needed when calling dispatch* directly.

Returns a map from string command name to command Var.

print-summary clj

(print-summary command-map errors)

Prints the command's summary to *out*; partially generated by clojure.tools.cli, and then enhanced with more information about positional command line arguments.

This is often used when a command performs additional validation of its arguments and needs to output the summary and errors on failure.

Uses the command map that is available in defcommand function (using the :as clause).

errors is a seq of strings to display as errors.

set-prevent-exit! clj

(set-prevent-exit! flag)

Normally, after displaying a command summary, System/exit is called (with 0 if for --help, or 1 if a validation error).

For testing purposes, this can be prevented; instead, an exception is thrown, with message "Exit" and ex-data {:status <status>}.