Update liquid docs for loop's named params

template.rb: Correct typo in docs

.github/dependabot.yaml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/liquid.yml

@@ -31,8 +31,8 @@ jobs:
           - { ruby: ruby-head, allowed-failure: false, rubyopt: "--yjit" }
     name: Test Ruby ${{ matrix.entry.ruby }}
     steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+      - uses: ruby/setup-ruby@dffc446db9ba5a0c4446edb5bca1c5c473a806c5 # v1.235.0
         with:
           ruby-version: ${{ matrix.entry.ruby }}
           bundler-cache: true
@@ -45,8 +45,8 @@ jobs:
   memory_profile:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+      - uses: ruby/setup-ruby@dffc446db9ba5a0c4446edb5bca1c5c473a806c5 # v1.235.0
         with:
           bundler-cache: true
       - run: bundle exec rake memory_profile:run

History.md

@@ -1,6 +1,7 @@
 # Liquid Change Log
 
-## 5.8.1 (unreleased)
+## 5.8.7
+* Expose body content in the `Doc` tag [James Meng]
 
 ## 5.8.1
 

lib/liquid/standardfilters.rb

@@ -386,7 +386,6 @@ module Liquid
         end
       elsif ary.all? { |el| el.respond_to?(:[]) }
         begin
-          property = Utils.to_s(property)
           ary.sort { |a, b| nil_safe_compare(a[property], b[property]) }
         rescue TypeError
           raise_property_error(property)
@@ -416,7 +415,6 @@ module Liquid
         end
       elsif ary.all? { |el| el.respond_to?(:[]) }
         begin
-          property = Utils.to_s(property)
           ary.sort { |a, b| nil_safe_casecmp(a[property], b[property]) }
         rescue TypeError
           raise_property_error(property)
@@ -504,7 +502,6 @@ module Liquid
       elsif ary.empty? # The next two cases assume a non-empty array.
         []
       else
-        property = Utils.to_s(property)
         ary.uniq do |item|
           item[property]
         rescue TypeError
@@ -536,11 +533,6 @@ module Liquid
     # @liquid_syntax array | map: string
     # @liquid_return [array[untyped]]
     def map(input, property)
-      property = Utils.to_s(property)
-
-      # Return the input array if property is empty (no-op)
-      return InputIterator.new(input, context).to_a if property.empty?
-
       InputIterator.new(input, context).map do |e|
         e = e.call if e.is_a?(Proc)
 
@@ -570,7 +562,6 @@ module Liquid
       elsif ary.empty? # The next two cases assume a non-empty array.
         []
       else
-        property = Liquid::Utils.to_s(property)
         ary.reject do |item|
           item[property].nil?
         rescue TypeError
@@ -960,8 +951,6 @@ module Liquid
     # @liquid_syntax array | sum
     # @liquid_return [number]
     def sum(input, property = nil)
-      property = property.nil? ? nil : Utils.to_s(property)
-
       ary = InputIterator.new(input, context)
       return 0 if ary.empty?
 
@@ -990,9 +979,8 @@ module Liquid
 
     def filter_array(input, property, target_value, default_value = [], &block)
       ary = InputIterator.new(input, context)
-      return default_value if ary.empty?
 
-      property = Utils.to_s(property)
+      return default_value if ary.empty?
 
       block.call(ary) do |item|
         if target_value.nil?
@@ -1009,7 +997,7 @@ module Liquid
     end
 
     def raise_property_error(property)
-      raise Liquid::ArgumentError, "cannot select the property '#{property}'"
+      raise Liquid::ArgumentError, "cannot select the property '#{Utils.to_s(property)}'"
     end
 
     def apply_operation(input, operand, operation)
@@ -1081,7 +1069,10 @@ module Liquid
       end
 
       def uniq(&block)
-        to_a.uniq(&block)
+        to_a.uniq do |item|
+          item = Utils.to_liquid_value(item)
+          block ? yield(item) : item
+        end
       end
 
       def compact

lib/liquid/tags/assign.rb

@@ -9,6 +9,10 @@ module Liquid
   #   Creates a new variable.
   # @liquid_description
   #   You can create variables of any [basic type](/docs/api/liquid/basics#types), [object](/docs/api/liquid/objects), or object property.
+  #
+  #   > Caution:
+  #   > Predefined Liquid objects can be overridden by variables with the same name.
+  #   > To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.
   # @liquid_syntax
   #   {% assign variable_name = value %}
   # @liquid_syntax_keyword variable_name The name of the variable being created.

