Reading per-tool configuration files
Clojure tools need a well-known place to store user and project configuration. This library defines that place and provides functions for reading the files stored there. Writing them is provided by tools.deps.config.edit.
The two are separate to isolate dependencies needed for writing but not reading.
TBD
Tools are identified by a qualified lib symbol (e.g., my.org/my-tool). Tool
config files live under a .cli-config directory at one of two locations:
:user- the user config dir shared by all of a user's projects:project- the project dir specific to a single project
Under .cli-config each tool has two well-known paths: a config file of
settings and a data directory for any other files the tool needs. This
library reads the config file. For the data directory, it manages the
location and the tool manages the contents. A tool may use either or
both. The examples below assume:
(require '[clojure.tools.deps.config :as dc])The config file lives at <location>/.cli-config/<lib-ns>/<lib-name>.edn
and is expected to contain a 1-level map with keyword keys.
(config lib & {:keys [defaults overrides]}) - read and merge in order :defaults < user config < project config < :overrides
;; With a user config file of {:color :dark}
;; and a project config file of {:width 120}:
(dc/config 'my.org/my-tool
:defaults {:color :auto :width 80 :timeout 30 :silent false}
:overrides {:silent true})
;; => {:color :dark, :width 120, :timeout 30, :silent true}(read-config location lib) - read the config file at a single location, returns its value or nil
;; The value of <user-config-dir>/.cli-config/my.org/my-tool.edn
(dc/read-config :user 'my.org/my-tool)
;; => {:color :dark}(config-file location lib) - return the config file as a java.io.File
(dc/config-file :user 'my.org/my-tool)
;; => java.io.File at <user-config-dir>/.cli-config/my.org/my-tool.ednFor additional needs beyond the config map, each tool has a well-known data
directory at <location>/.cli-config/<lib-ns>/<lib-name>/. The directory
can hold any files in any format. The following functions hand you the paths
and the tool is in charge of managing the contents.
(data-dir location lib) - return the tool's data directory as a java.io.File
(dc/data-dir :user 'my.org/my-tool)
;; => java.io.File at <user-config-dir>/.cli-config/my.org/my-tool(data-file location lib path) - return a java.io.File at path within the tool's data directory
(dc/data-file :user 'my.org/my-tool "prompt.clj")
;; => java.io.File at <user-config-dir>/.cli-config/my.org/my-tool/prompt.cljCopyright © Rich Hickey and contributors
All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 which can be found in the file LICENSE at the root of this distribution. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software.