[WIP] Support for nested boolean expressions in parentheses

- Added unit tests for range syntax
- Added logical expression unit tests
- parser respects parentheses during expression traversal

.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

Gemfile

@@ -20,7 +20,13 @@ group :benchmark, :test do
   end
 end
 
+group :development do
+  gem "webrick"
+end
+
 group :test do
+  gem 'ruby-lsp'
+  gem 'debug'
   gem 'rubocop', '~> 1.61.0'
   gem 'rubocop-shopify', '~> 2.12.0', require: false
   gem 'rubocop-performance', require: false

History.md

@@ -1,12 +1,34 @@
 # Liquid Change Log
 
-## 5.8.0 (unreleased)
+## 5.8.1 (unreleased)
+
+## 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 [Guilherme Carreiro]
+
+## 5.7.1 2025-01-24
+
+* 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.rb

@@ -80,6 +80,8 @@ require 'liquid/variable_lookup'
 require 'liquid/range_lookup'
 require 'liquid/resource_limits'
 require 'liquid/expression'
+require 'liquid/expression/comparison_expression'
+require 'liquid/expression/logical_expression'
 require 'liquid/template'
 require 'liquid/condition'
 require 'liquid/utils'

lib/liquid/condition.rb

@@ -52,6 +52,10 @@ module Liquid
       @@method_literals[markup] || parse_context.parse_expression(markup)
     end
 
+    def self.parse(markup, ss, cache)
+      @@method_literals[markup] || Expression.parse(markup, ss, cache)
+    end
+
     attr_reader :attachment, :child_condition
     attr_accessor :left, :operator, :right
 
@@ -112,11 +116,15 @@ module Liquid
     private
 
     def equal_variables(left, right)
+      if left.is_a?(MethodLiteral) && right.is_a?(MethodLiteral)
+        return left.to_s == right.to_s
+      end
+
       if left.is_a?(MethodLiteral)
         if right.respond_to?(left.method_name)
           return right.send(left.method_name)
         else
-          return nil
+          return left.to_s == right
         end
       end
 
@@ -124,7 +132,7 @@ module Liquid
         if left.respond_to?(right.method_name)
           return left.send(right.method_name)
         else
-          return nil
+          return right.to_s == left
         end
       end
 

lib/liquid/expression.rb

@@ -26,6 +26,7 @@ module Liquid
     RANGES_REGEX = /\A\(\s*(?>(\S+)\s*\.\.)\s*(\S+)\s*\)\z/
     INTEGER_REGEX = /\A(-?\d+)\z/
     FLOAT_REGEX = /\A(-?\d+)\.\d+\z/
+    QUOTED_STRING = /\A#{QuotedString}\z/
 
     class << self
       def parse(markup, ss = StringScanner.new(""), cache = nil)
@@ -33,12 +34,9 @@ module Liquid
 
         markup = markup.strip # markup can be a frozen string
 
-        if (markup.start_with?('"') && markup.end_with?('"')) ||
-          (markup.start_with?("'") && markup.end_with?("'"))
-          return markup[1..-2]
-        elsif LITERALS.key?(markup)
-          return LITERALS[markup]
-        end
+        return markup[1..-2] if QUOTED_STRING.match?(markup)
+
+        return LITERALS[markup] if LITERALS.key?(markup)
 
         # Cache only exists during parsing
         if cache
@@ -51,6 +49,9 @@ module Liquid
       end
 
       def inner_parse(markup, ss, cache)
