Liking cljdoc? Tell your friends :D

biiwide.tools.cli

Tools for working with command line arguments.

Tools for working with command line arguments.
raw docstring

*env*clj

source

cliclj

(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.

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.
sourceraw docstring

envclj

(env)
(env var-name)
(env var-name missing)

Get an environment variable.

Get an environment variable.
sourceraw docstring

format-linesclj

(format-lines lens parts)

Format a sequence of summary parts into columns. lens is a sequence of lengths to use for parts. There are two sequences of lengths if we are not displaying defaults. There are three sequences of lengths if we are showing defaults.

Format a sequence of summary parts into columns. lens is a sequence of
lengths to use for parts. There are two sequences of lengths if we are
not displaying defaults. There are three sequences of lengths if we
are showing defaults.
sourceraw docstring

get-default-optionsclj

(get-default-options option-specs)

Extract the map of default options from a sequence of option vectors.

Extract the map of default options from a sequence of option vectors.
sourceraw docstring

make-summary-partclj

(make-summary-part show-defaults? spec)

Given a single compiled option spec, turn it into a formatted string, optionally with its default values if requested.

Given a single compiled option spec, turn it into a formatted string,
optionally with its default values if requested.
sourceraw docstring

parse-optsclj

(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 toggles that default to nil, 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.

            Multiple option entries can share the same :id in order to
            transform a value in different ways, but only one of these
            option entries may contain a :default entry.

            This option is mandatory.

: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.

:env An environment variable to check.

: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 ...]. Multiple pairs of validation functions and error messages may be provided.

:validate-fn A vector of functions that receives the parsed option value and returns a falsy value or throws an exception when the value is invalid. The validations are tried in the given order.

:validate-msg A vector of error messages corresponding to :validate-fn 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.

:no-defaults Only include option values specified in arguments and do not include any default values in the resulting options map. Useful for parsing options from multiple sources; i.e. from a config file and from the command line.

:strict Parse required arguments strictly: if a required argument value matches any other option, it is considered to be missing (and you have a parse error).

: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.

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 toggles that default to nil, 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.

                Multiple option entries can share the same :id in order to
                transform a value in different ways, but only one of these
                option entries may contain a :default entry.

                This option is mandatory.

  :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.

  :env          An environment variable to check.

  :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 ...]. Multiple pairs
                of validation functions and error messages may be provided.

  :validate-fn  A vector of functions that receives the parsed option value
                and returns a falsy value or throws an exception when the
                value is invalid. The validations are tried in the given
                order.

  :validate-msg A vector of error messages corresponding to :validate-fn
                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.

  :no-defaults  Only include option values specified in arguments and do not
                include any default values in the resulting options map.
                Useful for parsing options from multiple sources; i.e. from a
                config file and from the command line.

  :strict       Parse required arguments strictly: if a required argument value
                matches any other option, it is considered to be missing (and
                you have a parse error).

  :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.
sourceraw docstring

summarizeclj

(summarize specs)

Reduce options specs into a options summary for printing at a terminal. Note that the specs argument should be the compiled version. That effectively means that you shouldn't call summarize directly. When you call parse-opts you get back a :summary key which is the result of calling summarize (or your user-supplied :summary-fn option) on the compiled option specs.

Reduce options specs into a options summary for printing at a terminal.
Note that the specs argument should be the compiled version. That effectively
means that you shouldn't call summarize directly. When you call parse-opts
you get back a :summary key which is the result of calling summarize (or
your user-supplied :summary-fn option) on the compiled option specs.
sourceraw docstring

with-envcljmacro

(with-env env-bindings & body)

Evaluate a form with a dynamic environment.

Evaluate a form with a dynamic environment.
sourceraw docstring

with-env*clj

(with-env* env-map f)

Execute a function with a dynamic environment.

Execute a function with a dynamic environment.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close