nl.jomco.envopts — nl.jomco/envopts 0.0.3

NAME

envopts - Clojure library for parsing configuration from environment

SYNOPSIS

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

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

specs

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

{:environment-key {:parser  envopts/as-str
                   :default some-value
                   :opt-key option-key}
 :other-key       ...}

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.

Options

Options are specified as a map of the following keys:

• :parser - parser function for expected type, one of the built-in parsers or your own (see below). The default is nl.jomco.envopts/as-str.
• :default - the default value for the option. If no default is specified, the key is required.
• :opt-key - the key to use for the parsed option in the configuration options map. The default is to use the same key as used in the specs map.

types

Since environment variables are always strings, you need a parser to convert an environment value into 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.

as-float clj

(as-float s)

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

as-http clj

(as-http s)

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

Valid: "https://jomco.nl/" Invalid: "mailto:[e-mail]" Invalid: "jomco.nl"

Returns [parsed] or [nil error].

as-int clj

(as-int s)

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

as-str clj

(as-str s)

Parses s as a string. Returns [s]

errs-description clj

(errs-description errs)

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

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 to option descriptions, one for every option. The full specification is in 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

specs-description clj

(specs-description specs)

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