Luoma - Ruby¶

Luoma is a modern template engine with a well-defined, composable, implementation agnostic expression language.

Luoma markup will be familiar to anyone who's used Liquid, Jinja or Django's template language, but with a strictly immutable data model, first-class blocks and expressions, and functional primitives for when data transformation is necessary.

If you're a template author, start with Luoma for template authors. The rest of this documentation covers how to install, configure, use and extend Luoma if you're an application developer.

Install¶

Add 'luoma' to your Gemfile:

gem 'luoma', '~> 0.1.0'

Or:

gem install luoma

Or:

bundle add luoma

Quick start¶

Render¶

Render a template by passing a string to Luoma.render(source, data = nil). If data is given it should be a hash mapping strings to objects. Hash values will be available as template variables bound to their associated keys.

require "luoma"

puts luoma.render("Hello, {{ you }}!", "you" => "World")  # Hello, World!

Luoma.render is a convenience method equivalent to Luoma::DEFAULT_ENVIRONMENT.parse(source).render(data).

Parse¶

Often you'll want to render the same template multiple times with different variables. We can parse source text without immediately rendering it using Luoma.parse(source, globals: nil). Luoma.parse returns an instance of Luoma::Template with a render(data)method.

require "luoma"

template = Luoma.parse("Hello, {{ you }}!")
puts template.render("you" => "World") # Hello, World!
puts template.render("you" => "Luoma") # Hello, Luoma!

If globals is given, data from globals is pined to the resulting template and merged into data from Luoma::Template#render every time the template is rendered, with render arguments taking priority over pinned data.

Luoma.parse is a convenience method equivalent to Luoma::DEFAULT_ENVIRONMENT.parse(source) or Luoma::Environment.new.parse(source).

Configure¶

Both Luoma.parse and Luoma.render are convenience functions that use the default Luoma environment. For all but the simplest of cases you'll want to configure your own instance of Luoma::Environment, then load and render templates from that.

require "luoma"

env = Luoma::Environment.new(
  loader: Luoma::CachingFileSystemLoader.new("templates/")
)

template = env.get_template("index.luoma")
another_template = env.parse("{% render 'index.luoma' %}")
# ...