liquid2 0.1.0

data/lib/liquid2/context.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require_relative "utils/chain_hash"
+
+module Liquid2
+  # Hash-like obj for resolving built-in dynamic objs.
+  class BuiltIn
+    def key?(key)
+      %w[now today].include?(key)
+    end
+
+    def fetch(key, default = :undefined)
+      case key
+      when "now", "today"
+        Time.now
+      else
+        default
+      end
+    end
+
+    def [](key)
+      case key
+      when "now", "today"
+        Time.now
+      end
+    end
+  end
+
+  # Per render contextual information. A new RenderContext is created automatically
+  # every time `Template#render` is called.
+  class RenderContext
+    attr_reader :env, :template, :disabled_tags, :globals
+    attr_accessor :interrupts, :tag_namespace
+
+    BUILT_IN = BuiltIn.new
+
+    # @param template [Template]
+    # @param globals [Hash<String, Object>?]
+    # @param disabled_tags [Array<String>?]
+    # @param copy_depth [Integer?]
+    # @param parent [RenderContext?]
+    # @param parent_scope [Array[_Namespace]] Namespaces from a parent render context.
+    # @param loop_carry [Integer?]
+    # @param local_namespace_carry [Integer?]
+    def initialize(
+      template,
+      globals: nil,
+      disabled_tags: nil,
+      copy_depth: 0,
+      parent: nil,
+      loop_carry: 1,
+      local_namespace_carry: 0
+    )
+      @env = template.env
+      @template = template
+      @globals = globals || {} # steep:ignore UnannotatedEmptyCollection
+      @disabled_tags = disabled_tags || []
+      @copy_depth = copy_depth
+      @parent = parent
+      @loop_carry = loop_carry
+
+      # The current size of the local namespace. _size_ is a non-specific measure of the
+      # amount of memory used to store template local variables.
+      @assign_score = local_namespace_carry
+
+      # A namespace for template local variables (those bound with `assign` or `capture`).
+      @locals = {}
+
+      # A namespace for `increment` and `decrement` counters.
+      @counters = Hash.new(0)
+
+      # Namespaces are searched from right to left. When a RenderContext is extended, the
+      # temporary namespace is pushed to the end of this queue.
+      # TODO: exclude @globals if globals is empty
+      @scope = ReadOnlyChainHash.new(@counters, BUILT_IN, @globals, @locals)
+
+      # A namespace supporting stateful tags, such as `cycle` and `increment`.
+      # It's OK to use this hash for storing custom tag state.
+      @tag_namespace = {
+        cycles: Hash.new(0),
+        stop_index: {},
+        extends: Hash.new { |hash, key| hash[key] = [] },
+        macros: {}
+      }
+
+      # A stack of forloop objs used for populating forloop.parentloop.
+      @loops = [] # : Array[ForLoop]
+
+      # A stack of interrupts used to signal breaking and continuing `for` loops.
+      @interrupts = [] # : Array[Symbol]
+    end
+
+    # Evaluate _obj_ as an expression in the render current context.
+    def evaluate(obj)
+      obj.respond_to?(:evaluate) ? obj.evaluate(self) : obj
+    end
+
+    # Add _key_ to the local scope with value _value_.
+    # @param key [String]
+    # @param value [Object]
+    # @return [nil]
+    def assign(key, value)
+      @locals[key] = value
+      if (limit = @env.local_namespace_limit)
+        # Note that this approach does not account for overwriting keys/values
+        # in the local scope. The assign score is always incremented.
+        @assign_score += assign_score(value)
+        raise LiquidResourceLimitError, "local namespace limit reached" if @assign_score > limit
+      end
+    end
+
+    alias []= assign
+
+    # Resolve _path_ to variable/data in the current scope.
+    # @param head [String|Integer] First segment of the path.
+    # @param path [Array<String|Integer>] Remaining path segments.
+    # @param node [Node?] An associated token to use for error context.
+    # @param default [Object?] A default value to return if the path can no be resolved.
+    # @return [Object]
+    def fetch(head, path, node:, default: :undefined)
+      obj = @scope.fetch(evaluate(head))
+
+      if obj == :undefined
+        return @env.undefined(head, node: node) if default == :undefined
+
+        return default
+      end
+
+      index = 0
+      while (segment = path[index])
+        index += 1
+        segment = evaluate(segment)
+        segment = segment.to_liquid(self) if segment.respond_to?(:to_liquid)
+
+        if obj.respond_to?(:[]) &&
+           ((obj.respond_to?(:key?) && obj.key?(segment)) ||
+            (obj.respond_to?(:fetch) && segment.is_a?(Integer)))
+          obj = obj[segment]
+          next
+        end
+
+        obj = if segment == "size" && obj.respond_to?(:size)
+                obj.size
+              elsif segment == "first" && obj.respond_to?(:first)
+                obj.first
+              elsif segment == "last" && obj.respond_to?(:last)
+                obj.last
+              else
+                return default == :undefined ? @env.undefined(head, node: node) : default
+              end
+      end
+
+      obj
+    end
+
+    # Resolve variable _name_ in the current scope.
+    # @param name [String]
+    # @return [Object?]
+    def resolve(name) = @scope.fetch(name)
+
+    alias [] resolve
+
+    # Extend the scope of this context with the given namespace. Expects a block.
+    # @param namespace [Hash<String, Object>]
+    # @param template [Template?] Replace the current template for the duration of the block.
+    def extend(namespace, template: nil)
+      if @scope.size > @env.context_depth_limit
+        raise LiquidResourceLimitError, "context depth limit reached"
+      end
+
+      template_ = @template
+      @template = template if template
+      @scope << namespace
+      yield
+    ensure
+      @template = template_
+      @scope.pop
+    end
+
+    # Copy this render context and add _namespace_ to the new scope.
+    # @param namespace [Hash<String, Object>]
+    # @param template [Template?] The template obj bound to the new context.
+    # @param disabled_tags [Set<String>] Names of tags to disallow in the new context.
+    # @param carry_loop_iterations [bool] If true, pass the current loop iteration count to the
+    #   new context.
+    # @param block_scope [bool] It true, retain the current scope in the new context. Otherwise
+    #   only global variables will be included in the new context's scope.
+    def copy(namespace,
+             template: nil,
+             disabled_tags: nil,
+             carry_loop_iterations: false,
+             block_scope: false)
+      if @copy_depth > @env.context_depth_limit
+        raise LiquidResourceLimitError, "context depth limit reached"
+      end
+
+      loop_carry = if carry_loop_iterations
+                     @loops.map(&:length).reduce(@loop_carry) { |acc, value| acc * value }
+                   else
+                     1
+                   end
+
+      scope = if block_scope
+                ReadOnlyChainHash.new(@scope, namespace)
+              else
+                ReadOnlyChainHash.new(@globals, namespace)
+              end
+
+      self.class.new(template || @template,
+                     globals: scope,
+                     disabled_tags: disabled_tags,
+                     copy_depth: @copy_depth + 1,
+                     parent: self,
+                     loop_carry: loop_carry,
+                     local_namespace_carry: @assign_score)
+    end
+
+    # Push a new namespace and forloop for the duration of a block.
+    # @param namespace [Hash<String, Object>]
+    # @param forloop [ForLoop]
+    def loop(namespace, forloop)
+      raise_for_loop_limit(length: forloop.length)
+      @loops << forloop
+      @scope << namespace
+      yield
+    ensure
+      @scope.pop
+      @loops.pop
+    end
+
+    # Return the last ForLoop obj if one is available, or an instance of Undefined otherwise.
+    def parent_loop(node)
+      return @env.undefined("parentloop", node: node) if @loops.empty?
+
+      @loops.last
+    end
+
+    # Get or set the stop index of a for loop.
+    def stop_index(key, index: nil)
+      if index
+        @tag_namespace[:stop_index][key] = index
+      else
+        @tag_namespace[:stop_index].fetch(key, 0)
+      end
+    end
+
+    def raise_for_loop_limit(length: 1)
+      return nil unless @env.loop_iteration_limit
+
+      loop_count = @loops.map(&:length).reduce(length * @loop_carry) { |acc, value| acc * value }
+
+      return unless loop_count > (@env.loop_iteration_limit || raise)
+
+      raise LiquidResourceLimitError, "loop iteration limit reached"
+    end
+
+    def raise_for_output_limit(length)
+      return unless @env.output_stream_limit && (@env.output_stream_limit || raise) < length
+
+      raise LiquidResourceLimitError, "output limit reached"
+    end
+
+    def get_output_buffer(parent_buffer)
+      return StringIO.new unless @env.output_stream_limit
+
+      carry = parent_buffer.is_a?(LimitedStringIO) ? parent_buffer.size : 0
+      LimitedStringIO.new((@env.output_stream_limit || raise) - carry)
+    end
+
+    def increment(name)
+      val = @counters[name]
+      @counters[name] = val + 1
+      val
+    end
+
+    def decrement(name)
+      val = @counters[name] - 1
+      @counters[name] = val
+      val
+    end
+
+    protected
+
+    def assign_score(value)
+      case value
+      when String
+        value.bytesize
+      when Array
+        value.sum(1) { |item| assign_score(item) } + 1
+      when Hash
+        value.sum(1) { |k, v| assign_score(k) + assign_score(v) }
+      else
+        1
+      end
+    end
+  end
+end