+        return LogicalExpression.parse(markup, ss, cache)    if LogicalExpression.logical?(markup)
+        return ComparisonExpression.parse(markup, ss, cache) if ComparisonExpression.comparison?(markup)
+
         if (markup.start_with?("(") && markup.end_with?(")")) && markup =~ RANGES_REGEX
           return RangeLookup.parse(
             Regexp.last_match(1),

lib/liquid/expression/comparison_expression.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Liquid
+  class Expression
+    class ComparisonExpression
+      # We can improve the resiliency of lax parsing by not expecting whitespace
+      # surrounding the operator (ie \s+ => \s*).
+      # However this is not in parity with existing lax parsing behavior.
+      COMPARISON_REGEX = /\A\s*(.+?)\s+(==|!=|<>|<=|>=|<|>|contains)\s+(.+)\s*\z/
+
+      class << self
+        def comparison?(markup)
+          markup.match(COMPARISON_REGEX)
+        end
+
+        def parse(markup, ss, cache)
+          match = comparison?(markup)
+
+          if match
+            left = Condition.parse(match[1].strip, ss, cache)
+            operator = match[2].strip
+            right = Condition.parse(match[3].strip, ss, cache)
+            return Condition.new(left, operator, right)
+          end
+
+          Condition.new(parse(markup, ss, cache), nil, nil)
+        end
+      end
+    end
+  end
+end

lib/liquid/expression/logical_expression.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Liquid
+  class Expression
+    class LogicalExpression
+      LOGICAL_REGEX = /\A\s*(.+?)\s+(and|or)\s+(.+)\s*\z/i
+      EXPRESSIONS_AND_OPERATORS = /(?:\b(?:\s?and\s?|\s?or\s?)\b|(?:\s*(?!\b(?:\s?and\s?|\s?or\s?)\b)(?:#{QuotedFragment}|\S+)\s*)+)/o
+      BOOLEAN_OPERATORS = ['and', 'or'].freeze
+
+      class << self
+        def logical?(markup)
+          markup.match(LOGICAL_REGEX)
+        end
+
+        def boolean_operator?(markup)
+          BOOLEAN_OPERATORS.include?(markup)
+        end
+
+        def parse(markup, ss, cache)
+          expressions = markup.scan(EXPRESSIONS_AND_OPERATORS)
+
+          expression = expressions.pop
+          condition  = parse_condition(expression, ss, cache)
+
+          until expressions.empty?
+            operator = expressions.pop.to_s.strip
+
+            next unless boolean_operator?(operator)
+
+            expression    = expressions.pop.to_s.strip
+            new_condition = parse_condition(expression, ss, cache)
+
+            case operator
+            when 'and' then new_condition.and(condition)
+            when 'or'  then new_condition.or(condition)
+            end
+
+            condition = new_condition
+          end
+
+          condition
+        end
+
+        private
+
+        def parse_condition(expr, ss, cache)
+          return ComparisonExpression.parse(expr, ss, cache) if comparison?(expr)
+          return LogicalExpression.parse(expr, ss, cache)    if logical?(expr)
+
+          Condition.new(Expression.parse(expr, ss, cache), nil, nil)
+        end
+
+        def comparison?(...)
+          ComparisonExpression.comparison?(...)
+        end
+      end
+    end
+  end
+end

lib/liquid/lexer.rb

@@ -14,6 +14,8 @@ module Liquid
     COMPARISON_LESS_THAN = [:comparison, "<"].freeze
     COMPARISON_LESS_THAN_OR_EQUAL = [:comparison, "<="].freeze
     COMPARISON_NOT_EQUAL_ALT = [:comparison, "<>"].freeze
+    BOOLEAN_AND = [:boolean_operator, "and"].freeze
+    BOOLEAN_OR = [:boolean_operator, "or"].freeze
     DASH = [:dash, "-"].freeze
     DOT = [:dot, "."].freeze
     DOTDOT = [:dotdot, ".."].freeze
@@ -151,6 +153,10 @@ module Liquid
               # Special case for "contains"
               output << if type == :id && t == "contains" && output.last&.first != :dot
                 COMPARISON_CONTAINS
+              elsif type == :id && t == "and" && output.last&.first != :dot
+                BOOLEAN_AND
+              elsif type == :id && t == "or" && output.last&.first != :dot
+                BOOLEAN_OR
               else
                 [type, t]
               end
@@ -161,6 +167,12 @@ module Liquid
         end
         # rubocop:enable Metrics/BlockNesting
         output << EOS
+      rescue ::ArgumentError => e
+        if e.message == "invalid byte sequence in #{ss.string.encoding}"
+          raise SyntaxError, "Invalid byte sequence in #{ss.string.encoding}"
+        else
+          raise
+        end
       end
 
       def raise_syntax_error(start_pos, ss)

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/parser.rb

@@ -48,7 +48,7 @@ module Liquid
 
     def expression
       token = @tokens[@p]
-      case token[0]
+      expr = case token[0]
       when :id
         str = consume
         str << variable_lookups
@@ -60,12 +60,41 @@ module Liquid
       when :string, :number
         consume
       when :open_round
-        consume
-        first = expression
-        consume(:dotdot)
+        consume_round_parentheses(token)
+      else
+        raise SyntaxError, "#{token} is not a valid expression"
+      end
+      if look(:comparison)
+        operator = consume(:comparison)
+        left     = expr
+        right    = expression
+
+        "#{left} #{operator} #{right}"
+      elsif look(:boolean_operator)
+        operator = consume(:boolean_operator)
+        left     = expr
+        right    = expression
+        if look(:close_round)
+          "(#{left} #{operator} #{right})"
+        else
+          "#{left} #{operator} #{right}"
+        end
+      else
+        expr
+      end
+    end
+
+    def consume_round_parentheses(token)
+      consume
+      first = expression
+      dotdot_token = consume?(:dotdot)
+      if dotdot_token
         last = expression
         consume(:close_round)
         "(#{first}..#{last})"
+      elsif look(:close_round)
+        consume(:close_round)
+        first
       else
         raise SyntaxError, "#{token} is not a valid expression"
       end

lib/liquid/standardfilters.rb

@@ -387,7 +387,7 @@ module Liquid
         end
       elsif ary.all? { |el| el.respond_to?(:[]) }
         begin
-          ary.sort { |a, b| nil_safe_compare(fetch_property(a, property), fetch_property(b, property)) }
+          ary.sort { |a, b| nil_safe_compare(a[property], b[property]) }
         rescue TypeError
           raise_property_error(property)
         end
@@ -416,7 +416,7 @@ module Liquid
         end
       elsif ary.all? { |el| el.respond_to?(:[]) }
         begin
-          ary.sort { |a, b| nil_safe_casecmp(fetch_property(a, property), fetch_property(b, property)) }
+          ary.sort { |a, b| nil_safe_casecmp(a[property], b[property]) }
         rescue TypeError
           raise_property_error(property)
         end
@@ -456,10 +456,10 @@ module Liquid
     #   Tests if any item in an array has a specific property value.
     # @liquid_description
     #   This requires you to provide both the property name and the associated value.
-    # @liquid_syntax array | some: string, string
+    # @liquid_syntax array | has: string, string
     # @liquid_return [boolean]
     def has(input, property, target_value = nil)
-      filter_array(input, property, target_value) { |ary, &block| ary.any?(&block) }
+      filter_array(input, property, target_value, false) { |ary, &block| ary.any?(&block) }
     end
 
     # @liquid_public_docs
@@ -472,7 +472,7 @@ module Liquid
     # @liquid_syntax array | find: string, string
     # @liquid_return [untyped]
     def find(input, property, target_value = nil)
-      filter_array(input, property, target_value) { |ary, &block| ary.find(&block) }
+      filter_array(input, property, target_value, nil) { |ary, &block| ary.find(&block) }
     end
 
     # @liquid_public_docs
@@ -485,7 +485,7 @@ module Liquid
     # @liquid_syntax array | find_index: string, string
     # @liquid_return [number]
     def find_index(input, property, target_value = nil)
-      filter_array(input, property, target_value) { |ary, &block| ary.find_index(&block) }
+      filter_array(input, property, target_value, nil) { |ary, &block| ary.find_index(&block) }
     end
 
     # @liquid_public_docs
@@ -504,7 +504,7 @@ module Liquid
         []
       else
         ary.uniq do |item|
-          fetch_property(item, property)
+          item[property]
         rescue TypeError
           raise_property_error(property)
         rescue NoMethodError
@@ -540,7 +540,7 @@ module Liquid
         if property == "to_liquid"
           e
         elsif e.respond_to?(:[])
-          r = fetch_property(e, property)
+          r = e[property]
           r.is_a?(Proc) ? r.call : r
         end
       end
@@ -564,7 +564,7 @@ module Liquid
         []
       else
         ary.reject do |item|
-          fetch_property(item, property).nil?
+          item[property].nil?
         rescue TypeError
           raise_property_error(property)
         rescue NoMethodError
@@ -950,7 +950,7 @@ module Liquid
         if property.nil?
           item
         elsif item.respond_to?(:[])
-          fetch_property(item, property)
+          item[property]
         else
           0
         end
@@ -969,16 +969,16 @@ module Liquid
 
     attr_reader :context
 
-    def filter_array(input, property, target_value, &block)
+    def filter_array(input, property, target_value, default_value = [], &block)
       ary = InputIterator.new(input, context)
 
-      return [] if ary.empty?
+      return default_value if ary.empty?
 
       block.call(ary) do |item|
         if target_value.nil?
-          fetch_property(item, property)
+          item[property]
         else
-          fetch_property(item, property) == target_value
+          item[property] == target_value
         end
       rescue TypeError
         raise_property_error(property)
@@ -988,31 +988,6 @@ module Liquid
       end
     end
 
-    def fetch_property(drop, property_or_keys)
-      ##
-      # This keeps backward compatibility by supporting properties containing
-      # dots. This is valid in Liquid syntax and used in some runtimes, such as
-      # Shopify with metafields.
-      #
-      # Using this approach, properties like 'price.value' can be accessed in
-      # both of the following examples:
-      #
-      # ```
-      # [
-      #   { 'name' => 'Item 1', 'price.price' => 40000 },
-      #   { 'name' => 'Item 2', 'price' => { 'value' => 39900 } }
-      # ]
-      # ```
-      value = drop[property_or_keys]
-
-      return value if !value.nil? || !property_or_keys.is_a?(String)
-
-      keys = property_or_keys.split('.')
-      keys.reduce(drop) do |drop, key|
-        drop.respond_to?(:[]) ? drop[key] : drop
-      end
-    end
-
     def raise_property_error(property)
       raise Liquid::ArgumentError, "cannot select the property '#{property}'"
     end

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 string value.
+  #     @param {string} [bar] - An optional string 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/tokenizer.rb

@@ -103,6 +103,12 @@ module Liquid
 
       pos = @ss.pos -= 2
       @source.byteslice(start, pos - start)
+    rescue ::ArgumentError => e
+      if e.message == "invalid byte sequence in #{@ss.string.encoding}"
+        raise SyntaxError, "Invalid byte sequence in #{@ss.string.encoding}"
+      else
+        raise
+      end
     end
 
     def next_variable_token

lib/liquid/version.rb

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

test/integration/standard_filter_test.rb

@@ -54,30 +54,6 @@ class TestEnumerable < Liquid::Drop
   end
 end
 
-class TestDeepEnumerable < Liquid::Drop
-  include Enumerable
-
-  class Product < Liquid::Drop
-    attr_reader :title, :price, :premium
-
-    def initialize(title:, price:, premium: nil)
-      @title = { "content" => title, "language" => "en" }
-      @price = { "value" => price, "unit" => "USD" }
-      @premium = { "category" => premium } if premium
-    end
-  end
-
-  def each(&block)
-    [
-      Product.new(title: "Pro goggles",    price: 1299),
-      Product.new(title: "Thermal gloves", price: 1299),
-      Product.new(title: "Alpine jacket",  price: 3999, premium: 'Basic'),
-      Product.new(title: "Mountain boots", price: 3899, premium: 'Pro'),
-      Product.new(title: "Safety helmet",  price: 1999)
-    ].each(&block)
-  end
-end
-
 class NumberLikeThing < Liquid::Drop
   def initialize(amount)
     @amount = amount
@@ -157,6 +133,18 @@ class StandardFiltersTest < Minitest::Test
     assert_equal([], @filters.slice(input, -(1 << 63), 6))
   end
 
+  def test_find_on_empty_array
+    assert_nil(@filters.find([], 'foo', 'bar'))
+  end
+
+  def test_find_index_on_empty_array
+    assert_nil(@filters.find_index([], 'foo', 'bar'))
+  end
+
+  def test_has_on_empty_array
+    refute(@filters.has([], 'foo', 'bar'))
+  end
+
   def test_truncate
     assert_equal('1234...', @filters.truncate('1234567890', 7))
     assert_equal('1234567890', @filters.truncate('1234567890', 20))
@@ -426,15 +414,6 @@ class StandardFiltersTest < Minitest::Test
     end
   end
 
-  def test_sort_natural_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | sort_natural: 'title.content' | map: 'title.content' | join: ', ' -}}
-    LIQUID
-    expected_output = "Alpine jacket, Mountain boots, Pro goggles, Safety helmet, Thermal gloves"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_legacy_sort_hash
     assert_equal([{ a: 1, b: 2 }], @filters.sort(a: 1, b: 2))
   end
@@ -471,15 +450,6 @@ class StandardFiltersTest < Minitest::Test
     end
   end
 
-  def test_uniq_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | uniq: 'price.value' | map: "title.content" | join: ', ' -}}
-    LIQUID
-    expected_output = "Pro goggles, Alpine jacket, Mountain boots, Safety helmet"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_compact_empty_array
     assert_equal([], @filters.compact([], "a"))
   end
