lambdaisland.cli — com.lambdaisland/cli 1.27.121

Command line argument parsing and handling

With support for subcommands, following UNIX conventions.

*opts* clj

add-defaults clj

(add-defaults init-opts flagpairs)

add-processed-flags clj

(add-processed-flags cmdspec extra-flags)

We process flag information for easier use, this results in :flagpairs (ordered sequence of pairs, mainly used in printing help information), and :flagmap (for easy lookup), added to the cmdspec. As we process arguments we may need to add additional flags, based on the current subcommand. This function is used both for the top-level as for subcommand handling of flags.

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)

build-flagmap-entries clj

(build-flagmap-entries [flagstr flagopts])

call-handler clj

(call-handler handler opts & args)

cmd->flags clj

(cmd->flags cmdspec args)

coerce-to-pairs clj

(coerce-to-pairs o)

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)

flag-re clj

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)

parse-flagstr clj

(parse-flagstr flagstr flagopts)

parse-flagstrs clj

(parse-flagstrs flagpairs)

prepare-flagpairs clj

(prepare-flagpairs flagstrs)

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)

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)