liquid 4.0.0 → 5.10.0

data/lib/liquid/tags/comment.rb

@@ -1,7 +1,22 @@
+# 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 will be parsed, but not executed.
+  # @liquid_syntax
+  #   {% comment %}
+  #     content
+  #   {% endcomment %}
+  # @liquid_syntax_keyword content The content of the comment.
   class Comment < Block
-    def render(_context)
-      ''.freeze
+    def render_to_output_buffer(_context, output)
+      output
     end
 
     def unknown_tag(_tag, _markup, _tokens)
@@ -10,7 +25,64 @@ module Liquid
     def blank?
       true
     end
-  end
 
-  Template.register_tag('comment'.freeze, Comment)
+    private
+
+    def parse_body(body, tokenizer)
+      if parse_context.depth >= MAX_DEPTH
+        raise StackLevelError, "Nesting too deep"
+      end
+
+      parse_context.depth += 1
+      comment_tag_depth = 1
+
+      begin
+        # Consume tokens without creating child nodes.
+        # The children tag doesn't require to be a valid Liquid except the comment and raw tag.
+        # The child comment and raw tag must be closed.
+        while (token = tokenizer.send(:shift))
+          tag_name = if tokenizer.for_liquid_tag
+            next if token.empty? || token.match?(BlockBody::WhitespaceOrNothing)
+
+            tag_name_match = BlockBody::LiquidTagToken.match(token)
+
+            next if tag_name_match.nil?
+
+            tag_name_match[1]
+          else
+            token =~ BlockBody::FullToken
+            Regexp.last_match(2)
+          end
+
+          case tag_name
+          when "raw"
+            parse_raw_tag_body(tokenizer)
+          when "comment"
+            comment_tag_depth += 1
+          when "endcomment"
+            comment_tag_depth -= 1
+          end
+
+          if comment_tag_depth.zero?
+            parse_context.trim_whitespace = (token[-3] == WhitespaceControl) unless tokenizer.for_liquid_tag
+            return false
+          end
+        end
+
+        raise_tag_never_closed(block_name)
+      ensure
+        parse_context.depth -= 1
+      end
+
+      false
+    end
+
+    def parse_raw_tag_body(tokenizer)
+      while (token = tokenizer.send(:shift))
+        return if token =~ BlockBody::FullTokenPossiblyInvalid && "endraw" == Regexp.last_match(2)
+      end
+
+      raise_tag_never_closed("raw")
+    end
+  end
 end

data/lib/liquid/tags/continue.rb

@@ -1,18 +1,20 @@
+# 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](/docs/api/liquid/tags/for) to skip to the next iteration.
+  # @liquid_syntax
+  #   {% continue %}
   class Continue < Tag
-    def interrupt
-      ContinueInterrupt.new
+    INTERRUPT = ContinueInterrupt.new.freeze
+
+    def render_to_output_buffer(context, output)
+      context.push_interrupt(INTERRUPT)
+      output
     end
   end
-
-  Template.register_tag('continue'.freeze, Continue)
 end

data/lib/liquid/tags/cycle.rb

@@ -1,57 +1,140 @@
+# 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](/docs/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
+    UNNAMED_CYCLE_PATTERN = /\w+:0x\h{8}/
+
+    attr_reader :variables
 
     def initialize(tag_name, markup, options)
       super
-      case markup
-      when NamedSyntax
-        @variables = variables_from_string($2)
-        @name = Expression.parse($1)
-      when SimpleSyntax
-        @variables = variables_from_string(markup)
-        @name = @variables.to_s
-      else
-        raise SyntaxError.new(options[:locale].t("errors.syntax.cycle".freeze))
-      end
+      parse_with_selected_parser(markup)
+    end
+
+    def named?
+      @is_named
     end
 
-    def render(context)
-      context.registers[:cycle] ||= Hash.new(0)
+    def render_to_output_buffer(context, output)
+      context.registers[:cycle] ||= {}
 
-      context.stack do
-        key = context.evaluate(@name)
-        iteration = context.registers[:cycle][key]
-        result = context.evaluate(@variables[iteration])
-        iteration += 1
-        iteration  = 0 if iteration >= @variables.size
-        context.registers[:cycle][key] = iteration
-        result
+      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
 
