Ash Ra Template

Expressive template system for Clojure.

Motivation: Of the Clojure templating libraries we identified, none seemed to assist in porting a non-trivial amount of ERB-templated content to a Clojure-based static site generation tool. We find the ability to in-line arbitrary Clojure code is intoxicatingly pragmatic (also expressed as: Enough rope to hang oneself). Seeking to wield such expressive power in a general-purpose templating system, we wrote Ash Ra Template, or ART.

Works with Clojure 1.9 and newer.

Components

ART library, including detailed information about using the ART library and ART template syntax, rendering API and options, and processing.

Boot task for rendering ART templates.

Leiningen plugin for rendering ART templates.

Quickstart

Include this library from Clojars by adding the latest version of vivid/ash-ra-template to your project dependencies, such as in a Leiningen project.clj:

    :dependencies [[vivid/ash-ra-template "0.4.0"]]

Render a template string:

(require [vivid.art :as art])

(art/render "There were <%= (+ 1 2) %> swallows, dancing in the sky.")

Or, to render from a file:

(art/render (slurp "prelude.html.art"))

Development

Pull Requests are welcome! We work with people offering PRs to revise and iterate leading to solutions in accord with project goals and release criteria. Commits must include Signed-off-by indicating acceptance of the Developer's Certificate of Origin. Unproductive behavior such as unkindness towards others and derailment is not tolerated.

The Path to Version 1.0

• ~Default to a subset of ERB syntax (as of Ruby 2.0). Accept alternative tag nomenclature :delimiters. Provide examples for Mustache, PHP, and others.~
• ~Accept an optional map of :bindings (definitions) that are made available for symbol resolution during render.~
• ~api-contract tests for :dependencies.~
• ~Automated testing on all supported versions of Clojure.~
• ~Boot task for rendering templates.~
• ~Leiningen plugin for rendering templates.~
• ~Document approach to quality assurance.~
• ~Stabilize minimal requirements of the project, including Clojure version and dependencies.~
• ~Expose a public API.~
• ~Documentation organized by project and use.~
• ~Test on the most recent releases of each significant JDK (8 and 11 at the time of this writing).~
• Explain the value of ART. Compare and contrast with other templating systems. Emphasize symbolic computation, and the importance of providing native idioms at each point along the value chain, for example a web-based production workflow where professionals handle HTML and CSS.
• Delimiter escaping rules.
• Clarify the mechanics of the template evaluation runtime: dependencies + default deps, requires.
• Provide examples for nesting templates (akin to yield).
• Fast runtime performance, fast test feedback.
• Sufficient error reporting + documentation.
• Java policies, to make it possible to execute untrusted / unknown code within templates.
• AOT compilation.
• Sign releases.
• Declare version 1.0.0 once the community deems the ART feature-complete, reliable, and properly documented.

Beyond Version 1.0

• Consider parsing option mode magic within template content.
• Consider an option to infer outer-most parens.
• JetBrains IDEA plugin providing support for .art files.
• Performance.

Attributions

• Original implementation by Vivid Inc.
• ShimDandy, boot-pods, clj-embed as reference material regarding the evaluation of Clojure code within a sandboxed runtime.
• Illustration by Ruxandra.
• The Boot test code initially mimicked perun-selmer.

License

© Copyright Vivid Inc. EPL licensed.