@@ -496,15 +466,6 @@ class StandardFiltersTest < Minitest::Test
     end
   end
 
-  def test_compact_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | compact: 'premium.category' | map: 'title.content' | join: ', ' -}}
-    LIQUID
-    expected_output = "Alpine jacket, Mountain boots"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_reverse
     assert_equal([4, 3, 2, 1], @filters.reverse([1, 2, 3, 4]))
   end
@@ -614,15 +575,6 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result("213", '{{ foo | sort: "bar" | map: "foo" }}', { "foo" => TestEnumerable.new })
   end
 
-  def test_sort_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | sort: 'price.value' | map: 'title.content' | join: ', ' -}}
-    LIQUID
-    expected_output = "Pro goggles, Thermal gloves, Safety helmet, Mountain boots, Alpine jacket"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_first_and_last_call_to_liquid
     assert_template_result('foobar', '{{ foo | first }}', { 'foo' => [ThingWithToLiquid.new] })
     assert_template_result('foobar', '{{ foo | last }}', { 'foo' => [ThingWithToLiquid.new] })
@@ -939,15 +891,6 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "array" => array })
   end
 
-  def test_reject_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | reject: 'title.content', 'Pro goggles' | map: 'price.value' | join: ', ' -}}
-    LIQUID
-    expected_output = "1299, 3999, 3899, 1999"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_has
     array = [
       { "handle" => "alpha", "ok" => true },
@@ -976,6 +919,18 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, "{{ array | has: 'ok', true }}", { "array" => array })
   end
 
+  def test_has_with_empty_arrays
+    template = <<~LIQUID
+      {%- assign has_product = products | has: 'title.content', 'Not found' -%}
+      {%- unless has_product -%}
+        Product not found.
+      {%- endunless -%}
+    LIQUID
+    expected_output = "Product not found."
+
+    assert_template_result(expected_output, template, { "products" => [] })
+  end
+
   def test_has_with_false_value
     array = [
       { "handle" => "alpha", "ok" => true },
@@ -1004,16 +959,6 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "array" => array })
   end
 
-  def test_has_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | has: 'title.content', 'Pro goggles' -}},
-      {{- products | has: 'title.content', 'foo' -}}
-    LIQUID
-    expected_output = "true,false"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_find_with_value
     products = [
       { "title" => "Pro goggles",    "price" => 1299 },
@@ -1032,14 +977,16 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "products" => products })
   end
 
-  def test_find_with_deep_enumerables
+  def test_find_with_empty_arrays
     template = <<~LIQUID
-      {%- assign product = products | find: 'title.content', 'Pro goggles' -%}
-      {{- product.title.content -}}
+      {%- assign product = products | find: 'title.content', 'Not found' -%}
+      {%- unless product -%}
+        Product not found.
+      {%- endunless -%}
     LIQUID
-    expected_output = "Pro goggles"
+    expected_output = "Product not found."
 
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
+    assert_template_result(expected_output, template, { "products" => [] })
   end
 
   def test_find_index_with_value
@@ -1060,14 +1007,16 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "products" => products })
   end
 
-  def test_find_index_with_deep_enumerables
+  def test_find_index_with_empty_arrays
     template = <<~LIQUID
-      {%- assign index = products | find_index: 'title.content', 'Alpine jacket' -%}
-      {{- index -}}
+      {%- assign index = products | find_index: 'title.content', 'Not found' -%}
+      {%- unless index -%}
+        Index not found.
+      {%- endunless -%}
     LIQUID
-    expected_output = "2"
+    expected_output = "Index not found."
 
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
+    assert_template_result(expected_output, template, { "products" => [] })
   end
 
   def test_where
@@ -1168,15 +1117,6 @@ class StandardFiltersTest < Minitest::Test
     assert_nil(@filters.where([nil], "ok"))
   end
 
-  def test_where_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | where: 'title.content', 'Pro goggles' | map: 'price.value' -}}
-    LIQUID
-    expected_output = "1299"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   def test_all_filters_never_raise_non_liquid_exception
     test_drop = TestDrop.new(value: "test")
     test_drop.context = Context.new
@@ -1328,15 +1268,6 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result("0", "{{ input | sum: 'subtotal' }}", { "input" => input })
   end
 
-  def test_sum_with_deep_enumerables
-    template = <<~LIQUID
-      {{- products | sum: 'price.value' -}}
-    LIQUID
-    expected_output = "12495"
-
-    assert_template_result(expected_output, template, { "products" => TestDeepEnumerable.new })
-  end
-
   private
 
   def with_timezone(tz)