lib/liquid/tags/capture.rb

@@ -9,6 +9,10 @@ module Liquid
   #   Creates a new variable with a string value.
   # @liquid_description
   #   You can create complex strings with Liquid logic and variables.
+  #
+  #   > Caution:
+  #   > Predefined Liquid objects can be overridden by variables with the same name.
+  #   > To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.
   # @liquid_syntax
   #   {% capture variable %}
   #     value

lib/liquid/tags/decrement.rb

@@ -7,6 +7,10 @@ module Liquid
   # @liquid_name decrement
   # @liquid_summary
   #   Creates a new variable, with a default value of -1, that's decreased by 1 with each subsequent call.
+  #
+  #   > Caution:
+  #   > Predefined Liquid objects can be overridden by variables with the same name.
+  #   > To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.
   # @liquid_description
   #   Variables that are declared with `decrement` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
   #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across

lib/liquid/tags/doc.rb

@@ -27,7 +27,6 @@ module Liquid
   #     @example
   #     {% render 'message', foo: 'Hello', bar: 'World' %}
   #   {% enddoc %}
-  #   {{ foo }}, {{ bar }}!
   class Doc < Block
     NO_UNEXPECTED_ARGS = /\A\s*\z/
 
@@ -37,6 +36,8 @@ module Liquid
     end
 
     def parse(tokens)
+      @body = +""
+
       while (token = tokens.shift)
         tag_name = token =~ BlockBody::FullTokenPossiblyInvalid && Regexp.last_match(2)
 
@@ -44,8 +45,10 @@ module Liquid
 
         if tag_name == block_delimiter
           parse_context.trim_whitespace = (token[-3] == WhitespaceControl)
+          @body << Regexp.last_match(1) if Regexp.last_match(1) != ""
           return
         end
+        @body << token unless token.empty?
       end
 
       raise_tag_never_closed(block_name)
@@ -56,11 +59,11 @@ module Liquid
     end
 
     def blank?
-      true
+      @body.empty?
     end
 
     def nodelist
-      []
+      [@body]
     end
 
     private

lib/liquid/tags/for.rb

@@ -20,8 +20,8 @@ module Liquid
   # @liquid_syntax_keyword variable The current item in the array.
   # @liquid_syntax_keyword array The array to iterate over.
   # @liquid_syntax_keyword expression The expression to render for each iteration.
-  # @liquid_optional_param limit [number] The number of iterations to perform.
-  # @liquid_optional_param offset [number] The 1-based index to start iterating at.
+  # @liquid_optional_param limit: [number] The number of iterations to perform.
+  # @liquid_optional_param offset: [number] The 1-based index to start iterating at.
   # @liquid_optional_param range [untyped] A custom numeric range to iterate over.
   # @liquid_optional_param reversed [untyped] Iterate in reverse order.
   class For < Block

lib/liquid/tags/increment.rb

@@ -7,6 +7,10 @@ module Liquid
   # @liquid_name increment
   # @liquid_summary
   #   Creates a new variable, with a default value of 0, that's increased by 1 with each subsequent call.
+  #
+  #   > Caution:
+  #   > Predefined Liquid objects can be overridden by variables with the same name.
+  #   > To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.
   # @liquid_description
   #   Variables that are declared with `increment` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
   #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across

lib/liquid/tags/table_row.rb

@@ -19,9 +19,9 @@ module Liquid
   # @liquid_syntax_keyword variable The current item in the array.
   # @liquid_syntax_keyword array The array to iterate over.
   # @liquid_syntax_keyword expression The expression to render.
