TDD: Unit tests for infix operators (no functionality yet)

Co-authored-by: Ian Ker-Seymer <[email protected]>

.github/workflows/liquid.yml

@@ -14,8 +14,21 @@ jobs:
           - { ruby: 3.0, allowed-failure: false } # minimum supported
           - { ruby: 3.2, allowed-failure: false }
           - { ruby: 3.3, allowed-failure: false }
+          - { ruby: 3.3, allowed-failure: false }
           - { ruby: 3.4, allowed-failure: false } # latest
+          - {
+              ruby: 3.4,
+              allowed-failure: false,
+              rubyopt: "--enable-frozen-string-literal",
+            }
+          - { ruby: 3.4, allowed-failure: false, rubyopt: "--yjit" }
           - { ruby: ruby-head, allowed-failure: false }
+          - {
+              ruby: ruby-head,
+              allowed-failure: false,
+              rubyopt: "--enable-frozen-string-literal",
+            }
+          - { ruby: ruby-head, allowed-failure: false, rubyopt: "--yjit" }
     name: Test Ruby ${{ matrix.entry.ruby }}
     steps:
       - uses: actions/checkout@v3
@@ -26,6 +39,8 @@ jobs:
           bundler: latest
       - run: bundle exec rake
         continue-on-error: ${{ matrix.entry.allowed-failure }}
+        env:
+          RUBYOPT: ${{ matrix.entry.rubyopt }}
 
   memory_profile:
     runs-on: ubuntu-latest

History.md

@@ -1,24 +1,34 @@
 # Liquid Change Log
 
-## 5.7.3 (unreleased)
+## 5.8.1 (unreleased)
 
-* Raise Liquid::SyntaxError when parsing invalidly encoded strings
+## 5.8.1
+
+* Fix `{% doc %}` tag to be visitable [Guilherme Carreiro]
+
+## 5.8.0
+
+* Introduce the new `{% doc %}` tag [Guilherme Carreiro]
+
+## 5.7.3
+
+* Raise Liquid::SyntaxError when parsing invalidly encoded strings [Chris AtLee]
 
 ## 5.7.2 2025-01-31
 
-* Fix array filters to not support nested properties
+* Fix array filters to not support nested properties [Guilherme Carreiro]
 
 ## 5.7.1 2025-01-24
 
-* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays
-* Fix the `has` filter to return `false` when filtering empty arrays
+* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays [Guilherme Carreiro]
+* Fix the `has` filter to return `false` when filtering empty arrays [Guilherme Carreiro]
 
 ## 5.7.0 2025-01-16
 
 ### Features
 
-* Add `find`, `find_index`, `has`, and `reject` filters to arrays
-* Compatibility with Ruby 3.4
+* Add `find`, `find_index`, `has`, and `reject` filters to arrays [Guilherme Carreiro]
+* Compatibility with Ruby 3.4 [Ian Ker-Seymer]
 
 ## 5.6.4 2025-01-14
 

lib/liquid/locales/en.yml

@@ -2,12 +2,14 @@
   errors:
     syntax:
       tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: %{tag}"
+      block_tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: {% %{tag} %}{% end%{tag} %}"
       assign: "Syntax Error in 'assign' - Valid syntax: assign [var] = [source]"
       capture: "Syntax Error in 'capture' - Valid syntax: capture [var]"
       case: "Syntax Error in 'case' - Valid syntax: case [condition]"
       case_invalid_when: "Syntax Error in tag 'case' - Valid when condition: {% when [condition] [or condition2...] %}"
       case_invalid_else: "Syntax Error in tag 'case' - Valid else condition: {% else %} (no parameters) "
       cycle: "Syntax Error in 'cycle' - Valid syntax: cycle [name :] var [, var2, var3 ...]"
+      doc_invalid_nested: "Syntax Error in 'doc' - Nested doc tags are not allowed"
       for: "Syntax Error in 'for loop' - Valid syntax: for [item] in [collection]"
       for_invalid_in: "For loops require an 'in' clause"
       for_invalid_attribute: "Invalid attribute in for loop. Valid attributes are limit and offset"

lib/liquid/tags.rb

@@ -19,6 +19,7 @@ require_relative "tags/comment"
 require_relative "tags/raw"
 require_relative "tags/render"
 require_relative "tags/cycle"
+require_relative "tags/doc"
 
 module Liquid
   module Tags
