boot.from.clojure.tools.cli — boot/pod 2.8.1

cli clj

(cli args & specs)

THIS IS A LEGACY FUNCTION and may be deprecated in the future. Please use clojure.tools.cli/parse-opts in new applications.

Parse the provided args using the given specs. Specs are vectors describing a command line argument. For example:

["-p" "--port" "Port to listen on" :default 3000 :parse-fn #(Integer/parseInt %)]

First provide the switches (from least to most specific), then a doc string, and pairs of options.

Valid options are :default, :parse-fn, and :flag. See https://github.com/clojure/tools.cli/wiki/Documentation-for-0.2.4 for more detailed examples.

Returns a vector containing a map of the parsed arguments, a vector of extra arguments that did not match known switches, and a documentation banner to provide usage instructions.

compile-option-specs clj

(compile-option-specs specs)

Map a sequence of option specification vectors to a sequence of:

{:id Keyword ; :server :short-opt String ; "-s" :long-opt String ; "--server" :required String ; "HOSTNAME" :desc String ; "Remote server" :default Object ; nil :default-desc String ; "example.com" :parse-fn IFn ; #(InetAddress/getByName %) :assoc-fn IFn ; assoc :validate-fn IFn ; (partial instance? Inet4Address) :validate-msg String ; "Must be an IPv4 host" }

:id defaults to the keywordized name of long-opt without leading dashes, but may be overridden in the option spec.

The option spec entry :validate [fn msg] desugars into the two entries :validate-fn and :validate-msg.

A :default entry will not be included in the compiled spec unless specified.

An option spec may also be passed as a map containing the entries above, in which case that subset of the map is transferred directly to the result vector.

An assertion error is thrown if any :id values are unset, or if there exist any duplicate :id, :short-opt, or :long-opt values.

parse-opts clj

(parse-opts args option-specs & options)

Parse arguments sequence according to given option specifications and the GNU Program Argument Syntax Conventions:

https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html

Option specifications are a sequence of vectors with the following format:

[short-opt long-opt-with-required-description description :property value]

The first three string parameters in an option spec are positional and optional, and may be nil in order to specify a later parameter.

By default, options are boolean flags that are set to true when toggled, but the second string parameter may be used to specify that an option requires an argument.

e.g. ["-p" "--port PORT"] specifies that --port requires an argument, of which PORT is a short description.

The :property value pairs are optional and take precedence over the positional string arguments. The valid properties are:

:id The key for this option in the resulting option map. This is normally set to the keywordized name of the long option without the leading dashes.

            Must be a unique truthy value.

:short-opt The short format for this option, normally set by the first positional string parameter: e.g. "-p". Must be unique.

:long-opt The long format for this option, normally set by the second positional string parameter; e.g. "--port". Must be unique.

:required A description of the required argument for this option if one is required; normally set in the second positional string parameter after the long option: "--port PORT".

            The absence of this entry indicates that the option is a
            boolean toggle that is set to true when specified on the
            command line.

:desc A optional short description of this option.

:default The default value of this option. If none is specified, the resulting option map will not contain an entry for this option unless set on the command line.

:default-desc An optional description of the default value. This should be used when the string representation of the default value is too ugly to be printed on the command line.

:parse-fn A function that receives the required option argument and returns the option value.

            If this is a boolean option, parse-fn will receive the value
            true. This may be used to invert the logic of this option:

            ["-q" "--quiet"
             :id :verbose
             :default true
             :parse-fn not]

:assoc-fn A function that receives the current option map, the current option :id, and the current parsed option value, and returns a new option map.

            This may be used to create non-idempotent options, like
            setting a verbosity level by specifying an option multiple
            times. ("-vvv" -> 3)

            ["-v" "--verbose"
             :default 0
             :assoc-fn (fn [m k _] (update-in m [k] inc))]

:validate A vector of [validate-fn validate-msg].

:validate-fn A function that receives the parsed option value and returns a falsy value when the value is invalid.

:validate-msg An optional message that will be added to the :errors vector on validation failure.

parse-opts returns a map with four entries:

{:options The options map, keyed by :id, mapped to the parsed value :arguments A vector of unprocessed arguments :summary A string containing a minimal options summary :errors A possible vector of error message strings generated during parsing; nil when no errors exist }

A few function options may be specified to influence the behavior of parse-opts:

:in-order Stop option processing at the first unknown argument. Useful for building programs with subcommands that have their own option specs.

:summary-fn A function that receives the sequence of compiled option specs (documented at #'clojure.tools.cli/compile-option-specs), and returns a custom option summary string.

summarize clj

(summarize specs)

Reduce options specs into a options summary for printing at a terminal.