luoma 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: acb537ba303e1ce24a308b621d0ea4f878531d04d321d0ead9e2a261c2b76832
+  data.tar.gz: cc19b11460124b48b80766259d508408570323e596b6dbea5ee120edb874d298
+SHA512:
+  metadata.gz: 05e51ff2461365ee5b41c0bd50545dc5c7444e44ee18da6fe4b15aa058cf9cc4d6d1e43420a41c61d9e37fa9fcdce096842212dd54f52f4ecd0cd34434799b04
+  data.tar.gz: 76bc4f2e919b162257b4eaf55331e7b436614442433d40056bb759ead9392a7099e195185cb8bed78219dbcd14380c93e2a89117c3d2ddfbe63e3396cdaab2e3

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+ES)��IX`�
x%uj�l�vC���x�k��e���Ֆ3�wX
mUucр��0b�4QY���A���#��EL+L���[����S�J���1��i��'衐�#
6?�$s������[t
+�/�4m�JB_�;�I�w��?~�~��So�(��$�n~��

data/.rdoc_options

@@ -0,0 +1,16 @@
+# .rdoc_options
+title: Luoma Ruby
+main_page: README.md
+markup: markdown
+exclude:
+  - bin/
+  - dev.rb
+  - Gemfile
+  - Gemfile.lock
+  - performance/
+  - Rakefile
+  - sig/
+  - Steepfile
+  - test/
+  - tmp/
+  - docs/

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 James Prior
+
+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.

data/README.md

@@ -0,0 +1,68 @@
+<h1 align="center">Luoma - Ruby</h1>
+
+<p align="center">A modern template engine for Ruby.</p>
+
+<p align="center">
+  <a href="https://github.com/jg-rp/luoma-ruby/blob/main/LICENSE.txt">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/jg-rp/luoma-ruby?style=flat-square">
+  </a>
+  <a href="https://github.com/jg-rp/luoma-ruby/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/jg-rp/luoma-ruby/main.yml?branch=main&label=tests&style=flat-square" alt="Tests">
+  </a>
+  <br>
+  <a href="https://rubygems.org/gems/luoma">
+    <img alt="Gem Version" src="https://img.shields.io/gem/v/luoma?style=flat-square">
+  </a>
+  <a href="https://github.com/jg-rp/luoma-ruby">
+    <img alt="Static Badge" src="https://img.shields.io/badge/Ruby-3.1%20%7C%203.2%20%7C%203.3%20%7C%203.4-CC342D?style=flat-square">
+  </a>
+</p>
+
+**Table of Contents**
+
+- [Install](#install)
+- [Example](#example)
+- [Links](#links)
+- [License](#license)
+
+## Install
+
+Add `'luoma'` to your Gemfile:
+
+```
+gem 'luoma', '~> 0.1.0'
+```
+
+Or
+
+```
+gem install luoma
+```
+
+Or
+
+```
+bundle add luoma
+```
+
+## Example
+
+```ruby
+require "luoma"
+
+template = Luoma.parse("Hello, {{ you }}!")
+puts template.render("you" => "World")  # Hello, World!
+puts template.render("you" => "Luoma")  # Hello, Luoma!
+```
+
+## Links
+
+- Documentation: https://jg-rp.github.io/luoma/
+- Change log: https://github.com/jg-rp/luoma-ruby/blob/main/CHANGELOG.md
+- RubyGems: https://rubygems.org/gems/luoma
+- Source code: https://github.com/jg-rp/luoma-ruby
+- Issue tracker: https://github.com/jg-rp/luoma-ruby/issues
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new do |task|
+  task.plugins << "rubocop-minitest"
+  task.plugins << "rubocop-rake"
+  task.plugins << "rubocop-performance"
+end
+
+require "steep/rake_task"
+
+Steep::RakeTask.new do |t|
+  t.check.severity_level = :error
+  t.watch.verbose
+end
+
+namespace :docs do
+  desc "Build the documentation using Zensical"
+  task :build do
+    puts "Building documentation with Zensical..."
+    build_success = system("zensical build --clean")
+    abort("Error: Failed to build documentation.") unless build_success
+  end
+
+  desc "Build and publish documentation to GitHub Pages"
+  task deploy: :build do
+    site_dir = "site"
+
+    abort("Error: Output directory '#{site_dir}' missing. Build may have failed.") unless Dir.exist?(site_dir)
+
+    # Retrieve the remote URL of your main Git repository
+    remote = `git config --get remote.origin.url`.strip
+    abort("Error: Could not determine Git remote URL for 'origin'.") if remote.empty?
+
+    target_branch = "gh-pages"
+
+    puts "Publishing '#{site_dir}' to #{target_branch} branch on #{remote}..."
+
+    # Use a temporary directory to avoid touching local working tree state
+    Dir.mktmpdir do |tmp_dir|
+      # Copy all contents of the build folder into the temp directory
+      FileUtils.cp_r(File.join(site_dir, "."), tmp_dir)
+
+      # Initialize a temporary git repo and push to the remote branch
+      Dir.chdir(tmp_dir) do
+        system("git init -q")
+        system("git checkout -b #{target_branch}")
+        system("git add .")
+        system("git commit -q -m 'Deploy documentation updates [skip ci]'")
+
+        pushed = system("git push --force #{remote} #{target_branch}")
+        abort("Error: Failed to push to GitHub Pages.") unless pushed
+      end
+    end
+
+    puts "Successfully deployed documentation to GitHub Pages!"
+  end
+end
+
+task default: %i[test rubocop steep]

data/Steepfile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+  #   ignore_signature "sig/test"
+
+  check "lib" # Directory name
+  #   check "path/to/source.rb"         # File name
+  #   check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+
+  library "base64"
+  library "bigdecimal"
+  library "cgi"
+  library "json"
+  library "strscan"
+  library "stringio"
+  library "time"
+  library "pathname"
+  library "monitor"
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end

data/certs/jgrp.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEhTCCAu2gAwIBAgIBATANBgkqhkiG9w0BAQsFADBEMRYwFAYDVQQDDA1qYW1l
+c2dyLnByaW9yMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+FgNjb20wHhcNMjUxMDI1MDc0ODI4WhcNMjYxMDI1MDc0ODI4WjBEMRYwFAYDVQQD
+DA1qYW1lc2dyLnByaW9yMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJ
+k/IsZAEZFgNjb20wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQDYTvQW
+0JzsHenYu4w0iHgJRtU9uK8vkDx1wlMioKlPFkaiMfxqUcTTfg80U/n8n/KKmpdq
+y2rpUqv+VPE2nrfCUncf7ukqs+gF8uehbciMXV4iOzsZmqmtlPUJiGuSyO8REe/O
+ERAyxYV8y5psF+WnW4uQzsWCKTnKbexIc6rf237veuYvYoBpnodJu0mJ0m9tBCFU
+qH3Nk1sHBRIEEwn+nTiIiOMb+QMU5p0NIQkIhJO3el5nEQgIGxMPnie7PnwxPquQ
+1rouuISbLmQy5oKYc9kScwnHdAu2PtnnJFNNuQ37vED375iQgMem/tK8EgMm9/Qr
+Qxd2DQqqehgtEySWntGHTxNLXQouqHIRyqzkbcCatJqC+PBBql1x2N1KqgyvbLM3
+B0dZCdJECr5J8zrluMxYsy7uGMmLz3LZ7PskGaJg4XxXP3j/B/e03/AxDj0neZZu
+xuDLIfMDSNILO1pskMc+Xp0xdnkbS4IjiMDTrhqABuEcdNYH/GpyTiA/I0cCAwEA
+AaOBgTB/MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBR4j7UhnpT9
+mLcAkshwkFtwVpMdejAiBgNVHREEGzAZgRdqYW1lc2dyLnByaW9yQGdtYWlsLmNv
+bTAiBgNVHRIEGzAZgRdqYW1lc2dyLnByaW9yQGdtYWlsLmNvbTANBgkqhkiG9w0B
+AQsFAAOCAYEAbTkg946BsGPQFX3jskBjwINeFnMP0IppuStonPQv3SNQu1SWP0xS
+o1Qji1dxkWDfOcp1ffrRMUo7ecrJbTqQ5Sdx+7zw0OLodSVqSu1LMIVDw/T73smg
+ADO2r3eZ8vxCKh7z4wUeKXvmBXi5NvpmvhH7D+qeG4OMLI8jnfmfbSHZQZbe2tpd
+tJC+MYVok/m91fBrfv5wqLsR5QiJl3vcVhG+xACd46gr3JZFOxBqpSJrCYL8Gwqx
+BaKEySCLGqkb0d1Rnt2/zTR2KtW2QJVH9rBMnJ+LsPEFKs1UHH4qHzxmwmmaQLon
+MoE4UJ51GHGrjJ4WsHOUSOy5UbjaQec3kuIDwTXKbHws0J0Ut9S4S38opZKdQHDD
+PUBpY0QA1CgE/VjKAYEDHOJyfUCNOl+sEESM+WxEXZAUVZLrFF7MljJqyQq+JyTD
+vFKHe1ZAA76NFrPscB/ODPTBK8i+u4gwrD1UAsVAHuIbOpQu4LYAujluCu5cl2A8
+HhmlCT7sTkqG
+-----END CERTIFICATE-----

data/docs/configuration.md

@@ -0,0 +1,180 @@
+---
+title: Setup
+---
+
+# Luoma environments
+
+Template parsing and rendering behavior is configured using an instance of `Luoma::Environment`. Once configured, parse templates with `Environment#parse(source)` or `Environment#get_template(name)`, both of which return an instance of `Luoma::Template`.
+
+An `Environment` is where you'd register custom filters or tags, or define variables that should be available to all templates, for example.
+
+!!! tip
+
+    In addition to the environment options shown here, `Luoma::Environment` is designed to be extended. You can, for example, override `Luoma::Environment#eq?` to redefine expression equality, or override `Luoma::Environment#serialize` to change the way objects are rendered. See [environment.rb](https://github.com/jg-rp/luoma-ruby/blob/main/lib/luoma/expression.rb) for a complete method reference and default implementations.
+
+## The default environment
+
+The default Luoma environment and new instances of `Luoma::Environment` constructed without any arguments are equivalent to passing the following arguments to `Environment.new`.
+
+```ruby
+env = Luoma::Environment.new(
+  auto_trim: nil,
+  globals: nil,
+  lexer: Luoma::UnifiedLexer,
+  loader: Luoma::HashLoader.new({}),
+  max_assign_score_cumulative: nil,
+  max_assign_score: nil,
+  max_context_depth: 30,
+  max_render_score_cumulative: nil,
+  max_render_score: nil,
+  max_render_size: nil,
+  parser: Luoma::UnifiedParser,
+  strict: false,
+  suppress_blank_control_flow_blocks: true,
+  undefined: Luoma::UndefinedDrop
+)
+```
+
+Top-level convenience methods `Luoma.parse` and `Luoma.render` always use the default environment.
+
+## Managing tags, filters and predicates
+
+New instances of `Luoma::Environment` and the [default Luoma environment](#the-default-environment) have all standard tags, filters and predicates enabled by default. `Environment.tags`, `Environment.filters` and `Environment.predicates` are hashes mapping strings to `_Tag`, filter callables and predicate callables, respectively. You can add, remove, replace or alias tags, filters and predicates in an environment by updating these mappings after environment initialization.
+
+This example removes th `{% include %}` tag and renames `downcase` to `lower` and `upcase` to `upper`.
+
+```ruby
+
+require "luoma"
+
+env = Luoma::Environment.new
+env.tags.delete("include")
+env.filters["lower"] = env.tags.delete("downcase")
+env.filters["upper"] = env.tags.delete("upcase")
+```
+
+Alternatively, you can extend `Luoma::Environment` and override `setup_tags_filters_and_predicates`.
+
+```ruby
+require "luoma"
+
+class MyLuomaEnv < Luoma::Environment
+  #: () -> void
+  def setup_tags_filters_and_predicates
+    super
+    @tags.delete("include")
+  end
+end
+
+env = MyLuomaEnv.new
+# ...
+```
+
+## Auto trim
+
+The `auto_trim` option sets the default whitespace trimming mode. Setting `auto_trim: "-"` or `auto_trim: "~"` is equivalent to adding `-` or `~` before every closing markup delimiter.
+
+```ruby
+require "luoma"
+
+source = <<~SOURCE.chomp
+  <ul>
+  {% for x in (1..4) %}
+    <li>{{ x }}</li>
+  {% endfor %}
+  </ul>
+  ---
+SOURCE
+
+puts Luoma::Environment.new.render(source)
+puts Luoma::Environment.new(auto_trim: "~").render(source)
+```
+
+```html title="output"
+<ul>
+  <li>1</li>
+
+  <li>2</li>
+
+  <li>3</li>
+
+  <li>4</li>
+</ul>
+---
+<ul>
+  <li>1</li>
+  <li>2</li>
+  <li>3</li>
+  <li>4</li>
+</ul>
+---
+```
+
+## Global variables
+
+Global template variables are those added by application developers, as opposed to local variables created by template authors with tags such as `{% assign %}` and `{% capture %}`. Globals can come from the following places, in order of highest to lowest priority.
+
+1. The _data_ argument to `Luoma.render`, `Luoma::Environment#render` or `Luoma::Template#render`.
+2. "overlay" or "matter" data provided by a template loader and bound to a `Luoma::Template` instance. This could be front matter parsed from the beginning of a template source file, or data from a database, for example.
+3. The `globals` argument to `Luoma.parse` or `Luoma::Environment#parse`. These variables are pinned to the resulting template.
+4. The `globals` argument when constructing a new `Luoma::Environment`. These variables are pinned to the environment and will be merged into other global data for every template rendered from the environment.
+
+You can change the global variable source priority by extending and overriding `Luoma::Environment#makeGlobals` and/or `Luoma::Template#makeGlobals`.
+
+## Resource limits
+
+For deployments where template authors are untrusted, you can set limits on some resources to avoid malicious templates from consuming too much memory or too many CPU cycles. If any limit is exceeded, a `Luoma::ResourceLimitError` is raised.
+
+!!! note
+
+    The following "scores" are non-specific measures of usage modelled on Shopify/liquid resource limits.
+
+    These numbers are for illustration purposes. You'll need to do a bit of trial and error to find the limits that work best for you.
+
+```ruby
+require "luoma"
+
+env = Luoma::Environment.new(
+  # Maximum of 2000 "bytes" assigned with the assign/capture tags per template
+  # or partial template.
+  max_assign_score: 2000,
+
+  # Maximum of 10,000 "bytes" assigned with the assign/capture tags for the
+  # root template and all partial templates combined.
+  max_assign_score_cumulative: 10000,
+
+  # Maximum nesting of 30 `for` loops and/or `render` tags, for example.
+  max_context_depth: 30,
+
+  # Maximum of 1000 nodes (text and markup in the template syntax tree) rendered
+  # per template.
+  max_render_score: 1000,
+
+  # Maximum of 5000 nodes (text and markup in the template syntax tree) rendered
+  # for the root template and any rendered partial templates combined.
+  max_render_score_cumulative: 5000,
+
+  # Maximum of 15,000 bytes written to the output buffer.
+  max_render_size: 15000,
+)
+```
+
+## Strict mode
+
+When `strict: false` (the default) unknown filters, unknown predicates and filter argument errors are silently ignored at render time. When `strict: true`, `Luoma::FilterNotFoundError`, `Luoma::PredicateNotFoundError` or `Luoma::FilterArgumentError` is raised, all of which inherit from `Luoma::LuomaError`.
+
+```ruby
+require "luoma"
+
+source = "Hello, {{ you | title }}"
+
+puts Luoma::Environment.new.render(source)
+puts Luoma::Environment.new(strict: true).render(source)
+
+# Hello,
+# /home/james/projects/luoma-ruby/lib/luoma/expression.rb:195:in 'Luoma::FilteredExpression#evaluate_filter': Luoma::FilterNotFoundError: unknown filter "title"
+#   -> "Hello, {{ you | title }}":1:17
+#   |
+# 1 | Hello, {{ you | title }}
+#   |                 ^^^^^ unknown filter "title"
+```

data/docs/custom_filters.md

@@ -0,0 +1,3 @@
+# Custom filters
+
+TODO

data/docs/custom_tags.md

@@ -0,0 +1,3 @@
+# Custom tags
+
+TODO:

data/docs/expressions.md

@@ -0,0 +1,3 @@
+# Expressions
+
+TODO

data/docs/extension_types.md

@@ -0,0 +1,41 @@
+# Extension types
+
+A drop is a developer-defined type that plays nicely with Luoma tags, filters, predicates and operators. Drops are often used to implement lazy data retrieval or context sensitive logic.
+
+The base drop, `Luoma::Drop`, is falsy, is an empty iterable/enumerable, is equal to nothing (including itself) and renders as an empty string.
+
+TODO: document the complete Drop API.
+
+## Built-in drops
+
+### `BlockDrop`
+
+A `Luoma::BlockDrop` encapsulates a block of Luoma markup. When an instance of `BlockDrop` is rendered, its internal markup is rendered to the output stream using variables from the current context, in the scope where it is "called".
+
+Similarly, if a `BlockDrop` is coerced to a string - passed to a filter or tag that expects a string value - its internal markup is rendered into a new string using variables from the current scope.
+
+Instances of `BlockDrop` are produced by the built-in `{% define %}` tag. When rendered, `{% define some_name %}...{% enddefine %}` binds a `BlockDrop` to the given name without writing to the output stream. This means blocks can be passed around and rendered multiple times in different contexts without loading a separate template.
+
+By default, Luoma has special rules for rendering **arrays** of `BlockDrop`. Given an array of `BlockDrop` instances and no other types, Luoma will render each block to the output stream separated by a single newline character. If an array contains `BlockDrop` instances mixed with strings, those blocks and strings are rendered in order without a separating newline. Otherwise the array is considered data and is output in JSON.
+
+### `ExpressionDrop`
+
+A `Luoma::ExpressionDrop` encapsulates a single Luoma expression for later evaluation. When rendered or coerced to a string, `ExpressionDrop` produces a textual representation of its expression.
+
+Lambda literals (`(a, b) -> expression`) evaluate to an instance of `ExpressionDrop`, without capturing anything about the scope in which it is defined. Internally, Luoma's filter application operator (`|`) recognizes instances of `ExpressionDrop` as user-defined filters, and some built-in filters accept instances of `ExpressionDrop` as arguments.
+
+### `RangeDrop`
+
+Range literals (`(1..5)`) evaluate to instances of `Luoma::RangeDrop`. When iterated, `RangeDrop` yields integers from its range of integer values.
+
+When rendered or coerced to a string, `RangeDrop` produces a JSON-like array of integers.
+
+### `UndefinedDrop`
+
+Undefined variables resolve to an instance of of `Luoma::UndefinedDrop`, or one of its subclasses. Undefined variable behavior is configured by passing a `Luoma::UndefinedDrop` singleton to `Luoma::Environment.new`.
+
+See [Undefined variables](./undefined_variables.md) for a breakdown of the built-in `Undefined` types.
+
+## Custom drops
+
+TODO: