Liking cljdoc? Tell your friends :D

nl.jomco.envopts

NAME

envopts - Clojure library for parsing configuration from environment

SYNOPSIS

(ns your-ns.main
  (:require [nl.jomco.envopts :as envopts]))

(def opt-specs {:port     ["port nr" :int :default 80]
                :hostname ["hostname to use" :str]})

(defn -main [& args]
  (let [[opts errs] (envopts/opts env opt-specs)]
    (when errs
      (.println *err* (envopts/errs-description errs))
      (System/exit 1))
    ... do something with opts))

Opt Specs

In envopts, you provide all available configuration options in a map of opt specs, which maps environment keys to options:

{"PORT"    ["The port used to listen to requests" :int :default 80 :in [:http :port]]
 :hostname ["The hostname to listen to requests" :str :in [:http :hostname]]
 :threads  ["The number of threads to start" :int]
 :auth-uri ["Authentication server endpoint" :http]}

Keys

The default in envopts is to use environ.core/env as the provider of the environment, in which case keys will be lisp-style lower-case keywords. I.e. the environment variable "USER_NAME" will be at key :user-name.

It's also possible to specify keys as strings, in which case they wil be converted to keywords to match the environ conversion.

Opt Specs

Opt specs can be specified as a vector - the compact version that is nice to read and write by hand, or as a map, which is easier to manipulate programmatically.

Spec vectors begin with a description and an optional type, followed by any other options:

{:port ["The port that will serve web requests" :int :default 80]}

Spec maps can contain the following keys:

  • :description - description of the given key
  • :type - a keyword that is registered in nl.jomco.envopts/parse multimethod.
  • :parser - parser function for expected type, one of the built-in parsers or your own (see below). If :parser is provided, it overrides the :type option.
  • :default - the default value for the option. If no default is specified, the key is required.
  • :in - the path to use for the parsed option in the configuration options map. The default is to use the key (converted to lower-snake-case keyword if necessary) that is used in the specs map.

types

Since environment variables are always strings, you need a parser to convert an environment value to another type. A few types are provided for you. See as-float, as-int, as-str and as-http.

implementing custom parsers

A parser function must take a string value and return a tuple:

  • [value] or [value nil], where value is the parsed value, or
  • [nil err] if the string value cannot be parsed.

err should be a partial sentence describing the error. It should complete the sentence "xxx is ...", so a good value for err would be "not a valid frobnitz". Any errs parsing the configuration map are aggregated and returned from opts for printing with errs-description.

# NAME

envopts - Clojure library for parsing configuration from environment

# SYNOPSIS

    (ns your-ns.main
      (:require [nl.jomco.envopts :as envopts]))

    (def opt-specs {:port     ["port nr" :int :default 80]
                    :hostname ["hostname to use" :str]})

    (defn -main [& args]
      (let [[opts errs] (envopts/opts env opt-specs)]
        (when errs
          (.println *err* (envopts/errs-description errs))
          (System/exit 1))
        ... do something with opts))

## Opt Specs

In envopts, you provide all available configuration options in a map
of opt specs, which maps environment keys to options:

    {"PORT"    ["The port used to listen to requests" :int :default 80 :in [:http :port]]
     :hostname ["The hostname to listen to requests" :str :in [:http :hostname]]
     :threads  ["The number of threads to start" :int]
     :auth-uri ["Authentication server endpoint" :http]}

Keys

The default in envopts is to use `environ.core/env` as the provider
of the environment, in which case keys will be lisp-style lower-case
keywords. I.e. the environment variable `"USER_NAME"` will be at key
`:user-name`.

It's also possible to specify keys as strings, in which case they wil
be converted to keywords to match the `environ` conversion.

Opt Specs

Opt specs can be specified as a vector - the compact version that is
nice to read and write by hand, or as a map, which is easier to
manipulate programmatically.

Spec vectors begin with a description and an optional type, followed
by any other options:

    {:port ["The port that will serve web requests" :int :default 80]}

Spec maps can contain the following keys:

  - :description - description of the given key
  - :type - a keyword that is registered in `nl.jomco.envopts/parse`
    multimethod.
  - :parser - parser function for expected type, one of the built-in parsers or
    your own (see below). If :parser is provided, it overrides the :type
    option.
  - :default - the default value for the option. If no default is specified, the key
    is *required*.
  - :in - the path to use for the parsed option in the configuration
    options map. The default is to use the key (converted to lower-snake-case
    keyword if necessary) that is used in the specs map.

