Skip to content

API.md

Latest commit

 

History

History
332 lines (265 loc) · 12.8 KB

API.md

File metadata and controls

332 lines (265 loc) · 12.8 KB

Table of contents

babashka.cli

apply-defaults

(apply-defaults m)
(apply-defaults m opts)

Function.

Fills missing keys in m from defaults. Existing keys in m win. Preserves metadata of m.

Supported options:

  • :exec-args - map of defaults.
  • :spec - spec; :default entries become defaults via spec->opts.

Source

auto-coerce

(auto-coerce s)

Function.

Auto-coerces s to data. Does not coerce when s is not a string. If s:

  • is true or false, it is coerced as boolean
  • starts with number, it is coerced as a number (through Clojure's edn/read-string)
  • starts with :, it is coerced as a keyword (through parse-keyword)

Source

coerce

(coerce s f)

Function.

Coerce string s using f. Does not coerce when s is not a string. f may be a keyword (:boolean, :int, :double, :symbol, :keyword) or a function. When f return nil, this is interpreted as a parse failure and throws.

Source

coerce-opts

(coerce-opts m)
(coerce-opts m opts)

Function.

Coerces values in the map m using the provided configuration. Does not coerce values that are not strings. Returns a new map with coerced values.

Supported options:

  • :coerce - a map of option (keyword) names to type keywords (optionally wrapped in a collection).
  • :spec - a spec of options. See spec.
  • :error-fn - error handler, called with a map containing :cause (:coerce), :msg, :option, :value, and :opts.

Source

dispatch

(dispatch table args)
(dispatch table args opts)

Function.

Subcommand dispatcher.

Dispatches on longest matching command entry in table by matching subcommands to the :cmds vector and invoking the correspondig :fn.

Table is in the form:

[{:cmds ["sub_1" .. "sub_n"] :fn f :args->opts [:lib]}
 ...
 {:cmds [] :fn f}]

When a match is found, :fn called with the return value of parse-args applied to args enhanced with:

  • :dispatch - the matching commands
  • :args - concatenation of unparsed commands and args
  • :rest-cmds: DEPRECATED, this will be removed in a future version

Use an empty :cmds vector to always match or to provide global options.

Provide an :error-fn to deal with non-matches.

Each entry in the table may have additional parse-args options.

For more information and examples, see README.md.

Source

format-opts

(format-opts {:as cfg, :keys [indent], :or {indent 2}})

Function.

Source

format-table

(format-table {:keys [rows indent], :or {indent 2}})

Function.

Source

merge-opts

(merge-opts m & ms)

Function.

Merges babashka CLI options.

Source

number-char?

(number-char? c)

Function.

Source

opts->table

(opts->table {:keys [spec order columns]})

Function.

Source

pad

(pad len s)

Function.

Source

pad-cells

(pad-cells rows)

Function.

Source

parse-args

(parse-args args)
(parse-args args opts)

Function.

Same as parse-opts with return data reshaped.

Returns a map with:

  • :opts parsed opts
  • :args remaining unparsed args

Source

parse-cmds

(parse-cmds args)
(parse-cmds args {:keys [no-keyword-opts]})

Function.

Parses sub-commands (arguments not starting with an option prefix). Returns a map with:

  • :cmds - The parsed subcommands
  • :args - The remaining (unparsed) arguments

Source

parse-keyword

(parse-keyword s)

Function.

Parse keyword from s. Ignores leading :.

Source

parse-opts

(parse-opts args)
(parse-opts args opts)

Function.

Returns a map of options parsed from command line arguments args, a seq of strings. Instead of a leading : either -- or - may be used as well.

Metadata on returned map, under :org.babashka/cli:

  • :args remaining unparsed args (not corresponding to any options)

Supported opts:

  • :coerce - a map of option (keyword) names to type keywords (optionally wrapped in a collection.)
  • :alias - a map of short names to long names.
  • :spec - a spec of options. See spec.
  • :restrict - true or coll of keys. Throw on first parsed option not in set of keys or keys of :spec and :coerce combined.
  • :require - a coll of options that are required. See require.
  • :validate - a map of validator functions. See validate.
  • :exec-args - a map of default args. Will be overridden by args specified in args. Values from :exec-args are NOT coerced or auto-coerced; provide them in their final form.
  • :no-keyword-opts - true. Support only --foo-style opts (i.e. :foo will not work).
  • :repeated-opts - true. Forces writing the option name for every value, e.g. --foo a --foo b, rather than --foo a b
  • :args->opts - consume unparsed commands and args as options
  • :collect - a map of collection fns. See custom collection handling.

Examples:

(parse-opts ["foo" ":bar" "1"])
;; => ^{:org.babashka/cli {:args ["foo"]}} {:bar 1}
(parse-opts [":b" "1"] {:aliases {:b :bar} :coerce {:bar parse-long}})
;; => {:bar 1}
(parse-opts ["--baz" "--qux"] {:spec {:baz {:desc "Baz"}} :restrict true})
;; => throws 'Unknown option --qux' exception b/c there is no :qux key in the spec

See also: parse-args

Source

parse-opts*

(parse-opts* args {:keys [coerce collect no-keyword-opts repeated-opts], :as opts})

Function.

Parses CLI args into a raw opts map. Returns string values unchanged (no coercion), does not apply :exec-args defaults, does not run :restrict/:require/:validate. Result map includes :org.babashka/cli metadata and internal ::implicit-true-keys / ::keys-order metadata used by coerce-opts.

Use this when you want to merge other sources (e.g. config files) before coerce/validate. Pipeline: parse-opts* -> merge -> apply-defaults -> coerce-opts -> validate-opts.

Supported options (subset of parse-opts): :alias/:aliases, :coerce, :collect, :no-keyword-opts, :repeated-opts, :args->opts, :spec.

Source

spec->opts

(spec->opts spec)
(spec->opts spec {:keys [exec-args]})

Function.

Converts spec into opts format. Pass existing opts as optional second argument.

Source

validate-opts

(validate-opts m)
(validate-opts m opts)

Function.

Validates the map m using the provided configuration. Returns m.

Supported options:

  • :restrict - true or coll of keys. Error on keys in m not in the restrict set or not derivable from :spec and :coerce.
  • :require - a coll of options that are required.
  • :validate - a map of option keys to validator functions (or maps with :pred and :ex-msg).
  • :spec - a spec of options (restrict, require, validate extracted from it).
  • :coerce - used with :restrict true to derive the set of known keys.
  • :error-fn - error handler, called with a map containing :cause, :msg, :option, and :opts.

Source

babashka.cli.exec

-main

(-main & args)

Function.

Main entrypoint for command line usage. Expects a namespace and var name followed by zero or more key value pair arguments that will be parsed and passed to the var. If the first argument is map-shaped, it is read as an EDN map containing parse instructions.

Example when used as a clojure CLI alias:

clojure -M:exec clojure.core prn :a 1 :b 2
;;=> {:a "1" :b "2"}

Source

main

(main & args)

Function.

Source