tilt 1.0.1 → 1.2.2

data/README.md

@@ -34,6 +34,15 @@ Support for these template engines is included with the package:
     RedCloth                   .textile          redcloth
     RDoc                       .rdoc             rdoc
     Radius                     .radius           radius
+    Markaby                    .mab              markaby
+    Nokogiri                   .nokogiri         nokogiri
+    CoffeeScript               .coffee           coffee-script (+node coffee)
+
+These template engines ship with their own Tilt integration:
+
+    ENGINE                     FILE EXTENSIONS   REQUIRED LIBRARIES
+    -------------------------- ----------------- ----------------------------
+    Slim                       .slim             slim (>= 0.7)
 
 See [TEMPLATES.md][t] for detailed information on template engine
 options and supported features.
@@ -150,44 +159,13 @@ Or, use BlueCloth for markdown instead of RDiscount:
 Template Compilation
 --------------------
 
-Tilt can compile generated Ruby source code produced by template engines and
-reuse on subsequent template invocations. Benchmarks show this yields a 5x-10x
+Tilt compiles generated Ruby source code produced by template engines and reuses
+it on subsequent template invocations. Benchmarks show this yields a 5x-10x
 performance increase over evaluating the Ruby source on each invocation.
 
 Template compilation is currently supported for these template engines:
 StringTemplate, ERB, Erubis, Haml, and Builder.
 
-To enable template compilation, the `Tilt::CompileSite` module must be mixed in
-to the scope object passed to the template's `#render` method. This can be
-accomplished by including (with `Module#include`) the module in the class used
-for scope objects or by extending (with `Object#extend`) scope objects before
-passing to `Template#render`:
-
-    require 'tilt'
-
-    template = Tilt::ERBTemplate.new('foo.erb')
-
-    # Slow. Uses Object#instance_eval to process template
-    class Scope
-    end
-    scope = Scope.new
-    template.render(scope)
-
-    # Fast. Uses compiled template and Object#send to process template
-    class Scope
-      include Tilt::CompileSite
-    end
-    scope = Scope.new
-    template.render(scope)
-
-    # Also fast, though a bit a slower due to having to extend each time
-    scope = Object.new
-    scope.extend Tilt::CompileSite
-    template.render(scope)
-
-When the `Tilt::CompileSite` module is not present, template execution falls
-back to evaluating the template from source on each invocation.
-
 LICENSE
 -------
 

data/lib/tilt.rb

@@ -1,7 +1,6 @@
-require 'digest/md5'
-
 module Tilt
-  VERSION = '1.0.1'
+  TOPOBJECT = defined?(BasicObject) ? BasicObject : Object
+  VERSION = '1.2.2'
 
   @template_mappings = {}
 
@@ -42,24 +41,12 @@ module Tilt
     @template_mappings[pattern]
   end
 
-  # Mixin allowing template compilation on scope objects.
-  #
-  # Including this module in scope objects passed to Template#render
-  # causes template source to be compiled to methods the first time they're
-  # used. This can yield significant (5x-10x) performance increases for
-  # templates that support it (ERB, Erubis, Builder).
-  #
-  # It's also possible (though not recommended) to include this module in
-  # Object to enable template compilation globally. The downside is that
-  # the template methods will polute the global namespace and could lead to
-  # unexpected behavior.
+  # Deprecated module.
   module CompileSite
-    def __tilt__
-    end
   end
 
   # Base class for template implementations. Subclasses must implement
-  # the #prepare method and one of the #evaluate or #evaluate_source
+  # the #prepare method and one of the #evaluate or #precompiled_template
   # methods.
   class Template
     # Template source; loaded from a file or given directly.
@@ -111,12 +98,15 @@ module Tilt
         self.class.engine_initialized = true
       end
 
-      # used to generate unique method names for template compilation
-      @stamp = (Time.now.to_f * 10000).to_i
-      @compiled_method_names = {}
+      # used to hold compiled template methods
+      @compiled_method = {}
 
-      # load template data and prepare
-      @reader = block || lambda { |t| File.read(@file) }
+      # used on 1.9 to set the encoding if it is not set elsewhere (like a magic comment)
+      # currently only used if template compiles to ruby
+      @default_encoding = @options.delete :default_encoding
+
+      # load template data and prepare (uses binread to avoid encoding issues)
+      @reader = block || lambda { |t| File.respond_to?(:binread) ? File.binread(@file) : File.read(@file) }
       @data = @reader.call(self)
       prepare
     end
@@ -174,26 +164,26 @@ module Tilt
         raise NotImplementedError
       end
     end
