Liking cljdoc? Tell your friends :D

Clojure only.

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-float^clj

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

source raw docstring

as-http^clj

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

source raw docstring

as-int^clj

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

source raw docstring

as-str^clj

(as-str s opt-spec)

Parses s as a string. Returns [s]

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

source raw docstring

errs-description^clj

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

source raw docstring

opts^clj

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

parse^cljmultimethod

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

source raw docstring

specs-description^clj

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

source raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

Raise an issue Browse cljdoc source Chat on Slack

× close

nl.jomco.envopts

NAME

SYNOPSIS

Opt Specs

types

implementing custom parsers

as-floatclj

as-httpclj

as-intclj

as-strclj

errs-descriptionclj

optsclj

parsecljmultimethod

specs-descriptionclj

as-float^clj

as-http^clj

as-int^clj

as-str^clj

errs-description^clj

opts^clj

parse^cljmultimethod

specs-description^clj