liquid 2.6.3 → 5.4.0

data/lib/liquid/tags/comment.rb

@@ -1,7 +1,29 @@
+# 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(context)
-      ''
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def unknown_tag(_tag, _markup, _tokens)
+    end
+
+    def blank?
+      true
     end
   end
 

data/lib/liquid/tags/continue.rb

@@ -1,20 +1,21 @@
-module Liquid
+# frozen_string_literal: true
 
-  # Continue tag to be used to break out of a for loop.
-  #
-  # == Basic Usage:
-  #    {% for item in collection %}
-  #      {% if item.condition %}
-  #        {% continue %}
-  #      {% endif %}
-  #    {% endfor %}
-  #
+module Liquid
+  # @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
 
-    def interrupt
-      ContinueInterrupt.new
+    def render_to_output_buffer(context, output)
+      context.push_interrupt(INTERRUPT)
+      output
     end
-
   end
 
   Template.register_tag('continue', Continue)

data/lib/liquid/tags/cycle.rb

@@ -1,47 +1,60 @@
-module Liquid
+# frozen_string_literal: true
 
-  # 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>
+module Liquid
+  # @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 = /^#{QuotedFragment}+/o
-    NamedSyntax  = /^(#{QuotedFragment})\s*\:\s*(.*)/o
+    SimpleSyntax = /\A#{QuotedFragment}+/o
+    NamedSyntax  = /\A(#{QuotedFragment})\s*\:\s*(.*)/om
 
-    def initialize(tag_name, markup, tokens)
+    attr_reader :variables
+
+    def initialize(tag_name, markup, options)
+      super
       case markup
       when NamedSyntax
-        @variables = variables_from_string($2)
-        @name = $1
+        @variables = variables_from_string(Regexp.last_match(2))
+        @name      = parse_expression(Regexp.last_match(1))
       when SimpleSyntax
         @variables = variables_from_string(markup)
-        @name = "'#{@variables.to_s}'"
+        @name      = @variables.to_s
       else
-        raise SyntaxError.new("Syntax Error in 'cycle' - Valid syntax: cycle [name :] var [, var2, var3 ...]")
+        raise SyntaxError, options[:locale].t("errors.syntax.cycle")
       end
-      super
     end
 
-    def render(context)
-      context.registers[:cycle] ||= Hash.new(0)
-
-      context.stack do
-        key = context[@name]
-        iteration = context.registers[:cycle][key]
-        result = context[@variables[iteration]]
-        iteration += 1
-        iteration  = 0  if iteration >= @variables.size
-        context.registers[:cycle][key] = iteration
-        result
+    def render_to_output_buffer(context, output)
+      context.registers[:cycle] ||= {}
+
+      key       = context.evaluate(@name)
+      iteration = context.registers[:cycle][key].to_i
+
+      val = context.evaluate(@variables[iteration])
+
+      if val.is_a?(Array)
+        val = val.join
+      elsif !val.is_a?(String)
+        val = val.to_s
       end
+
+      output << val
+
+      iteration += 1
+      iteration = 0 if iteration >= @variables.size
+
+      context.registers[:cycle][key] = iteration
+      output
     end
 
     private
@@ -49,10 +62,15 @@ module Liquid
     def variables_from_string(markup)
       markup.split(',').collect do |var|
         var =~ /\s*(#{QuotedFragment})\s*/o
-        $1 ? $1 : nil
+        Regexp.last_match(1) ? parse_expression(Regexp.last_match(1)) : nil
       end.compact
     end
 
+    class ParseTreeVisitor < Liquid::ParseTreeVisitor
+      def children
+        Array(@node.variables)
+      end
+    end
   end
 
   Template.register_tag('cycle', Cycle)

data/lib/liquid/tags/decrement.rb

@@ -1,38 +1,36 @@
-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.
+# frozen_string_literal: true
 
-  #   Hello: {% decrement variable %}
-  #
-  # gives you:
-  #
-  #    Hello: -1
-  #    Hello: -2
-  #    Hello: -3
+module Liquid
+  # @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, tokens)
-      @variable = markup.strip
-
+    def initialize(tag_name, markup, options)
       super
+      @variable = markup.strip
     end
 
-    def render(context)
+    def render_to_output_buffer(context, output)
       value = context.environments.first[@variable] ||= 0
-      value = value - 1
+      value -= 1
       context.environments.first[@variable] = value
-      value.to_s
+      output << value.to_s
+      output
     end
-
-    private
   end
 
   Template.register_tag('decrement', Decrement)

data/lib/liquid/tags/echo.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Liquid
+  # @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
+
+    def initialize(tag_name, markup, parse_context)
+      super
+      @variable = Variable.new(markup, parse_context)
+    end
+
+    def render(context)
+      @variable.render_to_output_buffer(context, +'')
+    end
+
+    class ParseTreeVisitor < Liquid::ParseTreeVisitor
+      def children
+        [@node.variable]
+      end
+    end
+  end
+
+  Template.register_tag('echo', Echo)
+end

data/lib/liquid/tags/for.rb

@@ -1,141 +1,205 @@
-module Liquid
+# frozen_string_literal: true
 
-  # "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 %}
-  #
-  # == 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.
+module Liquid
+  # @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(\w+)\s+in\s+(#{QuotedFragment}+)\s*(reversed)?/o
+    Syntax = /\A(#{VariableSegment}+)\s+in\s+(#{QuotedFragment}+)\s*(reversed)?/o
 
-    def initialize(tag_name, markup, tokens)
-      if markup =~ Syntax
-        @variable_name = $1
-        @collection_name = $2
-        @name = "#{$1}-#{$2}"
-        @reversed = $3
-        @attributes = {}
-        markup.scan(TagAttributes) do |key, value|
-          @attributes[key] = value
-        end
-      else
-        raise SyntaxError.new("Syntax Error in 'for loop' - Valid syntax: for [item] in [collection]")
-      end
+    attr_reader :collection_name, :variable_name, :limit, :from
 
-      @nodelist = @for_block = []
+    def initialize(tag_name, markup, options)
       super
+      @from = @limit = nil
+      parse_with_selected_parser(markup)
+      @for_block = new_body
+      @else_block = nil
+    end
+
+    def parse(tokens)
+      if parse_body(@for_block, tokens)
+        parse_body(@else_block, tokens)
+      end
+      if blank?
+        @else_block&.remove_blank_strings
+        @for_block.remove_blank_strings
+      end
+      @else_block&.freeze
+      @for_block.freeze
+    end
+
+    def nodelist
+      @else_block ? [@for_block, @else_block] : [@for_block]
     end
 
     def unknown_tag(tag, markup, tokens)
       return super unless tag == 'else'
-      @nodelist = @else_block = []
+      @else_block = new_body
     end
 
-    def render(context)
-      context.registers[:for] ||= Hash.new(0)
+    def render_to_output_buffer(context, output)
+      segment = collection_segment(context)
 
-      collection = context[@collection_name]
-      collection = collection.to_a if collection.is_a?(Range)
+      if segment.empty?
+        render_else(context, output)
+      else
+        render_segment(context, output, segment)
+      end
+
+      output
+    end
 
-      # Maintains Ruby 1.8.7 String#each behaviour on 1.9
-      return render_else(context) unless iterable?(collection)
+    protected
 
-      from = if @attributes['offset'] == 'continue'
-        context.registers[:for][@name].to_i
+    def lax_parse(markup)
+      if markup =~ Syntax
+        @variable_name   = Regexp.last_match(1)
+        collection_name  = Regexp.last_match(2)
+        @reversed        = !!Regexp.last_match(3)
+        @name            = "#{@variable_name}-#{collection_name}"
+        @collection_name = parse_expression(collection_name)
+        markup.scan(TagAttributes) do |key, value|
+          set_attribute(key, value)
+        end
       else
-        context[@attributes['offset']].to_i
+        raise SyntaxError, options[:locale].t("errors.syntax.for")
       end
+    end
 
-      limit = context[@attributes['limit']]
-      to    = limit ? limit.to_i + from : nil
+    def strict_parse(markup)
+      p = Parser.new(markup)
+      @variable_name = p.consume(:id)
+      raise SyntaxError, options[:locale].t("errors.syntax.for_invalid_in") unless p.id?('in')
 
+      collection_name  = p.expression
+      @collection_name = parse_expression(collection_name)
 
-      segment = Utils.slice_collection_using_each(collection, from, to)
+      @name     = "#{@variable_name}-#{collection_name}"
+      @reversed = p.id?('reversed')
 
-      return render_else(context) if segment.empty?
+      while p.look(:id) && p.look(:colon, 1)
+        unless (attribute = p.id?('limit') || p.id?('offset'))
+          raise SyntaxError, options[:locale].t("errors.syntax.for_invalid_attribute")
+        end
+        p.consume
+        set_attribute(attribute, p.expression)
+      end
+      p.consume(:end_of_string)
+    end
+
+    private
+
+    def collection_segment(context)
+      offsets = context.registers[:for] ||= {}
+
+      from = if @from == :continue
+        offsets[@name].to_i
+      else
+        from_value = context.evaluate(@from)
+        if from_value.nil?
+          0
+        else
+          Utils.to_integer(from_value)
+        end
+      end
+
+      collection = context.evaluate(@collection_name)
+      collection = collection.to_a if collection.is_a?(Range)
+
+      limit_value = context.evaluate(@limit)
+      to = if limit_value.nil?
+        nil
+      else
+        Utils.to_integer(limit_value) + from
+      end
 
+      segment = Utils.slice_collection(collection, from, to)
       segment.reverse! if @reversed
 
-      result = ''
+      offsets[@name] = from + segment.length
 
-      length = segment.length
+      segment
+    end
 
-      # Store our progress through the collection for the continue flag
-      context.registers[:for][@name] = from + segment.length
+    def render_segment(context, output, segment)
+      for_stack = context.registers[:for_stack] ||= []
+      length    = segment.length
 
       context.stack do
-        segment.each_with_index do |item, index|
-          context[@variable_name] = item
-          context['forloop'] = {
-            'name'    => @name,
-            'length'  => length,
-            'index'   => index + 1,
-            'index0'  => index,
-            'rindex'  => length - index,
-            'rindex0' => length - index - 1,
-            'first'   => (index == 0),
-          'last'    => (index == length - 1) }
-
-          result << render_all(@for_block, context)
-
-          # Handle any interrupts if they exist.
-          if context.has_interrupt?
+        loop_vars = Liquid::ForloopDrop.new(@name, length, for_stack[-1])
+
+        for_stack.push(loop_vars)
+
+        begin
+          context['forloop'] = loop_vars
+
+          segment.each do |item|
+            context[@variable_name] = item
+            @for_block.render_to_output_buffer(context, output)
+            loop_vars.send(:increment!)
+
+            # Handle any interrupts if they exist.
+            next unless context.interrupt?
             interrupt = context.pop_interrupt
-            break if interrupt.is_a? BreakInterrupt
-            next if interrupt.is_a? ContinueInterrupt
+            break if interrupt.is_a?(BreakInterrupt)
+            next if interrupt.is_a?(ContinueInterrupt)
           end
+        ensure
+          for_stack.pop
         end
       end
-      result
+
+      output
     end
 
-    private
+    def set_attribute(key, expr)
+      case key
+      when 'offset'
+        @from = if expr == 'continue'
+          Usage.increment('for_offset_continue')
+          :continue
+        else
+          parse_expression(expr)
+        end
+      when 'limit'
+        @limit = parse_expression(expr)
+      end
+    end
 
-      def render_else(context)
-        return @else_block ? [render_all(@else_block, context)] : ''
+    def render_else(context, output)
+      if @else_block
+        @else_block.render_to_output_buffer(context, output)
+      else
+        output
       end
+    end
 
-      def iterable?(collection)
-        collection.respond_to?(:each) || Utils.non_blank_string?(collection)
+    class ParseTreeVisitor < Liquid::ParseTreeVisitor
+      def children
+        (super + [@node.limit, @node.from, @node.collection_name]).compact
       end
+    end
   end
 
   Template.register_tag('for', For)