-
-    # Process the template and return the result. When the scope mixes in
-    # the Tilt::CompileSite module, the template is compiled to a method and
-    # reused given identical locals keys. When the scope object
-    # does not mix in the CompileSite module, the template source is
-    # evaluated with instance_eval. In any case, template executation
-    # is guaranteed to be performed in the scope object with the locals
-    # specified and with support for yielding to the block.
+    
     def evaluate(scope, locals, &block)
-      if scope.respond_to?(:__tilt__)
-        method_name = compiled_method_name(locals.keys)
-        if scope.respond_to?(method_name)
-          scope.send(method_name, locals, &block)
-        else
-          compile_template_method(method_name, locals)
-          scope.send(method_name, locals, &block)
-        end
-      else
-        evaluate_source(scope, locals, &block)
+      cached_evaluate(scope, locals, &block)
+    end
+
+    # Process the template and return the result. The first time this
+    # method is called, the template source is evaluated with instance_eval.
+    # On the sequential method calls it will compile the template to an
+    # unbound method which will lead to better performance. In any case,
+    # template executation is guaranteed to be performed in the scope object
+    # with the locals specified and with support for yielding to the block.
+    def cached_evaluate(scope, locals, &block)
+      # Redefine itself to use method compilation the next time:
+      def self.cached_evaluate(scope, locals, &block)
+        method = compiled_method(locals.keys)
+        method.bind(scope).call(locals, &block)
       end
+
+      # Use instance_eval the first time:
+      evaluate_source(scope, locals, &block)
     end
 
     # Generates all template source by combining the preamble, template, and
@@ -207,9 +197,16 @@ module Tilt
     # easier and more appropriate.
     def precompiled(locals)
       preamble = precompiled_preamble(locals)
+      template = precompiled_template(locals)
+      magic_comment = extract_magic_comment(template)
+      if magic_comment
+        # Magic comment e.g. "# coding: utf-8" has to be in the first line.
+        # So we copy the magic comment to the first line.
+        preamble = magic_comment + "\n" + preamble
+      end
       parts = [
         preamble,
-        precompiled_template(locals),
+        template,
         precompiled_postamble(locals)
       ]
       [parts.join("\n"), preamble.count("\n") + 1]
@@ -241,10 +238,10 @@ module Tilt
       ''
     end
 
-    # The unique compiled method name for the locals keys provided.
-    def compiled_method_name(locals_keys)
-      @compiled_method_names[locals_keys] ||=
-        generate_compiled_method_name(locals_keys)
+    # The compiled method for the locals keys provided.
+    def compiled_method(locals_keys)
+      @compiled_method[locals_keys] ||=
+        compile_template_method(locals_keys)
     end
 
   private
@@ -274,36 +271,59 @@ module Tilt
       end
     end
 
-    def generate_compiled_method_name(locals_keys)
-      parts = [object_id, @stamp] + locals_keys.map { |k| k.to_s }.sort
-      digest = Digest::MD5.hexdigest(parts.join(':'))
-      "__tilt_#{digest}"
-    end
-
-    def compile_template_method(method_name, locals)
+    def compile_template_method(locals)
       source, offset = precompiled(locals)
-      offset += 1
-      CompileSite.module_eval <<-RUBY, eval_file, line - offset
-        def #{method_name}(locals)
-          #{source}
+      offset += 5
+      method_name = "__tilt_#{Thread.current.object_id.abs}"
+      Object.class_eval <<-RUBY, eval_file, line - offset
+        #{extract_magic_comment source}
+        TOPOBJECT.class_eval do
+          def #{method_name}(locals)
+            Thread.current[:tilt_vars] = [self, locals]
+            class << self
+              this, locals = Thread.current[:tilt_vars]
+              this.instance_eval do
+               #{source}
+              end
+            end
+          end
         end
       RUBY
+      unbind_compiled_method(method_name)
+    end
 
-      ObjectSpace.define_finalizer self,
-        Template.compiled_template_method_remover(CompileSite, method_name)
+    def unbind_compiled_method(method_name)
+      method = TOPOBJECT.instance_method(method_name)
+      TOPOBJECT.class_eval { remove_method(method_name) }
+      method
     end
 
