luoma 0.1.0

data/docs/template_loaders.md

@@ -0,0 +1,177 @@
+# Template loaders
+
+A template loader is responsible for finding template source text given a name or identifier and will be called upon `Luoma::Environment#get_template` or by tags such as `{% render %}` and `{% include %}`. When a template can not be found, a `Luoma::TemplateNotFoundError` or `Luoma::NoSuchTemplateError` is thrown.
+
+Every `Luoma::Environment` has exactly one configured template loader, the default of which is an empty `Luoma::HashLoader`, meaning `Environment#get_template`, `{% render %}` and `{% include %}` will always throw an error.
+
+!!! info
+
+    Both `NoSuchTemplateError` and `TemplateNotFoundError` inherit from `Luoma::LuomaError`. The former is a detailed error including diagnostic information about where in the parent template `{% render %}`, `{% include %}` or `{% import %}` was called.
+
+    `NoSuchTemplateError` does not include diagnostic information. It is thrown by template loaders and surfaces when there is no parent template available, like when calling `Environment#get_template` directly.
+
+## Built-in loaders
+
+### `HashLoader`
+
+`Luoma::HashLoader` is a template loader that stores template source code in a hash, mapping strings to strings. Hash keys are template names and values are template source code.
+
+```ruby
+require "luoma"
+
+loader = Luoma::HashLoader.new(
+  "index" => "This is the index. {% render 'section' %}",
+  "section" => "Hi!"
+)
+
+env = Luoma::Environment.new(loader: loader)
+
+template = env.get_template("index")
+puts template.render
+```
+
+### `FileSystemLoader`
+
+`Luoma::FileSystemLoader` is a template loader that reads template source text from files on a file system.
+
+`FileSystemLoader.new` accepts a path or array of paths to search for files containing template source code. The `default_extension` keyword argument is a default file extension appended to the template name if it does not already have an extension.
+
+```ruby
+require "luoma"
+
+loader = Luoma::FileSystemLoader.new(
+  "./templates",
+  default_extension: ".luoma"
+)
+
+env = Luoma::Environment.new(loader: loader)
+
+# Look for `index.luoma` in the `templates` folder relative to the
+# current working directory.
+template = env.get_template("index")
+```
+
+### `CachingFileSystemLoader`
+
+`Luoma::CachingFileSystemLoader` is similar to `FileSystemLoader`, but caches parsed templates in an in-memory, least recently used (LRU) cache. The default cache size is 300 templates.
+
+```ruby
+require "luoma"
+
+loader = Luoma::CachingFileSystemLoader.new(
+  "./templates",
+  default_extension: ".luoma",
+  capacity: 500
+)
+
+env = Luoma::Environment.new(loader: loader)
+
+# Look for `index.luoma` in the `templates` folder relative to the
+# current working directory.
+template = env.get_template("index")
+
+# Get's cached `Luoma::Template` instance.
+same_template = env.get_template("index")
+```
+
+### `ChoiceLoader`
+
+`Luoma::ChoiceLoader` is a template loader that delegates to other template loaders. Given an array of `Luoma::TemplateLoader` instances, `ChoiceLoader` will try each in turn until a template is found.
+
+```ruby
+require "luoma"
+
+fallback_loader = Luoma::HashLoader.new(
+  "layout" => "A default layout {% include content %}"
+)
+
+dynamic_loader = Luoma::CachingFileSystemLoader.new(
+  "./templates",
+  default_extension: ".luoma",
+  capacity: 500,
+  auto_reload: true
+)
+
+env = Luoma::Environment.new(
+  loader: Luoma::ChoiceLoader.new([dynamic_loader, fallback_loader])
+)
+
+# Look for `layout.luoma` first, fallback to the hash loader if it
+# does not exist.
+template = env.get_template("layout")
+```
+
+## Custom loaders
+
+You are encouraged to write you own template loaders to read templates from a database or process front-matter, for example. Simply extend `Luoma::TemplateLoader` and implement `#get_source`.
+
+```ruby title="Method signature"
+def get_source: (
+  Luoma::Environment env,
+  ::String name,
+  ?context: Luoma::RenderContext? context,
+  **untyped kwargs
+) -> Luoma::TemplateSource
+```
+
+This example implements a simple front matter loader, which reads data from the start of a file and template source text from the rest.
+
+```ruby
+require "luoma"
+require "yaml"
+
+class FrontMatterLoader < Luoma::CachingFileSystemLoader
+  RE_FRONT_MATTER = /\A\s*---\s*(.*?)\s*---\s*/m
+
+  def get_source(env, name, context: nil, **)
+    template_meta = super
+    match = RE_FRONT_MATTER.match(template_meta.source)
+
+    return template_meta unless match
+
+    # TODO: YAML error handling and validation.
+    template_meta.matter = YAML.load(match[1])
+    template_meta.source = template_meta.source.slice(match[0].length..)
+  end
+end
+```
+
+## Load context
+
+Sometimes a template's name alone is not enough to identify the correct source text. For such cases, `TemplateLoader#get_source` accepts optional `context` and `kwargs` to help narrow the template search space.
+
+`context` will be set to the current `Luoma::RenderContext`, if one is available. `context` will always be `nil` when calling `Luoma::Environment#get_template` directly, as a render context does not yet exist.
+
+`kwargs` is an arbitrary mapping of strings to unknown objects. You can use this to bootstrap the loading sequence at parse time by passing arguments to `Environment#get_template`.
+
+By convention, built-in tags that load partial templates - `{% include %}`, `{% render %}` and `{% import %}` - set a `tag` keyword argument to the tag name (`"include"`, `"render"` and `"import"`, respectively), so you know what is tying to load a template. We could use this convention to mimic Shopify's "snippets" convention, where `{% include %}` and `{% render %}` implicitly look in a `snippets` subfolder.
+
+## Caching loaders
+
+The recommended way to implement template caching is to override `Luoma::TemplateLoader#load`. `load` delegates to `get_source` and calls back to `Environment#parse`, providing a convenient hook into the template loading process.
+
+Luoma includes `Luoma::CachingLoaderMixin`, a mixin module that adds an LRU cache to template loaders. We could implement a caching version of [`HashLoader`](#hashloader) as follows.
+
+```ruby
+require "luoma"
+
+class CachingHashLoader < Luoma::HashLoader
+  include CachingLoaderMixin
+
+  def initialize(
+    templates,
+    namespace_key: "",
+    capacity: 300,
+    thread_safe: false
+  )
+    super(templates)
+
+    initialize_cache(
+      auto_reload: false,
+      namespace_key: namespace_key,
+      capacity: capacity,
+      thread_safe: thread_safe
+    )
+  end
+end
+```

data/docs/undefined_variables.md

@@ -0,0 +1,3 @@
+# Undefined variables
+
+TODO:

data/docs-requirements.txt

@@ -0,0 +1,11 @@
+click==8.4.2
+deepmerge==2.1.0
+Jinja2==3.1.6
+Markdown==3.10.2
+MarkupSafe==3.0.3
+Pygments==2.20.0
+pygments-liquid2==0.2.0
+pymdown-extensions==11.0.1
+PyYAML==6.0.3
+tomli==2.4.1
+zensical==0.0.51

data/docs_/cycle.md

@@ -0,0 +1,17 @@
+
+Old:
+
+```
+{% cycle "some", "thing" %}
+{% cycle "some", "thing" %}
+{% cycle "some", "thing" %}
+```
+
+```title="output"
+some
+thing
+some
+```
+
+New:
+

data/docs_/font_rendering_example.md

@@ -0,0 +1,157 @@
+Old:
+
+```
+{%- liquid
+  assign rendered_fonts = ''
+
+  assign primary_font = settings.type_body_font
+  assign primary_font_bold = primary_font | font_modify: 'weight', 'bold'
+  assign primary_font_italic = primary_font | font_modify: 'style', 'italic'
+  assign primary_font_bold_italic = primary_font_bold | font_modify: 'style', 'italic'
+
+  assign primary_font_face_id = '[primary_font_family]-[primary_font_weight]-[primary_font_style]|' | replace: '[primary_font_family]', primary_font.family | replace: '[primary_font_weight]', primary_font.weight | replace: '[primary_font_style]', primary_font.style
+  assign primary_font_bold_face_id = '[primary_font_bold_family]-[primary_font_bold_weight]-[primary_font_bold_style]|' | replace: '[primary_font_bold_family]', primary_font_bold.family | replace: '[primary_font_bold_weight]', primary_font_bold.weight | replace: '[primary_font_bold_style]', primary_font_bold.style
+  assign primary_font_italic_face_id = '[primary_font_italic_family]-[primary_font_italic_weight]-[primary_font_italic_style]|' | replace: '[primary_font_italic_family]', primary_font_italic.family | replace: '[primary_font_italic_weight]', primary_font_italic.weight | replace: '[primary_font_italic_style]', primary_font_italic.style
+  assign primary_font_bold_italic_face_id = '[primary_font_bold_italic_family]-[primary_font_bold_italic_weight]-[primary_font_bold_italic_style]|' | replace: '[primary_font_bold_italic_family]', primary_font_bold_italic.family | replace: '[primary_font_bold_italic_weight]', primary_font_bold_italic.weight | replace: '[primary_font_bold_italic_style]', primary_font_bold_italic.style
+
+  assign secondary_font = settings.type_subheading_font
+  assign secondary_font_bold = secondary_font | font_modify: 'weight', 'bold'
+  assign secondary_font_italic = secondary_font | font_modify: 'style', 'italic'
+  assign secondary_font_bold_italic = secondary_font_bold | font_modify: 'style', 'italic'
+
+  assign secondary_font_face_id = '[secondary_font_family]-[secondary_font_weight]-[secondary_font_style]|' | replace: '[secondary_font_family]', secondary_font.family | replace: '[secondary_font_weight]', secondary_font.weight | replace: '[secondary_font_style]', secondary_font.style
+  assign secondary_font_bold_face_id = '[secondary_font_bold_family]-[secondary_font_bold_weight]-[secondary_font_bold_style]|' | replace: '[secondary_font_bold_family]', secondary_font_bold.family | replace: '[secondary_font_bold_weight]', secondary_font_bold.weight | replace: '[secondary_font_bold_style]', secondary_font_bold.style
+  assign secondary_font_italic_face_id = '[secondary_font_italic_family]-[secondary_font_italic_weight]-[secondary_font_italic_style]|' | replace: '[secondary_font_italic_family]', secondary_font_italic.family | replace: '[secondary_font_italic_weight]', secondary_font_italic.weight | replace: '[secondary_font_italic_style]', secondary_font_italic.style
+  assign secondary_font_bold_italic_face_id = '[secondary_font_bold_italic_family]-[secondary_font_bold_italic_weight]-[secondary_font_bold_italic_style]|' | replace: '[secondary_font_bold_italic_family]', secondary_font_bold_italic.family | replace: '[secondary_font_bold_italic_weight]', secondary_font_bold_italic.weight | replace: '[secondary_font_bold_italic_style]', secondary_font_bold_italic.style
+
+  assign tertiary_font = settings.type_heading_font
+  assign tertiary_font_bold = tertiary_font | font_modify: 'weight', 'bold'
+  assign tertiary_font_italic = tertiary_font | font_modify: 'style', 'italic'
+  assign tertiary_font_bold_italic = tertiary_font_bold | font_modify: 'style', 'italic'
+
+  assign tertiary_font_face_id = '[tertiary_font_family]-[tertiary_font_weight]-[tertiary_font_style]|' | replace: '[tertiary_font_family]', tertiary_font.family | replace: '[tertiary_font_weight]', tertiary_font.weight | replace: '[tertiary_font_style]', tertiary_font.style
+  assign tertiary_font_bold_face_id = '[tertiary_font_bold_family]-[tertiary_font_bold_weight]-[tertiary_font_bold_style]|' | replace: '[tertiary_font_bold_family]', tertiary_font_bold.family | replace: '[tertiary_font_bold_weight]', tertiary_font_bold.weight | replace: '[tertiary_font_bold_style]', tertiary_font_bold.style
+  assign tertiary_font_italic_face_id = '[tertiary_font_italic_family]-[tertiary_font_italic_weight]-[tertiary_font_italic_style]|' | replace: '[tertiary_font_italic_family]', tertiary_font_italic.family | replace: '[tertiary_font_italic_weight]', tertiary_font_italic.weight | replace: '[tertiary_font_italic_style]', tertiary_font_italic.style
+  assign tertiary_font_bold_italic_face_id = '[tertiary_font_bold_italic_family]-[tertiary_font_bold_italic_weight]-[tertiary_font_bold_italic_style]|' | replace: '[tertiary_font_bold_italic_family]', tertiary_font_bold_italic.family | replace: '[tertiary_font_bold_italic_weight]', tertiary_font_bold_italic.weight | replace: '[tertiary_font_bold_italic_style]', tertiary_font_bold_italic.style
+
+  assign accent_font = settings.type_accent_font
+  assign accent_font_bold = accent_font | font_modify: 'weight', 'bold'
+  assign accent_font_italic = accent_font | font_modify: 'style', 'italic'
+  assign accent_font_bold_italic = accent_font_bold | font_modify: 'style', 'italic'
+
+  assign accent_font_face_id = '[accent_font_family]-[accent_font_weight]-[accent_font_style]|' | replace: '[accent_font_family]', accent_font.family | replace: '[accent_font_weight]', accent_font.weight | replace: '[accent_font_style]', accent_font.style
+  assign accent_font_bold_face_id = '[accent_font_bold_family]-[accent_font_bold_weight]-[accent_font_bold_style]|' | replace: '[accent_font_bold_family]', accent_font_bold.family | replace: '[accent_font_bold_weight]', accent_font_bold.weight | replace: '[accent_font_bold_style]', accent_font_bold.style
+  assign accent_font_italic_face_id = '[accent_font_italic_family]-[accent_font_italic_weight]-[accent_font_italic_style]|' | replace: '[accent_font_italic_family]', accent_font_italic.family | replace: '[accent_font_italic_weight]', accent_font_italic.weight | replace: '[accent_font_italic_style]', accent_font_italic.style
+  assign accent_font_bold_italic_face_id = '[accent_font_bold_italic_family]-[accent_font_bold_italic_weight]-[accent_font_bold_italic_style]|' | replace: '[accent_font_bold_italic_family]', accent_font_bold_italic.family | replace: '[accent_font_bold_italic_weight]', accent_font_bold_italic.weight | replace: '[accent_font_bold_italic_style]', accent_font_bold_italic.style
+
+  unless rendered_fonts contains primary_font_face_id
+    echo primary_font | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: primary_font_face_id
+  endunless
+
+  unless rendered_fonts contains primary_font_bold_face_id
+    echo primary_font_bold | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: primary_font_bold_face_id
+  endunless
+
+  unless rendered_fonts contains primary_font_italic_face_id
+    echo primary_font_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: primary_font_italic_face_id
+  endunless
+
+  unless rendered_fonts contains primary_font_bold_italic_face_id
+    echo primary_font_bold_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: primary_font_bold_italic_face_id
+  endunless
+
+  unless rendered_fonts contains secondary_font_face_id
+    echo secondary_font | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: secondary_font_face_id
+  endunless
+
+  unless rendered_fonts contains secondary_font_bold_face_id
+    echo secondary_font_bold | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: secondary_font_bold_face_id
+  endunless
+
+  unless rendered_fonts contains secondary_font_italic_face_id
+    echo secondary_font_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: secondary_font_italic_face_id
+  endunless
+
+  unless rendered_fonts contains secondary_font_bold_italic_face_id
+    echo secondary_font_bold_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: secondary_font_bold_italic_face_id
+  endunless
+
+  unless rendered_fonts contains tertiary_font_face_id
+    echo tertiary_font | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: tertiary_font_face_id
+  endunless
+
+  unless rendered_fonts contains tertiary_font_bold_face_id
+    echo tertiary_font_bold | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: tertiary_font_bold_face_id
+  endunless
+
+  unless rendered_fonts contains tertiary_font_italic_face_id
+    echo tertiary_font_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: tertiary_font_italic_face_id
+  endunless
+
+  unless rendered_fonts contains tertiary_font_bold_italic_face_id
+    echo tertiary_font_bold_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: tertiary_font_bold_italic_face_id
+  endunless
+
+  unless rendered_fonts contains accent_font_face_id
+    echo accent_font | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: accent_font_face_id
+  endunless
+
+  unless rendered_fonts contains accent_font_bold_face_id
+    echo accent_font_bold | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: accent_font_bold_face_id
+  endunless
+
+  unless rendered_fonts contains accent_font_italic_face_id
+    echo accent_font_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: accent_font_italic_face_id
+  endunless
+
+  unless rendered_fonts contains accent_font_bold_italic_face_id
+    echo accent_font_bold_italic | font_face: font_display: 'swap'
+    assign rendered_fonts = rendered_fonts | append: accent_font_bold_italic_face_id
+  endunless
+%}
+```
+
+New:
+
+```title="font_utils"
+{% assign
+  bold        = f -> (f | font_modify: 'weight', 'bold'),
+  italic      = f -> (f | font_modify: 'style', 'italic'),
+  bold_italic = f -> (f | font_modify: 'weight', 'bold' | font_modify: 'style', 'italic')
+%}
+```
+
+```
+{%- import "font_utils" -%}
+
+{% with
+  font_types = [
+    settings.type_body_font,
+    settings.type_subheading_font,
+    settings.type_heading_font,
+    settings.type_accent_font
+  ],
+
+  font_faces = font_types
+    | flat_map : f -> [f, (f | bold), (f | italic), (f | bold_italic)]
+    | uniq     : f -> '${f.family}-${f.weight}-${f.style}'
+    | map      : f -> (f | font_face: font_display: 'swap')
+%}
+  {{- font_faces | join: "\n\n" -}}
+{% endwith %}
+```

data/docs_/header_block_example.md

@@ -0,0 +1,51 @@
+From Horizon `header.liquid`
+
+```
+{% liquid
+  assign bottom_row_blocks = ''
+
+  if section.settings.menu_row == 'bottom'
+    assign bottom_row_blocks = bottom_row_blocks | append: 'menu,'
+  endif
+
+  if section.settings.search_style != 'none'
+    if section.settings.search_row == 'bottom'
+      assign bottom_row_blocks = bottom_row_blocks | append: 'search,'
+    endif
+  endif
+
+  if section.settings.show_country or section.settings.show_language
+    if section.settings.localization_row == 'bottom'
+      assign bottom_row_blocks = bottom_row_blocks | append: 'localization,'
+    endif
+  endif
+
+  assign bottom_row_blocks = bottom_row_blocks | split: ',' | compact
+%}
+```
+
+```
+{% with settings = section.settings %}
+  {% assign
+    bottom_row_blocks = [
+      'menu' if settings.menu_row == 'bottom',
+      'search' if settings.search_style != 'none' and settings.search_row == 'bottom',
+      'localization' if (settings.show_country or settings.show_language) and settings.localization_row == 'bottom',
+    ] | compact
+  %}
+{% endwith %}
+```
+
+```
+{% with
+  s = section.settings,
+
+  blocks = [
+    'menu' if s.menu_row == 'bottom',
+    'search' if s.search_style != 'none' and s.search_row == 'bottom',
+    'localization' if (s.show_country or s.show_language) and s.localization_row == 'bottom',
+  ]
+%}
+  {% assign bottom_row_blocks = blocks | compact %}
+{% endwith %}
+```

data/docs_/increment_and_decrement.md

@@ -0,0 +1,49 @@
+Old:
+
+Start at zero, post output increment
+
+```
+{% increment foo %}
+{% increment foo %}
+{{ foo }}
+```
+
+```title="output"
+0
+1
+2
+```
+
+Start at zero, pre output decrement
+
+```
+{% decrement foo %}
+{% decrement foo %}
+{{ foo }}
+```
+
+```title="output"
+-1
+-2
+-2
+```
+
+New:
+
+```
+{% assign foo = 0 -%}
+{{ foo }}
+{% assign foo = foo + 1 -%}
+{{ foo }}
+{% assign foo = foo + 1 -%}
+{{ foo }}
+```
+
+```
+{% assign foo = 0 %}
+{% assign foo = foo - 1 -%}
+{{ foo }}
+{% assign foo = foo - 1 -%}
+{{ foo }}
+{{ foo }}
+```

data/docs_/logo_style_example.md

@@ -0,0 +1,40 @@
+From Horizon `_header-logo.liquid`:
+
+```
+{% liquid
+  assign logo_width = settings.logo_height | times: settings.logo.aspect_ratio | ceil
+  assign logo_width_mobile = settings.logo_height_mobile | times: settings.logo.aspect_ratio | ceil
+  assign inverse_logo_width = settings.logo_height | times: inverse_logo.aspect_ratio | ceil
+  assign inverse_logo_width_mobile = settings.logo_height_mobile | times: inverse_logo.aspect_ratio | ceil
+  assign logo_style = '--header-logo-image-width: ' | append: logo_width | append: 'px;' | append: '--header-logo-image-width-mobile: ' | append: logo_width_mobile | append: 'px; --header-logo-image-height: ' | append: settings.logo_height | append: 'px; --header-logo-image-height-mobile: ' | append: settings.logo_height_mobile | append: 'px;'
+  assign inverse_logo_style = '--header-logo-image-width: ' | append: inverse_logo_width | append: 'px;' | append: '--header-logo-image-width-mobile: ' | append: inverse_logo_width_mobile | append: 'px; --header-logo-image-height: ' | append: settings.logo_height | append: 'px; --header-logo-image-height-mobile: ' | append: settings.logo_height_mobile | append: 'px;'
+%}
+```
+
+```
+{% with
+  logo_width = settings.logo_height * settings.logo.aspect_ratio | ceil,
+  logo_width_mobile = settings.logo_height_mobile * settings.logo.aspect_ratio | ceil,
+  inverse_logo_width = settings.logo_height * inverse_logo.aspect_ratio | ceil,
+  inverse_logo_width_mobile = settings.logo_height_mobile * inverse_logo.aspect_ratio | ceil,
+
+  logo_styles = [
+    '--header-logo-image-width: ${logo_width}px;',
+    '--header-logo-image-width-mobile: ${logo_width_mobile}px;',
+    '--header-logo-image-height: ${settings.logo_height}px;',
+    '--header-logo-image-height-mobile: ${settings.logo_height_mobile}px;',
+  ],
+
+  inverse_logo_styles = [
+    '--header-logo-image-width: ${inverse_logo_width}px;',
+    '--header-logo-image-width-mobile: ${inverse_logo_width_mobile}px;',
+    '--header-logo-image-height: ${settings.logo_height}px;',
+    '--header-logo-image-height-mobile: ${settings.logo_height_mobile}px;',
+  ]
+%}
+  {% assign
+    logo_style = logo_styles | join,
+    inverse_logo_style = inverse_logo_styles | join,
+  %}
+{% endwith %}
+```

data/docs_/migration.md

@@ -0,0 +1,11 @@
+# Luoma idioms
+
+For anyone already familiar with [liquid](https://github.com/Shopify/liquid), here we show some legacy Liquid idioms and equivalent Luoma idioms side-by-side.
+
+## Comments
+
+Luoma does not include `{% comment %}...{% endcomment%}` or `{% # ... }` tags.
+
+```liquid
+{% comment %}  {% endcomment %}
+```

data/docs_/notes.md

@@ -0,0 +1,19 @@
+## Notes
+
+- There's no `{% comment %}` or `{% # %}` tag. Use `{# some comment #}` instead.
+- There's no `{% doc %}` tag. Use `{# some doc comment #}` instead.
+- There's no `{% liquid %}` or equivalent tag. Use compound and ternary expressions, multi assigns with the `{% assign %}` tag, and block-scoped variables with the `{% with %}` tag.
+- There's no `{% unless %}` tag. Use `{% if not (...) %}` or `{% if a != b %}`.
+- `{% for %}` does not accept arguments. Use the `slice` and `reverse` filters instead.
+- The `slice` filter accepts `start`, `stop` and `step` arguments instead of `limit` and `offset`. `start`, `stop` and `step` can be positional or keyword and positive or negative.
+- There's no `forloop` drop. Use optional index and array binding syntax: `{% for a, index, array in ... %}`.
+- Strings are iterated and sliced like an array of characters.
+- `{% render %}` and `{% include %}` don't accept binding or looping arguments. Use a `{% for %}` loop instead.
+- There's no `empty` or `blank` objects. Use `thing.empty?` and `thing.blank?` instead.
+- Filters that expect an array input do not implicitly flatten nested arrays. Use the `flatten` filter if needed.
+
+- First-class blocks with `{% define %} ... {% enddefine%}`
+- First-class expressions with `{% assign x = <lambda expr> %}`
+- Type predicates
+- Case tag accepts type predicates
+- `{% import %}` is a cross between `{% include %}` and `{% render %}`. It requires a string argument and renders a template just for its side effects, discarding any output.

data/lib/luoma/cache.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Luoma
+  # A least recently used cache relying on Ruby hash insertion order.
+  class LRUCache
+    attr_reader :max_size
+
+    def initialize(max_size = 128)
+      @data = {}
+      @max_size = max_size
+    end
+
+    # Return the cached value or nil if _key_ does not exist.
+    def [](key)
+      val = @data[key]
+      return nil if val.nil?
+
+      @data.delete(key)
+      @data[key] = val
+      val
+    end
+
+    def []=(key, value)
+      if @data.key?(key)
+        @data.delete(key)
+      elsif @data.length >= @max_size
+        @data.delete((@data.first || raise)[0])
+      end
+      @data[key] = value
+    end
+
+    def length
+      @data.length
+    end
+
+    def keys
+      @data.keys
+    end
+  end
+
+  # A thread safe least recently used cache.
+  class ThreadSafeLRUCache < LRUCache
+    include MonitorMixin
+
+    alias unsafe_get []
+    alias unsafe_set []=
+    alias unsafe_length length
+    alias unsafe_keys keys
+
+    def initialize(max_size = 128)
+      super
+    end
+
+    def [](key)
+      synchronize do
+        unsafe_get(key)
+      end
+    end
+
+    def []=(key, value)
+      synchronize do
+        unsafe_set(key, value)
+      end
+    end
+
+    def length
+      synchronize do
+        unsafe_length
+      end
+    end
+
+    def keys
+      synchronize do
+        unsafe_keys
+      end
+    end
+  end
+end

data/lib/luoma/chain_hash.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Luoma
+  # Combine multiple hashes for sequential lookup.
+  class ChainHash
+    #: (*_Namespace) -> void
+    def initialize(*hashes)
+      @hashes = hashes.to_a
+    end
+
+    #: (String) -> untyped
+    def [](key)
+      index = @hashes.length - 1
+      while index >= 0
+        h = @hashes[index]
+        index -= 1
+        v = h.fetch(key, :nothing)
+        return v unless v == :nothing
+      end
+    end
+
+    #: (String) -> bool
+    def key?(key)
+      index = @hashes.length - 1
+      while index >= 0
+        h = @hashes[index]
+        index -= 1
+        v = h.fetch(key, :nothing)
+        return true unless v == :nothing
+      end
+
+      false
+    end
+
+    #: (String, untyped) -> untyped
+    def fetch(key, default = :nothing)
+      index = @hashes.length - 1
+      while index >= 0
+        h = @hashes[index]
+        index -= 1
+        v = h.fetch(key, :nothing)
+        return v unless v == :nothing
+      end
+
+      default
+    end
+
+    def size = @hashes.length
+    def push(hash) = @hashes << hash
+    alias << push
+    def pop = @hashes.pop
+    def nil? = false
+  end
+end