Stencil

== Stencil === Free text templating system

Stencil is a templating system designed with a free text target in mind, and built around encouraging a separation of concerns. To that end, Stencil templates don't embed arbitrary Ruby, don't assume their output will be HTML, CSS or XML, and don't use any Ruby variable as a source.

Admittedly, the goals and design of Stencil are probably idiosyncratic, but they do reflect needs I had, and I figured someone else might want something similar.

Stencil is structured around data supplied in the form of hashes and arrays. Data is referenced using a reasonably compact (even terse) path. Recognizing that usually, data comes from disparate sources, there's a module that can be included into an object to smoothly extract a view or subview suitable for rendering.

Once views have been extracted, there's an RSpec matcher 'has_subview' that allows the details of a view to be tested easily.

Stencils directives are defined using a reasonably straightforward sub-classing design, and it's my experience that it's reasonably painless to add new directives.

Stencil also provides dynamic templates, that allow for output like JSON or XML from hashes and arrays. They can be applied within a normal template.

Stencil provides a number of pretty straightforward directives:

• [;= ;] will interpolate the data referred to by the path. Methods on the data can be called, but by design, Ruby constants and Kernel methods aren't available.
• [;if ;] works similarly to [;=;]
• [;each ;] for simple loops
• [;with ;] a common use case: make sure that a value exists, and assign it to the current context
• [;/;] or [;end;] terminates if, each and with. For convenience [;/ 3;] will dig out of 3 levels of nesting.
• [;apply ;] Apply a dynamic template
• [;include ;] Because templates should be able to include each other.

Some oddball directives, available by inclusion only,

• [;indent ;] (depth can come from a reference) - lets you indent text, per line
• [;wrap ;] Allow lines to be wrapped to a particular size.
• [;fcolor "red";] Terminal escapes to change text color
• [;bcolor "blue";] Terminal escapes for the background color
• [;bold;] [;inverse;] [;underline;] All terminal escapes
• [;nl;] Is the same as "\n", just a little prettier.

Stencil allows whitespace between the directive delimiters ([; ;]) and the directives themselves, which means that templates can be laid out more readably without wrecking the layout of the final output. (e.g. [; if true ;])

The directive delimiters were chosen first because they don't collide with any output I could think of, are easy to parse, an are quick to type. The end-of-block code: [;/;] is typed all without modifier (no shift) with one hand. It might sound weird, but I've come to really like it.

Templates can be defined in strings, or loaded from a path.