test/test_boolean_helper.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+module Minitest
+  module Assertions
+    include Liquid
+    def assert_with_lax_parsing(template, expected_output, context = {})
+      prev_error_mode = Liquid::Environment.default.error_mode
+      Liquid::Environment.default.error_mode = :lax
+
+      begin
+        actual_output = Liquid::Template.parse(template).render(context)
+      rescue StandardError => e
+        actual_output = e.message
+      ensure
+        Liquid::Environment.default.error_mode = prev_error_mode
+      end
+
+      assert_equal(expected_output.strip, actual_output.strip)
+    end
+
+    def assert_parity(liquid_expression, expected_result, args = {})
+      assert_condition(liquid_expression, expected_result, args)
+      assert_expression(liquid_expression, expected_result, args)
+    end
+
+    def assert_expression(liquid_expression, expected_result, args = {})
+      assert_parity_scenario(:expression, "{{ #{liquid_expression} }}", expected_result, args)
+    end
+
+    def assert_condition(liquid_condition, expected_result, args = {})
+      assert_parity_scenario(:condition, "{% if #{liquid_condition} %}true{% else %}false{% endif %}", expected_result, args)
+    end
+
+    def assert_parity_scenario(kind, template, exp_output, args = {})
+      act_output = Liquid::Template.parse(template).render(args)
+
+      assert_equal(exp_output, act_output, <<~ERROR_MESSAGE)
+        #{kind.to_s.capitalize} template failure:
+        ---
+        #{template}
+        ---
+        args: #{args.inspect}
+      ERROR_MESSAGE
+    end
+  end
+end
+
+class LinkDrop < Liquid::Drop
+  attr_accessor :levels, :links, :title, :type, :url
+
+  def initialize(levels: nil, links: nil, title: nil, type: nil, url: nil)
+    super()
+
+    @levels = levels
+    @links = links
+    @title = title
+    @type = type
+    @url = url
+  end
+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/boolean_precedence_unit_test.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'test_boolean_helper'
+
+class BooleanPrecedenceUnitTest < Minitest::Test
+  include Liquid
+
+  def test_basic_boolean_parenthesized_expressions
+    assert_parity("false and (false or true)", "false")
+    assert_parity("true and (false or true)", "true")
+    assert_parity("(true and false) or true", "true")
+    assert_parity("(false and true) or false", "false")
+  end
+
+  def test_nested_boolean_parentheses
+    assert_parity("(false and (true or false)) or true", "true")
+    assert_parity("true and (false or (true and true))", "true")
+    assert_parity("(true and (false or false)) or false", "false")
+  end
+
+  def test_multiple_operations_with_consistent_operators
+    assert_parity("(true and true) and (false or true)", "true")
+    assert_parity("(false or false) or (true and false)", "false")
+  end
+
+  def test_parentheses_changing_default_precedence
+    # Default precedence: (true and false) or true
+    assert_parity("true and false or true", "true")
+    # With parentheses: true and (false or true)
+    assert_parity("true and (false or true)", "true")
+
+    # Default precedence: false or (true and true)
+    assert_parity("false or true and true", "true")
+    # With parentheses: (false or true) and true
+    assert_parity("(false or true) and true", "true")
+  end
+
+  def test_boolean_parentheses_with_variables
+    assert_parity("(a or b) and c", "true", { "a" => true, "b" => false, "c" => true })
+    assert_parity("(a or b) and c", "false", { "a" => true, "b" => false, "c" => false })
+    assert_parity("a and (b or c)", "true", { "a" => true, "b" => false, "c" => true })
+    assert_parity("a and (b or c)", "false", { "a" => false, "b" => true, "c" => true })
+  end
+
+  def test_comparison_operators_inside_parentheses
+    assert_parity("(1 > 0) and (2 < 3)", "true")
+    assert_parity("(1 < 0) or (2 > 3)", "false")
+    assert_parity("true and (1 == 1)", "true")
+    assert_parity("false or (2 != 2)", "false")
+  end
+
+  def test_complex_nested_boolean_expressions
+    assert_parity("((true and false) or (false and true)) or ((false or true) and (true or false))", "true")
+    assert_parity("((true and true) or (false and false)) and ((true or false) and (false or true))", "true")
+  end
+
+  def test_not_operator_with_parentheses
+    # Testing how 'not' interacts with parentheses
+    assert_parity("not (true or false)", "false")
+    assert_parity("not (false and true)", "true")
+    assert_parity("(not false) and true", "true")
+    assert_parity("(not true) or false", "false")
+    assert_parity("not (not true)", "true")
+  end
+
+  def test_nil_values_with_boolean_precedence
+    # How nil values interact with boolean expressions and parentheses
+    assert_parity("nil and (true or false)", "false")
+    assert_parity("(nil or true) and false", "false")
+    assert_parity("(nil and nil) or true", "true")
+    assert_parity("true and (nil or false)", "false")
+  end
+
+  def test_mixed_primitive_types_with_parentheses
+    # Testing how different types interact in boolean expressions with parentheses
+    assert_parity("('' or 0) and true", "true")
+    assert_parity("(true and 'string') or false", "true")
+    assert_parity("(false or '') and 1", "false")
+    assert_parity("(nil or false) and 'text'", "false")
+  end
+
+  def test_triple_operator_precedence
+    # Testing three different operators with different parenthesizing
+    assert_parity("true or false and true or false", "true") # default precedence
+    assert_parity("true or (false and true) or false", "true")
+    assert_parity("(true or false) and (true or false)", "true")
+    assert_parity("((true or false) and true) or false", "true")
+    assert_parity("true or (false and (true or false))", "true")
+  end
+
+  def test_undefined_variables_with_parentheses
+    # How undefined variables behave with parentheses
+    assert_parity("(undefined_var or true) and false", "false")
+    assert_parity("true and (undefined_var or false)", "false")
+    assert_parity("(undefined_var and true) or true", "true")
+    assert_parity("false or (undefined_var and false)", "false")
+  end
+
+  def test_comparison_chaining_with_parentheses
+    # Testing how comparison chains work with parentheses
+    assert_parity("(1 < 2) and (2 < 3) and (3 < 4)", "true")
+    assert_parity("(1 < 2) and ((2 > 3) or (3 < 4))", "true")
+    assert_parity(
+      "(a > b) or ((c < d) and (e == f))",
+      "true",
+      { "a" => 5, "b" => 3, "c" => 1, "d" => 2, "e" => 7, "f" => 7 },
+    )
+    assert_parity(
+      "(a > b) or ((c < d) and (e == f))",
+      "false",
+      { "a" => 3, "b" => 5, "c" => 2, "d" => 1, "e" => 7, "f" => 8 },
+    )
+  end
+
+  def test_deeply_nested_expressions
+    # Testing very deep nesting to ensure parser handles it correctly
+    assert_parity("(((true and true) or (false and false)) and ((true or false) and (true)))", "true")
+    assert_parity(
+      "(((a or b) and c) or (d and (e or f)))",
+      "true",
+      { "a" => false, "b" => true, "c" => true, "d" => true, "e" => true, "f" => false },
+    )
+  end
+
+  def test_malformed_parentheses
+    # Unbalanced parentheses - missing closing parenthesis
+    template = "{% if (true and false %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Unbalanced parentheses - missing opening parenthesis
+    template = "{% if true and false) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Empty parentheses
+    template = "{% if () %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Consecutive opening parentheses without operators
+    template = "{% if ((true) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Consecutive closing parentheses without proper opening
+    template = "{% if (true)) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Parentheses with missing operand
+    template = "{% if (and true) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Operator followed immediately by closing parenthesis
+    template = "{% if (true and) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Nested malformed parentheses
+    template = "{% if (true and (false or true) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Double parentheses with no content between them
+    template = "{% if true and (()) %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Misplaced parentheses around operators
+    template = "{% if true (and) false %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+
+    # Parentheses at wrong position in expression
+    template = "{% if true) and (false %}true{% else %}false{% endif %}"
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse(template) }
+  end
+end

test/unit/boolean_unit_test.rb

