Sebastian's Gopherspace (HTTP Gateway)

Introduction
------------------------------------------------------------
 
confick is a tiny library to load and cache configuration
data from an EDN [1] file.
 
 
Installation
------------------------------------------------------------
 
This library can be installed from Clojars [2].
 
 
Example
------------------------------------------------------------
 
Given the following config.edn:
 
  {:tcp {:address "localhost"
         :port 8080}}
 
The complete configuration can be loaded with gulp,
individual values with lookup, or several values with bind:
 
  (require '[confick.core :as confick])
 
  ;; load the complete configuration
  (confick/gulp)
  ;; => {:tcp {:address "localhost", :port 8080}}
 
  ;; receive a mandatory configuration value
  (confick/lookup [:tcp :address] :required true)
  ;; => "localhost"
 
  ;; destructure configuration values in a let-like
  ;; binding
  (confick/bind [{:keys [address port]} :tcp]
    (format "%s:%d" address port))
  ;; => "localhost:8080"
 
  ;; use metadata for required values, defaults, and
  ;; validation
  (confick/bind
    [^:required addr [:tcp :address]
     ^{:default 80 :conform nat-int?} port [:tcp :port]]
    (println (format "%s:%d" addr port)))
 
  ;; force the next access to reload the configuration
  ;; file
  (confick/clear-cache!)
 
Configuration keys used with lookup and bind must be simple
values, such as keywords or strings. Collections such as
vectors, lists, maps, or sets are not supported as keys.
Nested maps remain accessible by passing a sequence of
simple keys as the configuration path.
 
 
Resolvable EDN values
------------------------------------------------------------
 
Configuration files support tagged literals for values that
are resolved when they are loaded through confick.core:
 
  {:database {:host "localhost"
              :password #env :database-password}
   :certificate #slurp "/run/secrets/certificate.pem"}
 
#env reads an environment variable or Java system property.
The keyword follows environ's naming conventions; for
example, :database-password corresponds to
DATABASE_PASSWORD.
 
#slurp reads the file at the given path and trims
surrounding whitespace from its contents. Relative paths are
resolved from the application's working directory.
 
If an environment variable or file does not exist, lookup
and bind treat the value as missing: optional values return
nil, defaults are applied, and required values cause an
exception.
 
gulp, lookup, and bind resolve these values automatically.
The lower-level confick.edn API keeps reading and resolving
as separate operations:
 
  (require '[confick.edn :as edn])
 
  (-> "{:password #env :database-password}"
      edn/read-string
      edn/resolve-vals)
 
In addition to standard EDN tagged literals such as #inst
and #uuid, confick supports #env and #slurp. Application-
defined tagged literal readers cannot be registered with
confick's EDN reader.
 
 
Configuration
------------------------------------------------------------
 
The default relative path of the configuration file is
"config.edn". It can be overridden with the CONFICK_PATH
environment variable or the confick.path Java system
property:
 
  CONFICK_PATH=/etc/my-app/config.edn java -jar my-app.jar
  java -Dconfick.path=/etc/my-app/config.edn -jar my-app.jar
 
If the configuration file does not exist, confick uses an
empty configuration map.
 
Configuration is cached for 60 seconds by default. Set
CONFICK_CACHE_MILLIS to a different duration in
milliseconds, or to zero to disable caching. The equivalent
Java system property is confick.cache.millis:
 
  CONFICK_CACHE_MILLIS=30000 java -jar my-app.jar
  java -Dconfick.cache.millis=0 -jar my-app.jar
 
 
References
------------------------------------------------------------
[1]: EDN
[2]: Clojars
 
 
Links
------------------------------------------------------------
main.zip
GitHub