temple 0.2.0 → 0.3.0

data/lib/temple/engine.rb

@@ -20,12 +20,14 @@ module Temple
   #
   #   class SpecialEngine < MyEngine
   #     append MyCodeOptimizer
-  #     replace Temple::Generators::ArrayBuffer, Temple::Generators::RailsOutputBuffer
+  #     before :ArrayBuffer, Temple::Filters::Validator
+  #     replace :ArrayBuffer, Temple::Generators::RailsOutputBuffer
   #   end
   #
   #   engine = MyEngine.new(:strict => "For MyParser")
   #   engine.call(something)
   #
+  # @api public
   class Engine
     include Mixins::Options
     include Mixins::EngineDSL
@@ -40,24 +42,26 @@ module Temple
     def initialize(o = {})
       super
       @chain = self.class.chain.dup
-      yield(self) if block_given?
       [*options[:chain]].compact.each {|block| block.call(self) }
-      @chain = build_chain
     end
 
     def call(input)
-      chain.inject(input) {|m, e| e.call(m) }
+      call_chain.inject(input) {|m, e| e.call(m) }
     end
 
     protected
 
-    def build_chain
-      chain.map do |e|
+    def chain_modified!
+      @call_chain = nil
+    end
+
+    def call_chain
+      @call_chain ||= @chain.map do |e|
         name, filter, option_filter, local_options = e
         case filter
         when Class
           filtered_options = Hash[*option_filter.select {|k| options.include?(k) }.map {|k| [k, options[k]] }.flatten]
-          filter.new(Utils::ImmutableHash.new(local_options, filtered_options))
+          filter.new(ImmutableHash.new(local_options, filtered_options))
         when UnboundMethod
           filter.bind(self)
         else

data/lib/temple/erb/engine.rb

@@ -1,11 +1,13 @@
 module Temple
   module ERB
+    # Example ERB engine implementation
+    #
+    # @api public
     class Engine < Temple::Engine
-      use Temple::ERB::Parser, :auto_escape
-      filter :EscapeHTML, :use_html_safe
+      use Temple::ERB::Parser
       use Temple::ERB::Trimming, :trim_mode
+      filter :Escapable, :use_html_safe, :disable_escape
       filter :MultiFlattener
-      filter :StaticMerger
       filter :DynamicInliner
       generator :ArrayBuffer
     end

data/lib/temple/erb/parser.rb

@@ -1,5 +1,8 @@
 module Temple
   module ERB
+    # Example ERB parser
+    #
+    # @api public
     class Parser
       include Mixins::Options
 
@@ -25,9 +28,9 @@ module Temple
             when '#'
               code.count("\n").times { result << [:newline] }
             when /=/
-              result << [:escape, indicator.length <= 1 && options[:auto_escape], [:dynamic, code]]
+              result << [:escape, indicator.size <= 1, [:dynamic, code]]
             else
-              result << [:block, code]
+              result << [:code, code]
             end
           end
         end

data/lib/temple/erb/template.rb

@@ -0,0 +1,11 @@
+module Temple
+  # ERB example implementation
+  #
+  # Example usage:
+  #   Temple::ERB::Template.new { "<%= 'Hello, world!' %>" }.render
+  #
+  module ERB
+    # ERB Template class
+    Template = Temple::Templates::Tilt(Engine)
+  end
+end

data/lib/temple/erb/trimming.rb

@@ -1,5 +1,11 @@
 module Temple
   module ERB
+    # ERB trimming
+    # Set option :trim_mode to
+    #    <> - omit newline for lines starting with <% and ending in %>
+    #    >  - omit newline for lines ending in %>
+    #
+    # @api public
     class Trimming < Filter
       def on_multi(*exps)
         case options[:trim_mode]
@@ -21,8 +27,10 @@ module Temple
         [:multi, *exps]
       end
 
+      protected
+
       def code?(exp)
-        exp[0] == :dynamic || exp[0] == :block
+        exp[0] == :escape || exp[0] == :code
       end
 
       def static?(exp)

data/lib/temple/filter.rb

@@ -1,4 +1,6 @@
 module Temple
+  # Temple base filter
+  # @api public
   class Filter
     include Utils
     include Mixins::Dispatcher

data/lib/temple/filters/control_flow.rb

