liquid2 0.1.0

data/lib/liquid2/static_analysis.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Liquid2
+  # Template static analysis.
+  module StaticAnalysis
+    # The location of a variable, tag or filter.
+    class Span
+      attr_reader :template_name, :index
+
+      def initialize(template_name, index)
+        @template_name = template_name
+        @index = index
+      end
+
+      # @param source [String] Template source text.
+      # @return [[Integer, Integer]] The line and column number of this span in _source_.
+      def line_col(source)
+        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]
+        end
+
+        raise "index is out of bounds for span"
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @template_name == other.template_name &&
+          @index == other.index
+      end
+
+      alias eql? ==
+
+      def hash
+        [@template_name, @index].hash
+      end
+    end
+
+    # A variable as a sequence of segments and its location.
+    class Variable
+      attr_reader :segments, :span
+
+      RE_PROPERTY = /\A[\u0080-\uFFFFa-zA-Z_][\u0080-\uFFFFa-zA-Z0-9_-]*\Z/
+
+      def initialize(segments, span)
+        @segments = segments
+        @span = span
+      end
+
+      def to_s
+        segments_to_s(@segments)
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @segments == other.segments &&
+          @span == other.span
+      end
+
+      alias eql? ==
+
+      def hash
+        @segments.hash
+      end
+
+      protected
+
+      def segments_to_s(segments)
+        head, *rest = segments
+
+        head.to_s + rest.map do |segment|
+          case segment
+          when Array
+            "[#{segments_to_s(segment)}]"
+          when String
+            if segment.match?(RE_PROPERTY)
+              ".#{segment}"
+            else
+              "[#{segment.inspect}]"
+            end
+          else
+            "[#{segment}]"
+          end
+        end.join
+      end
+    end
+
+    # Helper to manage variable scope during static analysis.
+    class StaticScope
+      def initialize(globals)
+        @stack = [globals]
+      end
+
+      def include?(key)
+        @stack.any? { |scope| scope.include?(key) }
+      end
+
+      def push(scope)
+        @stack << scope
+        self
+      end
+
+      def pop
+        @stack.pop
+      end
+
+      def add(name)
+        @stack.first.add(name)
+      end
+    end
+
+    # Helper to group variables by their root segment during static analysis.
+    class VariableMap
+      attr_reader :data
+
+      def initialize
+        @data = {}
+      end
+
+      def [](var)
+        key = var.segments.first.to_s
+        @data[key] = [] unless @data.include?(key)
+        @data[key]
+      end
+
+      def add(var)
+        send(:[], var) << var
+      end
+    end
+
+    # The result of analyzing a template.
+    class Result
+      attr_reader :variables, :globals, :locals, :filters, :tags
+
+      def initialize(variables, globals, locals, filters, tags)
+        @variables = variables
+        @globals = globals
+        @locals = locals
+        @filters = filters
+        @tags = tags
+      end
+    end
+
+    def self.analyze(template, include_partials:)
+      variables = VariableMap.new
+      globals = VariableMap.new
+      locals = VariableMap.new
+
+      # @type var filters: Hash[String, Array[Span]]
+      filters = Hash.new { |hash, key| hash[key] = [] }
+      # @type var tags: Hash[String, Array[Span]]
+      tags = Hash.new { |hash, key| hash[key] = [] }
+
+      # @type var template_scope: Set[String]
+      template_scope = Set[]
+      root_scope = StaticScope.new(template_scope)
+      static_context = Liquid2::RenderContext.new(template)
+
+      # Names of partial templates that have already been analyzed.
+      # @type var seen: Set[String]
+      seen = Set[]
+
+      # @type var visit: ^(Node, String, StaticScope) -> void
+      visit = lambda do |node, template_name, scope|
+        seen.add(template_name) unless template_name.empty?
+
+        # Update tags
+        tags[node.name] << Span.new(template_name, node.token.last) if node.is_a?(Liquid2::Tag)
+
+        # Update variables from node.expressions
+        node.expressions.each do |expr|
+          if expr.is_a?(Liquid2::Expression)
+            analyze_variables(expr, template_name, scope, globals,
+                              variables)
+          end
+
+          # Update filters from expr
+          extract_filters(expr, template_name).each do |name, span|
+            filters[name] << span
+          end
+        end
+
+        # Update template scope from node.template_scope
+        node.template_scope.each do |ident|
+          scope.add(ident.name)
+          locals.add(Variable.new([ident.name], Span.new(template_name, ident.token.last)))
+        end
+
+        if (partial = node.partial_scope)
+          partial_name = static_context.evaluate(partial.name).to_s
+
+          unless seen.include?(partial_name)
+            partial_scope = if partial.scope == :isolated
+                              StaticScope.new(Set.new(partial.in_scope.map(&:name)))
+                            else
+                              root_scope.push(Set.new(partial.in_scope.map(&:name)))
+                            end
+
+            node.children(static_context, include_partials: include_partials).each do |child|
+              seen.add(partial_name)
+              visit.call(child, partial_name, partial_scope) if child.is_a?(Liquid2::Node)
+            end
+
+            partial_scope.pop
+          end
+        else
+          scope.push(Set.new(node.block_scope.map(&:name)))
+          node.children(static_context, include_partials: include_partials).each do |child|
+            visit.call(child, template_name, scope) if child.is_a?(Liquid2::Node)
+          end
+          scope.pop
+        end
+      end
+
+      template.ast.each do |node|
+        visit.call(node, template.name, root_scope) if node.is_a?(Liquid2::Node)
+      end
+
+      Result.new(variables.data, globals.data, locals.data, filters, tags)
+    end
+
+    def self.extract_filters(expression, template_name)
+      filters = [] # : Array[[String, Span]]
+
+      if expression.is_a?(Liquid2::FilteredExpression)
+        expression.filters.each do |filter|
+          filters << [filter.name, Span.new(template_name, filter.token.last)]
+        end
+      elsif expression.is_a?(Liquid2::TernaryExpression)
+        expression.filters.each do |filter|
+          filters << [filter.name, Span.new(template_name, filter.token.last)]
+        end
+
+        expression.tail_filters.each do |filter|
+          filters << [filter.name, Span.new(template_name, filter.token.last)]
+        end
+      end
+
+      if expression.is_a?(Liquid2::Expression)
+        expression.children.each do |expr|
+          filters.concat(extract_filters(expr, template_name))
+        end
+      end
+
+      filters
+    end
+
+    def self.analyze_variables(expression, template_name, scope, globals, variables)
+      if expression.is_a?(Path)
+        var = Variable.new(segments(expression, template_name),
+                           Span.new(template_name, expression.token.last))
+        variables.add(var)
+
+        root = var.segments.first.to_s
+        globals.add(var) unless scope.include?(root)
+      end
+
+      if (child_scope = expression.scope)
+        scope.push(Set.new(child_scope.map(&:name)))
+        expression.children.each do |expr|
+          if expr.is_a?(Expression)
+            analyze_variables(expr, template_name, scope, globals,
+                              variables)
+          end
+        end
+        scope.pop
+      else
+        expression.children.each do |expr|
+          if expr.is_a?(Expression)
+            analyze_variables(expr, template_name, scope, globals,
+                              variables)
+          end
+        end
+      end
+    end
+
+    def self.segments(path, template_name)
+      # @type var segments_: Array[untyped]
+      segments_ = [path.head.is_a?(Path) ? segments(path.head, template_name) : path.head]
+
+      path.segments.each do |segment|
+        segments_ << if segment.is_a?(Path)
+                       segments(segment, template_name)
+                     else
+                       segment
+                     end
+      end
+
+      segments_
+    end
+  end
+end