-    def self.compiled_template_method_remover(site, method_name)
-      proc { |oid| garbage_collect_compiled_template_method(site, method_name) }
+    def extract_magic_comment(script)
+      comment = script.slice(/\A[ \t]*\#.*coding\s*[=:]\s*([[:alnum:]\-_]+).*$/)
+      return comment if comment and not %w[ascii-8bit binary].include?($1.downcase)
+      "# coding: #{@default_encoding}" if @default_encoding
     end
 
-    def self.garbage_collect_compiled_template_method(site, method_name)
-      site.module_eval do
-        begin
-          remove_method(method_name)
-        rescue NameError
-          # method was already removed (ruby >= 1.9)
-        end
+    # Special case Ruby 1.9.1's broken yield.
+    #
+    # http://github.com/rtomayko/tilt/commit/20c01a5
+    # http://redmine.ruby-lang.org/issues/show/3601
+    #
+    # Remove when 1.9.2 dominates 1.9.1 installs in the wild.
+    if RUBY_VERSION =~ /^1.9.1/
+      undef compile_template_method
+      def compile_template_method(locals)
+        source, offset = precompiled(locals)
+        offset += 1
+        method_name = "__tilt_#{Thread.current.object_id}"
+        Object.class_eval <<-RUBY, eval_file, line - offset
+          TOPOBJECT.class_eval do
+            def #{method_name}(locals)
+              #{source}
+            end
+          end
+        RUBY
+        unbind_compiled_method(method_name)
       end
     end
   end
@@ -528,11 +548,19 @@ module Tilt
 
   private
     def sass_options
-      options.merge(:filename => eval_file, :line => line)
+      options.merge(:filename => eval_file, :line => line, :syntax => :sass)
     end
   end
   register 'sass', SassTemplate
 
+  # Sass's new .scss type template implementation.
+  class ScssTemplate < SassTemplate
+  private
+    def sass_options
+      options.merge(:filename => eval_file, :line => line, :syntax => :scss)
+    end
+  end
+  register 'scss', ScssTemplate
 
   # Lessscss template implementation. See:
   # http://lesscss.org/
@@ -555,6 +583,73 @@ module Tilt
   register 'less', LessTemplate
 
 
+  # CoffeeScript template implementation. See:
+  # http://coffeescript.org/
+  #
+  # CoffeeScript templates do not support object scopes, locals, or yield.
+  class CoffeeScriptTemplate < Template
+    @@default_no_wrap = false
+
+    def self.default_no_wrap
+      @@default_no_wrap
+    end
+
+    def self.default_no_wrap=(value)
+      @@default_no_wrap = value
+    end
+
+    def initialize_engine
+      return if defined? ::CoffeeScript
+      require_template_library 'coffee_script'
+    end
+
+    def prepare
+      @no_wrap = options.key?(:no_wrap) ? options[:no_wrap] :
+        self.class.default_no_wrap
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= CoffeeScript.compile(data, :no_wrap => @no_wrap)
+    end
+  end
+  register 'coffee', CoffeeScriptTemplate
+
+
+  # Nokogiri template implementation. See:
+  # http://nokogiri.org/
+  class NokogiriTemplate < Template
+    def initialize_engine
+      return if defined?(::Nokogiri)
+      require_template_library 'nokogiri'
+    end
+
+    def prepare; end
+    
+    def evaluate(scope, locals, &block)
+      block &&= proc { yield.gsub(/^<\?xml version=\"1\.0\"\?>\n?/, "") }
+      
+      if data.respond_to?(:to_str)
+        super(scope, locals, &block)
+      else
+        ::Nokogiri::XML::Builder.new.tap(&data).to_xml
+      end
+    end
+
+    def precompiled_preamble(locals)
+      return super if locals.include? :xml
+      "xml = ::Nokogiri::XML::Builder.new\n#{super}"
+    end
+
+    def precompiled_postamble(locals)
+      "xml.to_xml"
+    end
+
+    def precompiled_template(locals)
+      data.to_str
+    end
+  end
+  register 'nokogiri', NokogiriTemplate
+
   # Builder template implementation. See:
   # http://builder.rubyforge.org/
   class BuilderTemplate < Template
@@ -563,20 +658,24 @@ module Tilt
       require_template_library 'builder'
     end
 
-    def prepare
-    end
+    def prepare; end
 
     def evaluate(scope, locals, &block)
+      return super(scope, locals, &block) if data.respond_to?(:to_str)
       xml = ::Builder::XmlMarkup.new(:indent => 2)
-      if data.respond_to?(:to_str)
-        locals[:xml] = xml
-        super(scope, locals, &block)
-      elsif data.kind_of?(Proc)
-        data.call(xml)
-      end
+      data.call(xml)
       xml.target!
     end
 
+    def precompiled_preamble(locals)
+      return super if locals.include? :xml
+      "xml = ::Builder::XmlMarkup.new(:indent => 2)\n#{super}"
+    end
+
+    def precompiled_postamble(locals)
+      "xml.target!"
+    end
+
     def precompiled_template(locals)
       data.to_str
     end
@@ -651,6 +750,29 @@ module Tilt
   register 'md', RDiscountTemplate
 
 
+  # BlueCloth Markdown implementation. See:
+  # http://deveiate.org/projects/BlueCloth/
+  #
+  # RDiscount is a simple text filter. It does not support +scope+ or
+  # +locals+. The +:smartypants+ and +:escape_html+ options may be set true
+  # to enable those flags on the underlying BlueCloth object.
+  class BlueClothTemplate < Template
+    def initialize_engine
+      return if defined? ::BlueCloth
+      require_template_library 'bluecloth'
+    end
+
+    def prepare
+      @engine = BlueCloth.new(data, options)
+      @output = nil
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= @engine.to_html
+    end
+  end
+
+
   # RedCloth implementation. See:
   # http://redcloth.org/
   class RedClothTemplate < Template
@@ -729,4 +851,51 @@ module Tilt
     end
   end
   register 'radius', RadiusTemplate
+
+
+  # Markaby
+  # http://github.com/markaby/markaby
+  class MarkabyTemplate < Template
+    def self.builder_class
+      @builder_class ||= Class.new(Markaby::Builder) do
+        def __capture_markaby_tilt__(&block)
+          __run_markaby_tilt__ do
+            text capture(&block)
+          end
+        end
+      end
+    end
+
+    def initialize_engine
+      return if defined? ::Markaby
+      require_template_library 'markaby'
+    end
+
+    def prepare
+    end
+
+    def evaluate(scope, locals, &block)
+      builder = self.class.builder_class.new({}, scope)
+      builder.locals = locals
+
+      if data.kind_of? Proc
+        (class << builder; self end).send(:define_method, :__run_markaby_tilt__, &data)
+      else
+        builder.instance_eval <<-CODE, __FILE__, __LINE__
+          def __run_markaby_tilt__
+            #{data}
+          end
+        CODE
+      end
+
+      if block
+        builder.__capture_markaby_tilt__(&block)
+      else
+        builder.__run_markaby_tilt__
+      end
+
+      builder.to_s
+    end
+  end
+  register 'mab', MarkabyTemplate
 end

data/test/markaby/locals.mab

@@ -0,0 +1 @@
+li foo

data/test/markaby/markaby.mab

@@ -0,0 +1 @@
+text "hello from markaby!"

data/test/markaby/markaby_other_static.mab

@@ -0,0 +1 @@
+text "_why?"

data/test/markaby/render_twice.mab

@@ -0,0 +1 @@
+text "foo"

data/test/markaby/scope.mab

@@ -0,0 +1 @@
+li foo

data/test/markaby/yielding.mab

@@ -0,0 +1,2 @@
+text("Hey ")
+yield

data/test/tilt_blueclothtemplate_test.rb

@@ -0,0 +1,64 @@
+require 'contest'
+require 'tilt'
+
+begin
+  require 'bluecloth'
+
+  class BlueClothTemplateTest < Test::Unit::TestCase
+    setup do
+      Tilt.register('markdown', Tilt::BlueClothTemplate)
+      Tilt.register('md', Tilt::BlueClothTemplate)
+      Tilt.register('mkd', Tilt::BlueClothTemplate)
+    end
+
+    teardown do
+      # Need to revert to RDiscount, otherwise the RDiscount test will fail
+      Tilt.register('markdown', Tilt::RDiscountTemplate)
+      Tilt.register('md', Tilt::RDiscountTemplate)
+      Tilt.register('mkd', Tilt::RDiscountTemplate)
+    end
+
+    test "registered for '.markdown' files unless RDiscount is loaded" do
+      unless defined?(RDiscount)
+        assert_equal Tilt::BlueClothTemplate, Tilt['test.markdown']
+      end
+    end
+
+    test "registered for '.md' files unless RDiscount is loaded" do
+      unless defined?(RDiscount)
+        assert_equal Tilt::BlueClothTemplate, Tilt['test.md']
+      end
+    end
+
+    test "registered for '.mkd' files unless RDiscount is loaded" do
+      unless defined?(RDiscount)
+        assert_equal Tilt::BlueClothTemplate, Tilt['test.mkd']
+      end
+    end
+
+    test "preparing and evaluating templates on #render" do
+      template = Tilt::BlueClothTemplate.new { |t| "# Hello World!" }
+      assert_equal "<h1>Hello World!</h1>", template.render
+    end
+
+    test "can be rendered more than once" do
+      template = Tilt::BlueClothTemplate.new { |t| "# Hello World!" }
+      3.times { assert_equal "<h1>Hello World!</h1>", template.render }
+    end
+
+    test "smartypants when :smart is set" do
+      template = Tilt::BlueClothTemplate.new(:smartypants => true) { |t|
+        "OKAY -- 'Smarty Pants'" }
+      assert_equal "<p>OKAY &mdash; &lsquo;Smarty Pants&rsquo;</p>",
+        template.render
+    end
+
+    test "stripping HTML when :filter_html is set" do
+      template = Tilt::BlueClothTemplate.new(:escape_html => true) { |t|
+        "HELLO <blink>WORLD</blink>" }
+      assert_equal "<p>HELLO &lt;blink>WORLD&lt;/blink></p>", template.render
+    end
+  end
+rescue LoadError => boom
+  warn "Tilt::BlueClothTemplate (disabled)\n"
+end

data/test/tilt_buildertemplate_test.rb

@@ -14,6 +14,11 @@ begin
       assert_equal "<em>Hello World!</em>\n", template.render
     end
 
+    test "can be rendered more than once" do
+      template = Tilt::BuilderTemplate.new { |t| "xml.em 'Hello World!'" }
+      3.times { assert_equal "<em>Hello World!</em>\n", template.render }
+    end
+
     test "passing locals" do
       template = Tilt::BuilderTemplate.new { "xml.em('Hey ' + name + '!')" }
       assert_equal "<em>Hey Joe!</em>\n", template.render(Object.new, :name => 'Joe')
@@ -28,7 +33,7 @@ begin
 
     test "passing a block for yield" do
       template = Tilt::BuilderTemplate.new { "xml.em('Hey ' + yield + '!')" }
-      assert_equal "<em>Hey Joe!</em>\n", template.render { 'Joe' }
+      3.times { assert_equal "<em>Hey Joe!</em>\n", template.render { 'Joe' }}
     end
 
     test "block style templates" do
@@ -38,6 +43,16 @@ begin
         end
       assert_equal "<em>Hey Joe!</em>\n", template.render
     end
+
+    test "allows nesting raw XML" do
+      subtemplate = Tilt::BuilderTemplate.new { "xml.em 'Hello World!'" }
+      template = Tilt::BuilderTemplate.new { "xml.strong { xml << yield }" }
+      3.times do
+        options = { :xml => Builder::XmlMarkup.new }
+        assert_equal "<strong>\n<em>Hello World!</em>\n</strong>\n",
+          template.render(options) { subtemplate.render(options) }
+      end
+    end
   end
 rescue LoadError
   warn "Tilt::BuilderTemplate (disabled)"

data/test/tilt_cache_test.rb

@@ -14,10 +14,9 @@ class TiltCacheTest < Test::Unit::TestCase
 
   test "caching with multiple complex arguments to #fetch" do
     template = nil
-    args = ['hello', {:foo => 'bar', :baz => 'bizzle'}]
-    result = @cache.fetch(*args) { template = Tilt::StringTemplate.new {''} }
+    result = @cache.fetch('hello', {:foo => 'bar', :baz => 'bizzle'}) { template = Tilt::StringTemplate.new {''} }
     assert_same template, result
-    result = @cache.fetch(*args) { fail 'should be cached' }
+    result = @cache.fetch('hello', {:foo => 'bar', :baz => 'bizzle'}) { fail 'should be cached' }
     assert_same template, result
   end
 

data/test/tilt_coffeescripttemplate_test.rb

@@ -0,0 +1,30 @@
+require 'contest'
+require 'tilt'
+
+begin
+  require 'coffee_script'
+
+  class CoffeeScriptTemplateTest < Test::Unit::TestCase
+    test "is registered for '.coffee' files" do
+      assert_equal Tilt::CoffeeScriptTemplate, Tilt['test.coffee']
+    end
+
+    test "compiles and evaluates the template on #render" do
+      template = Tilt::CoffeeScriptTemplate.new { |t| "puts 'Hello, World!'\n" }
+      assert_match "puts('Hello, World!');", template.render
+    end
+
+    test "can be rendered more than once" do
+      template = Tilt::CoffeeScriptTemplate.new { |t| "puts 'Hello, World!'\n" }
+      3.times { assert_match "puts('Hello, World!');", template.render }
+    end
+
+    test "disabling coffee-script wrapper" do
+      template = Tilt::CoffeeScriptTemplate.new(:no_wrap => true) { |t| "puts 'Hello, World!'\n" }
+      assert_equal "puts('Hello, World!');", template.render
+    end
+  end
+
+rescue LoadError => boom
+  warn "Tilt::CoffeeScriptTemplate (disabled)\n"
+end