lambdaisland.cli — com.lambdaisland/cli 1.30.130

Command line argument parsing and handling

With support for subcommands, following UNIX conventions.

*opts* clj

add-defaults clj

(add-defaults init-opts flagpairs)

append-middleware clj

(append-middleware opts {mw :middleware})

append-middleware* clj

(append-middleware* opts mw)

assoc-flag clj

(assoc-flag opts {:keys [middleware handler] :as flagspec} & args)

bind-opts-mw clj

(bind-opts-mw)

call-handler clj

(call-handler handler opts & args)

default-parse clj

(default-parse s)

dispatch clj

(dispatch & args)

Main entry point for com.lambdaisland/cli.

Takes either a single var, or a map describing the commands and flags that your CLI tool accepts. At a minimum it should contain either a :command or :commands, optionally followed by a vector of positional command line arguments (this second argument can generally be omitted, since we can access these through [[command-line-args]]).

• :name Name of the script/command as used in the shell, used in the help text
• :command Function that implements your command logic, receives a map of parsed CLI args. Can be a var, in which case additional configuration can be done through var metadata.
• :commands Map or flat vector of command-string command-map pairs
• :doc Docstring, taken from :command if it is a var.
• :flags Map or flat vector of flag-string flag-map
• :argnames Vector of positional argument names, only needed on the top level, for subcommands use the command-string to specify these.
• :init map or zero-arity function that provides the base options map, that parsed flags and arguments are added onto

These flags can also be used in (sub)command maps, with the exception of :name, :argnames, and :init.

A command-string consists of the name of the command, optionally followed by any named positional argument, either in all-caps, or delineated by angle brackets, e.g. create <id> <name> or delete ID.

A flag-string consists of command separated short (single-dash) or long (double-dash) flags, optionally followed by an argument name, either in all-caps, or delineated by angle brackets. The flag and argument are separated by either a space or an equals sign. e.g. --input=<filename>, -o, --output FILENAME.

Flag-maps can contain

• :doc Docstring, used in the help text
• :parse Function that parses/coerces the flag argument from string.
• :default Default value, gets passed through :parse if it's a string.
• :handler Function that transforms the options map when this flag is present. Single-arity for boolean (no-argument) flag, two-arity for flags that take an argument.
• :middleware Function or sequence of functions that will wrap the command function if this flag is present.
• :required Boolean value to indicate if the flag is required.

This docstring is just a summary, see the com.lambdaisland/cli README for details.

dispatch* clj

(dispatch* cmdspec)

(dispatch* {:keys [flags init] :as cmdspec} cli-args)

(dispatch* {:keys [commands doc argnames command flags flagpairs flagmap
                   middleware]
            :as cmdspec
            program-name :name
            :or {program-name "cli"}}
           pos-args
           opts)

handle-flag clj

(handle-flag {:keys [flagmap strict?] :as cmdspec} flag cli-args args flags)

help-mw clj

(help-mw {:keys [name doc argnames flagpairs] :or {name "cli"}})

long? clj

(long? f)

missing-flags clj

(missing-flags flagmap opts)

Return a set of required flags in flagmap not present in opts, or nil if all required flags are present.

missing-flags-mw clj

(missing-flags-mw {:keys [flagmap]})

parse-error! clj

(parse-error! & msg)

prepend-middleware* clj

(prepend-middleware* opts mw)

print-help clj

(print-help cmd-name doc command-pairs argnames flagpairs)

print-table clj

(print-table rows)

(print-table rows {:keys [pad] :or {pad 2}})

short? clj

(short? f)

spill-lines clj

(spill-lines segments width)

split-flags clj

(split-flags cmdspec cli-args opts)

Main processing loop, go over raw arguments, split into positional and flags, building up an argument vector, and flag/options map.

transpose clj

(transpose m)