cli-matic.core — cli-matic 0.5.4

ATTENTION

CLI-matic has one main entry-point: run-cmd.

As an end-user, you need nothing else, but the documentation that explains how parameters are to be run.

See examples/ to get started quickly.

Developers

Most of the logic will be run in run-cmd* to make testing easier, as run-cmd calls System/exit.

assert-cfg-sanity clj/s

(assert-cfg-sanity _)

assert-unique-values clj/s

(assert-unique-values name vec-opts option)

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.

check-one-spec clj/s

(check-one-spec name type spec value)

Checks one spec.

• If spec passes, returns nil; if not, returns the failure.
• If there is an error raised, creates a fake spec result.
• If spec is nil, we consider it a pass.
• if the value is nil, we consider it missing and don't need to check.

explain-data return nil if everything okay.

expound-string returns 'Success! ' if all goes well.

check-specs-on-parameters clj/s

(check-specs-on-parameters options parsed-results type)

Given a set of option (so, global options, or a subcommand's options) and the fully parsed results, we assert that any defined specs pass.

This we do only if the parameter is not nil, that is, is present or has a default value.

If the parameter should be present but it's not, it's not a spec issue but a ':default :present' issue.

errors-for-missing-mandatory-args clj/s

(errors-for-missing-mandatory-args climatic-options parsed-opts other-options)

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.

getReturnValue clj/s

(getReturnValue rv)

Evaluates the result of the CLI-matic subcommand. A result can be nil, or int?, or a deferred value, in which case we wait in a platform-specific way.

invoke-subcmd clj/s

(invoke-subcmd subcommand-def options)

Invokes a subcommand, and produces a Return Value.

The subcommand may:

• return an integer (to specify exit code)
• return nil
• throw a Throwable object

If there is a shutdown hook defined, we also add the shutdown hook before the command is run. If there is a shutdown hook, it is called anyway when the JVM terminates - if you only want this called on early shutdowns, it's up to you to keep some state in a shared atom and decide whether to do something or not.

mk-fake-args clj/s

(mk-fake-args parms)

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.

mkError clj/s

(mkError config subcommand error text)

Builds an error condition.

parse-cmds-with-defaults clj/s

(parse-cmds-with-defaults opts argv in-order? fn-env)

Parses a command line with environment 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).

parse-cmds-with-positions clj/s

(parse-cmds-with-positions opts argv fn-env)

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.

parse-command-line clj/s

(parse-command-line argv config)

This is where the magic happens.

Whereas in version 1 we had one 'global' level and one sub-command, now we have many. From the point of view of sub-commands, all intermediate levels but actual executable sub-commands are global levels; each of them may capture its own variables and have them validated via specs.

So we first try walking to the current level through the configuration, capture and verify what is needed at this level and then terminate only if we are on a leaf (executable subcommand) or there is any error.

Spec checking:

• If parsing goes well, parameter specs are checked on each parameter
• If all of them go well, general spec is checked on the current result of all parsing; that is, including results form all earlier general settings

TODO:

• candidates
• help

run-cmd clj/s

(run-cmd args supplied-config)

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 System.exit you cannot use it from a REPL (well, you technically can, but...).

run-cmd* clj/s

(run-cmd* setup args)

Executes our code.

It will try and parse the arguments via clojure.tools.cli and detect our subcommand.

If no subcommand was found, it will print the error reminder.

On exceptions, it will raise an exception message.