Skip to content

Latest commit

 

History

History
178 lines (125 loc) · 6.1 KB

README.md

File metadata and controls

178 lines (125 loc) · 6.1 KB
Raw

clj-art Ash Ra Template Clojure Tool

License Current version cljdoc

clj-art is a Clojure deps.edn tool for rendering Ash Ra Template .art templates.

Quick Start

$ cat oracle.art

<( (defn mult [multiplicands] (apply * multiplicands)) )>
Wait, I see it! Your destiny lies deep within the number <(= (mult mysterious-primes) )>.

$ cat deps.edn

{:aliases
  {:art {:extra-deps {net.vivid-inc/clj-art {:mvn/version "0.7.1"}}
         :main-opts  ["-m" "vivid.art.clj-tool"]}}}

$ clojure -A:art \
    --bindings "{mysterious-primes [7 191]}" \
    oracle.art

clj-art will render the output file oracle into the current directory.

You can also add the above alias to your personal ~/.clojure/deps.edn. You'll then be able to render ART templates using clojure at the CLI anywhere you desire.

$ clojure -A:art --help

Synopsis

clj-art is used with deps.edn.

Templates are supplied as one or more paths to .art template files and/or directory trees thereof. Those paths are scanned for all ART template files with the .art filename extension.

Templates are rendered and written under output-dir stripped of their .art filename extensions, overwriting any existing files with the same paths. output-dir and sub-paths therein are created as necessary.

Options

Argument Parameters Default Explanation
--bindings VAL Bindings made available to templates for symbol resolution. Currently limited to a single usage in clj-art.
--delimiters VAL lispy Template delimiters
--dependencies VAL Clojure deps map providing libs within the template evaluation environment.
-h, --help Displays lovely help and then exits
--output-dir DIR . Write rendered files to DIR
--to-phase One of: parse, translate, enscript, evaluate evaluate Stop the render dataflow on each template at an earlier phase
--watch-timeout-ms VAL 500 Trigger re-render once this timeout in milliseconds elapses, coalescing flurries of change to watched batches

Depending on what types of values a particular option accepts, ART attempts to interpret arguments in this order of precedence:

  1. As a map.
  2. As the (un-)qualified name of a var.
  3. As a path to an EDN file.
  4. As a path to a JSON file.
  5. As an EDN literal.

Cookbook

Custom bindings, delimiters, dependencies, and project code

{:aliases
 {:art {:extra-deps {net.vivid-inc/clj-art {:mvn/version "0.7.1"}}
        :main-opts  ["-m" "vivid.art.clj-tool"

                     ; Render all .art templates in the content/ directory
                     "content"

                     ; Map as a string
                     "--bindings" "{manufacturer,\"Acme,Corporation\",manufacture-year,\"2022\"}"
                     ; Var whose value is a map
                     "--bindings" "com.acme.data/product-data"
                     ; EDN as a string
                     "--bindings" "{current-year,2021}"
                     ; EDN file; top-level form is a map
                     "--bindings" "data/sales-offices.edn"
                     ; JSON file; file content is made available under the symbol 'partner-list
                     "--bindings" "data/partner-list.json"

                     ; Unqualified, resolves to #'vivid.art.delimiters/jinja
                     "--delimiters" "jinja"

                     "--dependencies" "{hiccup/hiccup,{:mvn/version,\"1.0.5\"}}"
                     "--to-phase" "enscript"
                     ; Render to the our/cdn/ directory
                     "--output-dir" "out/cdn"]}}}

Discussion: Template syntax is set by the :delimiters options. Clojure forms within the templates can resolve vars and dependencies provided by several factors: :bindings for resolving vars, :dependencies for libraries, and code in the project.

See also: Example. Rendering and options in the ART documentation.

Use space characters in arguments within deps.edn

Discussion: When supplying double-quoted parameters to options in your deps.edn file, spaces must be replaced with comma ',' characters.

  "--dependencies" "{hiccup/hiccup {:mvn/version \"1.0.5\"}}"    ; Bad, will fail

  "--dependencies" "{hiccup/hiccup,{:mvn/version,\"1.0.5\"}}"    ; OK

This mangling is idiosyncratic to deps.edn. clj-art invoked at the command line obediently accepts the plain form:

$ clojure -m vivid.art.clj-tool \
    "--dependencies" "{hiccup/hiccup {:mvn/version \"1.0.5\"}}"    ; OK
    ...

See also: Example.

Configure multi-batch rendering in deps.edn

{:aliases
  {:rndr-a {:extra-deps {net.vivid-inc/clj-art {:mvn/version "0.7.1"}}
            :main-opts  ["-m" "vivid.art.clj-tool" "src/templates/css"
                         "--dependencies" "{garden/garden,{:mvn/version,\"1.3.10\"}}"
                         "--output-dir" "src/resources"]}
   :rndr-b {:extra-deps {net.vivid-inc/clj-art {:mvn/version "0.7.1"}}
            :main-opts  ["-m" "vivid.art.clj-tool" "src/templates/java"
                         "--bindings" "{version,\"1.2.3\"}"
                         "--output-dir" "target/generated-sources/java"]}}}

Discussion: Each individual render batch is assigned its own unique key under :aliases, in this example aliases rndr-a and rndr-b. As deps.edn is not a build tool, but instead focuses on dependency resolution and the running of a single entry point, we are able to run any one batch:

$ clojure -A:rndr-a

See also: Example.

License

© Copyright Vivid Inc. and/or its affiliates. Apache License 2.0 licensed.