defenv.core — coreagile/defenv 2.0.0

add-to-global-defined-spec! clj

(add-to-global-defined-spec! env-name params)

Used primarily by defenv to add to the global environment state.

defenv clj macro

(defenv b & [doc-or-env env-or-fk & remaining])

Define a binding b to an environment variable. Creates a delayed object that, when dereferenced, will load an environment variable of the given key.

If doc-or-env and env-or-fk are both strings, we assume that doc-or-env is a docstring and env-or-fk is the environment variable to be pulled. Then, remaining become the params.

Else, we assume doc-or-env is the environment variable and we use env-or-fk as the first key of the params. This convention also allows for your documentation generator (like <https:// github.com / gdeer81/marginalia>) to detect docstrings in their conventional position.

If :default {value} shows up in the params, will send back the given value if the variable isn't defined.

If :tfn {function} shows up in the params, runs the given function against the result of the environment variable load, which is by default a string. Best not to use a lambda, as you won't get any helpful context on parse errors.

If you add :masked? and set it to true, the value won't be displayed in usage documentation.

If you add :optional? and set it to true, then there need not be a default value set, and the tfn will not get invoked if the value is missing.

display-env clj

(display-env)

(display-env env-spec)

(display-env env-spec out-fn)

Display the current environment to users in a friendly manner. If you call this function without an env-spec, we will print the result of documentation from all the defenv calls that have been executed in all the referred namespaces. Otherwise, it will be based on the spec given. This is the same format as you would send to env->map.

Also, in case you want to send your own function (instead of println), you can call the 2-argument alternative. out-fn will be executed with a string representation of the given environment. If env-spec is nil, we will use the global environment (modified using defenv).

display-spec clj

(display-spec)

(display-spec env-spec)

From an environment specification (or nil, if using the global), construct a specification for how to display the environment configuration.

display-spec->docs clj

(display-spec->docs display-spec)

Convert a display spec into a collection of objects suitable for displaying documentation

doc-table clj

(doc-table env-docs)

Convert a connection of spec docs into a nice table

env->map clj

(env->map env-spec)

Operates much like defenv except you can define multiple bindings at once, and receive a map of all values that have been found in the environment. Unlike defenv, however, this function will throw an exception if any required variable is missing, not just the one you ask for.

The map should look something like this:

{:ev1 {:env-name "MY_ENV_VAR"
       :tfn my-optional-parse-function
       :default "MY OPTIONAL DEFAULT VALUE"
       :masked? true
       :doc "Nice documentation"
       :optional? true}
 :other {:env-name "OTHER_VAR"}}

In this case, the :ev1 key will be filled in with the value of MY_ENV_VAR, unless it isn't present, in which case, it will receive the value MY OPTIONAL DEFAULT VALUE. Every key except for :env-name is optional.

In the case of :other, if there is no value for OTHER_VAR, there will be an exception thrown much like when attempting to deref a binding generated by defenvthat is required but missing.

extract-global-spec clj

(extract-global-spec f)

Extract the global environment config as a list of maps

get-global-env clj

(get-global-env env-name)

Used primarily by defenv to retrieve the global environment state.

on-load! clj

(on-load! f)

one clj

(one env-name & params)

Get a single environment variable value. You can use any of the params that you would use in env->map except :env-name, which is the env-name.

parse-bool clj

(parse-bool s)

parse-boolean clj deprecated

(parse-boolean s)

DEPRECATED in favor of parse-bool

parse-double clj

(parse-double s)

parse-float clj

(parse-float s)

parse-int clj

(parse-int s)

parse-long clj

(parse-long s)

parse-map clj

(parse-map s)

(parse-map {:keys [default-key key-fn]
            :or {default-key "default" key-fn identity}}
           s)

Parses a string containing key-value pairs into a map. Each pair is separated by a comma, and the key and value by an equal sign. Whitespace surrounding keys and values is ignored. Example: a=b,c=d parses to {"a"="b", "c"="d"}.

You can pass two configuration options into the opts map:

:default-key specifies what happens when either you don't follow the syntax (you get a map with the value of :default-key as its key, and the variable value as its value) or when you have a key in the map that is blank.

:key-fn specifies a function to execute on each key. This function is not executed on the :default-key

See defenv.tfn-spec for examples.

print-usage clj

(print-usage pfn message display-spec)

reset-defined-env! clj

(reset-defined-env!)

set-err-print-fn! clj

(set-err-print-fn! f)

set-error-print-enabled! clj

(set-error-print-enabled! enabled?)

spec->docs clj deprecated

(spec->docs display-spec)

DEPRECATED in favor of parse-bool

with-print-fn clj macro

(with-print-fn f & body)

with-usage-print-enabled clj macro

(with-usage-print-enabled & body)