@@ -0,0 +1,491 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'test_boolean_helper'
+
+class BooleanUnitTest < Minitest::Test
+  include Liquid
+  def test_simple_boolean_comparison
+    assert_parity("1 > 0", "true")
+    assert_parity("1 < 0", "false")
+  end
+
+  def test_boolean_and_operator
+    assert_parity("true and true", "true")
+    assert_parity("true and false", "false")
+  end
+
+  def test_boolean_or_operator
+    assert_parity("true or false", "true")
+    assert_parity("false or false", "false")
+  end
+
+  def test_operator_precedence
+    assert_parity("false and false or true", "false")
+  end
+
+  def test_complex_boolean_expressions
+    assert_parity("true and true and true", "true")
+    assert_parity("true and false and true", "false")
+    assert_parity("false or false or true", "true")
+  end
+
+  def test_boolean_with_variables
+    assert_parity("a and b", "true", { "a" => true, "b" => true })
+    assert_parity("a and b", "false", { "a" => true, "b" => false })
+    assert_parity("a or b", "true", { "a" => false, "b" => true })
+    assert_parity("a or b", "false", { "a" => false, "b" => false })
+  end
+
+  def test_nil_equals_nil
+    assert_parity("nil == nil", "true")
+  end
+
+  def test_nil_not_equals_nil
+    assert_parity("nil != nil", "false")
+  end
+
+  def test_nil_not_equals_empty_string
+    assert_parity("nil == ''", "false")
+    assert_parity("nil != ''", "true")
+  end
+
+  def test_undefined_variable_in_comparisons
+    assert_parity("undefined_var == nil", "true")
+    assert_parity("undefined_var != nil", "false")
+  end
+
+  def test_undefined_variable_compared_to_empty_string
+    assert_parity("undefined_var == ''", "false")
+    assert_parity("undefined_var != ''", "true")
+  end
+
+  def test_boolean_variable_in_comparisons
+    assert_parity("t == true", "true", { "t" => true })
+    assert_parity("f == false", "true", { "f" => false })
+  end
+
+  def test_boolean_variable_compared_to_nil
+    assert_parity("t == nil", "false", { "t" => true })
+    assert_parity("f == nil", "false", { "f" => false })
+    assert_parity("f != nil", "true", { "f" => false })
+  end
+
+  def test_nil_and_undefined_variables_in_boolean_expressions
+    assert_parity("x == undefined_var", "true", { "x" => nil })
+    assert_parity("x != undefined_var", "false", { "x" => nil })
+  end
+
+  def test_nil_literal_in_or_expression
+    assert_parity("nil or true", "true")
+  end
+
+  def test_nil_variable_in_or_expression
+    assert_parity("x or false", "false", { "x" => nil })
+  end
+
+  def test_mixed_boolean_expressions
+    assert_parity("a > b and c < d", "true",  { "a" => 99, "b" => 0, "c" => 0,  "d" => 99 })
+    assert_parity("a > b and c < d", "false", { "a" => 99, "b" => 0, "c" => 99, "d" => 0  })
+  end
+
+  def test_boolean_assignment_shorthand
+    template = Liquid::Template.parse("{% assign lazy_load = media_position > 1 %}{{ lazy_load }}")
+    assert_equal("false", template.render("media_position" => 1))
+    assert_equal("true",  template.render("media_position" => 2))
+  end
+
+  def test_equality_operators_with_integer_literals
+    assert_expression("1", "1")
+    assert_expression("1 == 1", "true")
+    assert_expression("1 != 1", "false")
+    assert_expression("1 == 2", "false")
+    assert_expression("1 != 2", "true")
+  end
+
+  def test_equality_operators_with_stirng_literals
+    assert_expression("'hello'", "hello")
+    assert_expression("'hello' == 'hello'", "true")
+    assert_expression("'hello' != 'hello'", "false")
+    assert_expression("'hello' == 'world'", "false")
+    assert_expression("'hello' != 'world'", "true")
+  end
+
+  def test_equality_operators_with_float_literals
+    assert_expression("1.5", "1.5")
+    assert_expression("1.5 == 1.5", "true")
+    assert_expression("1.5 != 1.5", "false")
+    assert_expression("1.5 == 2.5", "false")
+    assert_expression("1.5 != 2.5", "true")
+  end
+
+  def test_equality_operators_with_nil_literals
+    assert_expression("nil", "")
+    assert_expression("nil == nil", "true")
+    assert_expression("nil != nil", "false")
+    assert_expression("null == nil", "true")
+    assert_expression("null != nil", "false")
+  end
+
+  def test_equality_operators_with_boolean_literals
+    assert_expression("true", "true")
+    assert_expression("false", "false")
+    assert_expression("true == true", "true")
+    assert_expression("true != true", "false")
+    assert_expression("false == false", "true")
+    assert_expression("false != false", "false")
+    assert_expression("true == false", "false")
+    assert_expression("true != false", "true")
+  end
+
+  def test_equality_operators_with_empty_literals
+    assert_expression("empty", "")
+    assert_expression("empty == ''", "true")
+    assert_expression("empty == empty", "true")
+    assert_expression("empty != empty", "false")
+    assert_expression("blank == blank", "true")
+    assert_expression("blank != blank", "false")
+    assert_expression("empty == blank", "true")
+    assert_expression("empty != blank", "false")
+  end
+
+  def test_nil_renders_as_empty_string
+    # No parity needed here. This is to ensure expressions rendered with {{ }}
+    # will still render as an empty string to preserve pre-existing behavior.
+    assert_expression("nil", "")
+    assert_expression("x", "", { "x" => nil })
+    assert_parity_scenario(:expression, "hello {{ x }}", "hello ", { "x" => nil })
+  end
+
+  def test_nil_comparison_with_blank
+    assert_parity("nil_value == blank", "false")
+    assert_parity("nil_value != blank", "true")
+    assert_parity("undefined != blank", "true")
+    assert_parity("undefined == blank", "false")
+  end
+
+  def test_if_with_variables
+    assert_parity("value", "true",  { "value" => true })
+    assert_parity("value", "false", { "value" => false })
+  end
+
+  def test_nil_variable_in_and_expression
+    assert_condition("x and true", "false", { "x" => nil })
+    assert_condition("true and x", "false", { "x" => nil })
+
+    assert_expression("x and true", "",     { "x" => nil })
+    assert_expression("true and x", "",     { "x" => nil })
+  end
+
+  def test_boolean_variable_in_and_expression
+    assert_parity("true and x", "false", { "x" => false })
+    assert_parity("x and true", "false", { "x" => false })
+
+    assert_parity("true and x", "true",  { "x" => true })
+    assert_parity("x and true", "true",  { "x" => true })
+
+    assert_parity("true or x", "true",   { "x" => false })
+    assert_parity("x or true", "true",   { "x" => false })
+
+    assert_parity("true or x", "true",   { "x" => true })
+    assert_parity("x or true", "true",   { "x" => true })
+  end
+
+  def test_multi_variable_boolean_nil_and_expression
+    assert_condition("x and y", "false", { "x" => nil, "y" => true })
+    assert_condition("y and x", "false", { "x" => true, "y" => nil })
+
+    assert_expression("x and y", "",     { "x" => nil, "y" => true })
+    assert_expression("y and x", "",     { "x" => true, "y" => nil })
+  end
+
+  def test_multi_truthy_variables_and_expressions
+    assert_condition("x or y", "true",   { "x" => nil, "y" => "hello" })
+    assert_condition("y or x", "true",   { "x" => "hello", "y" => nil })
+
+    assert_expression("x or y", "hello", { "x" => nil, "y" => "hello" })
+    assert_expression("y or x", "hello", { "x" => "hello", "y" => nil })
+  end
+
+  def test_multi_variable_boolean_nil_or_expression
+    assert_parity("x or y", "true", { "x" => nil, "y" => true })
+    assert_parity("y or x", "true", { "x" => true, "y" => nil })
+  end
+
+  def test_links_not_blank_with_drop_returns_true_for_all_cases
+    link = LinkDrop.new(
+      levels: 0,
+      links: [
+        LinkDrop.new(levels: 1, links: [], title: "About", type: "page_link", url: "/pages/about"),
+        LinkDrop.new(levels: 1, links: [], title: "Contact", type: "page_link", url: "/pages/contact"),
+      ],
+      title: "Main Menu",
+      type: "menu",
+      url: nil,
+    )
+
+    template = <<~LIQUID
+      {%- if link.links != blank -%}
+        true
+      {%- else -%}
+        false
+      {%- endif -%}
+    LIQUID
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link.tap { |l| l.links = [] } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link.tap { |l| l.links = nil } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => LinkDrop.new })
+    assert_equal("true", act_output)
+  end
+
+  def test_links_truthy_with_drop_returns_false_for_nil_and_empty_drop
+    link = LinkDrop.new(
+      levels: 0,
+      links: [
+        LinkDrop.new(levels: 1, links: [], title: "About", type: "page_link", url: "/pages/about"),
+        LinkDrop.new(levels: 1, links: [], title: "Contact", type: "page_link", url: "/pages/contact"),
+      ],
+      title: "Main Menu",
+      type: "menu",
+      url: nil,
+    )
+
+    template = <<~LIQUID
+      {%- if link.links -%}
+        true
+      {%- else -%}
+        false
+      {%- endif -%}
+    LIQUID
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link.tap { |l| l.links = [] } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link.tap { |l| l.links = nil } })
+    assert_equal("false", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => {} })
+    assert_equal("false", act_output)
+  end
+
+  def test_links_not_blank_with_hash_returns_true_for_all_cases
+    link = {
+      "levels" => 0,
+      "links" => [
+        {
+          "levels" => 1,
+          "links" => [],
+          "title" => { "text" => "About" },
+          "type" => "page_link",
+          "url" => "/pages/about",
+        },
+        {
+          "levels" => 1,
+          "links" => [],
+          "title" => { "text" => "Contact" },
+          "type" => "page_link",
+          "url" => "/pages/contact",
+        },
+      ],
+      "title" => { "text" => "Main Menu" },
+      "type" => "menu",
+      "url" => nil,
+    }
+
+    template = <<~LIQUID
+      {%- if link.links != blank -%}
+        true
+      {%- else -%}
+        false
+      {%- endif -%}
+    LIQUID
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => { **link, "links" => [] } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => { **link, "links" => nil } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => {} })
+    assert_equal("true", act_output)
+  end
+
+  def test_links_truthy_with_hash_returns_false_for_nil_and_empty_hash
+    link = {
+      "levels" => 0,
+      "links" => [
+        {
+          "levels" => 1,
+          "links" => [],
+          "title" => { "text" => "About" },
+          "type" => "page_link",
+          "url" => "/pages/about",
+        },
+        {
+          "levels" => 1,
+          "links" => [],
+          "title" => { "text" => "Contact" },
+          "type" => "page_link",
+          "url" => "/pages/contact",
+        },
+      ],
+      "title" => { "text" => "Main Menu" },
+      "type" => "menu",
+      "url" => nil,
+    }
+
+    template = <<~LIQUID
+      {%- if link.links -%}
+        true
+      {%- else -%}
+        false
+      {%- endif -%}
+    LIQUID
+
+    act_output = Liquid::Template.parse(template).render({ "link" => link })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => { **link, "links" => [] } })
+    assert_equal("true", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => { **link, "links" => nil } })
+    assert_equal("false", act_output)
+
+    act_output = Liquid::Template.parse(template).render({ "link" => {} })
+    assert_equal("false", act_output)
+  end
+
+  def test_conditions_with_boolean_operators_without_whitespace_around_operator
+    template = <<~LIQUID
+      <option variant_id="{{ variant.id }}" {% if current_variant.id==variant.id %}selected{%- endif -%}>{{ variant.title }}</option>
+    LIQUID
+
+    context = {
+      "variant" => {
+        "id" => 420,
+        "title" => "Default Title",
+      },
+      "current_variant" => {
+        "id" => 420,
+      },
+    }
+
+    # Expected output
+    # Note: Ideally we would like the whitespace around the boolean operator to be optional.
+    # So the more correct expected output would be:
+    #
+    # <option variant_id="420" selected>Default Title</option>
+    #
+    # However, the existing behaviour in liquid-ruby is that the whitespace is required around the boolean operator.
+    expected_lax_output = <<~HTML
+      <option variant_id="420" >Default Title</option>
+    HTML
+
+    expected_strict_output = <<~HTML
+      <option variant_id="420" selected>Default Title</option>
+    HTML
+
+    # This bugged output only happens in lax mode.
+    assert_with_lax_parsing(template, expected_lax_output, context)
+
+    # Default test parsing mode (strict) works as properly expected
+    assert_equal(expected_strict_output.delete("\n"), actual_strict_output.delete("\n"))
+  end
+
+  # TESTING INCORRECT BEHAVIOUR OF LIQUID-RUBY
+  # If liquid-vm fails this test, we should change it.
+  def test_boolean_conditional_with_json_filter
+    # Define the Liquid template to test
+    template = <<~LIQUID
+      {{ template.name == 'index' | json }}
+    LIQUID
+
+    # Define the context for the template where the template name is 'index'
+    context = {
+      "template" => {
+        "name" => "product",
+      },
+    }
+
+    # Expected output
+    # Note: I dont know what is the correct output here but this is the liquid-ruby 'main' output.
+    #
+    # It feels incorrect but I dont know whats better
+    expected_output = "product"
+
+    # Render the template with the context
+    actual_parsed_template = Liquid::Template.parse(template)
+    actual_output = actual_parsed_template.render(context)
+
+    # Assert that the actual output matches the expected output
+    assert_equal(expected_output, actual_output.strip)
+  end
+
+  # TESTING INCORRECT BEHAVIOUR OF LIQUID-RUBY
+  # If liquid-vm fails this test, we should change it.
+  def test_chained_conditional_with_object_contains
+    # Define the Liquid template to test
+    template = <<~LIQUID
+      {{ settings.prefilter_status and template contains 'collection' }}
+    LIQUID
+
+    # Test with context containing 'collection'
+    context_with_collection = {
+      "template" => {
+        "name" => "collection",
+      },
+      "settings" => {
+        "prefilter_status" => true,
+      },
+    }
+    # NOTE: This is a bug that liquid-ruby `main` output returns the first value.
+    assert_with_lax_parsing(template, "true", context_with_collection)
+
+    # Test with context not containing 'collection'
+    context_without_collection = {
+      "template" => {
+        "name" => "not-collection",
+      },
+      "settings" => {
+        "prefilter_status" => true,
+      },
+    }
+    # NOTE: This is a bug that liquid-ruby `main` output returns the first value.
+    assert_with_lax_parsing(template, "true", context_without_collection)
+  end
+
+  # TESTING INCORRECT BEHAVIOUR OF LIQUID-RUBY
+  # If liquid-vm fails this test, we should change it.
+  def test_assign_boolean_expression_to_variable
+    template = <<~LIQUID
+      {%- liquid
+        assign is_preview_mode = content_for_header contains "foo" or content_for_header contains "bar"
+        echo is_preview_mode
+      -%}
+    LIQUID
+
+    context = { "content_for_header" => "Some content" }
+
+    # Expected output
+    # This value should be "false" but it is the value of the variable from the failed expression.
+    assert_template_result("Some content", template, context)
+
+    # This following validation should only be supported with our changes. It is the short-hand for the above template.
+    # The validation for it is the expected correct output.
+    template = Liquid::Template.parse("{% assign is_preview_mode = content_for_header contains 'foo' or content_for_header contains 'bar' %}{{ is_preview_mode }}")
+    assert_equal("false", template.render(context))
+  end
+end