@@ -0,0 +1,43 @@
+module Temple
+  module Filters
+    # Control flow filter which processes [:if, condition, yes-exp, no-exp]
+    # and [:block, code, content] expressions.
+    # This is useful for ruby code generation with lots of conditionals.
+    #
+    # @api public
+    class ControlFlow < Filter
+      def on_if(condition, yes, no = nil)
+        result = [:multi, [:code, "if #{condition}"], compile(yes)]
+        while no && no.first == :if
+          result << [:code, "elsif #{no[1]}"] << compile(no[2])
+          no = no[3]
+        end
+        result << [:code, 'else'] << compile(no) if no
+        result << [:code, 'end']
+        result
+      end
+
+      def on_case(arg, *cases)
+        result = [:multi, [:code, arg ? "case (#{arg})" : 'case']]
+        cases.map do |c|
+          condition, *exps = c
+          result << [:code, condition == :else ? 'else' : "when #{condition}"]
+          exps.each {|e| result << compile(e) }
+        end
+        result << [:code, 'end']
+        result
+      end
+
+      def on_cond(*cases)
+        on_case(nil, *cases)
+      end
+
+      def on_block(code, exp)
+        [:multi,
+         [:code, code],
+         compile(exp),
+         [:code, 'end']]
+      end
+    end
+  end
+end

data/lib/temple/filters/dynamic_inliner.rb

@@ -1,24 +1,24 @@
 module Temple
   module Filters
     # Inlines several static/dynamic into a single dynamic.
+    #
+    # @api public
     class DynamicInliner < Filter
       def on_multi(*exps)
-        res = [:multi]
+        result = [:multi]
         curr = nil
         prev = []
         state = :looking
 
-        # We add a noop because we need to do some cleanup at the end too.
-        (exps + [:noop]).each do |exp|
-          head, arg = exp
+        exps.each do |exp|
+          type, arg = exp
 
-          case head
+          case type
           when :newline
-            case state
-            when :looking
+            if state == :looking
               # We haven't found any static/dynamic, so let's just add it
-              res << exp
-            when :single, :several
+              result << exp
+            else
               # We've found something, so let's make sure the generated
               # dynamic contains a newline by escaping a newline and
               # starting a new string:
@@ -31,43 +31,40 @@ module Temple
           when :dynamic, :static
             case state
             when :looking
-              # Found a single static/dynamic.  We don't want to turn this
+              # Found a single static/dynamic. We don't want to turn this
               # into a dynamic yet.  Instead we store it, and if we find
               # another one, we add both then.
               state = :single
               prev = [exp]
-              curr = [:dynamic, '"' + send(head, arg)]
+              curr = [:dynamic, '"']
             when :single
-              # Yes! We found another one.  Append the content to the current
-              # dynamic and add it to the result.
-              curr[1] << send(head, arg)
-              res << curr
+              # Yes! We found another one. Add the current dynamic to the result.
               state = :several
-            when :several
-              # Yet another dynamic/single.  Just add it now.
-              curr[1] << send(head, arg)
+              result << curr
             end
+            curr[1] << (type == :static ? arg.inspect[1..-2] : "\#{#{arg}}")
           else
-            # We need to add the closing quote.
-            curr[1] << '"' unless state == :looking
-            # If we found a single exp last time, let's add it.
-            res.concat(prev) if state == :single
-            # Compile the current exp (unless it's the noop)
-            res << compile(exp) unless head == :noop
+            if state != :looking
+              # We need to add the closing quote.
+              curr[1] << '"'
+              # If we found a single exp last time, let's add it.
+              result.concat(prev) if state == :single
+            end
+            # Compile the current exp
+            result << compile(exp)
             # Now we're looking for more!
             state = :looking
           end
         end
 
-        res
-      end
-
-      def static(str)
-        str.inspect[1..-2]
-      end
+        if state != :looking
+          # We need to add the closing quote.
+          curr[1] << '"'
+          # If we found a single exp last time, let's add it.
+          result.concat(prev) if state == :single
+        end
 
-      def dynamic(str)
-        '#{%s}' % str
+        result
       end
     end
   end

data/lib/temple/filters/eraser.rb

@@ -0,0 +1,22 @@
+module Temple
+  module Filters
+    # Erase expressions with a certain type
+    #
+    # @api public
+    class Eraser < Filter
+      # [] is the empty type => keep all
+      default_options[:keep] = [[]]
+
+      def compile(exp)
+        exp.first == :multi || (do?(:keep, exp) && !do?(:erase, exp)) ?
+          super(exp) : [:multi]
+      end
+
+      protected
+
+      def do?(list, exp)
+        options[list].to_a.map {|type| [*type] }.any? {|type| exp[0,type.size] == type }
+      end
+    end
+  end
+end

