luoma 0.2.0 → 0.3.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: luoma
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - James Prior
@@ -64,28 +64,6 @@ files:
 - Rakefile
 - Steepfile
 - certs/jgrp.pem
-- docs-requirements.txt
-- docs/configuration.md
-- docs/custom_filters.md
-- docs/custom_tags.md
-- docs/expressions.md
-- docs/extension_types.md
-- docs/filter_reference.md
-- docs/index.md
-- docs/luoma_for_template_authors.md
-- docs/markdown.md
-- docs/predicate_reference.md
-- docs/static_analysis.md
-- docs/tag_reference.md
-- docs/template_loaders.md
-- docs/undefined_variables.md
-- docs_/cycle.md
-- docs_/font_rendering_example.md
-- docs_/header_block_example.md
-- docs_/increment_and_decrement.md
-- docs_/logo_style_example.md
-- docs_/migration.md
-- docs_/notes.md
 - lib/luoma.rb
 - lib/luoma/cache.rb
 - lib/luoma/chain_hash.rb
@@ -104,6 +82,7 @@ files:
 - lib/luoma/filters/array.rb
 - lib/luoma/filters/date.rb
 - lib/luoma/filters/default.rb
+- lib/luoma/filters/escape_js.rb
 - lib/luoma/filters/json.rb
 - lib/luoma/filters/math.rb
 - lib/luoma/filters/size.rb
@@ -163,6 +142,7 @@ files:
 - sig/luoma/filters/array.rbs
 - sig/luoma/filters/date.rbs
 - sig/luoma/filters/default.rbs
+- sig/luoma/filters/escape_js.rbs
 - sig/luoma/filters/json.rbs
 - sig/luoma/filters/math.rbs
 - sig/luoma/filters/size.rbs
@@ -203,7 +183,6 @@ files:
 - sig/luoma/tags/with.rbs
 - sig/luoma/template.rbs
 - sig/luoma/token.rbs
-- zensical.toml
 homepage: https://jg-rp.github.io/luoma-ruby/
 licenses:
 - MIT
@@ -228,6 +207,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: A modern template engine with a well-defined, composable agnostic expression
-  language.
+summary: A modern template engine with a well-defined, composable expression language.
 test_files: []

data/docs/configuration.md

@@ -1,180 +0,0 @@
----
-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

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

data/docs/custom_tags.md

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

data/docs/expressions.md

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

data/docs/extension_types.md

@@ -1,41 +0,0 @@
-# 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: