Trenni

Trenni is a templating system built loosely on top of XHTML markup. It uses efficient native parsers where possible and compiles templates into efficient Ruby. It also includes a markup builder to assist with the generation of pleasantly formatted markup which is compatible with the included parsers.

Build Status Code Climate Coverage Status

Motivation

Trenni was designed for Utopia. When I originally looked at template engines, I was surprised by the level of complexity and the effort involved in processing a template to produce useful output. In particular, many template engines generate an AST and walk over it to generate output (e.g. ERB, at least at the time I last checked). This is exceedingly slow in Ruby.

At the time (around 2008?) I was playing around with ramaze and found a template engine I really liked the design of, called ezamar. The template compilation process actually generates Ruby code which can then be compiled and executed efficiently. Another engine, by the same author, nagoro, also provided some inspiration.

More recently I was doing some investigation regarding using eval for executing the code. The problem is that it's not possible to replace the binding of a Proc once it's created, so template engines that evaluate code in a given binding cannot use a compiled proc, they must parse the code every time. By using a Proc we can generate a Ruby function which can be compiled to a faster representation by the VM.

In addition, I wanted a simple markup parser and builder for HTML style markup. These are used heavily by Utopia for implementing it's tag based evaluation. Trenni::Builder is a simple and efficient way to generate markup, it's not particularly notable, except that it doesn't use method_missing to implement normal behaviour which is sort of slow.

The 2nd release of Trenni in 2016 saw an overhaul of the internal parsers. I used Ragel to implement efficient event-based markup and template parsers, which can be compiled to both C and Ruby. This provides a native code path where possible giving speed-ups between 10x - 20x. In addition, the formal grammar is more robust.

Is it fast?

It's faster than Nokogiri for parsing markup:

Trenni::Native
Warming up --------------------------------------
      Large (Trenni)    71.000  i/100ms
    Large (Nokogiri)    28.000  i/100ms
Calculating -------------------------------------
      Large (Trenni)    662.050  (± 3.9%) i/s -      3.337k in   5.048115s
    Large (Nokogiri)    266.878  (±10.9%) i/s -      1.316k in   5.008464s

Comparison:
      Large (Trenni):      662.1 i/s
    Large (Nokogiri):      266.9 i/s - 2.48x slower

It's significantly faster than ERB:

Trenni::Template
Warming up --------------------------------------
     Trenni (object)    75.667k i/100ms
       ERB (binding)     6.940k i/100ms
Calculating -------------------------------------
     Trenni (object)      1.095M (± 7.9%) i/s -      5.448M in   5.007244s
       ERB (binding)     69.381k (± 7.1%) i/s -    347.000k in   5.027333s

Comparison:
     Trenni (object):  1094979.9 i/s
       ERB (binding):    69381.1 i/s - 15.78x  slower

Installation

Add this line to your application's Gemfile:

gem 'trenni'

And then execute:

$ bundle

Or install it yourself as:

$ gem install trenni

Usage

Markup Parser

The markup parser parses a loose super-set of HTML in a way that's useful for content processing, similar to an XSLT processor. It's designed to be faster and easier to use, and integrate directly into an output pipeline.

To invoke the markup parser:

require 'trenni'

buffer = Trenni::Buffer(string)

# Custom entities, or could use Trenni::Entities::HTML5
entities = {'amp' => '&', 'lt', => '<', 'gt' => '>', 'quot' => '"'}

# Modify this class to accumulate events or pass them on somewhere else.
class Delegate
    # Called when encountering an open tag: `<` name
    def open_tag_begin(name, offset)
    end

    # Called when encountering an attribute after open_tag_begin
    def attribute(key, value)
    end

    # Called when encountering the end of the opening tag.
    def open_tag_end(self_closing)
    end

    # Called when encountering the closing tag: '</' name '>'
    def close_tag(name, offset)
    end

    # Called with the full doctype: '<!DOCTYPE html>'
    def doctype(string)
    end

    # Called with the full comment: '<!-- comment -->'
    def comment(string)
    end

    # Called with the parsed instruction: '<?' identifier space+ body '?>'
    def instruction(string)
    end

    # Called with a cdata block: '<![CDATA[text]]>'
    def cdata(string)
    end

    # Called with any arbitrary pcdata text (e.g. between tags).
    def text(string)
    end
end

# Do the actual work:
Trenni::Parsers.parse_markup(buffer, Delegate.new, entities)

Templates

Trenni templates work essentially the same way as all other templating systems:

buffer = Trenni::Buffer('<?r self.each do |item| ?>#{item}<?r end ?>')
template = Trenni::Template.new(buffer)

items = 1..4

template.to_string(items) # => "1234"

The code above demonstrate the only two constructs, <?r expression ?> and #{output}.

Trenni doesn't support using binding for evaluation, as this is a slow code path. It uses instance_exec

Builder

Trenni can help construct XML/HTML using a simple DSL:

Trenni::Builder.fragment do |builder|
    builder.inline 'p' do
        builder.tag 'strong' do
            builder.text 'Hello'
        end
        builder.text ' World'
    end
    builder.tag 'script', type: 'text/html' do
        builder.text 'console.log("Hello World")'
    end
end
# => "<p><strong>Hello</strong> World</p>\n<script type=\"text/html\">\n\tconsole.log(\"Hello World\")\n</script>"

Integration

There is a language-trenni package for the Atom text editor. It provides syntax highlighting and integration when Trenni is used with the utopia web framework.

Trenni Formatters is a separate gem that uses Trenni::Builder to generate HTML forms easily.

Testing

To test the Ruby parsers:

rake generate_fallback_parsers && TRENNI_PREFER_FALLBACK=y rspec

To test the native C parsers:

rake generate_native_parsers && rake compile && rspec

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

Released under the MIT license.

Copyright, 2012, 2016, by Samuel G. D. Williams.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.