sinatra 1.0.a → 1.0.b

data/CHANGES

@@ -1,58 +1,88 @@
-= 1.0 / unreleased
+= 1.0 / 2010-01-28 (prerelease)
 
  * It's now possible to register blocks to run after each request using
    after filters. After filters run at the end of each request, after
-   routes and error handlers.
+   routes and error handlers. (Jimmy Schementi)
 
  * Sinatra now uses Tilt <http://github.com/rtomayko/tilt> for rendering
    templates. This adds support for template caching, consistent
    template backtraces, and support for new template engines, like
-   mustache and liquid.
+   mustache and liquid. (Ryan Tomayko)
+
+ * ERB, Erubis, and Haml templates are now compiled the first time
+   they're rendered instead of being string eval'd on each invocation.
+   Benchmarks show a 5x-10x improvement in render time. This also
+   reduces the number of objects created, decreasing pressure on Ruby's
+   GC. (Ryan Tomayko)
+
+ * New 'settings' method gives access to options in both class and request
+   scopes. This replaces the 'options' method. (Chris Wanstrath)
 
  * New boolean 'reload_templates' setting controls whether template files
    are reread from disk and recompiled on each request. Template read/compile
-   is cached by default in all environments except development.
+   is cached by default in all environments except development. (Ryan Tomayko)
 
- * New 'settings' method gives access to options in both class and request
-   scopes. This replaces the 'options' method.
- * New 'erubis' helper method for rendering Erubis templates.
+ * New 'erubis' helper method for rendering ERB template with Erubis. The
+   erubis gem is required. (Dylan Egan)
 
  * New 'cache_control' helper method provides a convenient way of
    setting the Cache-Control response header. Takes a variable number
    of boolean directives followed by a hash of value directives, like
-   this:
-       cache_control :public, :must_revalidate, :max_age => 60
+   this: cache_control :public, :must_revalidate, :max_age => 60
+   (Ryan Tomayko)
 
  * New 'expires' helper method is like cache_control but takes an
    integer number of seconds or Time object:
-       expires 300, :public, :must_revalidate
+   expires 300, :public, :must_revalidate
+   (Ryan Tomayko)
+
+ * New request.secure? method for checking for an SSL connection.
+   (Adam Wiggins)
 
- * Sinatra apps can now be run with a `-h <addr>` argument to specify
-   the address to bind to.
+ * Sinatra apps can now be run with a `-o <addr>` argument to specify
+   the address to bind to. (Ryan Tomayko)
 
  * Rack::Session::Cookie is now added to the middleware pipeline when
    running in test environments if the :sessions option is set.
+   (Simon Rozet)
 
  * Route handlers, before filters, templates, error mappings, and
    middleware are now resolved dynamically up the inheritance hierarchy
    when needed instead of duplicating the superclass's version when
    a new Sinatra::Base subclass is created. This should fix a variety
    of issues with extensions that need to add any of these things
-   to the base class.
+   to the base class. (Ryan Tomayko)
+
+ * Exception error handlers always override the raise_errors option now.
+   Previously, all exceptions would be raised outside of the application
+   when the raise_errors option was enabled, even if an error handler was
+   defined for that exception. The raise_errors option now controls
+   whether unhandled exceptions are raised (enabled) or if a generic 500
+   error is returned (disabled). (Ryan Tomayko)
 
-The following Sinatra features have been obsoleted in the 1.0 release:
+ * The X-Cascade response header is set to 'pass' when no matching route
+   is found or all routes pass. (Josh Peek)
 
