nl.jomco.envopts — nl.jomco/envopts 0.0.5

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.

as-float clj

(as-float s opt-spec)

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

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:[e-mail]" Invalid: "jomco.nl"

Returns [parsed] or [nil error].

as-int clj

(as-int s opt-spec)

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

as-str clj

(as-str s opt-spec)

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 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 clj multimethod

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

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