Reads one positional parameter from the arguments.
Returns a vector [parm value]
The value is NOT solved, so it's always a string.

Returns all subcommands, as strings.
We get all versions of all subcommands.

Maps all subcommands and subcommand aliases
to their canonical name.
E.g. {'add': 'add', 'a': 'add'}.

We basically add them all, then remove
nil keys.

Creates the `[arguments...]`

Checks configuration and throws if anything wrong.

1. are :option values unique?
2. are :short values unique?
3. do we have any positional arguments in global config?

First we make a list of `nil` plus all subcmds.

Check that all values are unique.
name is the area of the configuration
vec-opts are the options to check
option is the keyword to check.

Associates a new multiple value to the
current parameter map.
If the current value is not a vector, creates
a new vector with the new value.

Turns a collection of strings into one string,
or the string itself.

Returns the 'canonical' name of a subcommand,
i.e. the one that appears in :command, even
if we pass an alias or short version.

Captures positional parameters in the remaining-args of
a subcommand.

Out of a cli-matic arg list, generates a set of
options for tools.cli.
It also adds in the -? and --help options
to trigger display of helpness.

Gets us a sequence of errors if mandatory options are missing.
Options read by cli module are merged with other options, e.g.
positional parameters.

Maybe we should use a way to format commands

E.g.
(pp/cl-format true "~{ ~vA  ~vA  ~vA ~}" v)


(clojure.pprint/cl-format true "~3a ~a" "pippo" "pluto")

Creates a list of commands and descriptions.
Commands are of kind ::S/commands

This is where we generate global help, so
global attributes and subcommands.

Generates a section (as a collection of strings,
possibly nested, but we'll flatten it out).
If a section has no content, we return [].

Generates all sections.
All those positional parameters are not that nice.

This is where we generate help for a specific subcommand.

get title and description of description rows

Gets specific :options for a subcommand or,
if nil, for global.

To get the summary of options, we pass options to
tools.cli parse-opts and an empty set of arguments.
Parsing will fail but we get the :summary.
We then split it into a collection of lines.

Given args and the canonical name of a subcommand,
returns the map describing it.

Indents a single string, or each string
in a collection of strings.

Indents a single string.

Invokes a subcommand, and produces a Return Value.

The subcommand may:
 - return an integer (to specify exit code)
 - return nil
 - throw a Throwable object

Extracts all positional parameters from the configuration.

Builds a tools.cli option out of our own format.

If for-parsing is true, the option will be used for parsing;
if false, for generating help messages.

Writes a description with the env name by the end.

Builds the set of fake arguments that we append to our
subcommands' own CLI items
when we have positional parameters.
If value is nil, option is not added.

We receive a map of options and output a vector of strings.

Builds an error condition.

Pads s[, s1] to so many characters

This is where magic happens.
We first parse global options, then stop,
get the subcommand, parse specific options for the subcommand
and if all went well we prepare run it.

This function returns a structure ::S/lineParseResult
that contains information about what went wrong or the command
to run.

Parses a command line with environemt defaults.
We want environment defaults to be PARSED, so they will go through
the same validation/check cycle as other elements.
So - if any of them - we first run parsing disabling defaults,
then go check if they are available in parsed elements;
if they are not, we inject them as options to the left of argv
and parse again.
(as a side effect, if you have a wrong value for your option, and a
default, the default will be used - YMMV).

To process positional parameters, first we run some parsing; if
all goes well, we capture the values of positional
arguments and run parsing again with a command line that has those
items as if they were expressed.

This means that type casting and validation just happen in one place
(CLI parsing) and  we don't have to do them separately.

This function is used both for global and subcmd parsing,
but when doing global parsing, positional parameters are
not allowed, so they never come in.

Parses and validates a single command.
Returns its value, and an error message,
in a vector [:keyword err val].
Parsing is OK if error message is nil.

Sequence is:
- parsing (eg `2` -> 2), on exception parse error
- validation via spec
- validation via function, on exception validation error

Out of a cli-matic arg list, generates a set of
options for tools.cli.
It also adds in the -? and --help options
to trigger display of helpness.

This is the actual function that is executed.
It wraps run-cmd* and then does the printing
of any errors, of help pages and  System.exit.
As it invokes Sys.exit you cannot use it from a REPL.