+    # cycle [name:] expression(, expression)*
+    def rigid_parse(markup)
+      p = @parse_context.new_parser(markup)
+
+      @variables = []
+
+      raise SyntaxError, options[:locale].t("errors.syntax.cycle") if p.look(:end_of_string)
+
+      first_expression = safe_parse_expression(p)
+      if p.look(:colon)
+        # cycle name: expr1, expr2, ...
+        @name = first_expression
+        @is_named = true
+        p.consume(:colon)
+        # After the colon, parse the first variable (required for named cycles)
+        @variables << maybe_dup_lookup(safe_parse_expression(p))
+      else
+        # cycle expr1, expr2, ...
+        @variables << maybe_dup_lookup(first_expression)
+      end
+
+      # Parse remaining comma-separated expressions
+      while p.consume?(:comma)
+        break if p.look(:end_of_string)
+
+        @variables << maybe_dup_lookup(safe_parse_expression(p))
+      end
+
+      p.consume(:end_of_string)
+
+      unless @is_named
+        @name = @variables.to_s
+        @is_named = !@name.match?(UNNAMED_CYCLE_PATTERN)
+      end
+    end
+
+    def strict_parse(markup)
+      lax_parse(markup)
+    end
+
+    def lax_parse(markup)
+      case markup
+      when NamedSyntax
+        @variables = variables_from_string(Regexp.last_match(2))
+        @name      = parse_expression(Regexp.last_match(1))
+        @is_named = true
+      when SimpleSyntax
+        @variables = variables_from_string(markup)
+        @name      = @variables.to_s
+        @is_named = !@name.match?(UNNAMED_CYCLE_PATTERN)
+      else
+        raise SyntaxError, options[:locale].t("errors.syntax.cycle")
+      end
+    end
+
     def variables_from_string(markup)
       markup.split(',').collect do |var|
         var =~ /\s*(#{QuotedFragment})\s*/o
-        $1 ? Expression.parse($1) : nil
+        next unless Regexp.last_match(1)
+
+        var = parse_expression(Regexp.last_match(1))
+        maybe_dup_lookup(var)
       end.compact
     end
-  end
 
-  Template.register_tag('cycle', Cycle)
+    # For backwards compatibility, whenever a lookup is used in an unnamed cycle,
+    # we make it so that the @variables.to_s produces different strings for cycles
+    # called with the same arguments (since @variables.to_s is used as the cycle counter key)
+    # This makes it so {% cycle a, b %} and {% cycle a, b %} have independent counters even if a and b share value.
+    # This is not true for literal values, {% cycle "a", "b" %} and {% cycle "a", "b" %} share the same counter.
+    # I was really scratching my head about this one, but migrating away from this would be more headache
+    # than it's worth. So we're keeping this quirk for now.
+    def maybe_dup_lookup(var)
+      var.is_a?(VariableLookup) ? var.dup : var
+    end
+
+    class ParseTreeVisitor < Liquid::ParseTreeVisitor
+      def children
+        Array(@node.variables)
+      end
+    end
+  end
 end

data/lib/liquid/tags/decrement.rb

@@ -1,35 +1,42 @@
-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:
+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.
   #
-  #    Hello: -1
-  #    Hello: -2
-  #    Hello: -3
+  #   > 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
+  #   [snippets](/themes/architecture/snippets) included in the file.
   #
+  #   Similarly, variables that are created with `decrement` are independent from those created with [`assign`](/docs/api/liquid/tags/assign)
+  #   and [`capture`](/docs/api/liquid/tags/capture). However, `decrement` and [`increment`](/docs/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
+    attr_reader :variable_name
+
     def initialize(tag_name, markup, options)
       super
-      @variable = markup.strip
+      @variable_name = markup.strip
     end
 
-    def render(context)
-      value = context.environments.first[@variable] ||= 0
+    def render_to_output_buffer(context, output)
+      counter_environment = context.environments.first
+      value = counter_environment[@variable_name] || 0
       value -= 1
-      context.environments.first[@variable] = value
-      value.to_s
+      counter_environment[@variable_name] = value
+      output << value.to_s
+      output
     end
   end
-
-  Template.register_tag('decrement'.freeze, Decrement)
 end

data/lib/liquid/tags/doc.rb

@@ -0,0 +1,81 @@
+# 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.
+  #
+  #   For detailed documentation syntax and examples, see the
+  #   [`LiquidDoc` reference](/docs/storefronts/themes/tools/liquid-doc).
+  #
+  # @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 %}
+  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)
+      @body = +""
+
+      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)
+          @body << Regexp.last_match(1) if Regexp.last_match(1) != ""
+          return
+        end
+        @body << token unless token.empty?
+      end
+
+      raise_tag_never_closed(block_name)
+    end
+
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def blank?
+      @body.empty?
+    end
+
+    def nodelist
+      [@body]
+    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

data/lib/liquid/tags/echo.rb

@@ -0,0 +1,39 @@
+# 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](/docs/api/liquid/tags/liquid).
+  #
+  #   > Tip:
+  #   > You can use [filters](/docs/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
+end