data/lib/liquid2/tag.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Liquid2
+  # Base class for all Liquid tags.
+  class Tag < Node
+    def initialize(token)
+      super
+      return if token.first == :token_tag_name
+
+      raise "unexpected token kind for tag #{self.class} (#{token})"
+    end
+
+    # Render this tag to the output buffer.
+    # @param context [RenderContext]
+    # @param buffer [String]
+    def render(_context, _buffer)
+      raise "tags must implement `render: (RenderContext, String) -> void`."
+    end
+
+    def name = @token[1] || raise
+  end
+end

data/lib/liquid2/template.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Liquid2
+  # A compiled template bound to a Liquid environment and ready to be rendered.
+  class Template
+    attr_reader :env, :ast, :name, :path, :globals, :overlay, :up_to_date, :source
+
+    # @param env [Environment]
+    # @param source [String]
+    # @param ast [Array[Node | String]]
+    # @param name [String] The template's name.
+    # @param path [String?] The path or other qualifying data to _name_.
+    # @param globals [_Namespace] Global template variables.
+    # @param overlay [_Namespace] Additional template variables. Could be from front matter
+    #   or other meta data store, for example.
+    def initialize(env, source, ast, name: "", path: nil, up_to_date: nil, globals: nil,
+                   overlay: nil)
+      @env = env
+      @source = source
+      @ast = ast
+      @name = name
+      @path = path
+      @globals = globals || {} # steep:ignore UnannotatedEmptyCollection
+      @overlay = overlay || {} # steep:ignore UnannotatedEmptyCollection
+      @up_to_date = up_to_date
+    end
+
+    def to_s = @ast.to_s
+
+    # Return this template's path joined with its name, or just name if path is not available.
+    def full_name
+      @name + @path.to_s
+    end
+
+    # Render this template with data from _globals_ added to the render context.
+    # @param globals [Hash[::String, untyped]]
+    # @return [String]
+    def render(globals = nil)
+      buf = +""
+      context = RenderContext.new(self, globals: make_globals(globals))
+      render_with_context(context, buf)
+      buf
+    end
+
+    def render_with_context(context, buffer, partial: false, block_scope: false, namespace: nil)
+      # TODO: don't extend if namespace is nil
+      context.extend(namespace || {}) do
+        index = 0
+        while (node = @ast[index])
+          index += 1
+          case node
+          when String
+            buffer << node
+          else
+            node.render_with_disabled_tag_check(context, buffer)
+          end
+
+          context.raise_for_output_limit(buffer.bytesize)
+
+          next unless (interrupt = context.interrupts.pop)
+
+          if !partial || block_scope
+            raise LiquidSyntaxError.new("unexpected #{interrupt}",
+                                        node.token) # steep:ignore
+          end
+
+          context.interrupts << interrupt
+          break
+        end
+      end
+    rescue LiquidError => e
+      e.source = @source
+      e.template_name = @name unless @name.empty?
+      raise
+    end
+
+    # Merge template globals with another namespace.
+    def make_globals(namespace)
+      # TODO: optimize
+      @globals.merge(@overlay || {}, namespace || {})
+    end
+
+    # Return `false` if this template is stale and needs to be loaded again.
+    # `nil` is returned if an `up_to_date` proc is not available.
+    def up_to_date?
+      @up_to_date&.call
+    end
+
+    # Statically analyze this template and report variable, tag and filter usage.
+    # @param include_partials [bool]
+    # @return [Liquid2::StaticAnalysis::Result]
+    def analyze(include_partials: false)
+      Liquid2::StaticAnalysis.analyze(self, include_partials: include_partials)
+    end
+
+    # Return an array of comment nodes found in this template.
+    #
+    # Comment nodes have `token` and `text` attributes. Use `template.comments.map(&:text)`
+    # to get an array of comment strings. Each comment string includes leading and trailing
+    # whitespace.
+    #
+    # Note that this method does not try to load included or render templates when looking.
+    # for comment nodes.
+    #
+    # @return [Array[BlockComment | InlineComment | Comment]]
+    def comments
+      context = RenderContext.new(self)
+      nodes = [] # : Array[BlockComment | InlineComment | Comment]
+
+      # @type var visit: ^(Node) -> void
+      visit = lambda do |node|
+        if node.is_a?(BlockComment) || node.is_a?(InlineComment) || node.is_a?(Comment)
+          nodes << node
+        end
+
+        node.children(context, include_partials: false).each do |child|
+          visit.call(child) if child.is_a?(Node)
+        end
+      end
+
+      @ast.each { |node| visit.call(node) if node.is_a?(Node) }
+
+      nodes
+    end
+
+    # Return an array of variables used in this template, without path segments.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def variables(include_partials: false)
+      analyze(include_partials: include_partials).variables.keys
+    end
+
+    # Return an array of variables used in this template, including path segments.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def variable_paths(include_partials: false)
+      analyze(include_partials: include_partials).variables.values.flatten.map(&:to_s).uniq
+    end
+
+    # Return an array of variables used in this template, each as an array of segments.
+    # @param include_partials [bool]
+    # @return [Array[Array[String | Integer | Segment]]]
+    def variable_segments(include_partials: false)
+      analyze(include_partials: include_partials).variables.values.flatten.map(&:segments).uniq
+    end
+
+    # Return an array of global variables used in this template, without path segments.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def global_variables(include_partials: false)
+      analyze(include_partials: include_partials).globals.keys
+    end
+
+    # Return an array of global variables used in this template, including path segments.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def global_variable_paths(include_partials: false)
+      analyze(include_partials: include_partials).globals.values.flatten.map(&:to_s).uniq
+    end
+
+    # Return an array of global variables used in this template, each as an array of segments.
+    # @param include_partials [bool]
+    # @return [Array[Array[String | Integer | Segment]]]
+    def global_variable_segments(include_partials: false)
+      analyze(include_partials: include_partials).globals.values.flatten.map(&:segments).uniq
+    end
+
+    # Return the names of all filters used in this template.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def filter_names(include_partials: false)
+      analyze(include_partials: include_partials).filters.keys
+    end
+
+    # Return the names of all tags used in this template.
+    # @param include_partials [bool]
+    # @return [Array[String]]
+    def tag_names(include_partials: false)
+      analyze(include_partials: include_partials).tags.keys
+    end
+  end
+end

