render

big-config.render

BigConfig Render is a template engine based on yogthos/Selmer inspired by seancorfield/deps-new. Its naming conventions are heavily influenced by deps-new.

A minimal template consists of a resource directory, a target, and a transformation:

{::render/templates [{:template "resource-path"
                      :target-dir "target"
                      :transform [["."]]}]}

By default, render copies the contents of the source folder to the :target-dir and replaces any {{key-a}} strings with the corresponding :key-a value from the data map. These substitutions occur in the source and destination filenames, as well as within the file content itself.

• deps-new documentation can be used for reference. BigConfig version extends deps-new while attempting to minimize the breaking changes.

This documentation is created using BigConfig, quickdoc, selmer, and render:

(defn prepare [opts]
  (merge opts (ok) {::render/templates [{:template "quickdoc"
                                         :target-dir "../docs/api"
                                         :overwrite true
                                         :transform [["."]]}]}))
(let [wf (->workflow {:first-step ::start
                      :wire-fn (fn [step _]
                                 (case step
                                   ::start [prepare ::render]
                                   ::render [render/render ::end]
                                   ::end [identity]))})]
  (wf {}))

List of maps

• opts map: The BigConfig map threaded through the workflow steps.
• data map: The context passed to yogthos/Selmer (unless the :raw option is used).
• edn map: In deps-new, this is a physical file called template.edn. While adapting it to BigConfig, the name stuck, though it is now simply a map containing high-level rendering configuration.
• transform map: Detailed configuration used to transform template files into target files.
• files map: The mapping between template files and target files, including renaming rules.
• delimiters map: Custom opts for yogthos/Selmer if the template files delimiters conflicts with Selmer’s default.
• transform-opts map: Includes :only and :raw (see below).

Options for opts

• :big-config.render/templates (required): A seq of edn maps.
• :big-config.step/module (optional): Borrowed from weavejester/integrant. Used in monorepos to identify subprojects; available in data.
• :big-config.step/profile (optional): Similar to module, but to identify environments (e.g., prod, dev).

Options for data

• :module: Populated automatically from :big-config.step/module.
• :profile: Populated automatically from :big-config.step/profile.

Note: All the other keys must be created via data-fn or defined in the edn map.

Options for edn

• template (required): A resource path containing the template files. Using a resource path instead of a folder ensures workflows remain portable when used as dependencies.
• target-dir (required): The directory where the templates are generated. (e.g., .dist in the current working directory).
• transform (required): a seq of programmatic transformations.
• overwrite (optional): Accepts true or :delete, mirror deps-new behavior.
• data-fn (optional): A function called with data and opts. It must return the original or a modified data map.
• template-fn (optional): A function called with data and edn. It must return the original or a modified edn map.
• post-process-fn (optional): a function (or sequence of functions) invoked, after copying all the template files to the target, with edn and data.

Note: Additional keys of the edn map are copied to the data map automatically.

Transformation Structure

The transform key is a seq of tuples following this schema: [src target files delimiters transform-opts]. The src, target, and files values are rendered with yogthos/Selmer.

src

Can be a folder or a function/symbol. If it is a function, it is invoked with every key in the files map. The function is invoke with key and data.

{:transform
 [['ansible/render-files
   {:inventory "inventory.json"
    :config "default.config.yml"}
   :raw]]}

target, files, delimiters

{:transform
 ["src" "target"
  {"config.json" "config.json"}
  {:tag-open \<
   :tag-close \>
   :filter-open \<
   :filter-close \>}]}

transform-opts

• :only: By default, the entire folder is copied. Use :only as the last element of the tuple to copy only specified files and ignore the rest.

{:transform
 [["src" "src/{{data-key-a}}"
   {"main.clj" "{{data-key-b|selmer-filter:param-a:param-b}}.clj"}]
 ["test" "test/{{data-key-b}}"
   {"main_test.clj" "{{data-key-c}}_test.clj"}
   :only]]}

• :raw: Use this to suppress Selmer rendering for a specific directory.

{:transform
 [["resources" "resources/{{data-key-a}}"]
  ["templates" "resources/{{data-key-b}}/templates" :raw]]}

*non-replaced-exts*

The default list of extensions that are considered binary files and therefore copied verbatim. jpg jpeg png gif bmp bin.

_Source

render

(render opts)

Function.

This is the functional version of the template engine. See the big-config.render namespace for more information.

_Source

templates

(templates)
(templates opts)
(templates step-fns opts)
(templates [opts])
(templates step-fns [opts])

Function.

This is the workflow version of the template engine. See the big-config.render namespace for more information.

_Source