data/lib/liquid2/environment.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require_relative "loader"
+require_relative "parser"
+require_relative "template"
+require_relative "undefined"
+require_relative "filters/array"
+require_relative "filters/date"
+require_relative "filters/default"
+require_relative "filters/math"
+require_relative "filters/json"
+require_relative "filters/size"
+require_relative "filters/slice"
+require_relative "filters/sort"
+require_relative "filters/string"
+require_relative "nodes/tags/assign"
+require_relative "nodes/tags/block_comment"
+require_relative "nodes/tags/capture"
+require_relative "nodes/tags/case"
+require_relative "nodes/tags/cycle"
+require_relative "nodes/tags/decrement"
+require_relative "nodes/tags/doc"
+require_relative "nodes/tags/echo"
+require_relative "nodes/tags/for"
+require_relative "nodes/tags/if"
+require_relative "nodes/tags/include"
+require_relative "nodes/tags/increment"
+require_relative "nodes/tags/inline_comment"
+require_relative "nodes/tags/liquid"
+require_relative "nodes/tags/raw"
+require_relative "nodes/tags/render"
+require_relative "nodes/tags/tablerow"
+require_relative "nodes/tags/unless"
+
+module Liquid2
+  # Template parsing and rendering configuration.
+  #
+  # A Liquid::Environment is where you might register custom tags and filters,
+  # or store global context data that should be available to all templates.
+  #
+  # `Liquid2.parse(source)` is equivalent to `Liquid2::Environment.new.parse(source)`.
+  class Environment
+    attr_reader :tags, :local_namespace_limit, :context_depth_limit, :loop_iteration_limit,
+                :output_stream_limit, :filters, :suppress_blank_control_flow_blocks,
+                :shorthand_indexes
+
+    def initialize(
+      context_depth_limit: 30,
+      globals: nil,
+      loader: nil,
+      local_namespace_limit: nil,
+      loop_iteration_limit: nil,
+      output_stream_limit: nil,
+      shorthand_indexes: false,
+      suppress_blank_control_flow_blocks: true,
+      undefined: Undefined
+    )
+      # A mapping of tag names to objects responding to `parse(token, parser)`.
+      @tags = {}
+
+      # A mapping of filter names to objects responding to `#call(left, ...)`,
+      # along with a flag to indicate if the callable accepts a `context`
+      # keyword argument.
+      @filters = {}
+
+      # The maximum number of times a render context can be extended or copied before
+      # a Liquid2::LiquidResourceLimitError is raised.
+      @context_depth_limit = context_depth_limit
+
+      # Variables that are available to all templates rendered from this environment.
+      @globals = globals
+
+      # An instance of `Liquid2::Loader`. A template loader is responsible for finding and
+      # reading templates for `{% include %}` and `{% render %}` tags, or when calling
+      # `Liquid2::Environment.get_template(name)`.
+      @loader = loader || HashLoader.new({})
+
+      # The maximum allowed "size" of the template local namespace (variables from `assign`
+      # and `capture` tags) before a Liquid2::LiquidResourceLimitError is raised.
+      @local_namespace_limit = local_namespace_limit
+
+      # The maximum number of loop iterations allowed before a `LiquidResourceLimitError`
+      # is raised.
+      @loop_iteration_limit = loop_iteration_limit
+
+      # The maximum number of bytes that can be written to a template's output buffer
+      # before a `LiquidResourceLimitError` is raised.
+      @output_stream_limit = output_stream_limit
+
+      # We reuse the same string scanner when parsing templates for improved performance.
+      # TODO: Is this going to cause issues in multi threaded environments?
+      @scanner = StringScanner.new("")
+
+      # When `true`, allow shorthand dotted array indexes as well as bracketed indexes
+      # in variable paths. Defaults to `false`.
+      @shorthand_indexes = shorthand_indexes
+
+      # When `true`, suppress blank control flow block output, so as not to include
+      # unnecessary whitespace. Defaults to `true`.
+      @suppress_blank_control_flow_blocks = suppress_blank_control_flow_blocks
+
+      # An instance of `Liquid2::Undefined` used to represent template variables that
+      # don't exist.
+      @undefined = undefined
+
+      # Override `setup_tags_and_filters` in environment subclasses to configure custom
+      # tags and/or filters.
+      setup_tags_and_filters
+    end
+
+    # Parse _source_ text as a template.
+    # @param source [String] template source text.
+    # @return [Template]
+    def parse(source, name: "", path: nil, up_to_date: nil, globals: nil, overlay: nil)
+      Template.new(self,
+                   source,
+                   Parser.parse(self, source, scanner: @scanner),
+                   name: name, path: path, up_to_date: up_to_date,
+                   globals: make_globals(globals), overlay: overlay)
+    rescue LiquidError => e
+      e.source = source
+      e.template_name = name unless name.empty?
+      raise
+    end
+
+    # Parse and render template source text with _data_ as template variables.
+    # @param source [String]
+    # @param data [Hash[String, untyped]?]
+    # @return [String]
+    def render(source, data = nil)
+      parse(source).render(data)
+    end
+
+    # Add or replace a filter. The same callable can be registered multiple times with
+    # different names.
+    #
+    # If _callable_ accepts a keyword parameter called `context`, the active render
+    # context will be passed to `#call`.
+    #
+    # @param name [String] The name of the filter, as used by template authors.
+    # @param callable [responds to call] An object that responds to `#call(left, ...)`
+    #   and `#parameters`. Like a Proc or Method.
+    def register_filter(name, callable)
+      with_context = callable.parameters.index do |(kind, param)|
+        kind == :keyreq && param == :context
+      end
+      @filters[name] = [callable, with_context]
+    end
+
+    # Remove a filter from the filter register.
+    # @param name [String] The name of the filter.
+    # @return [callable | nil] The callable implementing the removed filter, or nil
+    #    if _name_ did not exist in the filter register.
+    def delete_filter(name)
+      @filters.delete(name)
+    end
+
+    def setup_tags_and_filters
+      @tags["#"] = InlineComment
+      @tags["assign"] = AssignTag
+      @tags["break"] = BreakTag
+      @tags["capture"] = CaptureTag
+      @tags["case"] = CaseTag
+      @tags["comment"] = BlockComment
+      @tags["continue"] = ContinueTag
+      @tags["cycle"] = CycleTag
+      @tags["decrement"] = DecrementTag
+      @tags["doc"] = DocTag
+      @tags["echo"] = EchoTag
+      @tags["for"] = ForTag
+      @tags["if"] = IfTag
+      @tags["include"] = IncludeTag
+      @tags["increment"] = IncrementTag
+      @tags["liquid"] = LiquidTag
+      @tags["raw"] = RawTag
+      @tags["render"] = RenderTag
+      @tags["tablerow"] = TableRowTag
+      @tags["unless"] = UnlessTag
+
+      register_filter("abs", Liquid2::Filters.method(:abs))
+      register_filter("append", Liquid2::Filters.method(:append))
+      register_filter("at_least", Liquid2::Filters.method(:at_least))
+      register_filter("at_most", Liquid2::Filters.method(:at_most))
+      register_filter("base64_decode", Liquid2::Filters.method(:base64_decode))
+      register_filter("base64_encode", Liquid2::Filters.method(:base64_encode))
+      register_filter("base64_url_safe_decode", Liquid2::Filters.method(:base64_url_safe_decode))
+      register_filter("base64_url_safe_encode", Liquid2::Filters.method(:base64_url_safe_encode))
+      register_filter("capitalize", Liquid2::Filters.method(:capitalize))
+      register_filter("ceil", Liquid2::Filters.method(:ceil))
+      register_filter("compact", Liquid2::Filters.method(:compact))
+      register_filter("concat", Liquid2::Filters.method(:concat))
+      register_filter("date", Liquid2::Filters.method(:date))
+      register_filter("default", Liquid2::Filters.method(:default))
+      register_filter("divided_by", Liquid2::Filters.method(:divided_by))
+      register_filter("downcase", Liquid2::Filters.method(:downcase))
+      register_filter("escape_once", Liquid2::Filters.method(:escape_once))
+      register_filter("escape", Liquid2::Filters.method(:escape))
+      register_filter("find_index", Liquid2::Filters.method(:find_index))
+      register_filter("find", Liquid2::Filters.method(:find))
+      register_filter("first", Liquid2::Filters.method(:first))
+      register_filter("floor", Liquid2::Filters.method(:floor))
+      register_filter("has", Liquid2::Filters.method(:has))
+      register_filter("join", Liquid2::Filters.method(:join))
+      register_filter("json", Liquid2::Filters.method(:json))
+      register_filter("last", Liquid2::Filters.method(:last))
+      register_filter("lstrip", Liquid2::Filters.method(:lstrip))
+      register_filter("map", Liquid2::Filters.method(:map))
+      register_filter("minus", Liquid2::Filters.method(:minus))
+      register_filter("modulo", Liquid2::Filters.method(:modulo))
+      register_filter("newline_to_br", Liquid2::Filters.method(:newline_to_br))
+      register_filter("plus", Liquid2::Filters.method(:plus))
+      register_filter("prepend", Liquid2::Filters.method(:prepend))
+      register_filter("reject", Liquid2::Filters.method(:reject))
+      register_filter("remove_first", Liquid2::Filters.method(:remove_first))
+      register_filter("remove_last", Liquid2::Filters.method(:remove_last))
+      register_filter("remove", Liquid2::Filters.method(:remove))
+      register_filter("replace_first", Liquid2::Filters.method(:replace_first))
+      register_filter("replace_last", Liquid2::Filters.method(:replace_last))
+      register_filter("replace", Liquid2::Filters.method(:replace))
+      register_filter("reverse", Liquid2::Filters.method(:reverse))
+      register_filter("round", Liquid2::Filters.method(:round))
+      register_filter("rstrip", Liquid2::Filters.method(:rstrip))
+      register_filter("size", Liquid2::Filters.method(:size))
+      register_filter("slice", Liquid2::Filters.method(:slice))
+      register_filter("sort_natural", Liquid2::Filters.method(:sort_natural))
+      register_filter("sort_numeric", Liquid2::Filters.method(:sort_numeric))
+      register_filter("sort", Liquid2::Filters.method(:sort))
+      register_filter("split", Liquid2::Filters.method(:split))
+      register_filter("strip_html", Liquid2::Filters.method(:strip_html))
+      register_filter("strip_newlines", Liquid2::Filters.method(:strip_newlines))
+      register_filter("strip", Liquid2::Filters.method(:strip))
+      register_filter("sum", Liquid2::Filters.method(:sum))
+      register_filter("times", Liquid2::Filters.method(:times))
+      register_filter("truncate", Liquid2::Filters.method(:truncate))
+      register_filter("truncatewords", Liquid2::Filters.method(:truncatewords))
+      register_filter("uniq", Liquid2::Filters.method(:uniq))
+      register_filter("url_encode", Liquid2::Filters.method(:url_encode))
+      register_filter("url_decode", Liquid2::Filters.method(:url_decode))
+      register_filter("upcase", Liquid2::Filters.method(:upcase))
+      register_filter("where", Liquid2::Filters.method(:where))
+    end
+
+    def undefined(name, node: nil)
+      @undefined.new(name, node: node)
+    end
+
+    # Trim _text_.
+    def trim(text, left_trim, right_trim)
+      case left_trim
+      when "-"
+        text.lstrip!
+      when "~"
+        text.sub!(/\A[\r\n]+/, "")
+      end
+
+      case right_trim
+      when "-"
+        text.rstrip!
+      when "~"
+        text.sub!(/[\r\n]+\Z/, "")
+      end
+    end
+
+    # Load and parse a template using the configured template loader.
+    # @param name [String] The template's name.
+    # @param globals [_Namespace?] Render context variables to attach to the template.
+    # @param context [RenderContext?] An optional render context that can be used to
+    #   narrow the template search space.
+    # @param kwargs Arbitrary arguments that can be used to narrow the template search
+    #   space.
+    # @return [Template]
+    def get_template(name, globals: nil, context: nil, **kwargs)
+      @loader.load(self, name, globals: globals, context: context, **kwargs)
+    rescue LiquidError => e
+      e.template_name = name unless e.template_name || e.is_a?(LiquidTemplateNotFoundError)
+      raise e
+    end
+
+    # Merge environment globals with another namespace.
+    def make_globals(namespace)
+      return @globals if namespace.nil?
+      return namespace if @globals.nil?
+
+      (@globals || raise).merge(namespace)
+    end
+  end
+end