## types

Since environment variables are always strings, you need a parser to
convert an environment value to another type. A few types are
provided for you. See `as-float`, `as-int`, `as-str` and
`as-http`.

## implementing custom parsers

A parser function must take a string value and return a tuple:

  - `[value]` or `[value nil]`, where `value` is the parsed value, or
  - `[nil err]` if the string value cannot be parsed.

`err` should be a partial sentence describing the error. It should
complete the sentence "xxx is ...", so a good value for `err` would be
"not a valid frobnitz". Any errs parsing the configuration map are
aggregated and returned from `opts` for printing with
`errs-description`.
raw docstring

as-floatclj

(as-float s opt-spec)

Parses s as a Double. Returns [parsed] or [nil error].

Parses s as a Double. Returns `[parsed]` or `[nil error]`.
sourceraw docstring

as-httpclj

(as-http s opt-spec)

Parses s as a web address. s must contain the http or https scheme.

Valid: "https://jomco.nl/" Invalid: "mailto:test@example.com" Invalid: "jomco.nl"

Returns [parsed] or [nil error].

Parses s as a web address. s must contain the `http` or `https`
scheme.

Valid: "https://jomco.nl/"
Invalid: "mailto:test@example.com"
Invalid: "jomco.nl"

Returns `[parsed]` or `[nil error]`.
sourceraw docstring

as-intclj

(as-int s opt-spec)

Parses s as a Long. Returns [parsed] or [nil error].

Parses s as a Long. Returns `[parsed]` or `[nil error]`.
sourceraw docstring

as-strclj

(as-str s opt-spec)

Parses s as a string. Returns [s]

Parses s as a string. Returns `[s]`
sourceraw docstring

errs-descriptionclj

(errs-description errs)

Return a multi-line string description of the errors, suitable for printing to the user.

Return a multi-line string description of the errors, suitable for
printing to the user.
sourceraw docstring

optsclj

(opts specs)
(opts env specs)

Parse options from the environment map given an option spec.

Takes one or two arguments:

  • env - an optional map of keywords to string values. if env is not provided, uses environ.core/env to get the map from the environment.
  • specs - a map of keys or strings to option descriptions, one for every option. This may be a compact description (vector) or a map. See also the ns documentation: nl.jomco.envopts.

Returns an [options errs] tuple:

  • options - when env can be parsed into a valid set of options, returns [options nil].
  • errs - when any option cannot be parsed, of when a required option is not provided in env, returns [nil errs].

errs can be printed using errs-description.

See also specs-description

Parse options from the environment map given an option spec.

Takes one or two arguments:

  - `env` - an optional map of keywords to string values. if `env`
    is not provided, uses `environ.core/env` to get the map from the
    environment.
  - `specs` - a map of keys or strings to option descriptions, one for every
    option. This may be a compact description (vector) or a map. See
    also the ns documentation: `nl.jomco.envopts`.

Returns an `[options errs]` tuple:

  - `options` - when `env` can be parsed into a valid set of options,
    returns `[options nil]`.
  - `errs` - when any option cannot be parsed, of when a required
    option is not provided in `env`, returns `[nil errs]`.

`errs` can be printed using `errs-description`.

See also `specs-description`
sourceraw docstring

parsecljmultimethod

Parses an environment string s according to the opt-spec map. This is the recommended extension point for handling custom types.

The multimethod dispatches on the value of :type in opt-spec.

Built-in implementations are:

 - :str
 - :int
 - :float
 - :http
Parses an environment string `s` according to the `opt-spec`
map. This is the recommended extension point for handling custom
types.

The multimethod dispatches on the value of `:type` in
`opt-spec`.

Built-in implementations are:

     - :str
     - :int
     - :float
     - :http
sourceraw docstring

specs-descriptionclj

(specs-description specs)

Return a multi-line string description of the option specs, suitable for printing to the user. See the ns documentation in nl.jomco.envopts for the format of specs

Return a multi-line string description of the option specs, suitable
for printing to the user. See the ns documentation
in `nl.jomco.envopts` for the format of `specs`
sourceraw docstring

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

× close