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

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

# 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]].