@@ -42,6 +43,7 @@ module Liquid
       'if' => If,
       'echo' => Echo,
       'tablerow' => TableRow,
+      'doc' => Doc,
     }.freeze
   end
 end

lib/liquid/tags/doc.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name doc
+  # @liquid_summary
+  #   Documents template elements with annotations.
+  # @liquid_description
+  #   The `doc` tag allows developers to include documentation within Liquid
+  #   templates. Any content inside `doc` tags is not rendered or outputted.
+  #   Liquid code inside will be parsed but not executed. This facilitates
+  #   tooling support for features like code completion, linting, and inline
+  #   documentation.
+  # @liquid_syntax
+  #   {% doc %}
+  #     Renders a message.
+  #
+  #     @param {string} foo - A foo value.
+  #     @param {string} [bar] - An optional bar value.
+  #
+  #     @example
+  #     {% render 'message', foo: 'Hello', bar: 'World' %}
+  #   {% enddoc %}
+  #   {{ foo }}, {{ bar }}!
+  class Doc < Block
+    NO_UNEXPECTED_ARGS = /\A\s*\z/
+
+    def initialize(tag_name, markup, parse_context)
+      super
+      ensure_valid_markup(tag_name, markup, parse_context)
+    end
+
+    def parse(tokens)
+      while (token = tokens.shift)
+        tag_name = token =~ BlockBody::FullTokenPossiblyInvalid && Regexp.last_match(2)
+
+        raise_nested_doc_error if tag_name == @tag_name
+
+        if tag_name == block_delimiter
+          parse_context.trim_whitespace = (token[-3] == WhitespaceControl)
+          return
+        end
+      end
+
+      raise_tag_never_closed(block_name)
+    end
+
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def blank?
+      true
+    end
+
+    def nodelist
+      []
+    end
+
+    private
+
+    def ensure_valid_markup(tag_name, markup, parse_context)
+      unless NO_UNEXPECTED_ARGS.match?(markup)
+        raise SyntaxError, parse_context.locale.t("errors.syntax.block_tag_unexpected_args", tag: tag_name)
+      end
+    end
+
+    def raise_nested_doc_error
+      raise SyntaxError, parse_context.locale.t("errors.syntax.doc_invalid_nested")
+    end
+  end
+end

lib/liquid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Liquid
-  VERSION = "5.7.3"
+  VERSION = "5.8.1"
 end

test/unit/block_unit_test.rb

@@ -47,12 +47,18 @@ class BlockUnitTest < Minitest::Test
     )
   end
 
-  def test_with_block
+  def test_comment_tag_with_block
     template = Liquid::Template.parse("  {% comment %} {% endcomment %} ")
     assert_equal([String, Comment, String], block_types(template.root.nodelist))
     assert_equal(3, template.root.nodelist.size)
   end
 
+  def test_doc_tag_with_block
+    template = Liquid::Template.parse("  {% doc %} {% enddoc %} ")
+    assert_equal([String, Doc, String], block_types(template.root.nodelist))
+    assert_equal(3, template.root.nodelist.size)
+  end
+
   private
 
   def block_types(nodelist)