-  # @liquid_optional_param cols [number] The number of columns that the table should have.
-  # @liquid_optional_param limit [number] The number of iterations to perform.
-  # @liquid_optional_param offset [number] The 1-based index to start iterating at.
+  # @liquid_optional_param cols: [number] The number of columns that the table should have.
+  # @liquid_optional_param limit: [number] The number of iterations to perform.
+  # @liquid_optional_param offset: [number] The 1-based index to start iterating at.
   # @liquid_optional_param range [untyped] A custom numeric range to iterate over.
   class TableRow < Block
     Syntax = /(\w+)\s+in\s+(#{QuotedFragment}+)/o

lib/liquid/template.rb

@@ -2,7 +2,7 @@
 
 module Liquid
   # Templates are central to liquid.
-  # Interpretating templates is a two step process. First you compile the
+  # Interpreting templates is a two step process. First you compile the
   # source code you got. During compile time some extensive error checking is performed.
   # your code should expect to get some SyntaxErrors.
   #

lib/liquid/version.rb

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

test/integration/standard_filter_test.rb

@@ -560,26 +560,6 @@ class StandardFiltersTest < Minitest::Test
     end
   end
 
-  def test_map_with_nil_property
-    array = [
-      { "handle" => "alpha", "value" => "A" },
-      { "handle" => "beta", "value" => "B" },
-      { "handle" => "gamma", "value" => "C" }
-    ]
-
-    assert_template_result("alpha beta gamma", "{{ array | map: nil | map: 'handle' | join: ' ' }}", { "array" => array })
-  end
-
-  def test_map_with_empty_string_property
-    array = [
-      { "handle" => "alpha", "value" => "A" },
-      { "handle" => "beta", "value" => "B" },
-      { "handle" => "gamma", "value" => "C" }
-    ]
-
-    assert_template_result("alpha beta gamma", "{{ array | map: '' | map: 'handle' | join: ' ' }}", { "array" => array })
-  end
-
   def test_map_with_value_property
     array = [
       { "handle" => "alpha", "value" => "A" },
@@ -591,16 +571,15 @@ class StandardFiltersTest < Minitest::Test
   end
 
   def test_map_returns_input_with_no_property
-    input = [
+    foo = [
       [1],
       [2],
       [3],
     ]
-    result = @filters.map(input, nil)
-    assert_equal(input.flatten, result)
 
-    result = @filters.map(input, '')
-    assert_equal(input.flatten, result)
+    assert_raises(Liquid::ArgumentError) do
+      @filters.map(foo, nil)
+    end
   end
 
   def test_sort_works_on_enumerables
@@ -1075,10 +1054,11 @@ class StandardFiltersTest < Minitest::Test
 
   def test_where_with_nil_is_a_no_op
     environment = { "array" => ["alpha", "beta", "gamma"] }
-    expected_output = "alpha beta gamma"
     template = "{{ array | where: nil | join: ' ' }}"
 
-    assert_template_result(expected_output, template, environment)
+    assert_raises(Liquid::ArgumentError) do
+      assert_template_result("alpha beta gamma", template, environment)
+    end
   end
 
   def test_where_with_value
@@ -1109,19 +1089,6 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "array" => array })
   end
 
-  def test_where_with_non_string_property
-    array = [
-      { "handle" => "alpha", "{}" => true },
-      { "handle" => "beta", "{}" => false },
-      { "handle" => "gamma", "{}" => false },
-      { "handle" => "delta", "{}" => true },
-    ]
-    template = "{{ array | where: some_property, true | map: 'handle' | join: ' ' }}"
-    expected_output = "alpha delta"
-
-    assert_template_result(expected_output, template, { "array" => array, "some_property" => {} })
-  end
-
   def test_where_string_keys
     input = [
       "alpha", "beta", "gamma", "delta"
@@ -1330,7 +1297,7 @@ class StandardFiltersTest < Minitest::Test
   end
 
   def test_sum_with_non_string_property
-    input = [{ "true" => 1 }, { "1.0" => 0.2, "1" => -0.3 }, { "1..5" => 0.4 }]
+    input = [{ true => 1 }, { 1.0 => 0.2, 1 => -0.3 }, { 1..5 => 0.4 }]
 
     assert_equal(1, @filters.sum(input, true))
     assert_equal(0.2, @filters.sum(input, 1.0))
@@ -1340,6 +1307,22 @@ class StandardFiltersTest < Minitest::Test
     assert_equal(0, @filters.sum(input, ""))
   end
 
+  def test_uniq_with_to_liquid_value
+    input = [StringDrop.new("foo"), StringDrop.new("bar"), "foo"]
+    expected = [StringDrop.new("foo"), StringDrop.new("bar")]
+    result = @filters.uniq(input)
+
+    assert_equal(expected, result)
+  end
+
+  def test_uniq_with_to_liquid_value_pick_correct_classes
+    input = ["foo", StringDrop.new("foo"), StringDrop.new("bar")]
+    expected = [String, StringDrop]
+    result = @filters.uniq(input).map(&:class)
+
+    assert_equal(expected, result)
+  end
+
   private
 
   def with_timezone(tz)

test/test_helper.rb

@@ -146,6 +146,35 @@ class BooleanDrop < Liquid::Drop
   end
 end
 
+class StringDrop < Liquid::Drop
+  include Comparable
+
+  def initialize(value)
+    super()
+    @value = value
+  end
+
+  def to_liquid_value
+    @value
+  end
+
+  def to_s
+    @value
+  end
+
+  def to_str
+    @value
+  end
+
+  def inspect
+    "#<StringDrop @value=#{@value.inspect}>"
+  end
+
+  def <=>(other)
+    to_liquid_value <=> Liquid::Utils.to_liquid_value(other)
+  end
+end
+
 class ErrorDrop < Liquid::Drop
   def standard_error
     raise Liquid::StandardError, 'standard error'

test/unit/environment_test.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class EnvironmentTest < Minitest::Test
+  include Liquid
+
+  class UnsubscribeFooter < Liquid::Tag
+    def render(_context)
+      'Unsubscribe Footer'
+    end
+  end
+
+  def test_custom_tag
+    email_environment = Liquid::Environment.build do |environment|
+      environment.register_tag("unsubscribe_footer", UnsubscribeFooter)
+    end
+
+    assert(email_environment.tags["unsubscribe_footer"])
+    assert(email_environment.tag_for_name("unsubscribe_footer"))
+    template = Liquid::Template.parse("{% unsubscribe_footer %}", environment: email_environment)
+
+    assert_equal('Unsubscribe Footer', template.render)
+  end
+end

test/unit/tags/doc_tag_unit_test.rb

@@ -20,6 +20,21 @@ class DocTagUnitTest < Minitest::Test
     assert_template_result('', template)
   end
 
+  def test_doc_tag_body_content
+    doc_content = "  Documentation content\n  @param {string} foo - test\n"
+    template_source = "{% doc %}#{doc_content}{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal(doc_content, doc_tag.nodelist.first.to_s)
+  end
+
   def test_doc_tag_does_not_support_extra_arguments
     error = assert_raises(Liquid::SyntaxError) do
       template = <<~LIQUID.chomp
@@ -116,6 +131,20 @@ class DocTagUnitTest < Minitest::Test
     assert_template_result('', template)
   end
 
+  def test_doc_tag_captures_token_before_enddoc
+    template_source = "{% doc %}{{ incomplete{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal("{{ incomplete", doc_tag.nodelist.first.to_s)
+  end
+
   def test_doc_tag_preserves_error_line_numbers
     template = Liquid::Template.parse(<<~LIQUID.chomp, line_numbers: true)
       {% doc %}
@@ -145,11 +174,11 @@ class DocTagUnitTest < Minitest::Test
 
   def test_doc_tag_delimiter_handling
     assert_template_result('', <<~LIQUID.chomp)
-      {% if true %}
-        {% doc %}
-          {% docEXTRA %}wut{% enddocEXTRA %}xyz
-        {% enddoc %}
-      {% endif %}
+      {%- if true -%}
+        {%- doc -%}
+          {%- docEXTRA -%}wut{% enddocEXTRA -%}xyz
+        {%- enddoc -%}
+      {%- endif -%}
     LIQUID
 
     assert_template_result('', "{% doc %}123{% enddoc xyz %}")
@@ -167,6 +196,80 @@ class DocTagUnitTest < Minitest::Test
     )
   end
 
+  def test_doc_tag_blank_with_empty_content
+    template_source = "{% doc %}{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal(true, doc_tag.blank?)
+  end
+
+  def test_doc_tag_blank_with_content
+    template_source = "{% doc %}Some documentation{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal(false, doc_tag.blank?)
+  end
+
+  def test_doc_tag_blank_with_whitespace_only
+    template_source = "{% doc %}    {% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal(false, doc_tag.blank?)
+  end
+
+  def test_doc_tag_nodelist_returns_array_with_body
+    doc_content = "Documentation content\n@param {string} foo"
+    template_source = "{% doc %}#{doc_content}{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal([doc_content], doc_tag.nodelist)
+    assert_equal(1, doc_tag.nodelist.length)
+    assert_equal(doc_content, doc_tag.nodelist.first)
+  end
+
+  def test_doc_tag_nodelist_with_empty_content
+    template_source = "{% doc %}{% enddoc %}"
+
+    doc_tag = nil
+    ParseTreeVisitor
+      .for(Template.parse(template_source).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        doc_tag = tag
+      end
+      .visit
+
+    assert_equal([""], doc_tag.nodelist)
+    assert_equal(1, doc_tag.nodelist.length)
+  end
+
   private
 
   def traversal(template)