liquid 5.3.0 → 5.4.0

data/lib/liquid/strainer_factory.rb

@@ -14,6 +14,10 @@ module Liquid
       strainer_from_cache(filters).new(context)
     end
 
+    def global_filter_names
+      GlobalCache.filter_method_names
+    end
+
     GlobalCache = Class.new(StrainerTemplate)
 
     private

data/lib/liquid/strainer_template.rb

@@ -36,6 +36,10 @@ module Liquid
         subclass.instance_variable_set(:@filter_methods, @filter_methods.dup)
       end
 
+      def filter_method_names
+        filter_methods.map(&:to_s).to_a
+      end
+
       private
 
       def filter_methods

data/lib/liquid/tablerowloop_drop.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Liquid
+  # @liquid_public_docs
+  # @liquid_type object
+  # @liquid_name tablerowloop
+  # @liquid_summary
+  #   Information about a parent [`tablerow` loop](/api/liquid/tags#tablerow).
   class TablerowloopDrop < Drop
     def initialize(length, cols)
       @length = length
@@ -10,40 +15,92 @@ module Liquid
       @index  = 0
     end
 
-    attr_reader :length, :col, :row
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The total number of iterations in the loop.
+    # @liquid_return [number]
+    attr_reader :length
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 1-based index of the current column.
+    # @liquid_return [number]
+    attr_reader :col
+
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 1-based index of current row.
+    # @liquid_return [number]
+    attr_reader :row
+
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 1-based index of the current iteration.
+    # @liquid_return [number]
     def index
       @index + 1
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 0-based index of the current iteration.
+    # @liquid_return [number]
     def index0
       @index
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 0-based index of the current column.
+    # @liquid_return [number]
     def col0
       @col - 1
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 1-based index of the current iteration, in reverse order.
+    # @liquid_return [number]
     def rindex
       @length - @index
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   The 0-based index of the current iteration, in reverse order.
+    # @liquid_return [number]
     def rindex0
       @length - @index - 1
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   Returns `true` if the current iteration is the first. Returns `false` if not.
+    # @liquid_return [boolean]
     def first
       @index == 0
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   Returns `true` if the current iteration is the last. Returns `false` if not.
+    # @liquid_return [boolean]
     def last
       @index == @length - 1
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   Returns `true` if the current column is the first in the row. Returns `false` if not.
+    # @liquid_return [boolean]
     def col_first
       @col == 1
     end
 
+    # @liquid_public_docs
+    # @liquid_summary
+    #   Returns `true` if the current column is the last in the row. Returns `false` if not.
+    # @liquid_return [boolean]
     def col_last
       @col == @cols
     end

