tilt 0.6 → 0.7

data/README.md

@@ -33,6 +33,12 @@ Support for these template engines is included with the package:
     RDiscount                  .markdown         rdiscount
     RedCloth                   .textile          redcloth
 
+See [TEMPLATES.md][t] for detailed information on template engine
+options and supported features.
+
+[t]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md
+   "Tilt Template Engine Documentation"
+
 Basic Usage
 -----------
 

data/Rakefile

@@ -16,38 +16,39 @@ end
 
 # PACKAGING =================================================================
 
-require 'rubygems/specification'
-$spec ||= eval(File.read('tilt.gemspec'))
-
-def package(ext='')
-  "dist/tilt-#{$spec.version}" + ext
-end
-
-desc 'Build packages'
-task :package => %w[.gem .tar.gz].map {|e| package(e)}
-
-desc 'Build and install as local gem'
-task :install => package('.gem') do
-  sh "gem install #{package('.gem')}"
-end
-
-directory 'dist/'
-
-file package('.gem') => %w[dist/ tilt.gemspec] + $spec.files do |f|
-  sh "gem build tilt.gemspec"
-  mv File.basename(f.name), f.name
-end
-
-file package('.tar.gz') => %w[dist/] + $spec.files do |f|
-  sh "git archive --format=tar HEAD | gzip > #{f.name}"
-end
-
-desc 'Upload gem and tar.gz distributables to rubyforge'
-task :release => [package('.gem'), package('.tar.gz')] do |t|
-  sh <<-SH
-    rubyforge add_release sinatra tilt #{$spec.version} #{package('.gem')} &&
-    rubyforge add_file    sinatra tilt #{$spec.version} #{package('.tar.gz')}
-  SH
+if defined?(Gem)
+  SPEC = eval(File.read('tilt.gemspec'))
+
+  def package(ext='')
+    "pkg/tilt-#{SPEC.version}" + ext
+  end
+
+  desc 'Build packages'
+  task :package => %w[.gem .tar.gz].map {|e| package(e)}
+
+  desc 'Build and install as local gem'
+  task :install => package('.gem') do
+    sh "gem install #{package('.gem')}"
+  end
+
+  directory 'pkg/'
+
+  file package('.gem') => %w[pkg/ tilt.gemspec] + SPEC.files do |f|
+    sh "gem build tilt.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w[pkg/] + SPEC.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc 'Upload gem and tar.gz distributables to rubyforge'
+  task :release => [package('.gem'), package('.tar.gz')] do |t|
+    sh <<-SH
+      rubyforge add_release sinatra tilt #{SPEC.version} #{package('.gem')} &&
+      rubyforge add_file    sinatra tilt #{SPEC.version} #{package('.tar.gz')}
+    SH
+  end
 end
 
 # GEMSPEC ===================================================================

data/TEMPLATES.md

@@ -67,6 +67,12 @@ of any combination of the following characters:
 The `$SAFE` level; when set, ERB code will be run in a
 separate thread with `$SAFE` set to the provided level.
 
+#### `:outvar => '_erbout'`
+
+The name of the variable used to accumulate template output. This can be
+any valid Ruby expression but must be assignable. By default a local
+variable named `_erbout` is used.
+
 ### See also
 
   * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