data/lib/temple/filters/escapable.rb

@@ -0,0 +1,39 @@
+module Temple
+  module Filters
+    # Escape dynamic or static expressions.
+    # This filter must be used after Temple::HTML::* and before the generators.
+    # It can be enclosed with Temple::Filters::DynamicInliner filters to
+    # reduce calls to Temple::Utils#escape_html.
+    #
+    # @api public
+    class Escapable < Filter
+      # Activate the usage of html_safe? if it is available (for Rails 3 for example)
+      set_default_options :use_html_safe => ''.respond_to?(:html_safe?),
+                          :disable_escape => false
+
+      def initialize(opts = {})
+        super
+        @escape_code = options[:escape_code] ||
+          "Temple::Utils.escape_html#{options[:use_html_safe] ? '_safe' : ''}((%s))"
+        @escaper = eval("proc {|v| #{@escape_code % 'v'} }")
+        @escape = false
+      end
+
+      def on_escape(flag, exp)
+        old = @escape
+        @escape = flag && !options[:disable_escape]
+        compile(exp)
+      ensure
+        @escape = old
+      end
+
+      def on_static(value)
+        [:static, @escape ? @escaper[value] : value]
+      end
+
+      def on_dynamic(value)
+        [:dynamic, @escape ? @escape_code % value : value]
+      end
+    end
+  end
+end

data/lib/temple/filters/multi_flattener.rb

@@ -1,9 +1,12 @@
 module Temple
   module Filters
+    # Flattens nested multi expressions
+    #
+    # @api public
     class MultiFlattener < Filter
       def on_multi(*exps)
         # If the multi contains a single element, just return the element
-        return compile(exps.first) if exps.length == 1
+        return compile(exps.first) if exps.size == 1
         result = [:multi]
 
         exps.each do |exp|

data/lib/temple/filters/static_merger.rb

@@ -10,27 +10,28 @@ module Temple
     #
     #   [:multi,
     #     [:static, "Hello World!"]]
+    #
+    # @api public
     class StaticMerger < Filter
       def on_multi(*exps)
-        res = [:multi]
-        curr = nil
-        state = :looking
+        result = [:multi]
+        text = nil
 
         exps.each do |exp|
           if exp.first == :static
-            if state == :looking
-              res << [:static, (curr = exp[1].dup)]
-              state = :static
+            if text
+              text << exp.last
             else
-              curr << exp[1]
+              text = exp.last.dup
+              result << [:static, text]
             end
           else
-            res << compile(exp)
-            state = :looking unless exp.first == :newline
+            result << compile(exp)
+            text = nil unless exp.first == :newline
           end
         end
 
-        res
+        result
       end
     end
   end

data/lib/temple/filters/validator.rb

@@ -0,0 +1,15 @@
+module Temple
+  module Filters
+    # Validates temple expression with given grammar
+    #
+    # @api public
+    class Validator < Filter
+      default_options[:grammar] = Temple::Grammar
+
+      def compile(exp)
+        options[:grammar].validate!(exp)
+        exp
+      end
+    end
+  end
+end

data/lib/temple/generators.rb

@@ -1,101 +1,56 @@
 module Temple
-  # == The Core Abstraction
+  # Exception raised if invalid temple expression is found
   #
-  # The core abstraction is what every template evetually should be compiled
-  # to. Currently it consists of four essential and two convenient types:
-  # multi, static, dynamic, block, newline and capture.
-  #
-  # When compiling, there's two different strings we'll have to think about.
-  # First we have the generated code. This is what your engine (from Temple's
-  # point of view) spits out. If you construct this carefully enough, you can
-  # make exceptions report correct line numbers, which is very convenient.
-  #
-  # Then there's the result. This is what your engine (from the user's point
-  # of view) spits out. It's what happens if you evaluate the generated code.
-  #
-  # === [:multi, *sexp]
-  #
-  # Multi is what glues everything together. It's simply a sexp which combines
-  # several others sexps:
-  #
-  #   [:multi,
-  #     [:static, "Hello "],
-  #     [:dynamic, "@world"]]
-  #
-  # === [:static, string]
-  #
-  # Static indicates that the given string should be appended to the result.
-  #
-  # Example:
-  #
-  #   [:static, "Hello World"]
-  #   # is the same as:
-  #   _buf << "Hello World"
-  #
-  #   [:static, "Hello \n World"]
-  #   # is the same as
-  #   _buf << "Hello\nWorld"
-  #
-  # === [:dynamic, ruby]
-  #
-  # Dynamic indicates that the given Ruby code should be evaluated and then
-  # appended to the result.
-  #
-  # The Ruby code must be a complete expression in the sense that you can pass
-  # it to eval() and it would not raise SyntaxError.
-  #
-  # === [:block, ruby]
-  #
-  # Block indicates that the given Ruby code should be evaluated, and may
-  # change the control flow. Any \n causes a newline in the generated code.
-  #
-  # === [:newline]
-  #
-  # Newline causes a newline in the generated code, but not in the result.
-  #
-  # === [:capture, variable_name, sexp]
-  #
-  # Evaluates the Sexp using the rules above, but instead of appending to the
-  # result, it sets the content to the variable given.
-  #
-  # Example:
+  # @api public
+  class InvalidExpression < RuntimeError
+  end
+
+  # Abstract generator base class
+  # Generators should inherit this class and
+  # compile the Core Abstraction to ruby code.
   #