test/unit/infix_operators_unit_test.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class InfixOperatorsUnitTest < Minitest::Test
+  include Liquid
+
+  def test_addition_operator
+    # Filter syntax
+    filter_template = Liquid::Template.parse("{{ num | plus: 3 }}")
+    # Infix syntax
+    infix_template = Liquid::Template.parse("{{ num + 3 }}")
+
+    assert_equal(filter_template.render("num" => 5), infix_template.render("num" => 5))
+    assert_equal("8", infix_template.render("num" => 5))
+  end
+
+  def test_subtraction_operator
+    # Filter syntax
+    filter_template = Liquid::Template.parse("{{ num | minus: 3 }}")
+    # Infix syntax
+    infix_template = Liquid::Template.parse("{{ num - 3 }}")
+
+    assert_equal(filter_template.render("num" => 5), infix_template.render("num" => 5))
+    assert_equal("2", infix_template.render("num" => 5))
+  end
+
+  def test_multiplication_operator
+    # Filter syntax
+    filter_template = Liquid::Template.parse("{{ num | times: 3 }}")
+    # Infix syntax
+    infix_template = Liquid::Template.parse("{{ num * 3 }}")
+
+    assert_equal(filter_template.render("num" => 5), infix_template.render("num" => 5))
+    assert_equal("15", infix_template.render("num" => 5))
+  end
+
+  def test_division_operator
+    # Filter syntax
+    filter_template = Liquid::Template.parse("{{ num | divided_by: 2 }}")
+    # Infix syntax
+    infix_template = Liquid::Template.parse("{{ num / 2 }}")
+
+    assert_equal(filter_template.render("num" => 10), infix_template.render("num" => 10))
+    assert_equal("5", infix_template.render("num" => 10))
+  end
+
+  def test_comparison_operators
+    # Greater than
+    assert_equal("true", Liquid::Template.parse("{{ 5 > 3 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 3 > 5 }}").render)
+
+    # Greater than or equal
+    assert_equal("true", Liquid::Template.parse("{{ 5 >= 5 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 3 >= 5 }}").render)
+
+    # Equal to
+    assert_equal("true", Liquid::Template.parse("{{ 5 == 5 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 3 == 5 }}").render)
+
+    # Less than or equal
+    assert_equal("true", Liquid::Template.parse("{{ 5 <= 5 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 6 <= 5 }}").render)
+
+    # Less than
+    assert_equal("true", Liquid::Template.parse("{{ 3 < 5 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 5 < 3 }}").render)
+  end
+
+  def test_logical_operators
+    # AND operator
+    assert_equal("true", Liquid::Template.parse("{{ true && true }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ true && false }}").render)
+
+    # OR operator
+    assert_equal("true", Liquid::Template.parse("{{ true || false }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ false || false }}").render)
+  end
+
+  def test_xor_operator
+    assert_equal("true", Liquid::Template.parse("{{ true ^ false }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ true ^ true }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ false ^ false }}").render)
+  end
+
+  def test_operator_precedence
+    # (10 - 2) * 3 = 24
+    assert_equal("24", Liquid::Template.parse("{{ (10 - 2) * 3 }}").render)
+    # 10 - (2 * 3) = 4
+    assert_equal("4", Liquid::Template.parse("{{ 10 - (2 * 3) }}").render)
+    # Without parentheses, multiplication has higher precedence
+    # 10 - 2 * 3 = 10 - 6 = 4
+    assert_equal("4", Liquid::Template.parse("{{ 10 - 2 * 3 }}").render)
+  end
+
+  def test_complex_expressions
+    # Multiple operations
+    assert_equal("9", Liquid::Template.parse("{{ 3 + 2 * 3 }}").render)
+    assert_equal("15", Liquid::Template.parse("{{ (3 + 2) * 3 }}").render)
+
+    # Mixed arithmetic and comparison
+    assert_equal("true", Liquid::Template.parse("{{ 3 + 2 > 4 }}").render)
+    assert_equal("false", Liquid::Template.parse("{{ 3 + 2 < 4 }}").render)
+
+    # Mixed arithmetic and logical
+    assert_equal("true", Liquid::Template.parse("{{ 3 + 2 > 4 && 10 / 2 == 5 }}").render)
+  end
+
+  def test_combined_operations
+    # In the proposed example
+    infix_template = Liquid::Template.parse("{% assign media_count = media_count - variant_images.size + 1 %}")
+    filter_template = Liquid::Template.parse("{% assign media_count = media_count | minus: variant_images.size | plus: 1 %}")
+
+    # Check that both templates have the same effect
+    context1 = Context.new("media_count" => 10, "variant_images" => [1, 2, 3])
+    context2 = Context.new("media_count" => 10, "variant_images" => [1, 2, 3])
+
+    infix_template.render(context1)
+    filter_template.render(context2)
+
+    assert_equal(context1["media_count"], context2["media_count"])
+    assert_equal(8, context1["media_count"])
+  end
+
+  def test_with_variables
+    template = Liquid::Template.parse("{{ a + b * c }}")
+    assert_equal("11", template.render("a" => 5, "b" => 2, "c" => 3))
+
+    template = Liquid::Template.parse("{{ (a + b) * c }}")
+    assert_equal("21", template.render("a" => 5, "b" => 2, "c" => 3))
+  end
+
+  def test_chained_comparisons
+    template = Liquid::Template.parse("{{ a < b && b < c }}")
+    assert_equal("true", template.render("a" => 1, "b" => 5, "c" => 10))
+    assert_equal("false", template.render("a" => 1, "b" => 15, "c" => 10))
+  end
+end