@@ -98,14 +104,19 @@ Set pattern for embedded Ruby code.
 
 See the [ERB](#erb) template documentation for examples, usage, and options.
 
-__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
-using this template engine within a threaded environment.
+#### `:outvar => '_erbout'`
+
+The name of the variable used to accumulate template output. This can be
+any valid Ruby expression but must be assignable. By default a local
+variable named `_erbout` is used.
 
 ### See also
 
   * [Erubis Home](http://www.kuwata-lab.com/erubis/)
   * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
 
+__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
+using this template engine within a threaded environment.
 
 <a name='haml'></a>
 Haml (`haml`)

data/lib/tilt.rb

@@ -1,10 +1,9 @@
 module Tilt
-  VERSION = '0.6'
+  VERSION = '0.7'
 
   @template_mappings = {}
 
-  # Hash of template path pattern => template implementation
-  # class mappings.
+  # Hash of template path pattern => template implementation class mappings.
   def self.mappings
     @template_mappings
   end
@@ -25,7 +24,7 @@ module Tilt
     end
   end
 
-  # Lookup a template class given for the given filename or file
+  # Lookup a template class for the given filename or file
   # extension. Return nil when no implementation is found.
   def self.[](file)
     if @template_mappings.key?(pattern = file.to_s.downcase)
@@ -44,9 +43,24 @@ module Tilt
     end
   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.
+  module CompileSite
+    def __tilt__
+    end
+  end
 
   # Base class for template implementations. Subclasses must implement
-  # the #compile! method and one of the #evaluate or #template_source
+  # the #prepare method and one of the #evaluate or #template_source
   # methods.
   class Template
     # Template source; loaded from a file or given directly.
@@ -63,52 +77,55 @@ module Tilt
     # interface.
     attr_reader :options
 
+    # Used to determine if this class's initialize_engine method has
+    # been called yet.
+    @engine_initialized = false
+    class << self
+      attr_accessor :engine_initialized
+      alias engine_initialized? engine_initialized
+    end
+
     # Create a new template with the file, line, and options specified. By
-    # default, template data is read from the file specified. When a block
-    # is given, it should read template data and return as a String. When
-    # file is nil, a block is required.
+    # default, template data is read from the file. When a block is given,
+    # it should read template data and return as a String. When file is nil,
+    # a block is required.
     #
-    # The #initialize_engine method is called if this is the very first
-    # time this template subclass has been initialized.
+    # All arguments are optional.
     def initialize(file=nil, line=1, options={}, &block)
-      raise ArgumentError, "file or block required" if file.nil? && block.nil?
-      options, line = line, 1 if line.is_a?(Hash)
-      @file = file
-      @line = line || 1
-      @options = options || {}
-      @reader = block || lambda { |t| File.read(file) }
-      @data = nil
-
-      if !self.class.engine_initialized
+      @file, @line, @options = nil, 1, {}
+
+      [options, line, file].compact.each do |arg|
+        case
+        when arg.respond_to?(:to_str)  ; @file = arg.to_str
+        when arg.respond_to?(:to_int)  ; @line = arg.to_int
+        when arg.respond_to?(:to_hash) ; @options = arg.to_hash
+        else raise TypeError
+        end
+      end
+
+      raise ArgumentError, "file or block required" if (@file || block).nil?
+
+      # call the initialize_engine method if this is the very first time
+      # an instance of this class has been created.
+      if !self.class.engine_initialized?
         initialize_engine
         self.class.engine_initialized = true
       end
-    end
-
-    # Called once and only once for each template subclass the first time
-    # the template class is initialized. This should be used to require the
-    # underlying template library and perform any initial setup.
-    def initialize_engine
-    end
-    @engine_initialized = false
-    class << self ; attr_accessor :engine_initialized ; end
 
+      # used to generate unique method names for template compilation
+      stamp = (Time.now.to_f * 10000).to_i
+      @_prefix = "__tilt_O#{object_id.to_s(16)}T#{stamp.to_s(16)}"
 
-    # Load template source and compile the template. The template is
-    # loaded and compiled the first time this method is called; subsequent
-    # calls are no-ops.
-    def compile
-      if @data.nil?
-        @data = @reader.call(self)
-        compile!
-      end
+      # load template data and prepare
+      @reader = block || lambda { |t| File.read(@file) }
+      @data = @reader.call(self)
+      prepare
     end
 
     # Render the template in the given scope with the locals specified. If a
     # block is given, it is typically available within the template via
     # +yield+.
     def render(scope=Object.new, locals={}, &block)
-      compile
       evaluate scope, locals || {}, &block
     end
 
@@ -128,26 +145,56 @@ module Tilt
     end
 
   protected
-    # Do whatever preparation is necessary to "compile" the template.
-    # Called immediately after template #data is loaded. Instance variables
-    # set in this method are available when #evaluate is called.
+    # Called once and only once for each template subclass the first time
+    # the template class is initialized. This should be used to require the
+    # underlying template library and perform any initial setup.
+    def initialize_engine
+    end
+
+    # Do whatever preparation is necessary to setup the underlying template
+    # engine. Called immediately after template data is loaded. Instance
+    # variables set in this method are available when #evaluate is called.
     #
     # Subclasses must provide an implementation of this method.
-    def compile!
-      raise NotImplementedError
+    def prepare
+      if respond_to?(:compile!)
+        # backward compat with tilt < 0.6; just in case
+        warn 'Tilt::Template#compile! is deprecated; implement #prepare instead.'
+        compile!
+      else
+        raise NotImplementedError
+      end
     end
 
-    # Process the template and return the result. Subclasses should override
-    # this method unless they implement the #template_source.
+    # 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)
-      source, offset = local_assignment_code(locals)
-      source = [source, template_source].join("\n")
-      scope.instance_eval source, eval_file, line - offset
+      if scope.respond_to?(:__tilt__)
+        method_name = compiled_method_name(locals.keys.hash)
+        if scope.respond_to?(method_name)
+          # fast path
+          scope.send method_name, locals, &block
+        else
+          # compile first and then run
+          compile_template_method(method_name, locals)
+          scope.send method_name, locals, &block
+        end
+      else
+        source, offset = local_assignment_code(locals)
+        source = [source, template_source].join("\n")
+        scope.instance_eval source, eval_file, line - offset
+      end
     end
 
     # Return a string containing the (Ruby) source code for the template. The
     # default Template#evaluate implementation requires this method be
-    # defined.
+    # defined and guarantees correct file/line handling, custom scopes, and
+    # support for template compilation when the scope object allows it.
     def template_source
       raise NotImplementedError
     end
@@ -159,6 +206,41 @@ module Tilt
       [source.join("\n"), source.length]
     end
 
+    def compiled_method_name(locals_hash)
+      "#{@_prefix}L#{locals_hash.to_s(16).sub('-', 'n')}"
+    end
+
+    def compile_template_method(method_name, locals)
+      source, offset = local_assignment_code(locals)
+      source = [source, template_source].join("\n")
+      offset += 1
+
+      # add the new method
+      CompileSite.module_eval <<-RUBY, eval_file, line - offset
+        def #{method_name}(locals)
+          #{source}
+        end
+      RUBY
+
+      # setup a finalizer to remove the newly added method
+      ObjectSpace.define_finalizer self,
+        Template.compiled_template_method_remover(CompileSite, method_name)
+    end
+
+    def self.compiled_template_method_remover(site, method_name)
+      proc { |oid| garbage_collect_compiled_template_method(site, method_name) }
+    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
+      end
+    end
+
     def require_template_library(name)
       if Thread.list.size > 1
         warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
@@ -174,7 +256,7 @@ module Tilt
   #   cache = Tilt::Cache.new
   #   cache.fetch(path, line, options) { Tilt.new(path, line, options) }
   #
-  # Subsequent invocations return the already compiled template object.
+  # Subsequent invocations return the already loaded template object.
   class Cache
     def initialize
       @cache = {}
@@ -196,7 +278,7 @@ module Tilt
   # The template source is evaluated as a Ruby string. The #{} interpolation
   # syntax can be used to generated dynamic output.
   class StringTemplate < Template
-    def compile!
+    def prepare
       @code = "%Q{#{data}}"
     end
 
@@ -214,8 +296,9 @@ module Tilt
       require_template_library 'erb' unless defined? ::ERB
     end
 
-    def compile!
-      @engine = ::ERB.new(data, options[:safe], options[:trim], '@_out_buf')
+    def prepare
+      @outvar = (options[:outvar] || '_erbout').to_s
+      @engine = ::ERB.new(data, options[:safe], options[:trim], @outvar)
     end
 
     def template_source
@@ -223,22 +306,23 @@ module Tilt
     end
 
     def evaluate(scope, locals, &block)
-      source, offset = local_assignment_code(locals)
-      source = [source, template_source].join("\n")
-
-      original_out_buf =
-        scope.instance_variables.any? { |var| var.to_sym == :@_out_buf } &&
-        scope.instance_variable_get(:@_out_buf)
-
-      scope.instance_eval source, eval_file, line - offset
-
-      output = scope.instance_variable_get(:@_out_buf)
-      scope.instance_variable_set(:@_out_buf, original_out_buf)
-
-      output
+      preserve_outvar_value(scope) { super }
     end
 
   private
+    # Retains the previous value of outvar when configured to use
+    # an instance variable. This allows multiple templates to be rendered
+    # within the context of an object without overwriting the outvar.
+    def preserve_outvar_value(scope)
+      if @outvar[0] == ?@
+        previous = scope.instance_variable_get(@outvar)
+        output = yield
+        scope.instance_variable_set(@outvar, previous)
+        output
+      else
+        yield
+      end
+    end
 
     # ERB generates a line to specify the character coding of the generated
     # source in 1.9. Account for this in the line offset.
@@ -259,13 +343,17 @@ module Tilt
       require_template_library 'erubis' unless defined? ::Erubis
     end
 
-    def compile!
-      Erubis::Eruby.class_eval(%Q{def add_preamble(src) src << "@_out_buf = _buf = '';" end})
+    def prepare
+      @options.merge!(:preamble => false, :postamble => false)
+      @outvar = (options.delete(:outvar) || '_erbout').to_s
       @engine = ::Erubis::Eruby.new(data, options)
     end
 
-  private
+    def template_source
+      ["#{@outvar} = _buf = ''", @engine.src, "_buf.to_s"].join(";")
+    end
 
+  private
     # Erubis doesn't have ERB's line-off-by-one under 1.9 problem. Override
     # and adjust back.
     if RUBY_VERSION >= '1.9.0'
@@ -285,15 +373,37 @@ module Tilt
       require_template_library 'haml' unless defined? ::Haml::Engine
     end
 
-    def compile!
+    def prepare
       @engine = ::Haml::Engine.new(data, haml_options)
     end
 
-    def evaluate(scope, locals, &block)
-      @engine.render(scope, locals, &block)
+    # Precompiled Haml source. Taken from the precompiled_with_ambles
+    # method in Haml::Precompiler:
+    # http://github.com/nex3/haml/blob/master/lib/haml/precompiler.rb#L111-126
+    def template_source
+      @engine.instance_eval do
+        <<-RUBY
+          _haml_locals = locals
+          begin
+            extend Haml::Helpers
+            _hamlout = @haml_buffer = Haml::Buffer.new(@haml_buffer, #{options_for_buffer.inspect})
+            _erbout = _hamlout.buffer
+            __in_erb_template = true
+            #{precompiled}
+            #{precompiled_method_return_value}
+          ensure
+            @haml_buffer = @haml_buffer.upper
+          end
+        RUBY
+      end
     end
 
   private
+    def local_assignment_code(locals)
+      source, offset = super
+      [source, offset + 6]
+    end
+
     def haml_options
       options.merge(:filename => eval_file, :line => line)
     end
@@ -310,12 +420,12 @@ module Tilt
       require_template_library 'sass' unless defined? ::Sass::Engine
     end
 
-    def compile!
+    def prepare
       @engine = ::Sass::Engine.new(data, sass_options)
     end
 
     def evaluate(scope, locals, &block)
-      @engine.render
+      @output ||= @engine.render
     end
 
   private
@@ -335,7 +445,7 @@ module Tilt
       require_template_library 'less' unless defined? ::Less::Engine
     end
 
-    def compile!
+    def prepare
       @engine = ::Less::Engine.new(data)
     end
 
@@ -345,6 +455,7 @@ module Tilt
   end
   register 'less', LessTemplate
 
+
   # Builder template implementation. See:
   # http://builder.rubyforge.org/
   class BuilderTemplate < Template
@@ -352,7 +463,7 @@ module Tilt
       require_template_library 'builder' unless defined?(::Builder)
     end
 
-    def compile!
+    def prepare
     end
 
     def evaluate(scope, locals, &block)
@@ -391,7 +502,7 @@ module Tilt
       require_template_library 'liquid' unless defined? ::Liquid::Template
     end
 
-    def compile!
+    def prepare
       @engine = ::Liquid::Template.parse(data)
     end
 
@@ -424,7 +535,7 @@ module Tilt
       require_template_library 'rdiscount' unless defined? ::RDiscount
     end
 
-    def compile!
+    def prepare
       @engine = RDiscount.new(data, *flags)
     end
 
@@ -444,7 +555,7 @@ module Tilt
       require_template_library 'redcloth' unless defined? ::RedCloth
     end
 
-    def compile!
+    def prepare
       @engine = RedCloth.new(data)
     end
 
@@ -468,7 +579,7 @@ module Tilt
       require_template_library 'mustache' unless defined? ::Mustache
     end
 
-    def compile!
+    def prepare
       Mustache.view_namespace = options[:namespace]
       Mustache.view_path = options[:view_path] || options[:mustaches]
       @engine = options[:view] || Mustache.view_class(name)
@@ -502,6 +613,7 @@ module Tilt
   end
   register 'mustache', MustacheTemplate
 
+
   # RDoc template. See:
   # http://rdoc.rubyforge.org/
   #
@@ -516,7 +628,7 @@ module Tilt
       end
     end
 
-    def compile!
+    def prepare
       markup = RDoc::Markup::ToHtml.new
       @engine = markup.convert(data)
     end
@@ -527,6 +639,7 @@ module Tilt
   end
   register 'rdoc', RDocTemplate
 
+
   # CoffeeScript info:
   # http://jashkenas.github.com/coffee-script/
   class CoffeeTemplate < Template
@@ -534,7 +647,7 @@ module Tilt
       require_template_library 'coffee-script' unless defined? ::CoffeeScript
     end
 
-    def compile!
+    def prepare
       @engine = ::CoffeeScript::compile(data, options)
     end
 

data/test/tilt_buildertemplate_test.rb

@@ -9,7 +9,7 @@ begin
       assert_equal Tilt::BuilderTemplate, Tilt['test.xml.builder']
     end
 
-    test "compiling and evaluating the template on #render" do
+    test "preparing and evaluating the template on #render" do
       template = Tilt::BuilderTemplate.new { |t| "xml.em 'Hello World!'" }
       assert_equal "<em>Hello World!</em>\n", template.render
     end

data/test/tilt_compilesite_test.rb

@@ -0,0 +1,62 @@
+require 'contest'
+require 'tilt'
+
+class CompileSiteTest < Test::Unit::TestCase
+  def setup
+    GC.start
+  end
+
+  class CompilingTemplate < Tilt::Template
+    def prepare
+    end
+
+    def template_source
+      @data.inspect
+    end
+  end
+
+  class Scope
+    include Tilt::CompileSite
+  end
+
+  test "compiling template source to a method" do
+    template = CompilingTemplate.new { |t| "Hello World!" }
+    template.render(Scope.new)
+    method_name = template.send(:compiled_method_name, [].hash)
+    method_name = method_name.to_sym if Symbol === Kernel.methods.first
+    assert Tilt::CompileSite.instance_methods.include?(method_name),
+      "CompileSite.instance_methods.include?(#{method_name.inspect})"
+    assert Scope.new.respond_to?(method_name),
+      "scope.respond_to?(#{method_name.inspect})"
+  end
+
+  test 'garbage collecting compiled methods' do
+    template = CompilingTemplate.new { '' }
+    method_name = template.send(:compiled_method_name, [].hash)
+    template.render(Scope.new)
+    assert Scope.new.respond_to?(method_name)
+    Tilt::Template.send(
+      :garbage_collect_compiled_template_method,
+      Tilt::CompileSite,
+      method_name
+    )
+    assert !Scope.new.respond_to?(method_name), "compiled method not removed"
+  end
+
+  def self.create_and_destroy_template
+    template = CompilingTemplate.new { 'Hello World' }
+    template.render(Scope.new)
+    method_name = template.send(:compiled_method_name, [].hash)
+    method_name = method_name.to_sym if Symbol === Kernel.methods.first
+    [template.object_id, method_name]
+  end
+
+  finalized_object_id, finalized_method_name = create_and_destroy_template
+
+  test "triggering compiled method gc finalizer" do
+    assert !Tilt::CompileSite.instance_methods.include?(finalized_method_name),
+      "CompileSite.instance_methods.include?(#{finalized_method_name.inspect})"
+    assert !Scope.new.respond_to?(finalized_method_name),
+      "Scope.new.respond_to?(#{finalized_method_name.inspect})"
+  end
+end

data/test/tilt_erbtemplate_test.rb

@@ -12,7 +12,7 @@ class ERBTemplateTest < Test::Unit::TestCase
     assert_equal Tilt::ERBTemplate, Tilt['test.rhtml']
   end
 
-  test "compiling and evaluating templates on #render" do
+  test "loading and evaluating templates on #render" do
     template = Tilt::ERBTemplate.new { |t| "Hello World!" }
     assert_equal "Hello World!", template.render
   end
@@ -77,9 +77,111 @@ class ERBTemplateTest < Test::Unit::TestCase
   end
 
   test "shorthand whole line syntax trim mode" do
-    template = Tilt.new('test.erb', 1, :trim => '%') { "\n% if true\nhello\n%end\n" }
+    template = Tilt.new('test.erb', :trim => '%') { "\n% if true\nhello\n%end\n" }
     assert_equal "\nhello\n", template.render
   end
+
+  test "using an instance variable as the outvar" do
+    template = Tilt::ERBTemplate.new(nil, :outvar => '@buf') { "<%= 1 + 1 %>" }
+    scope = Object.new
+    scope.instance_variable_set(:@buf, 'original value')
+    assert_equal '2', template.render(scope)
+    assert_equal 'original value', scope.instance_variable_get(:@buf)
+  end
+end
+
+class CompiledERBTemplateTest < Test::Unit::TestCase
+  def teardown
+    GC.start
+  end
+
+  class Scope
+    include Tilt::CompileSite
+  end
+
+  test "compiling template source to a method" do
+    template = Tilt::ERBTemplate.new { |t| "Hello World!" }
+    template.render(Scope.new)
+    method_name = template.send(:compiled_method_name, [].hash)
+    method_name = method_name.to_sym if Symbol === Kernel.methods.first
+    assert Tilt::CompileSite.instance_methods.include?(method_name),
+      "CompileSite.instance_methods.include?(#{method_name.inspect})"
+    assert Scope.new.respond_to?(method_name),
+      "scope.respond_to?(#{method_name.inspect})"
+  end
+
+  test "loading and evaluating templates on #render" do
+    template = Tilt::ERBTemplate.new { |t| "Hello World!" }
+    assert_equal "Hello World!", template.render(Scope.new)
+    assert_equal "Hello World!", template.render(Scope.new)
+  end
+
+  test "passing locals" do
+    template = Tilt::ERBTemplate.new { 'Hey <%= name %>!' }
+    assert_equal "Hey Joe!", template.render(Scope.new, :name => 'Joe')
+  end
+
+  test "evaluating in an object scope" do
+    template = Tilt::ERBTemplate.new { 'Hey <%= @name %>!' }
+    scope = Scope.new
+    scope.instance_variable_set :@name, 'Joe'
+    assert_equal "Hey Joe!", template.render(scope)
+    scope.instance_variable_set :@name, 'Jane'
+    assert_equal "Hey Jane!", template.render(scope)
+  end
+
+  test "passing a block for yield" do
+    template = Tilt::ERBTemplate.new { 'Hey <%= yield %>!' }
+    assert_equal "Hey Joe!", template.render(Scope.new) { 'Joe' }
+    assert_equal "Hey Jane!", template.render(Scope.new) { 'Jane' }
+  end
+
+  test "backtrace file and line reporting without locals" do
+    data = File.read(__FILE__).split("\n__END__\n").last
+    fail unless data[0] == ?<
+    template = Tilt::ERBTemplate.new('test.erb', 11) { data }
+    begin
+      template.render(Scope.new)
+      fail 'should have raised an exception'
+    rescue => boom
+      assert_kind_of NameError, boom
+      line = boom.backtrace.first
+      file, line, meth = line.split(":")
+      assert_equal 'test.erb', file
+      assert_equal '13', line
+    end
+  end
+
+  test "backtrace file and line reporting with locals" do
+    data = File.read(__FILE__).split("\n__END__\n").last
+    fail unless data[0] == ?<
+    template = Tilt::ERBTemplate.new('test.erb') { data }
+    begin
+      template.render(Scope.new, :name => 'Joe', :foo => 'bar')
+      fail 'should have raised an exception'
+    rescue => boom
+      assert_kind_of RuntimeError, boom
+      line = boom.backtrace.first
+      file, line, meth = line.split(":")
+      assert_equal 'test.erb', file
+      assert_equal '6', line
+    end
+  end
+
+  test "default non-stripping trim mode" do
+    template = Tilt.new('test.erb') { "\n<%= 1 + 1 %>\n" }
+    assert_equal "\n2\n", template.render(Scope.new)
+  end
+
+  test "stripping trim mode" do
+    template = Tilt.new('test.erb', :trim => '-') { "\n<%= 1 + 1 -%>\n" }
+    assert_equal "\n2", template.render(Scope.new)
+  end
+
+  test "shorthand whole line syntax trim mode" do
+    template = Tilt.new('test.erb', :trim => '%') { "\n% if true\nhello\n%end\n" }
+    assert_equal "\nhello\n", template.render(Scope.new)
+  end
 end
 
 __END__

data/test/tilt_erubistemplate_test.rb

@@ -9,7 +9,7 @@ begin
       assert_equal Tilt::ErubisTemplate, Tilt['test.html.erubis']
     end
 
-    test "compiling and evaluating templates on #render" do
+    test "preparing and evaluating templates on #render" do
       template = Tilt::ErubisTemplate.new { |t| "Hello World!" }
       assert_equal "Hello World!", template.render
     end
@@ -69,6 +69,14 @@ begin
       scope.instance_variable_set :@name, 'Joe'
       assert_equal "Hey Joe!", template.render(scope)
     end
+
+    test "using an instance variable as the outvar" do
+      template = Tilt::ErubisTemplate.new(nil, :outvar => '@buf') { "<%= 1 + 1 %>" }
+      scope = Object.new
+      scope.instance_variable_set(:@buf, 'original value')
+      assert_equal '2', template.render(scope)
+      assert_equal 'original value', scope.instance_variable_get(:@buf)
+    end
   end
 rescue LoadError => boom
   warn "Tilt::ErubisTemplate (disabled)\n"

data/test/tilt_hamltemplate_test.rb

@@ -12,7 +12,7 @@ begin
       assert_equal Tilt::HamlTemplate, Tilt['test.haml']
     end
 
-    test "compiling and evaluating templates on #render" do
+    test "preparing and evaluating templates on #render" do
       template = Tilt::HamlTemplate.new { |t| "%p Hello World!" }
       assert_equal "<p>Hello World!</p>\n", template.render
     end
@@ -66,6 +66,59 @@ begin
     end
   end
 
+  class CompiledHamlTemplateTest < Test::Unit::TestCase
+    class Scope
+      include Tilt::CompileSite
+    end
+
+    test "passing locals" do
+      template = Tilt::HamlTemplate.new { "%p= 'Hey ' + name + '!'" }
+      assert_equal "<p>Hey Joe!</p>\n", template.render(Scope.new, :name => 'Joe')
+    end
+
+    test "evaluating in an object scope" do
+      template = Tilt::HamlTemplate.new { "%p= 'Hey ' + @name + '!'" }
+      scope = Scope.new
+      scope.instance_variable_set :@name, 'Joe'
+      assert_equal "<p>Hey Joe!</p>\n", template.render(scope)
+    end
+
+    test "passing a block for yield" do
+      template = Tilt::HamlTemplate.new { "%p= 'Hey ' + yield + '!'" }
+      assert_equal "<p>Hey Joe!</p>\n", template.render(Scope.new) { 'Joe' }
+    end
+
+    test "backtrace file and line reporting without locals" do
+      data = File.read(__FILE__).split("\n__END__\n").last
+      fail unless data[0] == ?%
+      template = Tilt::HamlTemplate.new('test.haml', 10) { data }
+      begin
+        template.render(Scope.new)
+        fail 'should have raised an exception'
+      rescue => boom
+        assert_kind_of NameError, boom
+        line = boom.backtrace.first
+        file, line, meth = line.split(":")
+        assert_equal 'test.haml', file
+        assert_equal '12', line
+      end
+    end
+
+    test "backtrace file and line reporting with locals" do
+      data = File.read(__FILE__).split("\n__END__\n").last
+      fail unless data[0] == ?%
+      template = Tilt::HamlTemplate.new('test.haml') { data }
+      begin
+        res = template.render(Scope.new, :name => 'Joe', :foo => 'bar')
+      rescue => boom
+        assert_kind_of MockError, boom
+        line = boom.backtrace.first
+        file, line, meth = line.split(":")
+        assert_equal 'test.haml', file
+        assert_equal '5', line
+      end
+    end
+  end
 rescue LoadError => boom
   warn "Tilt::HamlTemplate (disabled)\n"
 end

data/test/tilt_liquidtemplate_test.rb

@@ -9,7 +9,7 @@ begin
       assert_equal Tilt::LiquidTemplate, Tilt['test.liquid']
     end
 
-    test "compiling and evaluating templates on #render" do
+    test "preparing and evaluating templates on #render" do
       template = Tilt::LiquidTemplate.new { |t| "Hello World!" }
       assert_equal "Hello World!", template.render
     end

data/test/tilt_mustachetemplate_test.rb

@@ -16,7 +16,7 @@ begin
       assert_equal Tilt::MustacheTemplate, Tilt['test.mustache']
     end
 
-    test "compiling and evaluating templates on #render" do
+    test "preparing and evaluating templates on #render" do
       template = Tilt::MustacheTemplate.new { |t| "Hello World!" }
       assert_equal "Hello World!", template.render
     end
@@ -33,7 +33,6 @@ begin
 
     test "locating views defined at the top-level" do
       template = Tilt::MustacheTemplate.new('foo.mustache') { "<p>Hey {{foo}}!</p>" }
-      template.compile
       assert_equal Views::Foo, template.engine
     end
 
@@ -46,7 +45,6 @@ begin
 
     test "locating views defined in a custom namespace" do
       template = Tilt::MustacheTemplate.new('bizzle.mustache', :namespace => Bar) { "<p>Hello World!</p>" }
-      template.compile
       assert_equal Bar::Views::Bizzle, template.engine
       assert_equal "<p>Hello World!</p>", template.render
     end
@@ -54,7 +52,6 @@ begin
     test "locating views in files" do
       view_path = File.expand_path('../tilt_mustache_views', __FILE__)
       template = Tilt::MustacheTemplate.new('external.mustache', :view_path => view_path) { "<p>{{hello}}!</p>" }
-      template.compile
       assert defined?(Views::External), "external.rb should have been required"
       assert_equal Views::External, template.engine
       assert_equal "<p>Stached!</p>", template.render

data/test/tilt_rdiscounttemplate_test.rb

@@ -17,20 +17,20 @@ begin
       assert_equal Tilt::RDiscountTemplate, Tilt['test.mkd']
     end
 
-    test "compiling and evaluating templates on #render" do
+    test "preparing and evaluating templates on #render" do
       template = Tilt::RDiscountTemplate.new { |t| "# Hello World!" }
       assert_equal "<h1>Hello World!</h1>\n", template.render
     end
 
     test "smartypants when :smart is set" do
-      template = Tilt::RDiscountTemplate.new(nil, :smart => true) { |t|
+      template = Tilt::RDiscountTemplate.new(:smart => true) { |t|
         "OKAY -- 'Smarty Pants'" }
       assert_equal "<p>OKAY &mdash; &lsquo;Smarty Pants&rsquo;</p>\n",
         template.render
     end
 
     test "stripping HTML when :filter_html is set" do
-      template = Tilt::RDiscountTemplate.new(nil, :filter_html => true) { |t|
+      template = Tilt::RDiscountTemplate.new(:filter_html => true) { |t|
         "HELLO <blink>WORLD</blink>" }
       assert_equal "<p>HELLO &lt;blink>WORLD&lt;/blink></p>\n", template.render
     end

data/test/tilt_rdoctemplate_test.rb

@@ -9,7 +9,7 @@ begin
       assert_equal Tilt::RDocTemplate, Tilt['test.rdoc']
     end
 
-    test "compiling and evaluating the template with #render" do
+    test "preparing and evaluating the template with #render" do
       template = Tilt::RDocTemplate.new { |t| "= Hello World!" }
       assert_equal "<h1>Hello World!</h1>\n", template.render
     end

data/test/tilt_stringtemplate_test.rb

@@ -6,7 +6,7 @@ class StringTemplateTest < Test::Unit::TestCase
     assert_equal Tilt::StringTemplate, Tilt['test.str']
   end
 
-  test "compiling and evaluating templates on #render" do
+  test "loading and evaluating templates on #render" do
     template = Tilt::StringTemplate.new { |t| "Hello World!" }
     assert_equal "Hello World!", template.render
   end
@@ -26,6 +26,7 @@ class StringTemplateTest < Test::Unit::TestCase
   test "passing a block for yield" do
     template = Tilt::StringTemplate.new { 'Hey #{yield}!' }
     assert_equal "Hey Joe!", template.render { 'Joe' }
+    assert_equal "Hey Moe!", template.render { 'Moe' }
   end
 
   test "multiline templates" do
@@ -66,6 +67,91 @@ class StringTemplateTest < Test::Unit::TestCase
   end
 end
 
+
+class CompiledStringTemplateTest < Test::Unit::TestCase
+  def teardown
+    GC.start
+  end
+
+  class Scope
+    include Tilt::CompileSite
+  end
+
+  test "compiling template source to a method" do
+    template = Tilt::StringTemplate.new { |t| "Hello World!" }
+    template.render(Scope.new)
+    method_name = template.send(:compiled_method_name, [].hash)
+    method_name = method_name.to_sym if Symbol === Kernel.methods.first
+    assert Tilt::CompileSite.instance_methods.include?(method_name),
+      "CompileSite.instance_methods.include?(#{method_name.inspect})"
+    assert Scope.new.respond_to?(method_name),
+      "scope.respond_to?(#{method_name.inspect})"
+  end
+
+  test "loading and evaluating templates on #render" do
+    template = Tilt::StringTemplate.new { |t| "Hello World!" }
+    assert_equal "Hello World!", template.render(Scope.new)
+  end
+
+  test "passing locals" do
+    template = Tilt::StringTemplate.new { 'Hey #{name}!' }
+    assert_equal "Hey Joe!", template.render(Scope.new, :name => 'Joe')
+    assert_equal "Hey Moe!", template.render(Scope.new, :name => 'Moe')
+  end
+
+  test "evaluating in an object scope" do
+    template = Tilt::StringTemplate.new { 'Hey #{@name}!' }
+    scope = Scope.new
+    scope.instance_variable_set :@name, 'Joe'
+    assert_equal "Hey Joe!", template.render(scope)
+    scope.instance_variable_set :@name, 'Moe'
+    assert_equal "Hey Moe!", template.render(scope)
+  end
+
+  test "passing a block for yield" do
+    template = Tilt::StringTemplate.new { 'Hey #{yield}!' }
+    assert_equal "Hey Joe!", template.render(Scope.new) { 'Joe' }
+    assert_equal "Hey Moe!", template.render(Scope.new) { 'Moe' }
+  end
+
+  test "multiline templates" do
+    template = Tilt::StringTemplate.new { "Hello\nWorld!\n" }
+    assert_equal "Hello\nWorld!\n", template.render(Scope.new)
+  end
+
+  test "backtrace file and line reporting without locals" do
+    data = File.read(__FILE__).split("\n__END__\n").last
+    fail unless data[0] == ?<
+    template = Tilt::StringTemplate.new('test.str', 11) { data }
+    begin
+      template.render(Scope.new)
+      fail 'should have raised an exception'
+    rescue => boom
+      assert_kind_of NameError, boom
+      line = boom.backtrace.first
+      file, line, meth = line.split(":")
+      assert_equal 'test.str', file
+      assert_equal '13', line
+    end
+  end
+
+  test "backtrace file and line reporting with locals" do
+    data = File.read(__FILE__).split("\n__END__\n").last
+    fail unless data[0] == ?<
+    template = Tilt::StringTemplate.new('test.str') { data }
+    begin
+      template.render(Scope.new, :name => 'Joe', :foo => 'bar')
+      fail 'should have raised an exception'
+    rescue => boom
+      assert_kind_of RuntimeError, boom
+      line = boom.backtrace.first
+      file, line, meth = line.split(":")
+      assert_equal 'test.str', file
+      assert_equal '6', line
+    end
+  end
+end
+
 __END__
 <html>
 <body>

data/test/tilt_template_test.rb

@@ -2,44 +2,50 @@ require 'contest'
 require 'tilt'
 
 class TiltTemplateTest < Test::Unit::TestCase
+
+  class MockTemplate < Tilt::Template
+    def prepare
+    end
+  end
+
   test "needs a file or block" do
     assert_raise(ArgumentError) { Tilt::Template.new }
   end
 
   test "initializing with a file" do
-    inst = Tilt::Template.new('foo.erb')
+    inst = MockTemplate.new('foo.erb') {}
     assert_equal 'foo.erb', inst.file
   end
 
   test "initializing with a file and line" do
-    inst = Tilt::Template.new('foo.erb', 55)
+    inst = MockTemplate.new('foo.erb', 55) {}
     assert_equal 'foo.erb', inst.file
     assert_equal 55, inst.line
   end
 
   test "uses correct eval_file" do
-    inst = Tilt::Template.new('foo.erb', 55)
+    inst = MockTemplate.new('foo.erb', 55) {}
     assert_equal 'foo.erb', inst.eval_file
   end
 
   test "uses a default filename for #eval_file when no file provided" do
-    inst = Tilt::Template.new { 'Hi' }
+    inst = MockTemplate.new { 'Hi' }
     assert_not_nil inst.eval_file
     assert !inst.eval_file.include?("\n")
   end
 
   test "calculating template's #basename" do
-    inst = Tilt::Template.new('/tmp/templates/foo.html.erb')
+    inst = MockTemplate.new('/tmp/templates/foo.html.erb') {}
     assert_equal 'foo.html.erb', inst.basename
   end
 
   test "calculating the template's #name" do
-    inst = Tilt::Template.new('/tmp/templates/foo.html.erb')
+    inst = MockTemplate.new('/tmp/templates/foo.html.erb') {}
     assert_equal 'foo', inst.name
   end
 
   test "initializing with a data loading block" do
-    Tilt::Template.new { |template| "Hello World!" }
+    MockTemplate.new { |template| "Hello World!" }
   end
 
   class InitializingMockTemplate < Tilt::Template
@@ -52,7 +58,7 @@ class TiltTemplateTest < Test::Unit::TestCase
       @@initialized_count += 1
     end
 
-    def compile!
+    def prepare
     end
   end
 
@@ -68,43 +74,42 @@ class TiltTemplateTest < Test::Unit::TestCase
     assert_equal 1, InitializingMockTemplate.initialized_count
   end
 
-  class CompilingMockTemplate < Tilt::Template
+  class PreparingMockTemplate < Tilt::Template
     include Test::Unit::Assertions
-    def compile!
+    def prepare
       assert !data.nil?
-      @compiled = true
+      @prepared = true
     end
-    def compiled? ; @compiled ; end
+    def prepared? ; @prepared ; end
   end
 
-  test "raises NotImplementedError when #compile! not defined" do
-    inst = Tilt::Template.new { |template| "Hello World!" }
-    assert_raise(NotImplementedError) { inst.render }
+  test "raises NotImplementedError when #prepare not defined" do
+    assert_raise(NotImplementedError) { Tilt::Template.new { |template| "Hello World!" } }
   end
 
   test "raises NotImplementedError when #evaluate or #template_source not defined" do
-    inst = CompilingMockTemplate.new { |t| "Hello World!" }
+    inst = PreparingMockTemplate.new { |t| "Hello World!" }
     assert_raise(NotImplementedError) { inst.render }
-    assert inst.compiled?
+    assert inst.prepared?
   end
 
-  class SimpleMockTemplate < CompilingMockTemplate
+  class SimpleMockTemplate < PreparingMockTemplate
     include Test::Unit::Assertions
     def evaluate(scope, locals, &block)
-      assert compiled?
+      assert prepared?
       assert !scope.nil?
       assert !locals.nil?
       "<em>#{@data}</em>"
     end
   end
 
-  test "compiles and evaluates the template on #render" do
+  test "prepares and evaluates the template on #render" do
     inst = SimpleMockTemplate.new { |t| "Hello World!" }
     assert_equal "<em>Hello World!</em>", inst.render
-    assert inst.compiled?
+    assert inst.prepared?
   end
 
-  class SourceGeneratingMockTemplate < CompilingMockTemplate
+  class SourceGeneratingMockTemplate < PreparingMockTemplate
     def template_source
       "foo = [] ; foo << %Q{#{data}} ; foo.join"
     end
@@ -113,7 +118,7 @@ class TiltTemplateTest < Test::Unit::TestCase
   test "template_source with locals" do
     inst = SourceGeneratingMockTemplate.new { |t| 'Hey #{name}!' }
     assert_equal "Hey Joe!", inst.render(Object.new, :name => 'Joe')
-    assert inst.compiled?
+    assert inst.prepared?
   end
 
   class Person

data/tilt.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'tilt'
-  s.version = '0.6'
-  s.date = '2010-02-22'
+  s.version = '0.7'
+  s.date = '2010-03-04'
 
   s.description = "Generic interface to multiple Ruby template engines"
   s.summary     = s.description
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
     test/tilt_buildertemplate_test.rb
     test/tilt_cache_test.rb
     test/tilt_coffeetemplate_test.rb
+    test/tilt_compilesite_test.rb
     test/tilt_erbtemplate_test.rb
     test/tilt_erubistemplate_test.rb
     test/tilt_hamltemplate_test.rb
@@ -50,6 +51,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rdiscount'
   s.add_development_dependency 'liquid'
   s.add_development_dependency 'less'
+  s.add_development_dependency 'coffee-script'
 
   s.extra_rdoc_files = %w[COPYING]
 

metadata

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 6
-  version: "0.6"
+  - 7
+  version: "0.7"
 platform: ruby
 authors: 
 - Ryan Tomayko
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-22 00:00:00 -08:00
+date: 2010-03-04 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -112,6 +112,18 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: coffee-script
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id009
 description: Generic interface to multiple Ruby template engines
 email: r@tomayko.com
 executables: []
@@ -130,6 +142,7 @@ files:
 - test/tilt_buildertemplate_test.rb
 - test/tilt_cache_test.rb
 - test/tilt_coffeetemplate_test.rb
+- test/tilt_compilesite_test.rb
 - test/tilt_erbtemplate_test.rb
 - test/tilt_erubistemplate_test.rb
 - test/tilt_hamltemplate_test.rb