data/lib/liquid2/undefined.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Liquid2
+  # The default undefined type. Can be iterated over an indexed without error.
+  class Undefined
+    attr_reader :force_default
+
+    def initialize(name, node: nil)
+      @name = name
+      @node = node
+      @force_default = false
+    end
+
+    def [](...) = self
+    def key?(...) = false
+    def include?(...) = false
+    def member?(...) = false
+    def fetch(...) = self
+    def ! = true
+    def ==(other) = other.nil? || other.is_a?(Undefined)
+    alias eql? ==
+    def size = 0
+    def length = 0
+    def to_s = ""
+    def to_i = 0
+    def to_f = 0.0
+    def each(...) = Enumerator.new {} # rubocop:disable Lint/EmptyBlock
+    def each_with_index(...) = Enumerator.new {} # rubocop:disable Lint/EmptyBlock
+    def join(...) = ""
+    def to_liquid(_context) = nil
+    def poke = true
+  end
+
+  # An undefined type that always raises an exception.
+  class StrictUndefined < Undefined
+    def initialize(name, node: nil)
+      super
+      @message = "#{name.inspect} is undefined"
+    end
+
+    def respond_to_missing? = true
+
+    def method_missing(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def [](...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def key?(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def include?(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def member?(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def fetch(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def !
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def ==(_other)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def !=(_other)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    alias eql? ==
+
+    def size
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def length
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def to_s
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def to_i
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def to_f
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def each(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def each_with_index(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def join(...)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def to_liquid(_context)
+      raise UndefinedError.new(@message, @node)
+    end
+
+    def poke
+      raise UndefinedError.new(@message, @node)
+    end
+  end
+
+  # A strict undefined type that plays nicely with the _default_ filter.
+  class StrictDefaultUndefined < StrictUndefined
+    def initialize(name, node: nil)
+      super
+      @force_default = true
+    end
+  end
+end

data/lib/liquid2/utils/cache.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Liquid2
+  # A least recently used cache relying on Ruby hash insertion order.
+  class LRUCache
+    attr_reader :max_size
+
+    def initialize(max_size = 128)
+      @data = {}
+      @max_size = max_size
+    end
+
+    # Return the cached value or nil if _key_ does not exist.
+    def [](key)
+      val = @data[key]
+      return nil if val.nil?
+
+      @data.delete(key)
+      @data[key] = val
+      val
+    end
+
+    def []=(key, value)
+      if @data.key?(key)
+        @data.delete(key)
+      elsif @data.length >= @max_size
+        @data.delete((@data.first || raise)[0])
+      end
+      @data[key] = value
+    end
+
+    def length
+      @data.length
+    end
+
+    def keys
+      @data.keys
+    end
+  end
+
+  # A thread safe least recently used cache.
+  class ThreadSafeLRUCache < LRUCache
+    include MonitorMixin
+
+    alias unsafe_get []
+    alias unsafe_set []=
+    alias unsafe_length length
+    alias unsafe_keys keys
+
+    def initialize(max_size = 128)
+      super
+    end
+
+    def [](key)
+      synchronize do
+        unsafe_get(key)
+      end
+    end
+
+    def []=(key, value)
+      synchronize do
+        unsafe_set(key, value)
+      end
+    end
+
+    def length
+      synchronize do
+        unsafe_length
+      end
+    end
+
+    def keys
+      synchronize do
+        unsafe_keys
+      end
+    end
+  end
+end