net.lewisship.cli-tools — io.github.hlship/cli-tools 0.6

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

best-match clj

(best-match input values)

Given an input string and a seq of possible values, returns the matching value if it can be uniquely identified.

values may be strings, symbols, or keywords.

best-match does a caseless substring match against the provided values. It returns the single value that matches the input. It returns nil if no value matches, or if multiple values match.

Some special handling for the - character; the input value is split on - and turned into a generous regular expression that matches the substring on either side of the - as well as the - itself.

Returns the string/symbol/keyword from values.

e.g. :parse-fn #(cli-tools/best-match % #{:red :green :blue}) would parse an input of red to :red, or an input of b to :blue; z matches nothing and returns nil, as would e which matches multiple values.

Expects symbols and keywords to be unqualified.

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 is variadic, accepting a number of strings, much like a -main function. For testing purposes, it may instead be passed a single map, a command map, which bypasses parsing of the arguments, and is used only for testing.

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 (optional, string) - used in command summary and errors
• :tool-doc (optional, 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 :tool-name option is only semi-optional; in a Babashka script, it will default from the babashka.file system property, if any. An exception is thrown if :tool-name is not provided and can't be defaulted.

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)

All options are required.

Returns nil.

exit clj

(exit status)

An indirect call to System/exit, passing a numeric status code (0 for success, non-zero for an error).

This is provided so that, during testing, when set-prevent-exit! has been called, the call to exit will instead throw an exception.

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>}.

sorted-name-list clj

(sorted-name-list values)

Converts a seq of strings, keywords, or symbols (as used with best-match) to a comma-separated string listing the values. This is often used with help summary or error messages related.