Ecology

Simple 12-factor application configuration in Common Lisp

Usage

This library exposes a defconfig macro which exposes a simple interface to pull in information from the programs environment. At the moment, only shell environment variables are implemented

At the moment, only env and default configuration resolvers exist. As I need them, I'll probably add more.

The defconfig macro

This is how configurations are created. The general syntax is as follows:

(ecology:defconfig (:prefix config-)
  (CONFIG_NAME :ENV "ENV_VAR" 
               :DEFAULT "default_value" 
               :KEY #'identity))

This will result in a config-home function the will return the value of $HOME at runtime.

(ecology:defconfig nil
  (home :env "HOME"))

(format t "My user's home is at the path \"~a\".~%" (config-home))
;; => My user's home is at the path "/home/mike".

Multiple configurations can be defined like so:

(ecology:defconfig nil
  (home :env "HOME")
  (user :env "USER")
  (editor :env "EDITOR"))

(config-home)
;; => "/home/mike"
(config-editor)
;; => "nvim"

Default values can be set with the default parameter. This can be set to any value.

(ecology:defconfig nil
  (missing-var :env "MISSING_VAR" :default "found_it!")
  (should-be-two :env "MISSING_TWO_VAR" :default (+ 1 1))
  (json-value :default (uiop:run-program (list "jq" "-r" ".json_key" "foo.json")
                         :output '(:string :stripped t)
                         :error-output '(:string :stripped t))))

(config-missing-var)
;; => "found_it!"
(config-should-be-two)
;; => 2

The prefix for the functions generated by defconfig are configurable:

(ecology:defconfig (:prefix eco-conf-)
  (home :env "HOME"))

(eco-conf-home)
;; => "/home/mike"

You can reference other configuration parameters:

(defconfig nil
    (int-var :default "3" :key (lambda (x) (parse-integer x)))
    (reference-var :default (* 2 (config-int-var))))

(config-reference-var)
;; => 6

There's a key parameter, which can help with general conversions on the value returned

(ecology:defconfig nil
  (nproc
    :default (uiop:run-program "nproc" :output '(:string :stripped t))
    :key (lambda (v) (parse-integer v))))

(config-nproc)
;; => 16 2

Installation

The easiest way to install is with roswell

$ ros install michaeldelago/ecology
# or if you're using qlot
$ qlot exec ros install michaeldelago/ecology

Author

• Mike Delago

Copyright

Copyright (c) 2023 Mike Delago

License

Licensed under the bsd-0 License.