- * The `sinatra/test` library is obsolete. This includes the
-   `Sinatra::Test` module, the `Sinatra::TestHarness` class,
-   and the `get_it`, `post_it`, `put_it`, `delete_it`, and `head_it`
-   helper methods.  The
+ * Filters do not run when serving static files anymore. (Ryan Tomayko)
+
+The following Sinatra features have been obsoleted (removed entirely) in
+the 1.0 release:
+
+ * The `sinatra/test` library is obsolete. This includes the `Sinatra::Test`
+   module, the `Sinatra::TestHarness` class, and the `get_it`, `post_it`,
+   `put_it`, `delete_it`, and `head_it` helper methods. The
    [`Rack::Test` library](http://gitrdoc.com/brynary/rack-test) should
    be used instead.
 
  * Test framework specific libraries (`sinatra/test/spec`,
-   `sinatra/test/bacon`,`sinatra/test/rspec`, etc.) are obsolete.
-   See http://www.sinatrarb.com/testing.html for instructions on
-   setting up a testing environment under each of these frameworks.
+   `sinatra/test/bacon`,`sinatra/test/rspec`, etc.) are obsolete. See
+   http://www.sinatrarb.com/testing.html for instructions on setting up a
+   testing environment under each of these frameworks.
+
+ * `Sinatra::Default` is obsolete; use `Sinatra::Base` instead.
+   `Sinatra::Base` acts more like `Sinatra::Default` in development mode.
+   For example, static file serving and sexy development error pages are
+   enabled by default.
 
  * Auto-requiring template libraries in the `erb`, `builder`, `haml`,
    and `sass` methods is obsolete due to thread-safety issues. You must
@@ -65,8 +95,13 @@ The following Sinatra features have been obsoleted in the 1.0 release:
    Template engine options should be passed in the second Hash argument
    instead.
 
+ * The `use_in_file_templates` method is obsolete. Use
+   `enable :inline_templates` or `set :inline_templates, 'path/to/file'`
+
  * The 'media_type' helper method is obsolete. Use 'mime_type' instead.
 
+ * The 'mime' main and class method is obsolete. Use 'mime_type' instead.
+
  * The request-level `send_data` method is no longer supported.
 
  * The `Sinatra::Event` and `Sinatra::EventContext` classes are no longer
@@ -100,6 +135,9 @@ The following Sinatra features have been obsoleted in the 1.0 release:
    within a request are now treated as internal server errors and result in
    a 500 response status.
 
