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
.
### 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-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 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 name type spec value)
Checks one spec.
explain-data
return nil if everything okay.
expound-string
returns 'Success!
' if all goes well.
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 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.
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 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.
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 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.
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 subcommand-def options)
Invokes a subcommand, and produces a Return Value.
The subcommand may:
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.
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 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.
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 config subcommand error text)
Builds an error condition.
Builds an error condition.
(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).
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 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.
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 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:
TODO:
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 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...).
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* 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.
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.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close