zensols.actioncli.parse — com.zensols.tools/actioncli 0.0.30

Parse action based command line arguments.

*dump-jvm-on-error* clj

Bind this from the REPL to avoid a system exit when testing the CLI.

*include-program-in-errors* clj

If non-nil add program name to error and warning messages in handle-exception and [[error-message]] and print-error-message.

*log-error* clj

Log exceptions in handle-exception.

*parse-context* clj

This context is bound when calling action bound functions. This is useful when other functions in this namespace need to be called with parse information.

This context is a map with the following keys:

• :action-context the context created with multi-action-context or single-action-context
• :arguments the arguments passed to the parse function
• :options the parsed options
• :single-action-mode? whether the action context was created with multi-action-context or single-action-context

*rethrow-error* clj

When not dying on error with *dump-jvm-on-error* also don't rethrow the exception in handle-exception.

create-actions clj

(create-actions action-context)

create-default-usage-format clj

(create-default-usage-format)

(create-default-usage-format usage-format)

Create a function that formats the usage statement.

error-msg clj

(error-msg errors)

Print every element of the sequence errors. If there errors is a singleton then only print one in the common usage format.

handle-exception clj

(handle-exception e)

Handle exceptions thrown from CLI actions.

See:

• *include-program-in-errors*
• *rethrow-error*
• *log-error*

help-message clj

(help-message & {:keys [action-key usage] :or {usage true}})

Generate the help message text and return it. The action-key is a keyword of the passed as a command to multi-action-context. By default the usage text is included unless the :usage key is false. If the :usage is the symbol only then only create the usage text and not the action/parameters.

help-option clj

(help-option)

(help-option short long)

Return an option that provides version information.

multi-action-context clj

(multi-action-context actions
                      &
                      {:keys [global-actions help-option version-option
                              action-print-order print-help-fn usage-format-fn
                              no-action-fn default-arguments]
                       :or {help-option (help-option)
                            no-action-fn (fn [] (println (help-message)))}})

Create a multi-action context with map action. These don't include the name of the action on the command line and are typical UNIX like command lines (ex: ls, grep, etc).

The parameter is action is a list of list of symbols takes the form:

'((:action-name1 package1 action1)
  ...)

where action-name is a key, package is the package and action is the action definition.

Keys

• help-option: the help action command, which defaults to help-option
• version-option: usually created with version-option
• global-actions: addition global actions in addition to the help and version options listed above
• action-print-order: an optional sequence of action name keys indicating what order to print action help
• print-help-fn: an optional function that takes a string argument of the generated option help to provide a way to customize the help message
• usage-format-fn: generate the usage portion of the help message that takes the names of all action if generating multi-action usage or nil for single action usage messages
• :no-action-fn a function to call when no action is given, defaults to printing the contents of help-message; set to nil to continue processing without an action

print-error-message clj

(print-error-message errors)

Print errors messages generated by [[error-message]].

process-arguments clj

(process-arguments action-context args)

Process the action line, which contains the action (action) and arguments args.

The action context is a map with actions. Actions in turn contains what to run when an action is given.

An example of an action context:

(defn- create-action-context []
  (multi-action-context
   '((:service com.example service start-server-action)
     (:repl zensols.actioncli repl repl-action))
   :version-option
   (->> (fn [] (println "version string"))
        version-option)
   :default-arguments ["service" "-p" "8080"]))

See the main document page for more info.

program-name clj

(program-name)

Return the program name used for info/error message. This is set with set-program-name.

set-program-name clj

(set-program-name program-name)

Set the program name used for info/error message.

single-action-context clj

(single-action-context action & options)

Create a single action context with map action. These don't include the name of the action on the command line and are typical UNIX like command lines (ex: ls, grep, etc).

The parameter is action is a list of symbols that takes the form:

'(package action)

where package is the package and action is the action definition.

See multi-action-context for the description of options.

version-option clj

(version-option print-fn)

(version-option print-fn short long)

Return an option that provides version information. The option uses print-fn to print the version of the program.

with-exception clj macro

(with-exception & forms)

Wrap a CLI forms in a try and call handle-exception if an exception occurs.