+ * The `:methodoverride' option to enable/disable the POST _method hack is
+   obsolete; use `:method_override` instead.
+
 = 0.9.2 / 2009-05-18
 
  * This version is compatible with Rack 1.0. [Rein Henrichs]

data/README.rdoc

@@ -203,6 +203,20 @@ and overridden on an individual basis.
     sass :stylesheet, :style => :expanded # overridden
   end
 
+=== Less Templates
+
+The less gem/library is required to render Less templates:
+
+  ## You'll need to require less in your app
+  require 'less'
+
+  get '/stylesheet.css' do
+    content_type 'text/css', :charset => 'utf-8'
+    less :stylesheet
+  end
+
+Renders <tt>./views/stylesheet.less</tt>.
+
 === Inline Templates
 
   get '/' do
@@ -565,20 +579,20 @@ system. The +Sinatra::Application+ class -- a special subclass of
 Sinatra::Base -- receives all :get, :put, :post, :delete, :before,
 :error, :not_found, :configure, and :set messages sent to the
 top-level. Have a look at the code for yourself: here's the
-{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064]
-being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].
+{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
+being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]
 
 == Command line
 
 Sinatra applications can be run directly:
 
-  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-h HOST] [-s HANDLER]
+  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
 
 Options are:
 
   -h # help
   -p # set the port (default is 4567)
-  -h # set the host (default is 0.0.0.0)
+  -o # set the host (default is 0.0.0.0)
   -e # set the environment (default is development)
   -s # specify rack server/handler (default is thin)
   -x # turn on the mutex lock (default is off)
@@ -611,12 +625,12 @@ To update the Sinatra sources in the future:
 
 == More
 
-* {Project Website}[http://sinatra.github.com/] - Additional documentation,
+* {Project Website}[http://www.sinatrarb.com/] - Additional documentation,
   news, and links to other resources.
-* {Contributing}[http://sinatra.github.com/contributing.html] - Find a bug? Need
+* {Contributing}[http://www.sinatrarb.com/contributing] - Find a bug? Need
   help? Have a patch?
 * {Lighthouse}[http://sinatra.lighthouseapp.com] - Issue tracking and release
   planning.
 * {Twitter}[http://twitter.com/sinatra]
-* {Mailing List}[http://groups.google.com/group/sinatrarb]
+* {Mailing List}[http://groups.google.com/group/sinatrarb/topics]
 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net

data/Rakefile

@@ -37,16 +37,19 @@ task 'doc'     => ['doc:api']
 task 'doc:api' => ['doc/api/index.html']
 
 file 'doc/api/index.html' => FileList['lib/**/*.rb','README.rdoc'] do |f|
+  require 'rbconfig'
+  hanna = RbConfig::CONFIG['ruby_install_name'].sub('ruby', 'hanna')
   rb_files = f.prerequisites
   sh((<<-end).gsub(/\s+/, ' '))
-    hanna --charset utf8 \
-          --fmt html \
-          --inline-source \
-          --line-numbers \
-          --main README.rdoc \
-          --op doc/api \
-          --title 'Sinatra API Documentation' \
-          #{rb_files.join(' ')}
+    #{hanna}
+      --charset utf8
+      --fmt html
+      --inline-source
+      --line-numbers
+      --main README.rdoc
+      --op doc/api
+      --title 'Sinatra API Documentation'
+      #{rb_files.join(' ')}
   end
 end
 CLEAN.include 'doc/api'

data/lib/sinatra/base.rb

@@ -8,12 +8,18 @@ require 'sinatra/showexceptions'
 # require tilt if available; fall back on bundled version.
 begin
   require 'tilt'
+  if Tilt::VERSION < '0.8'
+    warn "WARN: sinatra requires tilt >= 0.8; you have #{Tilt::VERSION}. " +
+         "loading bundled version..."
+    Object.send :remove_const, :Tilt
+    raise LoadError
+  end
 rescue LoadError
   require 'sinatra/tilt'
 end
 
 module Sinatra
-  VERSION = '1.0.a'
+  VERSION = '1.0.b'
 
   # The request object. See Rack::Request for more info:
   # http://rack.rubyforge.org/doc/classes/Rack/Request.html
@@ -240,6 +246,7 @@ module Sinatra
     # matches the time specified, execution is immediately halted with a
     # '304 Not Modified' response.
     def last_modified(time)
+      return unless time
       time = time.to_time if time.respond_to?(:to_time)
       time = time.httpdate if time.respond_to?(:httpdate)
       response['Last-Modified'] = time
@@ -284,15 +291,19 @@ module Sinatra
   #
   # Possible options are:
   #   :layout       If set to false, no layout is rendered, otherwise
-  #                 the specified layout is used (Ignored for `sass`)
+  #                 the specified layout is used (Ignored for `sass` and `less`)
   #   :locals       A hash with local variables that should be available
   #                 in the template
   module Templates
+    include Tilt::CompileSite
+
     def erb(template, options={}, locals={})
+      options[:outvar] = '@_out_buf'
       render :erb, template, options, locals
     end
 
     def erubis(template, options={}, locals={})
+      options[:outvar] = '@_out_buf'
       render :erubis, template, options, locals
     end
 
@@ -305,6 +316,11 @@ module Sinatra
       render :sass, template, options, locals
     end
 
+    def less(template, options={}, locals={})
+      options[:layout] = false
+      render :less, template, options, locals
+    end
+
     def builder(template=nil, options={}, locals={}, &block)
       options, template = template, nil if template.is_a?(Hash)
       template = Proc.new { block } if template.nil?
@@ -340,20 +356,23 @@ module Sinatra
 
     def compile_template(engine, data, options, views)
       @template_cache.fetch engine, data, options do
+        template = Tilt[engine]
+        raise "Template engine not found: #{engine}" if template.nil?
+
         case
         when data.is_a?(Symbol)
           body, path, line = self.class.templates[data]
           if body
             body = body.call if body.respond_to?(:call)
-            Tilt[engine].new(path, line.to_i, options) { body }
+            template.new(path, line.to_i, options) { body }
           else
             path = ::File.join(views, "#{data}.#{engine}")
-            Tilt[engine].new(path, 1, options)
+            template.new(path, 1, options)
           end
         when data.is_a?(Proc) || data.is_a?(String)
           body = data.is_a?(String) ? Proc.new { data } : data
           path, line = self.class.caller_locations.first
-          Tilt[engine].new(path, line.to_i, options, &body)
+          template.new(path, line.to_i, options, &body)
         else
           raise ArgumentError
         end
@@ -600,10 +619,16 @@ module Sinatra
       @env['sinatra.error'] = boom
 
       dump_errors!(boom) if settings.dump_errors?
-      raise boom         if settings.raise_errors? || settings.show_exceptions?
+      raise boom         if settings.show_exceptions?
 
       @response.status = 500
-      error_block! boom.class, Exception
+      if res = error_block!(boom.class)
+        res
+      elsif settings.raise_errors?
+        raise boom
+      else
+        error_block!(Exception)
+      end
     end
 
     # Find an custom error block for the key(s) specified.
@@ -613,8 +638,7 @@ module Sinatra
         while base.respond_to?(:errors)
           if block = base.errors[key]
             # found a handler, eval and return result
-            res = instance_eval(&block)
-            return res
+            return instance_eval(&block)
           else
             base = base.superclass
           end
@@ -679,11 +703,13 @@ module Sinatra
 
       # Sets an option to the given value.  If the value is a proc,
       # the proc will be called every time the option is accessed.
-      def set(option, value=self)
+      def set(option, value=self, &block)
+        raise ArgumentError if block && value != self
+        value = block if block
         if value.kind_of?(Proc)
           metadef(option, &value)
           metadef("#{option}?") { !!__send__(option) }
-          metadef("#{option}=") { |val| set(option, Proc.new{val}) }
+          metadef("#{option}=") { |val| metadef(option, &Proc.new{val}) }
         elsif value == self && option.respond_to?(:to_hash)
           option.to_hash.each { |k,v| set(k, v) }
         elsif respond_to?("#{option}=")
@@ -833,7 +859,7 @@ module Sinatra
     private
       def route(verb, path, options={}, &block)
         # Because of self.options.host
-        host_name(options.delete(:host)) if options.key?(:host)
+        host_name(options.delete(:bind)) if options.key?(:host)
 
         options.each {|option, args| send(option, *args)}
 
@@ -927,7 +953,7 @@ module Sinatra
         handler_name = handler.name.gsub(/.*::/, '')
         puts "== Sinatra/#{Sinatra::VERSION} has taken the stage " +
           "on #{port} for #{environment} with backup from #{handler_name}" unless handler_name =~/cgi/i
-        handler.run self, :Host => host, :Port => port do |server|
+        handler.run self, :Host => bind, :Port => port do |server|
           trap(:INT) do
             ## Use thins' hard #stop! if available, otherwise just #stop
             server.respond_to?(:stop!) ? server.stop! : server.stop
@@ -951,7 +977,7 @@ module Sinatra
         builder = Rack::Builder.new
         builder.use Rack::Session::Cookie if sessions?
         builder.use Rack::CommonLogger    if logging?
-        builder.use Rack::MethodOverride  if methodoverride?
+        builder.use Rack::MethodOverride  if method_override?
         builder.use ShowExceptions        if show_exceptions?
         middleware.each { |c,a,b| builder.use(c, *a, &b) }
 
@@ -1024,24 +1050,29 @@ module Sinatra
     reset!
 
     set :environment, (ENV['RACK_ENV'] || :development).to_sym
-    set :raise_errors, Proc.new { !development? }
-    set :dump_errors, Proc.new { development? }
+    set :raise_errors, Proc.new { test? }
+    set :dump_errors, Proc.new { !test? }
     set :show_exceptions, Proc.new { development? }
     set :clean_trace, true
     set :sessions, false
     set :logging, false
-    set :methodoverride, false
+    set :method_override, false
+
+    class << self
+      alias_method :methodoverride?, :method_override?
+      alias_method :methodoverride=, :method_override=
+    end
 
     set :run, false                       # start server via at-exit hook?
     set :running, false                   # is the built-in server running now?
     set :server, %w[thin mongrel webrick]
-    set :host, '0.0.0.0'
+    set :bind, '0.0.0.0'
     set :port, 4567
 
     set :app_file, nil
     set :root, Proc.new { app_file && File.expand_path(File.dirname(app_file)) }
     set :views, Proc.new { root && File.join(root, 'views') }
-    set :reload_templates, Proc.new { !development? }
+    set :reload_templates, Proc.new { development? }
     set :lock, false
 
     set :public, Proc.new { root && File.join(root, 'public') }
@@ -1095,13 +1126,9 @@ module Sinatra
   # top-level. Subclassing Sinatra::Base is heavily recommended for
   # modular applications.
   class Application < Base
-    set :raise_errors, Proc.new { test? }
-    set :dump_errors, true
-    set :sessions, false
     set :logging, Proc.new { ! test? }
-    set :methodoverride, true
+    set :method_override, true
     set :run, Proc.new { ! test? }
-    set :static, true
 
     def self.register(*extensions, &block) #:nodoc:
       added_methods = extensions.map {|m| m.public_instance_methods }.flatten

data/lib/sinatra/main.rb

@@ -17,7 +17,7 @@ module Sinatra
         op.on('-e env')    { |val| set :environment, val.to_sym }
         op.on('-s server') { |val| set :server, val }
         op.on('-p port')   { |val| set :port, val.to_i }
-        op.on('-h addr')   { |val| set :host, val }
+        op.on('-o addr')   { |val| set :bind, val }
       }.parse!(ARGV.dup)
     end
   end

data/lib/sinatra/tilt.rb

@@ -1,10 +1,11 @@
+require 'digest/md5'
+
 module Tilt
-  VERSION = '0.4'
+  VERSION = '0.8'
 
   @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 +26,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 +45,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,51 +79,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) }
-
-      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
+      @compiled_method_names = {}
 
-    # 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
 
@@ -127,43 +147,167 @@ 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
+
+    # Like Kernel::require but issues a warning urging a manual require when
+    # running under a threaded environment.
+    def require_template_library(name)
+      if Thread.list.size > 1
+        warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
+             "explicit require '#{name}' suggested."
+      end
+      require name
+    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)
+        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)
+      end
     end
 
-    # Return a string containing the (Ruby) source code for the template. The
-    # default Template#evaluate implementation requires this method be
-    # defined.
-    def template_source
+    # Generates all template source by combining the preamble, template, and
+    # postamble and returns a two-tuple of the form: [source, offset], where
+    # source is the string containing (Ruby) source code for the template and
+    # offset is the integer line offset where line reporting should begin.
+    #
+    # Template subclasses may override this method when they need complete
+    # control over source generation or want to adjust the default line
+    # offset. In most cases, overriding the #precompiled_template method is
+    # easier and more appropriate.
+    def precompiled(locals)
+      preamble = precompiled_preamble(locals)
+      parts = [
+        preamble,
+        precompiled_template(locals),
+        precompiled_postamble(locals)
+      ]
+      [parts.join("\n"), preamble.count("\n") + 1]
+    end
+
+    # A string containing the (Ruby) source code for the template. The
+    # default Template#evaluate implementation requires either this method
+    # or the #precompiled method be overridden. When defined, the base
+    # Template guarantees correct file/line handling, locals support, custom
+    # scopes, and support for template compilation when the scope object
+    # allows it.
+    def precompiled_template(locals)
       raise NotImplementedError
     end
 
+    # Generates preamble code for initializing template state, and performing
+    # locals assignment. The default implementation performs locals
+    # assignment only. Lines included in the preamble are subtracted from the
+    # source line offset, so adding code to the preamble does not effect line
+    # reporting in Kernel::caller and backtraces.
+    def precompiled_preamble(locals)
+      locals.map { |k,v| "#{k} = locals[:#{k}]" }.join("\n")
+    end
+
+    # Generates postamble code for the precompiled template source. The
+    # string returned from this method is appended to the precompiled
+    # template source.
+    def precompiled_postamble(locals)
+      ''
+    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)
+    end
+
   private
-    def local_assignment_code(locals)
-      return ['', 1] if locals.empty?
-      source = locals.collect { |k,v| "#{k} = locals[:#{k}]" }
-      [source.join("\n"), source.length]
+    # Evaluate the template source in the context of the scope object.
+    def evaluate_source(scope, locals, &block)
+      source, offset = precompiled(locals)
+      scope.instance_eval(source, eval_file, line - offset)
     end
 
-    def require_template_library(name)
-      if Thread.list.size > 1
-        warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
-             "explicit require '#{name}' suggested."
+    # JRuby doesn't allow Object#instance_eval to yield to the block it's
+    # closed over. This is by design and (ostensibly) something that will
+    # change in MRI, though no current MRI version tested (1.8.6 - 1.9.2)
+    # exhibits the behavior. More info here:
+    #
+    # http://jira.codehaus.org/browse/JRUBY-2599
+    #
+    # Additionally, JRuby's eval line reporting is off by one compared to
+    # all MRI versions tested.
+    #
+    # We redefine evaluate_source to work around both issues.
+    if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
+      undef evaluate_source
+      def evaluate_source(scope, locals, &block)
+        source, offset = precompiled(locals)
+        file, lineno = eval_file, (line - offset) - 1
+        scope.instance_eval { Kernel::eval(source, binding, file, lineno) }
+      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)
+      source, offset = precompiled(locals)
+      offset += 1
+      CompileSite.module_eval <<-RUBY, eval_file, line - offset
+        def #{method_name}(locals)
+          #{source}
+        end
+      RUBY
+
+      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
-      require name
     end
   end
 
@@ -173,7 +317,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 = {}
@@ -195,11 +339,11 @@ 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
 
-    def template_source
+    def precompiled_template(locals)
       @code
     end
   end
@@ -210,44 +354,46 @@ module Tilt
   # http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html
   class ERBTemplate < Template
     def initialize_engine
-      require_template_library 'erb' unless defined? ::ERB
+      return if defined? ::ERB
+      require_template_library '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
+    def precompiled_template(locals)
       @engine.src
     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
+    def precompiled_preamble(locals)
+      <<-RUBY
+        begin
+          __original_outvar = #{@outvar} if defined?(#{@outvar})
+          #{super}
+      RUBY
     end
 
-  private
+    def precompiled_postamble(locals)
+      <<-RUBY
+          #{super}
+        ensure
+          #{@outvar} = __original_outvar
+        end
+      RUBY
+    end
 
     # ERB generates a line to specify the character coding of the generated
     # source in 1.9. Account for this in the line offset.
     if RUBY_VERSION >= '1.9.0'
-      def local_assignment_code(locals)
+      def precompiled(locals)
         source, offset = super
         [source, offset + 1]
       end
     end
   end
+
   %w[erb rhtml].each { |ext| register ext, ERBTemplate }
 
 
@@ -255,20 +401,28 @@ module Tilt
   # http://www.kuwata-lab.com/erubis/
   class ErubisTemplate < ERBTemplate
     def initialize_engine
-      require_template_library 'erubis' unless defined? ::Erubis
+      return if defined? ::Erubis
+      require_template_library '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 precompiled_preamble(locals)
+      [super, "#{@outvar} = _buf = ''"].join("\n")
+    end
+
+    def precompiled_postamble(locals)
+      ["_buf", super].join("\n")
+    end
 
-    # Erubis doesn't have ERB's line-off-by-one under 1.9 problem. Override
-    # and adjust back.
+    # Erubis doesn't have ERB's line-off-by-one under 1.9 problem.
+    # Override and adjust back.
     if RUBY_VERSION >= '1.9.0'
-      def local_assignment_code(locals)
+      def precompiled(locals)
         source, offset = super
         [source, offset - 1]
       end
@@ -281,20 +435,54 @@ module Tilt
   # http://haml.hamptoncatlin.com/
   class HamlTemplate < Template
     def initialize_engine
-      require_template_library 'haml' unless defined? ::Haml::Engine
+      return if defined? ::Haml::Engine
+      require_template_library 'haml'
     end
 
-    def compile!
-      @engine = ::Haml::Engine.new(data, haml_options)
+    def prepare
+      options = @options.merge(:filename => eval_file, :line => line)
+      @engine = ::Haml::Engine.new(data, options)
     end
 
     def evaluate(scope, locals, &block)
-      @engine.render(scope, locals, &block)
+      if @engine.respond_to?(:precompiled_method_return_value, true)
+        super
+      else
+        @engine.render(scope, locals, &block)
+      end
     end
 
-  private
-    def haml_options
-      options.merge(:filename => eval_file, :line => line)
+    # 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 precompiled_template(locals)
+      @engine.precompiled
+    end
+
+    def precompiled_preamble(locals)
+      local_assigns = super
+      @engine.instance_eval do
+        <<-RUBY
+          begin
+            extend Haml::Helpers
+            _hamlout = @haml_buffer = Haml::Buffer.new(@haml_buffer, #{options_for_buffer.inspect})
+            _erbout = _hamlout.buffer
+            __in_erb_template = true
+            _haml_locals = locals
+            #{local_assigns}
+        RUBY
+      end
+    end
+
+    def precompiled_postamble(locals)
+      @engine.instance_eval do
+        <<-RUBY
+            #{precompiled_method_return_value}
+          ensure
+            @haml_buffer = @haml_buffer.upper
+          end
+        RUBY
+      end
     end
   end
   register 'haml', HamlTemplate
@@ -306,15 +494,16 @@ module Tilt
   # Sass templates do not support object scopes, locals, or yield.
   class SassTemplate < Template
     def initialize_engine
-      require_template_library 'sass' unless defined? ::Sass::Engine
+      return if defined? ::Sass::Engine
+      require_template_library 'sass'
     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
@@ -325,14 +514,36 @@ module Tilt
   register 'sass', SassTemplate
 
 
+  # Lessscss template implementation. See:
+  # http://lesscss.org/
+  #
+  # Less templates do not support object scopes, locals, or yield.
+  class LessTemplate < Template
+    def initialize_engine
+      return if defined? ::Less::Engine
+      require_template_library 'less'
+    end
+
+    def prepare
+      @engine = ::Less::Engine.new(data)
+    end
+
+    def evaluate(scope, locals, &block)
+      @engine.to_css
+    end
+  end
+  register 'less', LessTemplate
+
+
   # Builder template implementation. See:
   # http://builder.rubyforge.org/
   class BuilderTemplate < Template
     def initialize_engine
-      require_template_library 'builder' unless defined?(::Builder)
+      return if defined?(::Builder)
+      require_template_library 'builder'
     end
 
-    def compile!
+    def prepare
     end
 
     def evaluate(scope, locals, &block)
@@ -346,7 +557,7 @@ module Tilt
       xml.target!
     end
 
-    def template_source
+    def precompiled_template(locals)
       data.to_str
     end
   end
@@ -368,10 +579,11 @@ module Tilt
   # time when using this template engine.
   class LiquidTemplate < Template
     def initialize_engine
-      require_template_library 'liquid' unless defined? ::Liquid::Template
+      return if defined? ::Liquid::Template
+      require_template_library 'liquid'
     end
 
-    def compile!
+    def prepare
       @engine = ::Liquid::Template.parse(data)
     end
 
@@ -381,9 +593,8 @@ module Tilt
         scope  = scope.to_h.inject({}){ |h,(k,v)| h[k.to_s] = v ; h }
         locals = scope.merge(locals)
       end
-      # TODO: Is it possible to lazy yield ?
       locals['yield'] = block.nil? ? '' : yield
-      locals['content'] = block.nil? ? '' : yield
+      locals['content'] = locals['yield']
       @engine.render(locals)
     end
   end
@@ -402,15 +613,17 @@ module Tilt
     end
 
     def initialize_engine
-      require_template_library 'rdiscount' unless defined? ::RDiscount
+      return if defined? ::RDiscount
+      require_template_library 'rdiscount'
     end
 
-    def compile!
+    def prepare
       @engine = RDiscount.new(data, *flags)
+      @output = nil
     end
 
     def evaluate(scope, locals, &block)
-      @engine.to_html
+      @output ||= @engine.to_html
     end
   end
   register 'markdown', RDiscountTemplate
@@ -418,22 +631,24 @@ module Tilt
   register 'md', RDiscountTemplate
 
 
-# RedCloth implementation. See:
-# http://redcloth.org/
-class RedClothTemplate < Template
-  def initialize_engine
-    require_template_library 'redcloth' unless defined? ::RedCloth
-  end
+  # RedCloth implementation. See:
+  # http://redcloth.org/
+  class RedClothTemplate < Template
+    def initialize_engine
+      return if defined? ::RedCloth
+      require_template_library 'redcloth'
+    end
 
-  def compile!
-    @engine = RedCloth.new(data)
-  end
+    def prepare
+      @engine = RedCloth.new(data)
+      @output = nil
+    end
 
-  def evaluate(scope, locals, &block)
-    @engine.to_html
+    def evaluate(scope, locals, &block)
+      @output ||= @engine.to_html
+    end
   end
-end
-register 'textile', RedClothTemplate
+  register 'textile', RedClothTemplate
 
 
   # Mustache is written and maintained by Chris Wanstrath. See:
@@ -446,14 +661,16 @@ register 'textile', RedClothTemplate
     attr_reader :engine
 
     def initialize_engine
-      require_template_library 'mustache' unless defined? ::Mustache
+      return if defined? ::Mustache
+      require_template_library '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)
       options.each do |key, value|
-        next if %w[view namespace mustaches].include?(key.to_s)
+        next if %w[view view_path namespace mustaches].include?(key.to_s)
         @engine.send("#{key}=", value) if @engine.respond_to? "#{key}="
       end
     end
@@ -482,6 +699,7 @@ register 'textile', RedClothTemplate
   end
   register 'mustache', MustacheTemplate
 
+
   # RDoc template. See:
   # http://rdoc.rubyforge.org/
   #
@@ -490,20 +708,39 @@ register 'textile', RedClothTemplate
   # engine.
   class RDocTemplate < Template
     def initialize_engine
-      unless defined?(::RDoc::Markup)
-        require_template_library 'rdoc/markup'
-        require_template_library 'rdoc/markup/to_html'
-      end
+      return if defined?(::RDoc::Markup)
+      require_template_library 'rdoc/markup'
+      require_template_library 'rdoc/markup/to_html'
     end
 
-    def compile!
+    def prepare
       markup = RDoc::Markup::ToHtml.new
       @engine = markup.convert(data)
+      @output = nil
     end
 
     def evaluate(scope, locals, &block)
-      @engine.to_s
+      @output ||= @engine.to_s
     end
   end
   register 'rdoc', RDocTemplate
+
+
+  # CoffeeScript info:
+  # http://jashkenas.github.com/coffee-script/
+  class CoffeeTemplate < Template
+    def initialize_engine
+      return if defined? ::CoffeeScript
+      require_template_library 'coffee-script'
+    end
+
+    def prepare
+      @output = nil
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= ::CoffeeScript::compile(data, options)
+    end
+  end
+  register 'coffee', CoffeeTemplate
 end