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

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 map of options, which bypasses parsing and validation of the arguments, and is used only for testing.

Finally, the body is evaluated 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
• :flat (optional, boolean) - if true, then the default help will be flat (no categories)

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
• :categories - seq of maps describing the command categories (see locate-commands)
• :commands - seq of command maps (see locate-commands)

Each namespace forms a command category, represented as a map with keys:

• :category - symbol identifying the namespace
• :command-group string - optional, from :command-group metadata on namespace, groups commands with a prefix name
• :label - string (from :command-category metadata on namespace), defaults to the namespace name
• :order - number (from :command-category-order metadata on namespace), defaults to 0

In the help command summary, the categories are sorted into ascending order by :order, then by :label. Individual commands are listed under each category, in ascending alphabetic order.

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.

expand-dispatch-options clj

(expand-dispatch-options options)

Called by dispatch to expand the options before calling dispatch*. Some applications may call this instead of dispatch, modify the results, and then invoke dispatch*.

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 tuple: the command categories map, and the command map.

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.

select-option clj

(select-option short-opt
               long-opt
               desc-prefix
               input-values
               &
               {:keys [default] :as kvs})

Builds a standard option spec for selecting from a list of possible values. Uses best-match to parse the user-supplied value (allowing for reasonable abbeviations).

Following the input values is a list of key value pairs; the :default key, if non-nil, should be a member of input-values and will generate :default and :default-desc keys in the option spec.

Adds :parse-fn and :validate keys to the returned option spec, as well as :default and :default-desc. Additional key/value pairs are passed through as-is.

Usage (as part of a command's interface):

... format (select-option
               "-f" "--format FORMAT" "Output format:"
               #{:plain :csv :tsv :json :edn}) ...

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.