luoma 0.1.0

data/docs/index.md

@@ -0,0 +1,73 @@
+# 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](https://github.com/Shopify/liquid), [Jinja](https://jinja.palletsprojects.com/en/stable/) or [Django's template language](https://docs.djangoproject.com/en/6.0/topics/templates/#the-django-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](./luoma_for_template_authors.md). 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:
+
+```ruby
+gem 'luoma', '~> 0.1.0'
+```
+
+Or:
+
+```sh
+gem install luoma
+```
+
+Or:
+
+```sh
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+require "luoma"
+
+env = Luoma::Environment.new(
+  loader: Luoma::CachingFileSystemLoader.new("templates/")
+)
+
+template = env.get_template("index.luoma")
+another_template = env.parse("{% render 'index.luoma' %}")
+# ...
+```

data/docs/luoma_for_template_authors.md

@@ -0,0 +1,3 @@
+# Luoma for template authors
+
+TODO:

data/docs/markdown.md

@@ -0,0 +1,111 @@
+---
+icon: simple/markdown
+---
+
+# Markdown in 5min
+
+## Headers
+
+```
+# H1 Header
+## H2 Header
+### H3 Header
+#### H4 Header
+##### H5 Header
+###### H6 Header
+```
+
+## Text formatting
+
+```
+**bold text**
+*italic text*
+***bold and italic***
+~~strikethrough~~
+`inline code`
+```
+
+## Links and images
+
+```
+[Link text](https://example.com)
+[Link with title](https://example.com "Hover title")
+![Alt text](image.jpg)
+![Image with title](image.jpg "Image title")
+```
+
+## Lists
+
+```
+Unordered:
+
+- Item 1
+- Item 2
+  - Nested item
+
+Ordered:
+
+1. First item
+2. Second item
+3. Third item
+```
+
+## Blockquotes
+
+```
+> This is a blockquote
+> Multiple lines
+>> Nested quote
+```
+
+## Code blocks
+
+````
+```javascript
+function hello() {
+  console.log("Hello, world!");
+}
+```
+````
+
+## Tables
+
+```
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Row 1    | Data     | Data     |
+| Row 2    | Data     | Data     |
+```
+
+## Horizontal rule
+
+```
+---
+or
+***
+or
+___
+```
+
+## Task lists
+
+```
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+## Escaping characters
+
+```
+Use backslash to escape: \* \_ \# \`
+```
+
+## Line breaks
+
+```
+End a line with two spaces  
+to create a line break.
+
+Or use a blank line for a new paragraph.
+```

data/docs/predicate_reference.md

@@ -0,0 +1,3 @@
+# Built-in predicates
+
+TODO

data/docs/static_analysis.md

@@ -0,0 +1,3 @@
+# Static analysis
+
+TODO:

data/docs/tag_reference.md

@@ -0,0 +1,352 @@
+# Built-in tags
+
+## Comments
+
+```title="Syntax"
+{# <comment text> #}
+```
+
+Comments can be used to add documentation to your templates or "comment out" chunks of markup so that it wont be rendered.
+
+```liquid2
+{# This is a comment #}
+{#
+    Comments can
+    span
+    multiple lines
+#}
+```
+
+You can safely comment out markup containing comments by adding hashes, as long as the number of hashes is balanced.
+
+```liquid2
+{##
+  {# existing comment #}
+  {{ something }}
+##}
+```
+
+By convention, comments that start with a single hash on every line are considered doc comments to be parsed by a documentation generator.
+
+```liquid2
+{##
+ # @param font
+ # @returns CSS
+ ##}
+```
+
+## Output
+
+```title="Syntax"
+{{ <expression> }}
+```
+
+An expression surrounded by double curly braces (`{{` and `}}`) is an _output statement_. When rendered, the expression will be evaluated and the result written to the output stream.
+
+In this example the expression is the variable `you` - which will be resolved to a value and the value's string representation will be written to the output stream - but output statements can contain any expression.
+
+```liquid2
+Hello, {{ you }}!
+```
+
+## assign
+
+```title="Syntax"
+{% assign <identifier> = <expression> [, <identifier> = <expression> ...] %}
+```
+
+The `assign` tag binds the result of evaluating an expression to a name, creating or updating a variable.
+
+```liquid2
+{% assign foo = "bar" %}
+{% assign foo = 42 %}
+```
+
+A single `assign` tag can define multiple variables, separated by commas. Earlier bindings are immediately available in later expressions.
+
+```liquid2
+{% assign
+  a = 1,
+  b = a + 1
+%}
+```
+
+## capture
+
+```title="Syntax"
+{% capture <identifier> %} <markup> {% endcapture %}
+```
+
+The `capture` tag renders a block of markup to a string variable instead of writing it directly to the output stream.
+
+```liquid2
+{% assign first_name = "Sam" %}
+{% assign points = 120 %}
+
+{% capture message %}
+Hello {{ first_name }}!
+You have {{ points }} reward points.
+{% endcapture %}
+
+<p>{{ message }}</p>
+```
+
+```title="Output"
+<p>Hello Sam!
+You have 120 reward points.</p>
+```
+
+See also the [`define`](#define) tag.
+
+## case
+
+```title="Syntax"
+{% case <expression> %}
+  [ {% when <expression | predicate> [, <expression | predicate>] %} <markup> ] ...
+  [ {% else %} <markup> ]
+{% endcase %}
+```
+
+The `case` tag provides a multi-way conditional. It compares the result of a single expression against the result of one or more candidate expressions, and renders the block following the first matching `{% when %}` tag. If no branch matches, the optional `{% else %}` branch is rendered.
+
+```liquid2
+{% assign day = "Monday" %}
+
+{% case day %}
+  {% when "Monday" %}
+    Start of the work week!
+  {% when "Friday" %}
+    It's almost the weekend!
+  {% when "Saturday" or "Sunday" %}
+    Enjoy your weekend!
+  {% else %}
+    Just another weekday.
+{% endcase %}
+```
+
+`when` tags also understand _bare predicates_, like `.defined?` and `.empty?` in place of a standard expression.
+
+```liquid2
+{% case items %}
+  {% when empty? %}
+    No items.
+  {% else %}
+    {{ items | size }} items.
+{% endcase %}
+```
+
+## define
+
+```title="Syntax"
+{% define <identifier> [ visibility: ("public" | "private") ] %} <markup> {% enddefine %}
+```
+
+The `define` tag captures a block of markup for later rendering. `define` captures nothing about the scope in which it rendered. Defined blocks are rendered in the scope in which they are output or coerced to a string.
+
+```liquid2
+{% assign name = "Alice" %}
+
+{% define greeting %}
+Hello {{ name }}!
+{% enddefine %}
+
+{% assign name = "Bob" %}
+
+{{ greeting }}
+{{ greeting | upcase }}
+```
+
+```title="Output"
+Hello Bob!
+HELLO BOB!
+```
+
+`define` can be though of as a deferred [`capture`](#capture). See also [`import`](#import).
+
+## for
+
+```title="Syntax"
+{% for <identifier> [, identifier [, identifier]] in <expression> %}
+  <markup>
+  [ {% else %} <markup> ]
+{% endfor %}
+```
+
+The `for` tag renders its block once for each item in an iterable object. If the iterable is empty and an `else` block given, it will be rendered instead.
+
+```liquid2
+{% for product in collection %}
+  - {{ product.title }}
+{% else %}
+  No products available
+{% endfor %}
+```
+
+Optionally, the current zero-based iteration index can be bound to a name.
+
+```liquid2
+{% for product, index in collection %}
+  - {{ product.title }} at index {{ index }}
+{% endfor %}
+```
+
+And the optional third identifier binds the array being iterated to a name.
+
+```liquid2
+{% for product, index, array in collection %}
+  {%- assign last = index == (array | size) - 1 -%}
+  ...
+{% endfor %}
+```
+
+### break
+
+You can exit a loop early using the `break` tag.
+
+```liquid2
+{% for product in collection.products %}
+  {% if product.title == "Shirt" %}
+    {% break %}
+  {% endif %}
+
+  - {{ product.title }}
+{% endfor %}
+```
+
+### continue
+
+You can skip all or part of a loop iteration with the `continue` tag.
+
+```liquid2
+{% for product in collection.products %}
+  {% if product.title == "Shirt" %}
+    {% continue %}
+  {% endif %}
+
+  - {{ product.title }}
+{% endfor %}
+```
+
+## if
+
+```
+{% if <expression> %}
+  <markup>
+  [ {% elsif <expression> %} <markup> [ {% elsif <expression> %} ... ]]
+  [ {% else %} <markup> ... ]
+{% endif %}
+```
+
+The `if` tag conditionally renders its block if its expression evaluates to be truthy. Any number of `elsif` blocks can be given to add alternative conditions, and an `else` block is used as a default if no preceding conditions were truthy.
+
+```liquid2
+{% if product.title == "OK Hat" %}
+  This hat is OK.
+{% elsif product.title == "Rubbish Tie" %}
+  This tie is rubbish.
+{% else %}
+  Not sure what this is.
+{% endif %}
+```
+
+## import
+
+```title="Syntax"
+{% import <string> [ as <identifier>] %}
+```
+
+The `import` tag loads and renders a named template for its side effects, discarding its output. `import` is used to bring variables (including blocks defined with the [`define` tag](#define)) into scope.
+
+```liquid2
+{% import button_utils as buttons %}
+```
+
+## include
+
+```title="Syntax"
+{% include <template name>
+    [[,] <identifier>: <expression> [, [<identifier>: <expression> ... ]]]
+%}
+```
+
+The `include` tag loads and renders a named template, inserting the resulting text in its place. The name of the template to include can be a string literal or a variable resolving to a string. When rendered, the included template will share the same scope as the "calling" template.
+
+```liquid2
+{% include "snippets/header.html" %}
+```
+
+### Keyword arguments
+
+Additional keyword arguments given to the `include` tag will be added to the included template's scope, then go out of scope after the included template has been rendered.
+
+```liquid2
+{% include "partial_template" greeting: "Hello", num: 3, skip: 2 %}
+```
+
+## raw
+
+```
+{% raw %} <text> {% endraw %}
+```
+
+Any text between `{% raw %}` and `{% endraw %}` will not be interpreted as markup, but output as plain text instead.
+
+```liquid2
+{% raw %}
+  This will be rendered {{verbatim}}, with the curly brackets.
+{% endraw %}
+```
+
+## render
+
+```title="Syntax"
+{% render <string>
+    [[,] <identifier>: <expression> [, [<identifier>: <expression> ... ]]]
+%}
+```
+
+The `render` tag loads and renders a named template, inserting the resulting text in its place. The name of the template to include **must** be a string literal. When rendered, the included template will have its onw scope, without variables define in the calling template.
+
+```liquid2
+{% render "snippets/header.html" %}
+```
+
+### Keyword arguments
+
+Additional keyword arguments given to the `render` tag will be added to the rendered template's scope, then go out of scope after the it has been rendered.
+
+```liquid2
+{% render "partial_template" greeting: "Hello", num: 3, skip: 2 %}
+```
+
+## with
+
+```title="Syntax"
+{% with <identifier> = <expression> [, <identifier> = <expression> ... ] %}
+  <markup>
+{% endwith %}
+```
+
+The `with` tag introduces block-scoped variables. These variables have the potential to shadow global variables or variables assigned with `{% assign %}`, `{% capture %}` and `{% define %}`.
+
+```liquid2
+{% with p = collection.products.first %}
+  {{ p.title }}
+{% endwith %}
+
+{% with a = 1, b = 3.4 %}
+  {{ a }} + {{ b }} = {{ a + b }}
+{% endwith %}
+```
+
+When multiple bindings are given, earlier variables are in scope for later expressions.
+
+```liquid2
+{% with
+  a = 1,
+  b = 3.4,
+  c = a + b,
+%}
+  {{ a }} + {{ b }} = {{ c }}
+{% endwith %}
+```