data/lib/liquid2/errors.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Liquid2
+  # The base class for all Liquid errors.
+  class LiquidError < StandardError
+    attr_accessor :token, :template_name, :source
+
+    FULL_MESSAGE = ((RUBY_VERSION.split(".")&.map(&:to_i) <=> [3, 2, 0]) || -1) < 1
+
+    def initialize(message, token = nil)
+      super(message)
+      @token = token
+      @template_name = nil
+      @source = nil
+    end
+
+    def detailed_message(highlight: true, **kwargs)
+      return super unless @source.is_a?(String) && @token
+
+      _kind, value, index = @token || raise
+      line, col, current_line = error_context(@source || raise, index)
+
+      name_and_position = if @template_name
+                            "#{@template_name}:#{line}:#{col}"
+                          else
+                            "#{current_line.inspect}:#{line}:#{col}"
+                          end
+
+      pad = " " * line.to_s.length
+      pointer = (" " * col) + ("^" * (value&.length || 1))
+
+      <<~MESSAGE.strip
+        #{self.class}: #{message}
+        #{pad} -> #{name_and_position}
+        #{pad} |
+        #{line} | #{current_line}
+        #{pad} | #{pointer} #{highlight ? "\e[1m#{message}\e[0m" : message}
+      MESSAGE
+    end
+
+    def full_message(highlight: true, order: :top)
+      if FULL_MESSAGE
+        # For Ruby < 3.2.0
+        "#{super}\n#{detailed_message(highlight: highlight, order: order)}"
+      else
+        super
+      end
+    end
+
+    protected
+
+    def error_context(source, index)
+      lines = source.lines
+      cumulative_length = 0
+      target_line_index = -1
+
+      lines.each_with_index do |line, i|
+        cumulative_length += line.length
+        next unless index < cumulative_length
+
+        target_line_index = i
+        line_number = target_line_index + 1
+        column_number = index - (cumulative_length - lines[target_line_index].length)
+        return [line_number, column_number, lines[target_line_index].rstrip]
+      end
+
+      raise "index is out of bounds for span"
+    end
+  end
+
+  class LiquidSyntaxError < LiquidError; end
+  class LiquidArgumentError < LiquidError; end
+  class LiquidTypeError < LiquidError; end
+  class LiquidTemplateNotFoundError < LiquidError; end
+  class LiquidFilterNotFoundError < LiquidError; end
+  class LiquidResourceLimitError < LiquidError; end
+  class UndefinedError < LiquidError; end
+  class DisabledTagError < LiquidError; end
+end

data/lib/liquid2/expression.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Liquid2
+  # Base class for all expressions.
+  class Expression
+    attr_reader :token
+
+    # @param token [[Symbol, String?, Integer]]
+    def initialize(token)
+      @token = token
+    end
+
+    # Return children of this expression.
+    def children = []
+
+    # Return variables this expression adds to the scope of any child expressions.
+    # Currently used by lambda expressions only.
+    def scope = nil
+  end
+end