test/unit/tags/doc_tag_unit_test.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class DocTagUnitTest < Minitest::Test
+  def test_doc_tag
+    template = <<~LIQUID.chomp
+      {% doc %}
+        Renders loading-spinner.
+
+        @param {string} foo - some foo
+        @param {string} [bar] - optional bar
+
+        @example
+        {% render 'loading-spinner', foo: 'foo' %}
+        {% render 'loading-spinner', foo: 'foo', bar: 'bar' %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_does_not_support_extra_arguments
+    error = assert_raises(Liquid::SyntaxError) do
+      template = <<~LIQUID.chomp
+        {% doc extra %}
+        {% enddoc %}
+      LIQUID
+
+      Liquid::Template.parse(template)
+    end
+
+    exp_error = "Liquid syntax error: Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}"
+    act_error = error.message
+
+    assert_equal(exp_error, act_error)
+  end
+
+  def test_doc_tag_must_support_valid_tags
+    assert_match_syntax_error("Liquid syntax error (line 1): 'doc' tag was never closed", '{% doc %} foo')
+    assert_match_syntax_error("Liquid syntax error (line 1): Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}", '{% doc } foo {% enddoc %}')
+    assert_match_syntax_error("Liquid syntax error (line 1): Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}", '{% doc } foo %}{% enddoc %}')
+  end
+
+  def test_doc_tag_ignores_liquid_nodes
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% if true %}
+        {% if ... %}
+        {%- for ? -%}
+        {% while true %}
+        {%
+          unless if
+        %}
+        {% endcase %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_unclosed_liquid_tags
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% if true %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_does_not_allow_nested_docs
+    error = assert_raises(Liquid::SyntaxError) do
+      template = <<~LIQUID.chomp
+        {% doc %}
+          {% doc %}
+            {% doc %}
+        {% enddoc %}
+      LIQUID
+
+      Liquid::Template.parse(template)
+    end
+
+    exp_error = "Liquid syntax error: Syntax Error in 'doc' - Nested doc tags are not allowed"
+    act_error = error.message
+
+    assert_equal(exp_error, act_error)
+  end
+
+  def test_doc_tag_ignores_nested_raw_tags
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% raw %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_unclosed_assign
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% assign foo = "1"
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_malformed_syntax
+    template = <<~LIQUID.chomp
+      {% doc %}
+      {% {{ {%- enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_preserves_error_line_numbers
+    template = Liquid::Template.parse(<<~LIQUID.chomp, line_numbers: true)
+      {% doc %}
+        {% if true %}
+      {% enddoc %}
+      {{ errors.standard_error }}
+    LIQUID
+
+    expected = <<~TEXT.chomp
+
+      Liquid error (line 4): standard error
+    TEXT
+
+    assert_equal(expected, template.render('errors' => ErrorDrop.new))
+  end
+
+  def test_doc_tag_whitespace_control
+    # Basic whitespace control
+    assert_template_result("Hello!", "      {%- doc -%}123{%- enddoc -%}Hello!")
+    assert_template_result("Hello!", "{%- doc -%}123{%- enddoc -%}     Hello!")
+    assert_template_result("Hello!", "      {%- doc -%}123{%- enddoc -%}     Hello!")
+    assert_template_result("Hello!", <<~LIQUID.chomp)
+      {%- doc %}Whitespace control!{% enddoc -%}
+      Hello!
+    LIQUID
+  end
+
+  def test_doc_tag_delimiter_handling
+    assert_template_result('', <<~LIQUID.chomp)
+      {% if true %}
+        {% doc %}
+          {% docEXTRA %}wut{% enddocEXTRA %}xyz
+        {% enddoc %}
+      {% endif %}
+    LIQUID
+
+    assert_template_result('', "{% doc %}123{% enddoc xyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\txyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\nxyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\n   xyz  enddoc %}")
+  end
+
+  def test_doc_tag_visitor
+    template_source = '{% doc %}{% enddoc %}'
+
+    assert_equal(
+      [Liquid::Doc],
+      visit(template_source),
+    )
+  end
+
+  private
+
+  def traversal(template)
+    ParseTreeVisitor
+      .for(Template.parse(template).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        tag_class = tag.class
+        tag_class
+      end
+  end
+
+  def visit(template)
+    traversal(template).visit.flatten.compact
+  end
+end