test/unit/expression/logical_expression_test.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'test_boolean_helper'
+
+class LogicalExpressionTest < Minitest::Test
+  include Liquid
+
+  def setup
+    @ss = StringScanner.new("")
+    @cache = {}
+  end
+
+  def test_logical_detection
+    assert(Expression::LogicalExpression.logical?("foo and bar"))
+    assert(Expression::LogicalExpression.logical?("foo or bar"))
+    assert(Expression::LogicalExpression.logical?("true and false"))
+    assert(Expression::LogicalExpression.logical?("1 or 0"))
+
+    refute(Expression::LogicalExpression.logical?("foo"))
+    refute(Expression::LogicalExpression.logical?("1 == 1"))
+    refute(Expression::LogicalExpression.logical?("a contains b"))
+    refute(Expression::LogicalExpression.logical?("not foo"))
+  end
+
+  def test_parenthesized_logical_detection
+    assert(Expression::LogicalExpression.logical?("a and (b or c)"))
+    assert(Expression::LogicalExpression.logical?("(a or b) and c"))
+  end
+
+  def test_boolean_operator_detection
+    assert(Expression::LogicalExpression.boolean_operator?("and"))
+    assert(Expression::LogicalExpression.boolean_operator?("or"))
+
+    refute(Expression::LogicalExpression.boolean_operator?("not"))
+    refute(Expression::LogicalExpression.boolean_operator?("=="))
+    refute(Expression::LogicalExpression.boolean_operator?("contains"))
+    refute(Expression::LogicalExpression.boolean_operator?("foo"))
+  end
+
+  def test_basic_parsing
+    result = Expression::LogicalExpression.parse("true and false", @ss, @cache)
+    assert_instance_of(Condition, result)
+
+    result = Expression::LogicalExpression.parse("a or b", @ss, @cache)
+    assert_instance_of(Condition, result)
+  end
+
+  def test_parsing_with_different_expressions
+    # Test with simple variable expressions
+    result = Expression::LogicalExpression.parse("var1 and var2", @ss, @cache)
+    assert_instance_of(Condition, result)
+
+    # Test with comparison expressions
+    result = Expression::LogicalExpression.parse("a == 1 and b != 2", @ss, @cache)
+    assert_instance_of(Condition, result)
+  end
+
+  def test_parsing_complex_expressions
+    # Test with nested logical expressions
+    result = Expression::LogicalExpression.parse("a and b or c", @ss, @cache)
+    assert_instance_of(Condition, result)
+
+    result = Expression::LogicalExpression.parse("a or b and c", @ss, @cache)
+    assert_instance_of(Condition, result)
+  end
+
+  def test_parsing_parenthesized_expressions
+    result = Expression::LogicalExpression.parse("(a and b) or c", @ss, @cache)
+    assert_instance_of(Condition, result)
+
+    result = Expression::LogicalExpression.parse("a and (b or c)", @ss, @cache)
+    assert_instance_of(Condition, result)
+
+    # Test with complex expressions
+    result = Expression::LogicalExpression.parse("(a or b) and (c or d)", @ss, @cache)
+    assert_instance_of(Condition, result)
+  end
+
+  def test_evaluation_of_parsed_expressions
+    context = Liquid::Context.new(
+      "a" => true,
+      "b" => false,
+      "c" => true,
+      "d" => false,
+    )
+
+    # Test simple logical expressions
+    expr = Expression::LogicalExpression.parse("a and c", @ss, @cache)
+    assert_equal(true, expr.evaluate(context))
+
+    expr = Expression::LogicalExpression.parse("a and b", @ss, @cache)
+    assert_equal(false, expr.evaluate(context))
+
+    expr = Expression::LogicalExpression.parse("b or c", @ss, @cache)
+    assert_equal(true, expr.evaluate(context))
+
+    expr = Expression::LogicalExpression.parse("b or d", @ss, @cache)
+    assert_equal(false, expr.evaluate(context))
+  end
+
+  def test_evaluation_of_complex_expressions
+    context = Liquid::Context.new(
+      "a" => true,
+      "b" => false,
+      "c" => true,
+      "d" => false,
+    )
+
+    # Test complex logical expressions
+    expr = Expression::LogicalExpression.parse("a and b or c", @ss, @cache)
+    assert_equal(true, expr.evaluate(context))
+  end
+
+  def test_evaluation_of_parenthesized_expressions
+    context = Liquid::Context.new(
+      "a" => true,
+      "b" => false,
+      "c" => true,
+      "d" => false,
+    )
+
+    expr = Expression::LogicalExpression.parse("a and (b or d)", @ss, @cache)
+    assert_equal(false, expr.evaluate(context))
+
+    expr = Expression::LogicalExpression.parse("(a or b) and (c or d)", @ss, @cache)
+    assert_equal(true, expr.evaluate(context))
+
+    expr = Expression::LogicalExpression.parse("(a or b) and (b or d)", @ss, @cache)
+    assert_equal(false, expr.evaluate(context))
+  end
+
+  def test_precedence_rules
+    context = Liquid::Context.new(
+      "a" => true,
+      "b" => false,
+      "c" => true,
+    )
+
+    # Test precedence rules (AND has higher precedence than OR)
+    # This should be interpreted as: a and (b or c)
+    expr1 = Expression::LogicalExpression.parse("a and b or c", @ss, @cache)
+    assert_equal(true, expr1.evaluate(context))
+
+    # Change context to make the expressions evaluate differently
+    context = Liquid::Context.new(
+      "a" => false,
+      "b" => false,
+      "c" => true,
+    )
+
+    # With these values, "a and (b or c)" would be false
+    expr1 = Expression::LogicalExpression.parse("a and b or c", @ss, @cache)
+    assert_equal(false, expr1.evaluate(context))
+  end
+
+  def test_precedence_with_parentheses
+    context = Liquid::Context.new(
+      "a" => true,
+      "b" => false,
+      "c" => true,
+    )
+
+    # This should be interpreted as: (a and b) or c
+    expr2 = Expression::LogicalExpression.parse("(a and b) or c", @ss, @cache)
+    assert_equal(true, expr2.evaluate(context))
+
+    # Change context to make the expressions evaluate differently
+    context = Liquid::Context.new(
+      "a" => false,
+      "b" => false,
+      "c" => true,
+    )
+
+    # But "(a and b) or c" would be true
+    expr2 = Expression::LogicalExpression.parse("(a and b) or c", @ss, @cache)
+    assert_equal(true, expr2.evaluate(context))
+  end
+
+  def test_integration_with_if_tag
+    # Test that our expressions work properly in actual templates
+    assert_template_result("true", "{% if true and true %}true{% else %}false{% endif %}")
+    assert_template_result("false", "{% if true and false %}true{% else %}false{% endif %}")
+    assert_template_result("true", "{% if false or true %}true{% else %}false{% endif %}")
+    assert_template_result("false", "{% if false or false %}true{% else %}false{% endif %}")
+  end
+
+  def test_integration_with_parenthesized_if_tag
+    # Test with parenthesized expressions
+    assert_template_result("true", "{% if (true and false) or true %}true{% else %}false{% endif %}")
+    assert_template_result("false", "{% if true and (false or false) %}true{% else %}false{% endif %}")
+    assert_template_result("true", "{% if true and (false or true) %}true{% else %}false{% endif %}")
+  end
+
+  def test_integration_with_variables
+    # Test with variables
+    template = "{% if a and b %}true{% else %}false{% endif %}"
+    assert_template_result("true", template, { "a" => true, "b" => true })
+    assert_template_result("false", template, { "a" => true, "b" => false })
+
+    template = "{% if a or b %}true{% else %}false{% endif %}"
+    assert_template_result("true", template, { "a" => true, "b" => false })
+    assert_template_result("false", template, { "a" => false, "b" => false })
+  end
+
+  def test_integration_with_parenthesized_variables
+    # Test with parenthesized expressions
+    template = "{% if (a and b) or c %}true{% else %}false{% endif %}"
+    assert_template_result("true", template, { "a" => true, "b" => true, "c" => false })
+    assert_template_result("true", template, { "a" => false, "b" => false, "c" => true })
+    assert_template_result("false", template, { "a" => false, "b" => false, "c" => false })
+
+    template = "{% if a and (b or c) %}true{% else %}false{% endif %}"
+    assert_template_result("true", template, { "a" => true, "b" => true, "c" => false })
+    assert_template_result("true", template, { "a" => true, "b" => false, "c" => true })
+    assert_template_result("false", template, { "a" => true, "b" => false, "c" => false })
+    assert_template_result("false", template, { "a" => false, "b" => true, "c" => true })
+  end
+end