-  #   [:multi,
-  #     [:static, "Some content"],
-  #     [:capture, "foo", [:static, "More content"]],
-  #     [:dynamic, "foo.downcase"]]
-  #   # is the same as:
-  #   _buf << "Some content"
-  #   foo = "More content"
-  #   _buf << foo.downcase
+  # @api public
   class Generator
     include Mixins::Options
 
     default_options[:buffer] = '_buf'
 
     def call(exp)
-      [preamble, compile(exp), postamble].join(' ; ')
+      [preamble, compile(exp), postamble].join('; ')
     end
 
     def compile(exp)
       type, *args = exp
-      if respond_to?("on_#{type}")
-        send("on_#{type}", *args)
+      method = "on_#{type}"
+      if respond_to?(method)
+        send(method, *args)
       else
-        raise "Generator supports only core expressions - found #{exp.inspect}"
+        raise InvalidExpression, "Generator supports only core expressions - found #{exp.inspect}"
       end
     end
 
     def on_multi(*exp)
-      exp.map { |e| compile(e) }.join(' ; ')
+      exp.map {|e| compile(e) }.join('; ')
     end
 
     def on_newline
       "\n"
     end
 
-    def on_capture(name, block)
-      options[:capture_generator].new(:buffer => name).call(block)
+    def on_capture(name, exp)
+      options[:capture_generator].new(:buffer => name).call(exp)
+    end
+
+    def on_static(text)
+      concat(text.inspect)
+    end
+
+    def on_dynamic(code)
+      concat(code)
+    end
+
+    def on_code(code)
+      code
     end
 
     protected
@@ -115,36 +70,24 @@ module Temple
     #   _buf = []
     #   _buf << "static"
     #   _buf << dynamic
-    #   block do
-    #     _buf << "more static"
-    #   end
     #   _buf.join
-    class ArrayBuffer < Generator
+    #
+    # @api public
+    class Array < Generator
       def preamble
         "#{buffer} = []"
       end
 
       def postamble
-        "#{buffer} = #{buffer}.join"
-      end
-
-      def on_static(text)
-        concat(text.inspect)
-      end
-
-      def on_dynamic(code)
-        concat(code)
-      end
-
-      def on_block(code)
-        code
+        buffer
       end
     end
 
-    # Just like ArrayBuffer, but doesn't call #join on the array.
-    class Array < ArrayBuffer
+    # Just like Array, but calls #join on the array.
+    # @api public
+    class ArrayBuffer < Array
       def postamble
-        buffer
+        "#{buffer} = #{buffer}.join"
       end
     end
 
@@ -153,10 +96,9 @@ module Temple
     #   _buf = ''
     #   _buf << "static"
     #   _buf << dynamic.to_s
-    #   block do
-    #     _buf << "more static"
-    #   end
     #   _buf
+    #
+    # @api public
     class StringBuffer < Array
       def preamble
         "#{buffer} = ''"
@@ -172,10 +114,9 @@ module Temple
     #   @output_buffer = ActionView::OutputBuffer
     #   @output_buffer.safe_concat "static"
     #   @output_buffer.safe_concat dynamic.to_s
-    #   block do
-    #     @output_buffer << "more static"
-    #   end
     #   @output_buffer
+    #
+    # @api public
     class RailsOutputBuffer < StringBuffer
       set_default_options :buffer_class => 'ActionView::OutputBuffer',
                           :buffer => '@output_buffer',