Skip to content

Latest commit

 

History

History
205 lines (143 loc) · 7 KB

README.md

File metadata and controls

205 lines (143 loc) · 7 KB
Raw

lein-art Ash Ra Template Leiningen Plugin

License Current version cljdoc

lein-art is a Leiningen plugin 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 project.clj

(defproject rndr "1.2.3"
  :plugins [[net.vivid-inc/lein-art "0.7.1"]]
  :art {:bindings   "{mysterious-primes [7 191]}"
        :templates  "oracle.art"
        :output-dir "."})

$ lein art

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

You can also add lein-art to your ~/.lein/profiles.clj

{:user {:plugins [[net.vivid-inc/lein-art "0.7.1"]]}}

You'll then be able to render ART templates using lein at the CLI anywhere you desire.

$ lein art --help

Synopsis

lein-art can be used with Leiningen project.clj and at the CLI.

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

project.clj CLI argument Parameters Default Explanation
:bindings --bindings VAL Bindings made available to templates for symbol resolution
:delimiters --delimiters VAL lispy Template delimiters
:dependencies --dependencies VAL Clojure deps map providing libs within the template evaluation environment.
-h, --help Displays lovely help and then exits
:output-dir --output-dir DIR . Write rendered files to DIR
:templates [FILES] VAL Paths to ART template files
:to-phase --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 and whether lein-art was invoked as a Leiningen configuration or from the CLI, 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

NOTE: THIS deps.edn EXAMPLE IS INCOMPLETE The authors so far don't know how to specify a Var that is defined within src/. For the sake of completeness, its value is copy & pasted into the example below in place of the var.

; Render all .art template files in the content/ directory to out/cdn/
(defproject art-example-custom-options "0"

  :plugins [[net.vivid-inc/lein-art "0.7.1"]]

  ; Render all .art template files in the content/ directory to out/cdn/
  :art {:templates    "content"

        :bindings     [{manufacturer     "Acme Corporation"    ; Map literal
                        manufacture-year "2022"}

                       ; (See note above)
                       ;#'com.acme.data/widget                 ; Var, value is a map
                       {products [{:name               "Bag of bird seed"
                                    :weight-kgs         1.0
                                    :minimum-order-qty  50
                                    :unit-price-dollars 0.39M}
                                   {:name               "Ironing board on rollerskates"
                                    :weight-kgs         2.0
                                    :minimum-order-qty  10
                                    :unit-price-dollars 17.95M}]}

                       "{current-year 2021}"                   ; EDN as a string
                       "data/sales-offices.edn"                ; EDN file; top-level form is a map
                       "data/partner-list.json"]               ; JSON file; file content is made available under the symbol 'partner-list


        :delimiters   "jinja"                                  ; Resolves to #'vivid.art.delimiters/jinja

        :dependencies {hiccup/hiccup {:mvn/version "1.0.5"}
                       ; Give templates use of project code.
                       art-example-custom-options {:mvn/version "LATEST"
                                               :local/root "."}}

        :output-dir   "out/cdn"})

Install the project code as a Jar into your local .m2 repository and then render the ART templates, perhaps as a Leiningen alias:

$ lein do clean, install, art
...
Rendering ART catalog/index.html
$ diff -r expected/ 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.

Re-render templates whenever they change in a Leiningen project

$ cat project.clj
(defproject art-example--watch "0"

  ; ART template batch configuration
  :art {:templates    "resources"
        :output-dir   "target"}

  :plugins [[net.vivid-inc/lein-art "0.7.1"]])  ; Render ART templates with lein-art

$ lein art watch
Press CTRL-C to interrupt watch
Rendering ART resources/...
...
Watching resources/...

Discussion: With the CLI command watch, ART will monitor .art template files in all batches. Whenever such a file changes, ART will re-render it. watch is especially useful when you are doing development work.

See also: Example.

Configure multi-batch rendering in project.clj

  ; Two ART render batches are defined here:
  :art [
    ; An ART render batch configuration
    {:templates    "src/templates/css"
     :dependencies {garden/garden {:mvn/version "1.3.10"}}
     :output-dir   "src/resources"}

    ; Another, different batch
    {:templates  ["src/templates/java"]
     :bindings   {version "1.2.3"}
     :output-dir "target/generated-sources/java"}]

Discussion: Several ART render batches can be specified as a section in `project.clj':

See also: Example.

License

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