data/lib/liquid/tags/assign.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Assign sets a variable in your template.
-  #
-  #   {% assign foo = 'monkey' %}
-  #
-  # You can then use the variable later in the page.
-  #
-  #  {{ foo }}
-  #
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category variable
+  # @liquid_name assign
+  # @liquid_summary
+  #   Creates a new variable.
+  # @liquid_description
+  #   You can create variables of any [basic type](/api/liquid/basics#types), [object](/api/liquid/objects), or object property.
+  # @liquid_syntax
+  #   {% assign variable_name = value %}
+  # @liquid_syntax_keyword variable_name The name of the variable being created.
+  # @liquid_syntax_keyword value The value you want to assign to the variable.
   class Assign < Tag
     Syntax = /(#{VariableSignature}+)\s*=\s*(.*)\s*/om
 

data/lib/liquid/tags/break.rb

@@ -10,6 +10,14 @@ module Liquid
   #      {% endif %}
   #    {% endfor %}
   #
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category iteration
+  # @liquid_name break
+  # @liquid_summary
+  #   Stops a [`for` loop](/api/liquid/tags#for) from iterating.
+  # @liquid_syntax
+  #   {% break %}
   class Break < Tag
     INTERRUPT = BreakInterrupt.new.freeze
 

data/lib/liquid/tags/capture.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Capture stores the result of a block into a variable without rendering it inplace.
-  #
-  #   {% capture heading %}
-  #     Monkeys!
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category variable
+  # @liquid_name capture
+  # @liquid_summary
+  #   Creates a new variable with a string value.
+  # @liquid_description
+  #   You can create complex strings with Liquid logic and variables.
+  # @liquid_syntax
+  #   {% capture variable %}
+  #     value
   #   {% endcapture %}
-  #   ...
-  #   <h1>{{ heading }}</h1>
-  #
-  # Capture is useful for saving content for use later in your template, such as
-  # in a sidebar or footer.
-  #
+  # @liquid_syntax_keyword variable The name of the variable being created.
+  # @liquid_syntax_keyword value The value you want to assign to the variable.
   class Capture < Block
     Syntax = /(#{VariableSignature}+)/o
 

data/lib/liquid/tags/case.rb

@@ -1,6 +1,27 @@
 # frozen_string_literal: true
 
 module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category conditional
+  # @liquid_name case
+  # @liquid_summary
+  #   Renders a specific expression depending on the value of a specific variable.
+  # @liquid_syntax
+  #   {% case variable %}
+  #     {% when first_value %}
+  #       first_expression
+  #     {% when second_value %}
+  #       second_expression
+  #     {% else %}
+  #       third_expression
+  #   {% endcase %}
+  # @liquid_syntax_keyword variable The name of the variable you want to base your case statement on.
+  # @liquid_syntax_keyword first_value A specific value to check for.
+  # @liquid_syntax_keyword second_value A specific value to check for.
+  # @liquid_syntax_keyword first_expression An expression to be rendered when the variable's value matches `first_value`.
+  # @liquid_syntax_keyword second_expression An expression to be rendered when the variable's value matches `second_value`.
+  # @liquid_syntax_keyword third_expression An expression to be rendered when the variable's value has no match.
   class Case < Block
     Syntax     = /(#{QuotedFragment})/o
     WhenSyntax = /(#{QuotedFragment})(?:(?:\s+or\s+|\s*\,\s*)(#{QuotedFragment}.*))?/om

data/lib/liquid/tags/comment.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name comment
+  # @liquid_summary
+  #   Prevents an expression from being rendered or output.
+  # @liquid_description
+  #   Any text inside `comment` tags won't be output, and any Liquid code won't be rendered.
+  # @liquid_syntax
+  #   {% comment %}
+  #     content
+  #   {% endcomment %}
+  # @liquid_syntax_keyword content The content of the comment.
   class Comment < Block
     def render_to_output_buffer(_context, output)
       output

data/lib/liquid/tags/continue.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Continue tag to be used to break out of a for loop.
-  #
-  # == Basic Usage:
-  #    {% for item in collection %}
-  #      {% if item.condition %}
-  #        {% continue %}
-  #      {% endif %}
-  #    {% endfor %}
-  #
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category iteration
+  # @liquid_name continue
+  # @liquid_summary
+  #   Causes a [`for` loop](/api/liquid/tags#for) to skip to the next iteration.
+  # @liquid_syntax
+  #   {% continue %}
   class Continue < Tag
     INTERRUPT = ContinueInterrupt.new.freeze
 

data/lib/liquid/tags/cycle.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
-  #
-  #   {% for item in items %}
-  #     <div class="{% cycle 'red', 'green', 'blue' %}"> {{ item }} </div>
-  #   {% end %}
-  #
-  #    <div class="red"> Item one </div>
-  #    <div class="green"> Item two </div>
-  #    <div class="blue"> Item three </div>
-  #    <div class="red"> Item four </div>
-  #    <div class="green"> Item five</div>
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category iteration
+  # @liquid_name cycle
+  # @liquid_summary
+  #   Loops through a group of strings and outputs them one at a time for each iteration of a [`for` loop](/api/liquid/tags#for).
+  # @liquid_description
+  #   The `cycle` tag must be used inside a `for` loop.
   #
+  #   > Tip:
+  #   > Use the `cycle` tag to output text in a predictable pattern. For example, to apply odd/even classes to rows in a table.
+  # @liquid_syntax
+  #   {% cycle string, string, ... %}
   class Cycle < Tag
     SimpleSyntax = /\A#{QuotedFragment}+/o
     NamedSyntax  = /\A(#{QuotedFragment})\s*\:\s*(.*)/om

data/lib/liquid/tags/decrement.rb

@@ -1,24 +1,23 @@
 # frozen_string_literal: true
 
 module Liquid
-  # decrement is used in a place where one needs to insert a counter
-  #     into a template, and needs the counter to survive across
-  #     multiple instantiations of the template.
-  #     NOTE: decrement is a pre-decrement, --i,
-  #           while increment is post:      i++.
-  #
-  #     (To achieve the survival, the application must keep the context)
-  #
-  #     if the variable does not exist, it is created with value 0.
-
-  #   Hello: {% decrement variable %}
-  #
-  # gives you:
-  #
-  #    Hello: -1
-  #    Hello: -2
-  #    Hello: -3
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category variable
+  # @liquid_name decrement
+  # @liquid_summary
+  #   Creates a new variable, with a default value of -1, that's decreased by 1 with each subsequent call.
+  # @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
+  #   [snippets](/themes/architecture#snippets) included in the file.
   #
+  #   Similarly, variables that are created with `decrement` are independent from those created with [`assign`](/api/liquid/tags#assign)
+  #   and [`capture`](/api/liquid/tags#capture). However, `decrement` and [`increment`](/api/liquid/tags#increment) share
+  #   variables.
+  # @liquid_syntax
+  #   {% decrement variable_name %}
+  # @liquid_syntax_keyword variable_name The name of the variable being decremented.
   class Decrement < Tag
     def initialize(tag_name, markup, options)
       super

data/lib/liquid/tags/echo.rb

@@ -1,16 +1,23 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Echo outputs an expression
-  #
-  #   {% echo monkey %}
-  #   {% echo user.name %}
-  #
-  # This is identical to variable output syntax, like {{ foo }}, but works
-  # inside {% liquid %} tags. The full syntax is supported, including filters:
-  #
-  #   {% echo user | link %}
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name echo
+  # @liquid_summary
+  #   Outputs an expression.
+  # @liquid_description
+  #   Using the `echo` tag is the same as wrapping an expression in curly brackets (`{{` and `}}`). However, unlike the curly
+  #   bracket method, you can use the `echo` tag inside [`liquid` tags](/api/liquid/tags#liquid).
   #
+  #   > Tip:
+  #   > You can use [filters](/api/liquid/filters) on expressions inside `echo` tags.
+  # @liquid_syntax
+  #   {% liquid
+  #     echo expression
+  #   %}
+  # @liquid_syntax_keyword expression The expression to be output.
   class Echo < Tag
     attr_reader :variable
 

data/lib/liquid/tags/for.rb

@@ -1,50 +1,29 @@
 # frozen_string_literal: true
 
 module Liquid
-  # "For" iterates over an array or collection.
-  # Several useful variables are available to you within the loop.
-  #
-  # == Basic usage:
-  #    {% for item in collection %}
-  #      {{ forloop.index }}: {{ item.name }}
-  #    {% endfor %}
-  #
-  # == Advanced usage:
-  #    {% for item in collection %}
-  #      <div {% if forloop.first %}class="first"{% endif %}>
-  #        Item {{ forloop.index }}: {{ item.name }}
-  #      </div>
-  #    {% else %}
-  #      There is nothing in the collection.
-  #    {% endfor %}
-  #
-  # You can also define a limit and offset much like SQL.  Remember
-  # that offset starts at 0 for the first item.
-  #
-  #    {% for item in collection limit:5 offset:10 %}
-  #      {{ item.name }}
-  #    {% end %}
-  #
-  #  To reverse the for loop simply use {% for item in collection reversed %} (note that the flag's spelling is different to the filter `reverse`)
-  #
-  # == Available variables:
-  #
-  # forloop.name:: 'item-collection'
-  # forloop.length:: Length of the loop
-  # forloop.index:: The current item's position in the collection;
-  #                 forloop.index starts at 1.
-  #                 This is helpful for non-programmers who start believe
-  #                 the first item in an array is 1, not 0.
-  # forloop.index0:: The current item's position in the collection
-  #                  where the first item is 0
-  # forloop.rindex:: Number of items remaining in the loop
-  #                  (length - index) where 1 is the last item.
-  # forloop.rindex0:: Number of items remaining in the loop
-  #                   where 0 is the last item.
-  # forloop.first:: Returns true if the item is the first item.
-  # forloop.last:: Returns true if the item is the last item.
-  # forloop.parentloop:: Provides access to the parent loop, if present.
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category iteration
+  # @liquid_name for
+  # @liquid_summary
+  #   Renders an expression for every item in an array.
+  # @liquid_description
+  #   You can do a maximum of 50 iterations with a `for` loop. If you need to iterate over more than 50 items, then use the
+  #   [`paginate` tag](/api/liquid/tags#paginate) to split the items over multiple pages.
   #
+  #   > Tip:
+  #   > Every `for` loop has an associated [`forloop` object](/api/liquid/objects#forloop) with information about the loop.
+  # @liquid_syntax
+  #   {% for variable in array %}
+  #     expression
+  #   {% endfor %}
+  # @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 range [untyped] A custom numeric range to iterate over.
+  # @liquid_optional_param reversed [untyped] Iterate in reverse order.
   class For < Block
     Syntax = /\A(#{VariableSegment}+)\s+in\s+(#{QuotedFragment}+)\s*(reversed)?/o
 

data/lib/liquid/tags/if.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 module Liquid
-  # If is the conditional block
-  #
-  #   {% if user.admin %}
-  #     Admin user!
-  #   {% else %}
-  #     Not admin user
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category conditional
+  # @liquid_name if
+  # @liquid_summary
+  #   Renders an expression if a specific condition is `true`.
+  # @liquid_syntax
+  #   {% if condition %}
+  #     expression
   #   {% endif %}
-  #
-  #    There are {% if count < 5 %} less {% else %} more {% endif %} items than you need.
-  #
+  # @liquid_syntax_keyword condition The condition to evaluate.
+  # @liquid_syntax_keyword expression The expression to render if the condition is met.
   class If < Block
     Syntax                  = /(#{QuotedFragment})\s*([=!<>a-z_]+)?\s*(#{QuotedFragment})?/o
     ExpressionsAndOperators = /(?:\b(?:\s?and\s?|\s?or\s?)\b|(?:\s*(?!\b(?:\s?and\s?|\s?or\s?)\b)(?:#{QuotedFragment}|\S+)\s*)+)/o

data/lib/liquid/tags/include.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Include allows templates to relate with other templates
-  #
-  # Simply include another template:
-  #
-  #   {% include 'product' %}
-  #
-  # Include a template with a local variable:
-  #
-  #   {% include 'product' with products[0] %}
-  #
-  # Include a template for a collection:
-  #
-  #   {% include 'product' for products %}
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category theme
+  # @liquid_name include
+  # @liquid_summary
+  #   Renders a [snippet](/themes/architecture#snippets).
+  # @liquid_description
+  #   Inside the snippet, you can access and alter variables that are [created](/api/liquid/tags#variable-tags) outside of the
+  #   snippet.
+  # @liquid_syntax
+  #   {% include 'filename' %}
+  # @liquid_syntax_keyword filename The name of the snippet to render, without the `.liquid` extension.
+  # @liquid_deprecated
+  #   Deprecated because the way that variables are handled reduces performance and makes code harder to both read and maintain.
   #
+  #   The `include` tag has been replaced by [`render`](/api/liquid/tags#render).
   class Include < Tag
     prepend Tag::Disableable
 

data/lib/liquid/tags/increment.rb

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
 module Liquid
-  # increment is used in a place where one needs to insert a counter
-  #     into a template, and needs the counter to survive across
-  #     multiple instantiations of the template.
-  #     (To achieve the survival, the application must keep the context)
-  #
-  #     if the variable does not exist, it is created with value 0.
-  #
-  #   Hello: {% increment variable %}
-  #
-  # gives you:
-  #
-  #    Hello: 0
-  #    Hello: 1
-  #    Hello: 2
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category variable
+  # @liquid_name increment
+  # @liquid_summary
+  #   Creates a new variable, with a default value of 0, that's increased by 1 with each subsequent call.
+  # @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
+  #   [snippets](/themes/architecture#snippets) included in the file.
   #
+  #   Similarly, variables that are created with `increment` are independent from those created with [`assign`](/api/liquid/tags#assign)
+  #   and [`capture`](/api/liquid/tags#capture). However, `increment` and [`decrement`](/api/liquid/tags#decrement) share
+  #   variables.
+  # @liquid_syntax
+  #   {% increment variable_name %}
+  # @liquid_syntax_keyword variable_name The name of the variable being incremented.
   class Increment < Tag
     def initialize(tag_name, markup, options)
       super

data/lib/liquid/tags/inline_comment.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name inline_comment
+  # @liquid_summary
+  #   Prevents an expression from being rendered or output.
+  # @liquid_description
+  #   Any text inside an `inline_comment` tag won't be rendered or output.
+  #
+  #   You can create multi-line inline comments. However, each line must begin with a `#`.
+  # @liquid_syntax
+  #   {% # content %}
+  # @liquid_syntax_keyword content The content of the comment.
+  class InlineComment < Tag
+    def initialize(tag_name, markup, options)
+      super
+
+      # Semantically, a comment should only ignore everything after it on the line.
+      # Currently, this implementation doesn't support mixing a comment with another tag
+      # but we need to reserve future support for this and prevent the introduction
+      # of inline comments from being backward incompatible change.
+      #
+      # As such, we're forcing users to put a # symbol on every line otherwise this
+      # tag will throw an error.
+      if markup.match?(/\n\s*[^#\s]/)
+        raise SyntaxError, options[:locale].t("errors.syntax.inline_comment_invalid")
+      end
+    end
+
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def blank?
+      true
+    end
+  end
+
+  Template.register_tag('#', InlineComment)
+end

data/lib/liquid/tags/raw.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name raw
+  # @liquid_summary
+  #   Outputs any Liquid code as text instead of rendering it.
+  # @liquid_syntax
+  #   {% raw %}
+  #     expression
+  #   {% endraw %}
+  # @liquid_syntax_keyword expression The expression to be output without being rendered.
   class Raw < Block
     Syntax = /\A\s*\z/
     FullTokenPossiblyInvalid = /\A(.*)#{TagStart}\s*(\w+)\s*(.*)?#{TagEnd}\z/om