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

{: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]}

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

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

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 same key as 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]].