test/unit/lexer_unit_test.rb

@@ -131,6 +131,88 @@ class LexerUnitTest < Minitest::Test
     assert_equal([[:id, "false"], [:number, "1"], [:end_of_string]], tokenize("false 1"))
   end
 
+  def test_error_with_invalid_utf8
+    error = assert_raises(SyntaxError) do
+      tokenize("\x00\xff")
+    end
+    assert_equal(
+      'Liquid syntax error: Invalid byte sequence in UTF-8',
+      error.message,
+    )
+  end
+
+  def test_boolean_and_operator
+    exp = [
+      [:id, "true"],
+      [:boolean_operator, "and"],
+      [:id, "false"],
+      [:end_of_string],
+    ]
+    act = tokenize("true and false")
+    assert_equal(exp, act)
+  end
+
+  def test_boolean_or_operator
+    exp = [
+      [:id, "false"],
+      [:boolean_operator, "or"],
+      [:id, "true"],
+      [:end_of_string],
+    ]
+    act = tokenize("false or true")
+    assert_equal(exp, act)
+  end
+
+  def test_boolean_operators_in_complex_expressions
+    exp = [
+      [:id, "a"],
+      [:boolean_operator, "and"],
+      [:id, "b"],
+      [:boolean_operator, "or"],
+      [:id, "c"],
+      [:end_of_string],
+    ]
+    act = tokenize("a and b or c")
+    assert_equal(exp, act)
+  end
+
+  def test_boolean_operators_with_comparisons
+    exp = [
+      [:id, "a"],
+      [:comparison, ">"],
+      [:number, "5"],
+      [:boolean_operator, "and"],
+      [:id, "b"],
+      [:comparison, "<"],
+      [:number, "10"],
+      [:end_of_string],
+    ]
+    act = tokenize("a > 5 and b < 10")
+    assert_equal(exp, act)
+  end
+
+  def test_boolean_operators_as_property_names
+    exp = [
+      [:id, "obj"],
+      [:dot, "."],
+      [:id, "and"],
+      [:dot, "."],
+      [:id, "property"],
+      [:end_of_string],
+    ]
+    act = tokenize("obj.and.property")
+    assert_equal(exp, act)
+
+    exp = [
+      [:id, "obj"],
+      [:dot, "."],
+      [:id, "or"],
+      [:end_of_string],
+    ]
+    act = tokenize("obj.or")
+    assert_equal(exp, act)
+  end
+
   private
 
   def tokenize(input)

