cli-matic.core
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 bhe 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 bhe 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-sanityclj/s
(assert-cfg-sanity currentCfg)Checks configuration and throws if anything wrong.
- are :option values unique?
- are :short values unique?
- do we have any positional arguments in global config?
First we make a list of nil plus all subcmds.
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.
assert-unique-valuesclj/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 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-specclj/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.
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. explain-data return nil if everything okay. expound-string returns 'Success! ' if all goes well.
check-specs-on-parametersclj/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.
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.
check-specs-on-parsed-argsclj/s
(check-specs-on-parsed-args parsed-args canonical-subcommand config)As a last step, before we call the subcommand itself, we assert that any spec that was actually defined is passed.
We just care about the first spec that fails, so we can get a lazy list of failures and get the first of them (or nil).
As a last step, before we call the subcommand itself, we assert that any spec that was actually defined is passed. We just care about the first spec that fails, so we can get a lazy list of failures and get the first of them (or nil).
errors-for-missing-mandatory-argsclj/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.
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.
invoke-subcmdclj/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.
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-argsclj/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.
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.
mkErrorclj/s
(mkError config subcommand error text)Builds an error condition.
Builds an error condition.
parse-cmdsclj/s
(parse-cmds argv config)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 to run it.
This function returns a structure ::S/lineParseResult that contains information about what went wrong or the command to run.
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 to run it. This function returns a structure ::S/lineParseResult that contains information about what went wrong or the command to run.
parse-cmds-with-defaultsclj/s
(parse-cmds-with-defaults cmt-options argv in-order? fn-env)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).
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).
parse-cmds-with-positionsclj/s
(parse-cmds-with-positions config canonical-subcommand subcommand-parms)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-single-argclj/s
(parse-single-arg optionDef stringValue)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
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
run-cmdclj/s
(run-cmd args supplied-setup)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.
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.
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.
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