keypin.core — keypin 0.8.0

Public API for the core functionality.

defkey clj macro

(defkey the-sym arg-vec & more)

Define one or more keys as defn vars using argument vectors, which could be invoked as (keydef store) to fetch the value of the key. Every argument vector must have one of the following arities:

[key]
[key options]
[key validator description]
[key validator description options]

Options

Kwarg	Description
:pred	Validator function (fn [value]) -> boolean - default fn just returns true
:desc	Description string for the config - default: "No description"
:lookup	Function to look the key up (details below) - default: lookup-key - ordinary key look up
:parser	The value parser fn (fn [key raw-value]) -> parsed-value, e.g. keypin.util/str->long
:default	Default value when key is not found (subject to validator, unspecified => no default value)
:sysprop	System property name that can override the config value (before parsing)
:envvar	Environment variable that can override the config value and system property (before parsing)
:source	Source or container (of reference type, e.g. atom/agent/promise etc.) of key/value pairs
:pre-xform	Middleware function (fn [option-map]) -> option-map used before key definition is created
:post-xform	Middleware function (fn [keypin.type.KeyAttributes]) -> keypin.type.KeyAttributes

The validator is a predicate (fn [parsed-value]) -> boolean that returns true for valid values, false otherwise.

First argument to defkey can optionally be a base option-map for all argument vectors.

Examples

(defkey
  ip   [:ip-address]
  port [:port #(< 1023 % 65535) "Server port" {:parser keypin.util/str->int :default 3000}])

(port {:port "3009"})  ; returns 3009
(port {})              ; returns 3000

(defkey
  {:lookup lookup-key}
  ip   ["server.ip.address"]
  port ["server.port" #(< 1023 % 65535) "Server port" {:parser keypin.util/str->int :default 3000}])

See: make-key

edn-file-io clj

Reader/writer for EDN files.

letval clj macro

(letval bindings & body)

Like let, except in which the left hand side is a destructuring map, right hand side is the argument to key finder. Beside symbols, the destructuring map optionally supports :defs (symbols bound to key finders) and :as keys.

Example

(letval [{:defs [foo bar] ; foo, bar are key finders
          baz baz-key     ; baz-key is a key finder
          :as m} {:foo 10 :bar 20 :baz 30}]
  ;; foo, bar and baz are now bound to values looked up in the map
  ...)

lookup-key clj

(lookup-key the-map
            the-key
            validator
            description
            value-parser
            default-value?
            default-value
            not-found)

Look up a key in an associative data structure - a map or something that implements clojure.lang.Associative.

lookup-keypath clj

(lookup-keypath the-map
                ks
                validator
                description
                value-parser
                default-value?
                default-value
                not-found)

Look up a key path in an associative data structure - a map or something that implements clojure.lang.Associative.

make-key clj

(make-key {:keys [the-key pred desc lookup parser default sysprop envvar source]
           :or {pred i/return-true
                desc "No description"
                lookup lookup-key
                parser i/identity-parser}
           :as options})

Create a key that can be looked up in a config store (keypin.type/IStore, java.util.Map, java.util.Properties or map/vector) instance.

Options

Kwarg	Description
:the-key	(Required) Key to be used for looking up value
:pred	Validator function (fn [value]) -> boolean - default fn just returns true
:desc	Description string for the config - default: "No description"
:lookup	Function to look the key up (details below) - default: lookup-key - ordinary key look up
:parser	The value parser fn (fn [key raw-value]) -> parsed-value, e.g. keypin.util/str->long
:default	Default value when key is not found (subject to validator, unspecified => no default value)
:sysprop	System property name that can override the config value (before parsing)
:envvar	Environment variable that can override the config value and system property (before parsing)
:source	Source or container (of reference type, e.g. atom/agent/promise etc.) of key/value pairs

Lookup function

(fn [store
     key
     validator
     description
     value-parser
     default-value?
     default-value
     not-found-handler]) -> value

;; validator is a predicate function: (fn [parsed-value]) -> boolean
;; not-found-handler is (fn [not-found-message]), called when the store does not have the key

See: lookup-key, lookup-keypath

property-file-io clj

Reader/writer for properties files.

read-config clj

(read-config config-filenames)

(read-config config-filenames
             {:keys [parent-key logger config-readers media-readers realize?]
              :or {parent-key "parent.filenames"
                   logger u/default-logger
                   config-readers [property-file-io edn-file-io]
                   realize? true}
              :as options})

Read config file(s) returning a java.util.Map instance.

Options

Kwarg	Type	Description	Default
:parent-key	string	key to identify the parent config filenames	"parent.filenames"
:logger	object	instance of keypin.Logger	prints to *err*
:config-readers	list/vec	collection of keypin.ConfigIO instances	for .properties, .edn files
:media-readers	list/vec	collection of keypin.MediaReader instances	for filesystem and classpath
:realize?	boolean	whether realize template variables in string	true

realize-config clj

(realize-config config)

(realize-config config
                {:keys [logger config-mapper]
                 :or {logger u/default-logger config-mapper Mapper/DEFAULT}
                 :as options})

Realize config by applying variable substitution, if any.

Options

Kwarg	Type	Description	Default
:logger	object	instance of keypin.Logger	prints to *err*
:config-mapper	object	instance of keypin.Mapper	keypin.Mapper/DEFAULT

write-config clj

(write-config config-filename config)

(write-config config-filename
              config
              {:keys [logger config-writers escape?]
               :or {logger u/default-logger
                    config-writers [property-file-io edn-file-io]
                    escape? true}
               :as options})

Write config to a specified file.

Options

Kwarg	Type	Description	Default
:logger	object	instance of keypin.Logger	prints to *err*
:config-writers	list/vec	collection of keypin.ConfigIO instances	for .properties, .edn files
:escape?	boolean	whether escape values when writing	true