test/unit/range_unit_test.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class RangeUnitTest < Minitest::Test
+  include Liquid
+
+  def test_basic_range_creation
+    assert_template_result("1 2 3 4 5", "{% for i in (1..5) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_with_variables
+    assert_template_result("3 4 5", "{% assign start = 3 %}{% for i in (start..5) %}{{ i }} {% endfor %}")
+    assert_template_result("1 2 3", "{% assign end = 3 %}{% for i in (1..end) %}{{ i }} {% endfor %}")
+    assert_template_result("2 3 4", "{% assign start = 2 %}{% assign end = 4 %}{% for i in (start..end) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_with_whitespace
+    assert_template_result("1 2 3", "{% for i in ( 1 .. 3 ) %}{{ i }} {% endfor %}")
+    assert_template_result("1 2 3", "{% for i in (1 .. 3) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_with_expressions
+    assert_template_result("3 4 5", "{% assign x = 1 %}{% assign start = x | plus: 2 %}{% for i in (start..5) %}{{ i }} {% endfor %}")
+    assert_template_result("1 2 3", "{% assign x = 2 %}{% assign end = x | plus: 1 %}{% for i in (1..end) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_with_literals_in_iteration
+    assert_template_result("1 2 3 4 5", "{% for i in (1..5) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_size_and_first_last
+    assert_template_result("5", "{{ (1..5) | size }}")
+    assert_template_result("1", "{{ (1..5) | first }}")
+    assert_template_result("5", "{{ (1..5) | last }}")
+  end
+
+  def test_empty_ranges
+    assert_template_result("", "{% for i in (5..1) %}{{ i }}{% endfor %}")
+  end
+
+  def test_ranges_in_conditionals
+    assert_template_result("yes", "{% if 3 >= (1..5) %}no{% else %}yes{% endif %}")
+    assert_template_result("yes", "{% if (1..5) contains 3 %}yes{% else %}no{% endif %}")
+    assert_template_result("no", "{% if (1..5) contains 6 %}yes{% else %}no{% endif %}")
+  end
+
+  def test_range_with_negative_numbers
+    assert_template_result("-3 -2 -1 0", "{% for i in (-3..0) %}{{ i }} {% endfor %}")
+  end
+
+  def test_range_with_floats
+    # Liquid doesn't support float ranges, should either error or not iterate
+    template = "{% for i in (1.5..3.5) %}{{ i }} {% endfor %}"
+    # Floats are rounded down to the nearest integer
+    assert_template_result("1 2 3", template)
+  end
+
+  # def test_ranges_with_calculated_endpoints
+  #   assert_template_result(
+  #     "3 4 5",
+  #     "{% assign start = 1 %}{% assign end = 7 %}{% for i in (start | plus: 2 .. end | minus: 2) %}{{ i }} {% endfor %}",
+  #   )
+  # end
+
+  def test_malformed_ranges
+    # Missing start value
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in (..5) %}{{ i }}{% endfor %}") }
+    # Missing end value
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in (1..) %}{{ i }}{% endfor %}") }
+    # Missing both values
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in (..) %}{{ i }}{% endfor %}") }
+    # Wrong syntax (no parentheses)
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in 1..5 %}{{ i }}{% endfor %}") }
+    # Unbalanced parentheses
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in (1..5 %}{{ i }}{% endfor %}") }
+    # Invalid characters in range
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% for i in (#..@) %}{{ i }}{% endfor %}") }
+    # Invalid range
+    assert_raises(Liquid::SyntaxError) { Liquid::Template.parse("{% assign start = 1 %}{% assign end = 7 %}{% for i in (start | plus: 2 .. end | minus: 2) %}{{ i }} {% endfor %}") }
+  end
+
+  def test_ranges_with_strings_and_variables
+    assert_template_result(
+      "3 4 5",
+      "{% assign range = (3..5) %}{% for i in range %}{{ i }} {% endfor %}",
+    )
+    assert_template_result(
+      "4 5 6",
+      "{% assign start = 4 %}{% assign range = (start..6) %}{% for i in range %}{{ i }} {% endfor %}",
+    )
+  end
+
+  def test_ranges_with_limit_and_offset
+    assert_template_result(
+      "2 3",
+      "{% for i in (1..5) limit:2 offset:1 %}{{ i }} {% endfor %}",
+    )
+    assert_template_result(
+      "3 4 5",
+      "{% for i in (1..5) offset:2 %}{{ i }} {% endfor %}",
+    )
+    assert_template_result(
+      "1 2",
+      "{% for i in (1..5) limit:2 %}{{ i }} {% endfor %}",
+    )
+  end
+
+  def test_reversed_ranges
+    assert_template_result(
+      "5 4 3 2 1",
+      "{% for i in (1..5) reversed %}{{ i }} {% endfor %}",
+    )
+  end
+
+  def test_variable_ranges_with_reversed
+    assert_template_result(
+      "4 3 2 1",
+      "{% assign num = 4 %}{% for i in (1..num) reversed %}{{ i }} {% endfor %}",
+    )
+  end
+
+  def test_assigned_ranges_with_reversed
+    assert_template_result(
+      "5 4 3 2 1",
+      "{% assign range = (1..5) %}{% for i in range reversed %}{{ i }} {% endfor %}",
+    )
+  end
+
+  private
+
+  def assert_template_result(expected, template, assigns = {})
+    assert_equal(expected, Liquid::Template.parse(template).render!(assigns).strip)
+  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

test/unit/template_unit_test.rb

@@ -35,4 +35,15 @@ class TemplateUnitTest < Minitest::Test
   def test_template_inheritance
     assert_equal("foo", TemplateSubclass.parse("foo").render)
   end
+
+  def test_invalid_utf8
+    input = "\xff\x00"
+    error = assert_raises(SyntaxError) do
+      Liquid::Tokenizer.new(source: input, string_scanner: StringScanner.new(input))
+    end
+    assert_equal(
+      'Liquid syntax error: Invalid byte sequence in UTF-8',
+      error.message,
+    )
+  end
 end