orb_template 0.1.0

data/lib/orb/temple/compiler.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module ORB
+  module Temple
+    # The Compiler is used in the ORB::Engine to compile an input document string
+    # into a Temple expression that gets passed on to the next step in the pipeline.
+    class Compiler
+      # The Compiler is initialized by the Engine pipeline with the options passed to the Engine
+      def initialize(options = {})
+        @options = options
+        @identity = Identity.new
+      end
+
+      # Then the pipeline executes the #call method with an ORB::AST::*Node input
+      def call(ast)
+        return runtime_error(ast) if ast.is_a?(ORB::Error)
+
+        transform(ast)
+      rescue CompilerError => e
+        raise e
+      rescue ORB::Error => e
+        runtime_error(e)
+      end
+
+      private
+
+      # Entry point for the compiler, dispatches to the appropriate method based on the node type
+      # The `context` argument is used to pass information down the tree of nodes
+      # The compile method is usually called on a root node, which then calls `compile` on its children
+      # even though it can be called on any node in the AST to compile the subtree under that node.
+      #
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      def transform(node, context = {})
+        if node.is_a?(ORB::AST::RootNode)
+          transform_children(node, context)
+        elsif node.is_a?(ORB::AST::TextNode)
+          transform_text_node(node, context)
+        elsif node.is_a?(ORB::AST::PrintingExpressionNode)
+          transform_printing_expression_node(node, context)
+        elsif node.is_a?(ORB::AST::ControlExpressionNode)
+          transform_control_expression_node(node, context)
+        elsif node.is_a?(ORB::AST::TagNode) && node.compiler_directives?
+          transform_directives_for_tag_node(node, context)
+        elsif node.is_a?(ORB::AST::TagNode) && node.dynamic?
+          transform_dynamic_tag_node(node, context)
+        elsif node.is_a?(ORB::AST::TagNode) && node.html_tag?
+          transform_html_tag_node(node, context)
+        elsif node.is_a?(ORB::AST::TagNode) && node.component_tag?
+          transform_component_tag_node(node, context)
+        elsif node.is_a?(ORB::AST::TagNode) && node.component_slot_tag?
+          transform_component_slot_tag_node(node, context)
+        elsif node.is_a?(ORB::AST::BlockNode)
+          transform_block_node(node, context)
+        elsif node.is_a?(ORB::AST::PublicCommentNode)
+          transform_public_comment_node(node, context)
+        elsif node.is_a?(ORB::AST::PrivateCommentNode)
+          transform_private_comment_node(node, context)
+        elsif node.is_a?(ORB::AST::NewlineNode)
+          transform_newline_node(node, context)
+        elsif node.is_a?(ORB::Error)
+          runtime_error(node)
+        else
+          raise ORB::CompilerError, "Unknown node type: #{node.class} for #{node.inspect}"
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Compile the children of a node and collect the result into a Temple expression
+      def transform_children(node, context)
+        [:multi, *node.children.map { |child| transform(child, context) }]
+      end
+
+      # Compile a TextNode into a Temple expression
+      def transform_text_node(node, _context)
+        [:static, node.text]
+      end
+
+      # Compile an PExpressionNode into a Temple expression
+      def transform_printing_expression_node(node, context)
+        if node.block?
+          tmp = @identity.generate(:variable)
+          [:multi,
+            # Capture the result of the code in a variable. We can't do
+            # `[:dynamic, code]` because it's probably not a complete
+            # expression (which is a requirement for Temple).
+            [
+              :block, "#{tmp} = #{node.expression}",
+
+              # Capture the content of a block in a separate buffer. This means
+              # that `yield` will not output the content to the current buffer,
+              # but rather return the output.
+              #
+              # The capturing can be disabled with the option :disable_capture.
+              # Output code in the block writes directly to the output buffer then.
+              # Rails handles this by replacing the output buffer for helpers.
+              if @options.fetch(:disable_capture, false)
+                transform_children(node, context)
+              else
+                [:capture, @identity.generate(:variable), transform_children(node, context)]
+              end
+            ],
+            # Output the content.
+            [:escape, true, [:dynamic, tmp]]]
+        elsif node.children.any?
+          [:multi, [:escape, true, [:dynamic, node.expression]], transform_children(node, context)]
+        else
+          [:escape, true, [:dynamic, node.expression]]
+        end
+      end
+
+      # Compile an NPExpressionNode into a Temple expression
+      def transform_control_expression_node(node, context)
+        if node.block?
+          tmp = @identity.generate(:variable)
+          [:multi,
+            [:block, "#{tmp} = #{node.expression}", transform_children(node, context)]]
+        elsif node.children.any?
+          [:multi, [:code, node.expression], transform_children(node, context)]
+        else
+          [:code, node.expression]
+        end
+      end
+
+      # Compile an HTML TagNode into a Temple expression
+      def transform_html_tag_node(node, context)
+        [:orb, :tag, node.tag, node.attributes, transform_children(node, context)]
+      end
+
+      # Compile a component TagNode into a Temple expression
+      def transform_component_tag_node(node, context)
+        [:orb, :component, node, transform_children(node, context)]
+      end
+
+      # Compile a component slot TagNode into a Temple expression
+      def transform_component_slot_tag_node(node, context)
+        [:orb, :slot, node, transform_children(node, context)]
+      end
+
+      # Compile a block node into a Temple expression
+      def transform_block_node(node, context)
+        case node.name
+        when :if
+          [:orb, :if, node.expression, transform_children(node, context)]
+        when :for
+          [:orb, :for, node.expression, transform_children(node, context)]
+        else
+          [:static, 'Unknown block node']
+        end
+      end
+
+      # Compile a comment node into a Temple expression
+      def transform_public_comment_node(node, _context)
+        [:html, :comment, [:static, node.text]]
+      end
+
+      # Compile a private_comment node into a Temple expression
+      def transform_private_comment_node(_node, _context)
+        [:static, ""]
+      end
+
+      # Compile a newline node into a Temple expression
+      def transform_newline_node(_node, _context)
+        [:newline]
+      end
+
+      # Compile a tag node with directives
+      def transform_directives_for_tag_node(node, context)
+        # First, process any :if directives
+        if_directive = node.directives.fetch(:if, false)
+        if if_directive
+          node.remove_directive(:if)
+          return [:if,
+            if_directive,
+            transform(node, context)]
+        end
+
+        # Second, process any :for directives
+        for_directive = node.directives.fetch(:for, false)
+        if for_directive
+          node.remove_directive(:for)
+          return [:orb, :for, for_directive, transform(node, context)]
+        end
+
+        # Last, render as a dynamic node expression
+        transform(node, context)
+      end
+
+      # Compile a dynamic tag node
+      def transform_dynamic_tag_node(node, context)
+        [:orb, :dynamic, node, transform_children(node, context)]
+      end
+
+      # Helper or raising exceptions during compilation
+      def runtime_error(error)
+        [:multi].tap do |temple|
+          (error.line - 1).times { temple << [:newline] } if error.line
+          temple << [:code, %[raise ORB::Error.new(%q[#{error.message}], #{error.line.inspect})]]
+        end
+      end
+    end
+  end
+end

data/lib/orb/temple/engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'temple'
+
+module ORB
+  module Temple
+    class Engine < ::Temple::Engine
+      # This overwrites some Temple default options or sets default options for ORB specific filters.
+      # It is recommended to set the default settings only once in the code and avoid duplication. Only use
+      # `define_options` when you have to override some default settings.
+      define_options generator: ::Temple::Generators::StringBuffer,
+        buffer_class: 'ActionView::OutputBuffer',
+        format: :xhtml,
+        default_tag: 'div',
+        pretty: false,
+        attr_quote: '"',
+        sort_attrs: true,
+        merge_attrs: { 'class' => ' ' },
+        streaming: true,
+        use_html_safe: true,
+        disable_capture: false
+      filter :Encoding
+      filter :RemoveBOM
+      use ORB::Temple::Parser
+      use ORB::Temple::Compiler
+      use ORB::Temple::Filters
+      html :AttributeSorter
+      html :AttributeMerger
+      use(:AttributeRemover) { ::Temple::HTML::AttributeRemover.new(remove_empty_attrs: options[:merge_attrs].keys) }
+      html :Fast
+      filter :Ambles
+      filter :Escapable
+      filter :StaticAnalyzer
+      filter :ControlFlow
+      filter :MultiFlattener
+      filter :StaticMerger
+      use(:Generator) { options[:generator] }
+    end
+  end
+end

data/lib/orb/temple/filters.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module ORB
+  module Temple
+    class Filters < ::Temple::Filter
+      def initialize(options = {})
+        @options = options
+        @attributes_compiler = AttributesCompiler.new
+      end
+
+      # Handle an HTML tag expression `[:orb, :tag, name, attributes, content]`
+      #
+      # @param [String] name The name of the tag
+      # @param [Array] attributes The attributes to be passed in to the tag
+      # @param [Array] content (optional) child nodes of the tag
+      # @return [Array] compiled Temple core expression
+      def on_orb_tag(name, attributes, content = nil)
+        [:html, :tag, name, @attributes_compiler.compile_attributes(attributes), compile(content)]
+      end
+
+      # Handle a component tag expression `[:orb, :component, name, attributes, content]`
+      #
+      # @param [String] name The name of the component
+      # @param [Array<ORB::AST::Attribute>] attributes The attributes to be passed in to the component
+      # @param [Array] content (optional) Temple expression
+      # @return [Array] compiled Temple core expression
+      def on_orb_component(node, content = [])
+        tmp = unique_name
+
+        # Lookup the component class name using the ORB lookup mechanism
+        # that traverses the configured namespaces
+        name = node.tag.gsub('.', '::')
+        komponent = ORB.lookup_component(name)
+        komponent_name = komponent || name
+
+        block_name = "__orb__#{komponent_name.rpartition('::').last.underscore}"
+        block_name = node.directives.fetch(:with, block_name)
+
+        # We need to compile the attributes into a set of captures and a set of arguments
+        # since arguments passed to the view component constructor may be defined as
+        # dynamic expressions in our template, and we need to first capture their results.
+        arg_captures = @attributes_compiler.compile_captures(node.attributes, tmp)
+        args = @attributes_compiler.compile_komponent_args(node.attributes, tmp)
+
+        # Construct the render call for the view component
+        code = "render #{komponent_name}.new(#{args}) do |#{block_name}|"
+
+        # Return a compiled Temple expression that captures the component render call
+        # and then evaluates the result into the OutputBuffer.
+        [:multi,
+          *arg_captures,
+          # Capture the result of the component render call into a variable
+          # we can't do :dynamic here because it's probably not a complete expression
+          [:block, "#{tmp} = #{code}",
+            # Capture the content of the block into a separate buffer
+            # [:capture, unique_name, compile(content)]
+            compile(content)],
+          # Output the content
+          [:escape, true, [:dynamic, tmp.to_s]]]
+      end
+
+      # Handle a component slot tag expression `[:orb, :slot, name, attributes, content]`
+      #
+      # @param [String] name The name of the slot
+      # @param [Array<ORB::AST::Attribute>] attributes the attributes to be passed in to the slot
+      # @param [Array] content (optional) Temple expression for the slot content
+      # @return [Array] compiled Temple expression
+      def on_orb_slot(node, content = [])
+        tmp = unique_name
+
+        # We need to compile the attributes into a set of captures and a set of arguments
+        # since arguments passed to the view component constructor may be defined as
+        # dynamic expressions in our template, and we need to first capture their results.
+        arg_captures = @attributes_compiler.compile_captures(node.attributes, tmp)
+        args = @attributes_compiler.compile_komponent_args(node.attributes, tmp)
+
+        # Prepare the slot name, parent name, and block name
+        slot_name = node.slot
+        parent_name = "__orb__#{node.component.underscore}"
+        block_name = node.directives.fetch(:with, "__orb__#{slot_name}")
+
+        # Construct the code to call the slot on the parent component
+        code = "#{parent_name}.with_#{slot_name}(#{args}) do |#{block_name}|"
+
+        # Return a compiled Temple expression that captures the slot call
+        [:multi,
+          *arg_captures,
+          [:code, code], compile(content),
+          [:code, "end"]]
+      end
+
+      # Handle an if block expression `[:orb, :if, condition, yes, no]`
+      #
+      # @param [String] condition The condition to be evaluated
+      # @param [Array] yes The content to be rendered if the condition is true
+      # @param [Array] no (optional) The content to be rendered if the condition is false
+      # @return [Array] compiled Temple expression
+      def on_orb_if(condition, yes, no = nil)
+        result = [:if, condition, compile(yes)]
+        result << compile(no) if no
+        result
+      end
+
+      # Handle a for block expression `[:orb, :for, expression, content]`
+      #
+      # @param [String] expression The iterator expression to be evaluated
+      # @param [Array] content The content to be rendered for each iteration
+      # @return [Array] compiled Temple expression
+      def on_orb_for(expression, content)
+        enumerator, collection = expression.split(' in ')
+        code = "#{collection}.each do |#{enumerator}|"
+
+        [:multi,
+          [:code, code], compile(content),
+          [:code, "end"]]
+      end
+
+      # Handle a dynamic node expression `[:orb, :dynamic, node, content]`
+      #
+      def on_orb_dynamic(node, content)
+        # TODO: Determine whether the node is an html_tag, component, or slot node
+        tmp = unique_name
+        splats = @attributes_compiler.compile_splat_attributes(node.splat_attributes)
+        code = "content_tag('#{node.tag}', #{splats}) do"
+
+        [:multi,
+          [:block, "#{tmp} = #{code}", compile(content)],
+          [:escape, true, [:dynamic, tmp]]]
+      end
+    end
+  end
+end

data/lib/orb/temple/generators.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# TODO: This class is a WIP and not used in production code, yet.
+#
+# Eventually this class will be used to generate the Ruby code from the AST.
+# It tries to match the behaviour of the rails ERB Template handler as close as possible.
+module ORB
+  module Temple
+    module Generators
+      class Generator
+        include Utils
+        include Mixins::CompiledDispatcher
+        include Mixins::Options
+
+        define_options :save_buffer,
+          :streaming,
+          capture_generator: 'Generator',
+          buffer_class: 'ActionView::OutputBuffer',
+          buffer: '@output_buffer',
+          freeze_static: true
+
+        def call(exp)
+          [preamble, compile(exp), postamble].flatten.compact.join('; ')
+        end
+
+        def preamble
+          [save_buffer, create_buffer]
+        end
+
+        def postamble
+          [return_buffer, restore_buffer]
+        end
+
+        def save_buffer
+          "begin; #{@original_buffer = unique_name} = #{buffer} if defined?(#{buffer})" if options[:save_buffer]
+        end
+
+        def restore_buffer
+          "ensure; #{buffer} = #{@original_buffer}; end" if options[:save_buffer]
+        end
+
+        def create_buffer
+          if buffer == '@output_buffer'
+            "#{buffer} = output_buffer || #{options[:buffer_class]}.new"
+          else
+            "#{buffer} = #{options[:buffer_class]}.new"
+          end
+        end
+
+        def return_buffer
+          'nil'
+        end
+
+        def on(*exp)
+          raise InvalidExpression, "Generator supports only core expressions - found #{exp.inspect}"
+        end
+
+        def on_multi(*exp)
+          exp.map { |e| compile(e) }.join('; ')
+        end
+
+        def on_newline
+          "\n"
+        end
+
+        def on_capture(name, exp)
+          capture_generator.new(capture_generator: options[:capture_generator],
+            freeze_static: options[:freeze_static],
+            buffer: name).call(exp)
+        end
+
+        def on_static(text)
+          concat(options[:freeze_static] ? "#{text.inspect}.freeze" : text.inspect)
+        end
+
+        def on_dynamic(code)
+          concat(code)
+        end
+
+        def on_code(code)
+          code
+        end
+
+        protected
+
+        def buffer
+          options[:buffer]
+        end
+
+        def capture_generator
+          @capture_generator ||= if Class === options[:capture_generator]
+                                   options[:capture_generator]
+                                 else
+                                   Generators.const_get(options[:capture_generator])
+                                 end
+        end
+
+        def safe_concat(str)
+          "#{buffer}.safe_append=#{str}"
+        end
+
+        def concat(str)
+          "#{buffer}.append=#{str}"
+        end
+      end
+    end
+  end
+end

data/lib/orb/temple/identity.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ORB
+  module Temple
+    class Identity
+      def initialize
+        @unique_id = 0
+      end
+
+      def generate(prefix = nil)
+        @unique_id += 1
+        ["_orb_compiler", prefix, @unique_id].compact.join('_')
+      end
+    end
+  end
+end

data/lib/orb/temple/parser.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ORB
+  module Temple
+    class Parser
+      def initialize(options = {})
+        @options = options
+
+        # Only raise errors when is used as a standalone library
+        # and not within the Temple engine
+        @raise_errors = !options.key?(:generator)
+      end
+
+      def call(template)
+        tokenizer = ORB::Tokenizer2.new(template, **@options)
+        tokens = tokenizer.tokenize!
+
+        parser = ORB::Parser.new(tokens, **@options)
+        @root = parser.parse!
+
+        @root
+      rescue ORB::Error => e
+        e.set_backtrace(e.backtrace.unshift("#{@options.fetch(:filename, :nofile)}:#{e.line || 42}"))
+
+        # Within the Temple engine, tokenizer and parser errors shouldn't be raised
+        # but instead passed on to the compiler, so we can raise them there and
+        # render nice error templates.
+        raise if @raise_errors
+
+        error_with_lineno(e)
+      end
+
+      private
+
+      def error_with_lineno(error)
+        return error if error.line
+
+        trace = error.backtrace.first
+        return error unless trace
+
+        line = trace.match(/\d+\z/).to_s.to_i
+        Error.new(error.message, line)
+      end
+    end
+  end
+end

data/lib/orb/temple.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ORB
+  module Temple
+    extend ActiveSupport::Autoload
+
+    autoload :Filters
+    autoload :ComponentFilter
+    autoload :AttributesCompiler
+    autoload :Parser
+    autoload :Compiler
+    autoload :Identity
+    autoload :Engine
+    autoload :Generator, 'orb/temple/generators'
+  end
+end

data/lib/orb/token.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ORB
+  # A simple PORO to represent a token.
+  class Token
+    attr_accessor :type, :value, :meta
+
+    def initialize(type, value, meta = {})
+      @type = type
+      @value = value
+      @meta = meta
+      @line = line || 0
+    end
+
+    def set_meta(key, value)
+      meta[key.to_sym] = value
+    end
+
+    def respond_to_missing?(method, _include_private = false)
+      meta.has_key?(method.to_sym)
+    end
+
+    def method_missing(method, *args, &block)
+      if meta.has_key?(method.to_sym)
+        meta[method.to_sym]
+      else
+        super
+      end
+    end
+
+    def ==(other)
+      type == other.type &&
+        value == other.value &&
+        meta == other.meta
+    end
+
+    attr_reader :line
+
+    def inspect
+      to_s
+    end
+
+    def to_s
+      "#<ORB::Token[#{type}] meta=#{meta.inspect} value=#{value.inspect}>"
+    end
+  end
+end