adamwiggins-sinatra 0.8.9 → 0.10.1

data/Rakefile

@@ -1,26 +1,15 @@
-require 'rubygems'
 require 'rake/clean'
+require 'rake/testtask'
 require 'fileutils'
 
 task :default => :test
+task :spec => :test
 
 # SPECS ===============================================================
 
-desc 'Run specs with story style output'
-task :spec do
-  pattern = ENV['TEST'] || '.*'
-  sh "specrb --testcase '#{pattern}' --specdox -Ilib:test test/*_test.rb"
-end
-
-desc 'Run specs with unit test style output'
-task :test do |t|
-  sh "specrb -Ilib:test test/*_test.rb"
-end
-
-desc 'Run compatibility specs'
-task :compat do |t|
-  pattern = ENV['TEST'] || '.*'
-  sh "specrb --testcase '#{pattern}' -Ilib:test compat/*_test.rb"
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
 # PACKAGING ============================================================
@@ -38,7 +27,7 @@ def spec
 end
 
 def package(ext='')
-  "dist/sinatra-#{spec.version}" + ext
+  "pkg/sinatra-#{spec.version}" + ext
 end
 
 desc 'Build packages'
@@ -49,25 +38,27 @@ task :install => package('.gem') do
   sh "gem install #{package('.gem')}"
 end
 
-directory 'dist/'
+directory 'pkg/'
+CLOBBER.include('pkg')
 
-file package('.gem') => %w[dist/ sinatra.gemspec] + spec.files do |f|
+file package('.gem') => %w[pkg/ sinatra.gemspec] + spec.files do |f|
   sh "gem build sinatra.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}"
+file package('.tar.gz') => %w[pkg/] + spec.files do |f|
+  sh <<-SH
+    git archive \
+      --prefix=sinatra-#{source_version}/ \
+      --format=tar \
+      HEAD | gzip > #{f.name}
+  SH
 end
 
 # Rubyforge Release / Publish Tasks ==================================
 
-desc 'Publish website to rubyforge'
-task 'publish:doc' => 'doc/api/index.html' do
-  sh 'scp -rp doc/* rubyforge.org:/var/www/gforge-projects/sinatra/'
-end
-
-task 'publish:gem' => [package('.gem'), package('.tar.gz')] do |t|
+desc 'Publish gem and tarball to rubyforge'
+task 'release' => [package('.gem'), package('.tar.gz')] do |t|
   sh <<-end
     rubyforge add_release sinatra sinatra #{spec.version} #{package('.gem')} &&
     rubyforge add_file    sinatra sinatra #{spec.version} #{package('.tar.gz')}
@@ -78,7 +69,7 @@ end
 # Building docs requires HAML and the hanna gem:
 #   gem install mislav-hanna --source=http://gems.github.com
 
-task 'doc'     => ['doc:api','doc:site']
+task 'doc'     => ['doc:api']
 
 desc 'Generate Hanna RDoc under doc/api'
 task 'doc:api' => ['doc/api/index.html']
@@ -98,53 +89,6 @@ file 'doc/api/index.html' => FileList['lib/**/*.rb','README.rdoc'] do |f|
 end
 CLEAN.include 'doc/api'
 
-def rdoc_to_html(file_name)
-  require 'rdoc/markup/to_html'
-  rdoc = RDoc::Markup::ToHtml.new
-  rdoc.convert(File.read(file_name))
-end
-
-def haml(locals={})
-  require 'haml'
-  template = File.read('doc/template.haml')
-  haml = Haml::Engine.new(template, :format => :html4, :attr_wrapper => '"')
-  haml.render(Object.new, locals)
-end
-
-desc 'Build website HTML and stuff'
-task 'doc:site' => ['doc/index.html', 'doc/book.html']
-
-file 'doc/index.html' => %w[README.rdoc doc/template.haml] do |file|
-  File.open(file.name, 'w') do |file|
-    file << haml(:title => 'Sinatra', :content => rdoc_to_html('README.rdoc'))
-  end
-end
-CLEAN.include 'doc/index.html'
-
-file 'doc/book.html' => ['book/output/sinatra-book.html'] do |file|
-  File.open(file.name, 'w') do |file|
-    book_content = File.read('book/output/sinatra-book.html')
-    file << haml(:title => 'Sinatra Book', :content => book_content)
-  end
-end
-CLEAN.include 'doc/book.html'
-
-file 'book/output/sinatra-book.html' => FileList['book/**'] do |f|
-  unless File.directory?('book')
-    sh 'git clone git://github.com/cschneid/sinatra-book.git book'
-  end
-  sh((<<-SH).strip.gsub(/\s+/, ' '))
-    cd book &&
-    git fetch origin &&
-    git rebase origin/master &&
-    thor book:build
-  SH
-end
-CLEAN.include 'book/output/sinatra-book.html'
-
-desc 'Build the Sinatra book'
-task 'doc:book' => ['book/output/sinatra-book.html']
-
 # Gemspec Helpers ====================================================
 
 def source_version
@@ -152,12 +96,7 @@ def source_version
   line.match(/.*VERSION = '(.*)'/)[1]
 end
 
-project_files =
-  FileList[
-    '{lib,test,compat,images}/**',
-    'Rakefile', 'CHANGES', 'README.rdoc'
-  ]
-file 'sinatra.gemspec' => project_files do |f|
+task 'sinatra.gemspec' => FileList['{lib,test,compat}/**','Rakefile','CHANGES','*.rdoc'] do |f|
   # read spec file and split out manifest section
   spec = File.read(f.name)
   head, manifest, tail = spec.split("  # = MANIFEST =\n")

data/lib/sinatra.rb

@@ -1,3 +1,7 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
 require 'sinatra/base'
 require 'sinatra/main'
-require 'sinatra/compat'
+
+use_in_file_templates!

data/lib/sinatra/base.rb

@@ -1,32 +1,42 @@
+require 'thread'
 require 'time'
 require 'uri'
 require 'rack'
 require 'rack/builder'
+require 'sinatra/showexceptions'
 
 module Sinatra
-  VERSION = '0.8.9'
+  VERSION = '0.10.1'
 
+  # The request object. See Rack::Request for more info:
+  # http://rack.rubyforge.org/doc/classes/Rack/Request.html
   class Request < Rack::Request
     def user_agent
       @env['HTTP_USER_AGENT']
     end
 
+    # Returns an array of acceptable media types for the response
     def accept
-      @env['HTTP_ACCEPT'].split(',').map { |a| a.strip }
+      @env['HTTP_ACCEPT'].to_s.split(',').map { |a| a.strip }
     end
-  end
 
-  class Response < Rack::Response
-    def initialize
-      @status, @body = 200, []
-      @header = Rack::Utils::HeaderHash.new({'Content-Type' => 'text/html'})
+    # Override Rack 0.9.x's #params implementation (see #72 in lighthouse)
+    def params
+      self.GET.update(self.POST)
+    rescue EOFError, Errno::ESPIPE
+      self.GET
     end
 
-    def write(str)
-      @body << str.to_s
-      str
+    def secure?
+      (@env['HTTP_X_FORWARDED_PROTO'] || @env['rack.url_scheme']) == 'https'
     end
+  end
 
+  # The response object. See Rack::Response and Rack::ResponseHelpers for
+  # more info:
+  # http://rack.rubyforge.org/doc/classes/Rack/Response.html
+  # http://rack.rubyforge.org/doc/classes/Rack/Response/Helpers.html
+  class Response < Rack::Response
     def finish
       @body = block if block_given?
       if [204, 304].include?(status.to_i)
@@ -35,19 +45,20 @@ module Sinatra
       else
         body = @body || []
         body = [body] if body.respond_to? :to_str
-        if header["Content-Length"].nil? && body.respond_to?(:to_ary)
+        if body.respond_to?(:to_ary)
           header["Content-Length"] = body.to_ary.
-            inject(0) { |len, part| len + part.length }.to_s
+            inject(0) { |len, part| len + Rack::Utils.bytesize(part) }.to_s
         end
         [status.to_i, header.to_hash, body]
       end
     end
   end
 
-  class NotFound < NameError # :)
+  class NotFound < NameError #:nodoc:
     def code ; 404 ; end
   end
 
+  # Methods available to routes, before filters, and views.
   module Helpers
     # Set or retrieve the response status code.
     def status(value=nil)
@@ -75,7 +86,7 @@ module Sinatra
 
     # Halt processing and return the error status provided.
     def error(code, body=nil)
-      code, body = 500, code.to_str if code.respond_to? :to_str
+      code, body    = 500, code.to_str if code.respond_to? :to_str
       response.body = body unless body.nil?
       halt code
     end
@@ -85,6 +96,12 @@ module Sinatra
       error 404, body
     end
 
+    # Set multiple response headers with Hash.
+    def headers(hash=nil)
+      response.headers.merge! hash if hash
+      response.headers
+    end
+
     # Access the underlying Rack session.
     def session
       env['rack.session'] ||= {}
@@ -118,23 +135,35 @@ module Sinatra
       end
     end
 
-    # Use the contents of the file as the response body and attempt to
+    # Use the contents of the file at +path+ as the response body.
     def send_file(path, opts={})
       stat = File.stat(path)
       last_modified stat.mtime
+
       content_type media_type(opts[:type]) ||
         media_type(File.extname(path)) ||
         response['Content-Type'] ||
         'application/octet-stream'
+
       response['Content-Length'] ||= (opts[:length] || stat.size).to_s
+
+      if opts[:disposition] == 'attachment' || opts[:filename]
+        attachment opts[:filename] || path
+      elsif opts[:disposition] == 'inline'
+        response['Content-Disposition'] = 'inline'
+      end
+
       halt StaticFile.open(path, 'rb')
     rescue Errno::ENOENT
       not_found
     end
 
+    # Rack response body used to deliver static files. The file contents are
+    # generated iteratively in 8K chunks.
     class StaticFile < ::File #:nodoc:
       alias_method :to_path, :path
       def each
+        rewind
         while buf = read(8192)
           yield buf
         end
@@ -177,109 +206,148 @@ module Sinatra
         halt 304 if etags.include?(value) || etags.include?('*')
       end
     end
+
+    ## Sugar for redirect (example:  redirect back)
+    def back ; request.referer ; end
+
   end
 
+  # Template rendering methods. Each method takes the name of a template
+  # to render as a Symbol and returns a String with the rendered output,
+  # as well as an optional hash with additional options.
+  #
+  # `template` is either the name or path of the template as symbol
+  # (Use `:'subdir/myview'` for views in subdirectories), or a string
+  # that will be rendered.
+  #
+  # Possible options are:
+  #   :layout       If set to false, no layout is rendered, otherwise
+  #                 the specified layout is used (Ignored for `sass`)
+  #   :locals       A hash with local variables that should be available
+  #                 in the template
   module Templates
-    def render(engine, template, options={})
-      data = lookup_template(engine, template, options)
-      output = __send__("render_#{engine}", template, data, options)
-      layout, data = lookup_layout(engine, options)
+    def erb(template, options={}, locals={})
+      render :erb, template, options, locals
+    end
+
+    def haml(template, options={}, locals={})
+      render :haml, template, options, locals
+    end
+
+    def sass(template, options={}, locals={})
+      options[:layout] = false
+      render :sass, template, options, locals
+    end
+
+    def builder(template=nil, options={}, locals={}, &block)
+      options, template = template, nil if template.is_a?(Hash)
+      template = lambda { block } if template.nil?
+      render :builder, template, options, locals
+    end
+
+  private
+    def render(engine, template, options={}, locals={})
+      # merge app-level options
+      options = self.class.send(engine).merge(options) if self.class.respond_to?(engine)
+
+      # extract generic options
+      layout = options.delete(:layout)
+      layout = :layout if layout.nil? || layout == true
+      views = options.delete(:views) || self.class.views || "./views"
+      locals = options.delete(:locals) || locals || {}
+
+      # render template
+      data, options[:filename], options[:line] = lookup_template(engine, template, views)
+      output = __send__("render_#{engine}", data, options, locals)
+
+      # render layout
       if layout
-        __send__("render_#{engine}", layout, data, options) { output }
-      else
-        output
+        data, options[:filename], options[:line] = lookup_layout(engine, layout, views)
+        if data
+          output = __send__("render_#{engine}", data, options, locals) { output }
+        end
       end
+
+      output
     end
 
-    def lookup_template(engine, template, options={})
+    def lookup_template(engine, template, views_dir, filename = nil, line = nil)
       case template
       when Symbol
-        if cached = self.class.templates[template]
-          lookup_template(engine, cached, options)
-        else
-          ::File.read(template_path(engine, template, options))
-        end
+        load_template(engine, template, views_dir, options)
       when Proc
-        template.call
+        filename, line = self.class.caller_locations.first if filename.nil?
+        [template.call, filename, line.to_i]
       when String
-        template
+        filename, line = self.class.caller_locations.first if filename.nil?
+        [template, filename, line.to_i]
       else
         raise ArgumentError
       end
     end
 
-    def lookup_layout(engine, options)
-      return if options[:layout] == false
-      options.delete(:layout) if options[:layout] == true
-      template = options[:layout] || :layout
-      data = lookup_template(engine, template, options)
-      [template, data]
-    rescue Errno::ENOENT
-      nil
-    end
+    def load_template(engine, template, views_dir, options={})
+      base = self.class
+      while base.respond_to?(:templates)
+        if cached = base.templates[template]
+          return lookup_template(engine, cached[:template], views_dir, cached[:filename], cached[:line])
+        else
+          base = base.superclass
+        end
+      end
 
-    def template_path(engine, template, options={})
-      views_dir =
-        options[:views_directory] || self.options.views || "./views"
-      "#{views_dir}/#{template}.#{engine}"
+      # If no template exists in the cache, try loading from disk.
+      path = ::File.join(views_dir, "#{template}.#{engine}")
+      [ ::File.read(path), path, 1 ]
     end
 
-    def erb(template, options={})
-      require 'erb' unless defined? ::ERB
-      render :erb, template, options
+    def lookup_layout(engine, template, views_dir)
+      lookup_template(engine, template, views_dir)
+    rescue Errno::ENOENT
+      nil
     end
 
-    def render_erb(template, data, options, &block)
+    def render_erb(data, options, locals, &block)
+      original_out_buf = defined?(@_out_buf) && @_out_buf
       data = data.call if data.kind_of? Proc
-      instance = ::ERB.new(data)
-      locals = options[:locals] || {}
-      locals_assigns = locals.to_a.collect { |k,v| "#{k} = locals[:#{k}]" }
-      src = "#{locals_assigns.join("\n")}\n#{instance.src}"
-      eval src, binding, '(__ERB__)', locals_assigns.length + 1
-      instance.result(binding)
-    end
 
-    def haml(template, options={})
-      require 'haml' unless defined? ::Haml
-      options[:options] ||= self.class.haml if self.class.respond_to? :haml
-      render :haml, template, options
-    end
+      instance = ::ERB.new(data, nil, nil, '@_out_buf')
+      locals_assigns = locals.to_a.collect { |k,v| "#{k} = locals[:#{k}]" }
 
-    def render_haml(template, data, options, &block)
-      engine = ::Haml::Engine.new(data, options[:options] || {})
-      engine.render(self, options[:locals] || {}, &block)
-    end
+      filename = options.delete(:filename) || '(__ERB__)'
+      line = options.delete(:line) || 1
+      line -= 1 if instance.src =~ /^#coding:/
 
-    def sass(template, options={}, &block)
-      require 'sass' unless defined? ::Sass
-      options[:layout] = false
-      render :sass, template, options
+      render_binding = binding
+      eval locals_assigns.join("\n"), render_binding
+      eval instance.src, render_binding, filename, line
+      @_out_buf, result = original_out_buf, @_out_buf
+      result
     end
 
-    def render_sass(template, data, options, &block)
-      engine = ::Sass::Engine.new(data, options[:sass] || {})
-      engine.render
+    def render_haml(data, options, locals, &block)
+      ::Haml::Engine.new(data, options).render(self, locals, &block)
     end
 
-    def builder(template=nil, options={}, &block)
-      require 'builder' unless defined? ::Builder
-      options, template = template, nil if template.is_a?(Hash)
-      template = lambda { block } if template.nil?
-      render :builder, template, options
+    def render_sass(data, options, locals, &block)
+      ::Sass::Engine.new(data, options).render
     end
 
-    def render_builder(template, data, options, &block)
-      xml = ::Builder::XmlMarkup.new(:indent => 2)
+    def render_builder(data, options, locals, &block)
+      options = { :indent => 2 }.merge(options)
+      filename = options.delete(:filename) || '<BUILDER>'
+      line = options.delete(:line) || 1
+      xml = ::Builder::XmlMarkup.new(options)
       if data.respond_to?(:to_str)
-        eval data.to_str, binding, '<BUILDER>', 1
+        eval data.to_str, binding, filename, line
       elsif data.kind_of?(Proc)
         data.call(xml)
       end
       xml.target!
     end
-
   end
 
+  # Base class for all Sinatra applications and middleware.
   class Base
     include Rack::Utils
     include Helpers
@@ -292,6 +360,7 @@ module Sinatra
       yield self if block_given?
     end
 
+    # Rack call interface.
     def call(env)
       dup.call!(env)
     end
@@ -302,34 +371,69 @@ module Sinatra
       @env      = env
       @request  = Request.new(env)
       @response = Response.new
-      @params   = nil
-      error_detection { dispatch! }
-      @response.finish
+      @params   = indifferent_params(@request.params)
+
+      invoke { dispatch! }
+      invoke { error_block!(response.status) }
+
+      status, header, body = @response.finish
+
+      # Never produce a body on HEAD requests. Do retain the Content-Length
+      # unless it's "0", in which case we assume it was calculated erroneously
+      # for a manual HEAD response and remove it entirely.
+      if @env['REQUEST_METHOD'] == 'HEAD'
+        body = []
+        header.delete('Content-Length') if header['Content-Length'] == '0'
+      end
+
+      [status, header, body]
     end
 
+    # Access options defined with Base.set.
     def options
       self.class
     end
 
+    # Exit the current block, halts any further processing
+    # of the request, and returns the specified response.
     def halt(*response)
-      throw :halt, *response
+      response = response.first if response.length == 1
+      throw :halt, response
     end
 
+    # Pass control to the next matching route.
+    # If there are no more matching routes, Sinatra will
+    # return a 404 response.
     def pass
       throw :pass
     end
 
+    # Forward the request to the downstream app -- middleware only.
+    def forward
+      fail "downstream app not set" unless @app.respond_to? :call
+      status, headers, body = @app.call(@request.env)
+      @response.status = status
+      @response.body = body
+      @response.headers.merge! headers
+      nil
+    end
+
   private
-    def dispatch!
-      self.class.filters.each {|block| instance_eval(&block)}
-      if routes = self.class.routes[@request.request_method]
-        path = @request.path_info
-        original_params = Hash.new{ |hash,k| hash[k.to_s] if Symbol === k }
-        original_params.merge! @request.params
-
-        routes.each do |pattern, keys, conditions, method_name|
-          if pattern =~ path
-            values = $~.captures.map{|val| val && unescape(val) }
+    # Run before filters defined on the class and all superclasses.
+    def filter!(base=self.class)
+      filter!(base.superclass) if base.superclass.respond_to?(:filters)
+      base.filters.each { |block| instance_eval(&block) }
+    end
+
+    # Run routes defined on the class and all superclasses.
+    def route!(base=self.class)
+      if routes = base.routes[@request.request_method]
+        original_params = @params
+        path            = unescape(@request.path_info)
+
+        routes.each do |pattern, keys, conditions, block|
+          if match = pattern.match(path)
+            values = match.captures.to_a
             params =
               if keys.any?
                 keys.zip(values).inject({}) do |hash,(k,v)|
@@ -345,28 +449,78 @@ module Sinatra
               else
                 {}
               end
-            @params = original_params.dup
-            @params.merge!(params)
+            @params = original_params.merge(params)
+            @block_params = values
 
-            catch(:pass) {
+            catch(:pass) do
               conditions.each { |cond|
                 throw :pass if instance_eval(&cond) == false }
-              return invoke(method_name)
-            }
+              route_eval(&block)
+            end
           end
         end
+
+        @params = original_params
+      end
+
+      # Run routes defined in superclass.
+      if base.superclass.respond_to?(:routes)
+        route! base.superclass
+        return
       end
-      raise NotFound
+
+      route_missing
     end
 
-    def invoke(handler)
-      res = catch(:halt) {
-        if handler.respond_to?(:call)
-          instance_eval(&handler)
-        else
-          send(handler)
-        end
-      }
+    # Run a route block and throw :halt with the result.
+    def route_eval(&block)
+      throw :halt, instance_eval(&block)
+    end
+
+    # No matching route was found or all routes passed. The default
+    # implementation is to forward the request downstream when running
+    # as middleware (@app is non-nil); when no downstream app is set, raise
+    # a NotFound exception. Subclasses can override this method to perform
+    # custom route miss logic.
+    def route_missing
+      if @app
+        forward
+      else
+        raise NotFound
+      end
+    end
+
+    # Attempt to serve static files from public directory. Throws :halt when
+    # a matching file is found, returns nil otherwise.
+    def static!
+      return if (public_dir = options.public).nil?
+      public_dir = File.expand_path(public_dir)
+
+      path = File.expand_path(public_dir + unescape(request.path_info))
+      return if path[0, public_dir.length] != public_dir
+      return unless File.file?(path)
+
+      send_file path, :disposition => nil
+    end
+
+    # Enable string or symbol key access to the nested params hash.
+    def indifferent_params(params)
+      params = indifferent_hash.merge(params)
+      params.each do |key, value|
+        next unless value.is_a?(Hash)
+        params[key] = indifferent_params(value)
+      end
+    end
+
+    def indifferent_hash
+      Hash.new {|hash,key| hash[key.to_s] if Symbol === key }
+    end
+
+    # Run the block with 'throw :halt' support and apply result to the response.
+    def invoke(&block)
+      res = catch(:halt) { instance_eval(&block) }
+      return if res.nil?
+
       case
       when res.respond_to?(:to_str)
         @response.body = [res]
@@ -379,7 +533,7 @@ module Sinatra
             headers.each { |k, v| @response.headers[k] = v } if headers
           elsif res.length == 2
             @response.status = res.first
-            @response.body = res.last
+            @response.body   = res.last
           else
             raise TypeError, "#{res.inspect} not supported"
           end
@@ -390,57 +544,113 @@ module Sinatra
         @response.body = res
       when (100...599) === res
         @response.status = res
-      when res.nil?
-        @response.body = []
       end
+
       res
     end
 
-    def error_detection
-      errmap = self.class.errors
-      yield
+    # Dispatch a request with error handling.
+    def dispatch!
+      filter!
+      static! if options.static? && (request.get? || request.head?)
+      route!
     rescue NotFound => boom
-      @env['sinatra.error'] = boom
-      @response.status = 404
-      @response.body = ['<h1>Not Found</h1>']
-      handler = errmap[boom.class] || errmap[NotFound]
-      invoke handler unless handler.nil?
+      handle_not_found!(boom)
     rescue ::Exception => boom
+      handle_exception!(boom)
+    end
+
+    def handle_not_found!(boom)
       @env['sinatra.error'] = boom
+      @response.status      = 404
+      @response.body        = ['<h1>Not Found</h1>']
+      error_block! boom.class, NotFound
+    end
 
-      if options.dump_errors?
-        msg = ["#{boom.class} - #{boom.message}:", *boom.backtrace].join("\n ")
-        @env['rack.errors'] << msg
-      end
+    def handle_exception!(boom)
+      @env['sinatra.error'] = boom
+
+      dump_errors!(boom) if options.dump_errors?
+      raise boom         if options.raise_errors? || options.show_exceptions?
 
-      raise boom if options.raise_errors?
       @response.status = 500
-      invoke errmap[boom.class] || errmap[Exception]
-    ensure
-      if @response.status >= 400 && errmap.key?(response.status)
-        invoke errmap[response.status]
+      error_block! boom.class, Exception
+    end
+
+    # Find an custom error block for the key(s) specified.
+    def error_block!(*keys)
+      keys.each do |key|
+        base = self.class
+        while base.respond_to?(:errors)
+          if block = base.errors[key]
+            # found a handler, eval and return result
+            res = instance_eval(&block)
+            return res
+          else
+            base = base.superclass
+          end
+        end
       end
+      nil
     end
 
-    @routes     = {}
-    @filters    = []
-    @conditions = []
-    @templates  = {}
-    @middleware = []
-    @callsite   = nil
-    @errors     = {}
+    def dump_errors!(boom)
+      backtrace = clean_backtrace(boom.backtrace)
+      msg = ["#{boom.class} - #{boom.message}:",
+        *backtrace].join("\n ")
+      @env['rack.errors'].write(msg)
+    end
+
+    def clean_backtrace(trace)
+      return trace unless options.clean_trace?
+
+      trace.reject { |line|
+        line =~ /lib\/sinatra.*\.rb/ ||
+          (defined?(Gem) && line.include?(Gem.dir))
+      }.map! { |line| line.gsub(/^\.\//, '') }
+    end
 
     class << self
-      attr_accessor :routes, :filters, :conditions, :templates,
-        :middleware, :errors
+      attr_reader :routes, :filters, :templates, :errors
+
+      def reset!
+        @conditions = []
+        @routes     = {}
+        @filters    = []
+        @templates  = {}
+        @errors     = {}
+        @middleware = []
+        @prototype  = nil
+        @extensions = []
+      end
 
+      # Extension modules registered on this class and all superclasses.
+      def extensions
+        if superclass.respond_to?(:extensions)
+          (@extensions + superclass.extensions).uniq
+        else
+          @extensions
+        end
+      end
+
+      # Middleware used in this class and all superclasses.
+      def middleware
+        if superclass.respond_to?(:middleware)
+          superclass.middleware + @middleware
+        else
+          @middleware
+        end
+      end
+
+      # 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)
         if value.kind_of?(Proc)
           metadef(option, &value)
           metadef("#{option}?") { !!__send__(option) }
           metadef("#{option}=") { |val| set(option, Proc.new{val}) }
         elsif value == self && option.respond_to?(:to_hash)
-          option.to_hash.each(&method(:set))
+          option.to_hash.each { |k,v| set(k, v) }
         elsif respond_to?("#{option}=")
           __send__ "#{option}=", value
         else
@@ -449,14 +659,19 @@ module Sinatra
         self
       end
 
+      # Same as calling `set :option, true` for each of the given options.
       def enable(*opts)
         opts.each { |key| set(key, true) }
       end
 
+      # Same as calling `set :option, false` for each of the given options.
       def disable(*opts)
         opts.each { |key| set(key, false) }
       end
 
+      # Define a custom error handler. Optionally takes either an Exception
+      # class, or an HTTP status code to specify which errors should be
+      # handled.
       def error(codes=Exception, &block)
         if codes.respond_to? :each
           codes.each { |err| error(err, &block) }
@@ -465,28 +680,43 @@ module Sinatra
         end
       end
 
+      # Sugar for `error(404) { ... }`
       def not_found(&block)
         error 404, &block
       end
 
+      # Define a named template. The block must return the template source.
       def template(name, &block)
-        templates[name] = block
+        filename, line = caller_locations.first
+        templates[name] = { :filename => filename, :line => line, :template => block }
       end
 
+      # Define the layout template. The block must return the template source.
       def layout(name=:layout, &block)
         template name, &block
       end
 
-      def use_in_file_templates!
-        line = caller.detect { |s| s !~ /lib\/sinatra.*\.rb/ &&
-          s !~ /\(.*\)/ }
-        file = line.sub(/:\d+.*$/, '')
-        if data = ::IO.read(file).split('__END__')[1]
+      # Load embeded templates from the file; uses the caller's __FILE__
+      # when no file is specified.
+      def use_in_file_templates!(file=nil)
+        file ||= caller_files.first
+
+        begin
+          app, data =
+            ::IO.read(file).split(/^__END__$/, 2)
+        rescue Errno::ENOENT
+          app, data = nil
+        end
+
+        if data
           data.gsub!(/\r\n/, "\n")
+          lines = app.count("\n") + 1
           template = nil
           data.each_line do |line|
+            lines += 1
             if line =~ /^@@\s*(.*)/
-              template = templates[$1.to_sym] = ''
+              template = ''
+              templates[$1.to_sym] = { :filename => file, :line => lines, :template => template }
             elsif template
               template << line
             end
@@ -501,14 +731,20 @@ module Sinatra
         Rack::Mime.mime_type(type, nil)
       end
 
+      # Define a before filter. Filters are run before all requests
+      # within the same context as route handlers and may access/modify the
+      # request and response.
       def before(&block)
         @filters << block
       end
 
+      # Add a route condition. The route is considered non-matching when the
+      # block returns false.
       def condition(&block)
         @conditions << block
       end
 
+   private
       def host_name(pattern)
         condition { pattern === request.host }
       end
@@ -523,8 +759,9 @@ module Sinatra
           end
         }
       end
+      alias_method :agent, :user_agent
 
-      def accept_mime_types(types)
+      def provides(*types)
         types = [types] unless types.kind_of? Array
         types.map!{|t| media_type(t)}
 
@@ -539,52 +776,72 @@ module Sinatra
         }
       end
 
+    public
+      # Defining a `GET` handler also automatically defines
+      # a `HEAD` handler.
       def get(path, opts={}, &block)
         conditions = @conditions.dup
-        _, _, _, method_name = route('GET', path, opts, &block)
+        route('GET', path, opts, &block)
 
         @conditions = conditions
-        head(path, opts) { invoke(method_name) ; [] }
+        route('HEAD', path, opts, &block)
       end
 
-      def put(path, opts={}, &bk); route 'PUT', path, opts, &bk; end
-      def post(path, opts={}, &bk); route 'POST', path, opts, &bk; end
-      def delete(path, opts={}, &bk); route 'DELETE', path, opts, &bk; end
-      def head(path, opts={}, &bk); route 'HEAD', path, opts, &bk; end
+      def put(path, opts={}, &bk);    route 'PUT',    path, opts, &bk end
+      def post(path, opts={}, &bk);   route 'POST',   path, opts, &bk end
+      def delete(path, opts={}, &bk); route 'DELETE', path, opts, &bk end
+      def head(path, opts={}, &bk);   route 'HEAD',   path, opts, &bk end
 
     private
-      def route(method, path, opts={}, &block)
-        host_name  opts[:host]  if opts.key?(:host)
-        user_agent opts[:agent] if opts.key?(:agent)
-        accept_mime_types opts[:provides] if opts.key?(:provides)
+      def route(verb, path, options={}, &block)
+        # Because of self.options.host
+        host_name(options.delete(:host)) if options.key?(:host)
+
+        options.each {|option, args| send(option, *args)}
 
         pattern, keys = compile(path)
         conditions, @conditions = @conditions, []
-        method_name = "route { #{method} #{path} }"
-        nmethods = instance_methods.grep(rx = /#{Regexp.escape(method_name)}/).size
-        method_name += " [#{nmethods}]"
 
-        define_method(method_name, &block)
+        define_method "#{verb} #{path}", &block
+        unbound_method = instance_method("#{verb} #{path}")
+        block =
+          if block.arity != 0
+            lambda { unbound_method.bind(self).call(*@block_params) }
+          else
+            lambda { unbound_method.bind(self).call }
+          end
+
+        invoke_hook(:route_added, verb, path, block)
+
+        (@routes[verb] ||= []).
+          push([pattern, keys, conditions, block]).last
+      end
 
-        (routes[method] ||= []).
-          push([pattern, keys, conditions, method_name]).last
+      def invoke_hook(name, *args)
+        extensions.each { |e| e.send(name, *args) if e.respond_to?(name) }
       end
 
       def compile(path)
         keys = []
         if path.respond_to? :to_str
+          special_chars = %w{. + ( )}
           pattern =
-            URI.encode(path).gsub(/((:\w+)|\*)/) do |match|
-              if match == "*"
+            path.to_str.gsub(/((:\w+)|[\*#{special_chars.join}])/) do |match|
+              case match
+              when "*"
                 keys << 'splat'
                 "(.*?)"
+              when *special_chars
+                Regexp.escape(match)
               else
                 keys << $2[1..-1]
-                "([^/?&#\.]+)"
+                "([^/?&#]+)"
               end
             end
           [/^#{pattern}$/, keys]
-        elsif path.respond_to? :=~
+        elsif path.respond_to?(:keys) && path.respond_to?(:match)
+          [path, path.keys]
+        elsif path.respond_to? :match
           [path, keys]
         else
           raise TypeError, path
@@ -592,70 +849,106 @@ module Sinatra
       end
 
     public
-      def development? ; environment == :development ; end
-      def test? ; environment == :test ; end
-      def production? ; environment == :production ; end
+      # Makes the methods defined in the block and in the Modules given
+      # in `extensions` available to the handlers and templates
+      def helpers(*extensions, &block)
+        class_eval(&block)  if block_given?
+        include(*extensions) if extensions.any?
+      end
+
+      def register(*extensions, &block)
+        extensions << Module.new(&block) if block_given?
+        @extensions += extensions
+        extensions.each do |extension|
+          extend extension
+          extension.registered(self) if extension.respond_to?(:registered)
+        end
+      end
+
+      def development?; environment == :development end
+      def production?;  environment == :production  end
+      def test?;        environment == :test        end
 
+      # Set configuration options for Sinatra and/or the app.
+      # Allows scoping of settings for certain environments.
       def configure(*envs, &block)
-        yield if envs.empty? || envs.include?(environment.to_sym)
+        yield self if envs.empty? || envs.include?(environment.to_sym)
       end
 
+      # Use the specified Rack middleware
       def use(middleware, *args, &block)
-        reset_middleware
+        @prototype = nil
         @middleware << [middleware, args, block]
       end
 
+      # Run the Sinatra app as a self-hosted server using
+      # Thin, Mongrel or WEBrick (in that order)
       def run!(options={})
-        set(options)
-        handler = Rack::Handler.get(server)
+        set options
+        handler      = detect_rack_handler
         handler_name = handler.name.gsub(/.*::/, '')
         puts "== Sinatra/#{Sinatra::VERSION} has taken the stage " +
-          "on #{port} for #{environment} with backup from #{handler_name}"
+          "on #{port} for #{environment} with backup from #{handler_name}" unless handler_name =~/cgi/i
         handler.run self, :Host => host, :Port => port do |server|
           trap(:INT) do
             ## Use thins' hard #stop! if available, otherwise just #stop
             server.respond_to?(:stop!) ? server.stop! : server.stop
-            puts "\n== Sinatra has ended his set (crowd applauds)"
+            puts "\n== Sinatra has ended his set (crowd applauds)" unless handler_name =~/cgi/i
           end
+          set :running, true
         end
       rescue Errno::EADDRINUSE => e
         puts "== Someone is already performing on port #{port}!"
       end
 
-      def call(env)
-        construct_middleware if @callsite.nil?
-        @callsite.call(env)
+      # The prototype instance used to process requests.
+      def prototype
+        @prototype ||= new
       end
 
-    private
-      def construct_middleware(builder=Rack::Builder.new)
-        builder.use Rack::Session::Cookie if sessions?
-        builder.use Rack::CommonLogger if logging?
-        builder.use Rack::MethodOverride if methodoverride?
-        @middleware.each { |c, args, bk| builder.use(c, *args, &bk) }
-        builder.run new
-        @callsite = builder.to_app
+      # Create a new instance of the class fronted by its middleware
+      # pipeline. The object is guaranteed to respond to #call but may not be
+      # an instance of the class new was called on.
+      def new(*args, &bk)
+        builder = Rack::Builder.new
+        builder.use Rack::Session::Cookie if sessions? && !test?
+        builder.use Rack::CommonLogger    if logging?
+        builder.use Rack::MethodOverride  if methodoverride?
+        builder.use ShowExceptions        if show_exceptions?
+        middleware.each { |c,a,b| builder.use(c, *a, &b) }
+
+        builder.run super
+        builder.to_app
       end
 
-      def reset_middleware
-        @callsite = nil
+      def call(env)
+        synchronize { prototype.call(env) }
+      end
+
+    private
+      def detect_rack_handler
+        servers = Array(self.server)
+        servers.each do |server_name|
+          begin
+            return Rack::Handler.get(server_name.downcase)
+          rescue LoadError
+          rescue NameError
+          end
+        end
+        fail "Server handler (#{servers.join(',')}) not found."
       end
 
       def inherited(subclass)
-        subclass.routes = dupe_routes
-        subclass.templates = templates.dup
-        subclass.conditions = []
-        subclass.filters = filters.dup
-        subclass.errors = errors.dup
-        subclass.middleware = middleware.dup
-        subclass.send :reset_middleware
+        subclass.reset!
         super
       end
 
-      def dupe_routes
-        routes.inject({}) do |hash,(request_method,routes)|
-          hash[request_method] = routes.dup
-          hash
+      @@mutex = Mutex.new
+      def synchronize(&block)
+        if lock?
+          @@mutex.synchronize(&block)
+        else
+          yield
         end
       end
 
@@ -663,18 +956,47 @@ module Sinatra
         (class << self; self; end).
           send :define_method, message, &block
       end
+
+    public
+      CALLERS_TO_IGNORE = [
+        /\/sinatra(\/(base|main|showexceptions))?\.rb$/, # all sinatra code
+        /\(.*\)/,              # generated code
+        /custom_require\.rb$/, # rubygems require hacks
+        /active_support/,      # active_support require hacks
+      ]
+
+      # add rubinius (and hopefully other VM impls) ignore patterns ...
+      CALLERS_TO_IGNORE.concat(RUBY_IGNORE_CALLERS) if defined?(RUBY_IGNORE_CALLERS)
+
+      # Like Kernel#caller but excluding certain magic entries and without
+      # line / method information; the resulting array contains filenames only.
+      def caller_files
+        caller_locations.
+          map { |file,line| file }
+      end
+
+      def caller_locations
+        caller(1).
+          map    { |line| line.split(/:(?=\d|in )/)[0,2] }.
+          reject { |file,line| CALLERS_TO_IGNORE.any? { |pattern| file =~ pattern } }
+      end
     end
 
+    reset!
+
     set :raise_errors, true
     set :dump_errors, false
+    set :clean_trace, true
+    set :show_exceptions, false
     set :sessions, false
     set :logging, false
     set :methodoverride, false
     set :static, false
     set :environment, (ENV['RACK_ENV'] || :development).to_sym
 
-    set :run, false
-    set :server, (defined?(Rack::Handler::Thin) ? "thin" : "mongrel")
+    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 :port, 4567
 
@@ -682,14 +1004,7 @@ module Sinatra
     set :root, Proc.new { app_file && File.expand_path(File.dirname(app_file)) }
     set :views, Proc.new { root && File.join(root, 'views') }
     set :public, Proc.new { root && File.join(root, 'public') }
-
-    # static files route
-    get(/.*[^\/]$/) do
-      pass unless options.static? && options.public?
-      path = options.public + unescape(request.path_info)
-      pass unless File.file?(path)
-      send_file path, :disposition => nil
-    end
+    set :lock, false
 
     error ::Exception do
       response.status = 500
@@ -705,6 +1020,8 @@ module Sinatra
       end
 
       error NotFound do
+        content_type 'text/html'
+
         (<<-HTML).gsub(/^ {8}/, '')
         <!DOCTYPE html>
         <html>
@@ -726,93 +1043,67 @@ module Sinatra
         </html>
         HTML
       end
-
-      error do
-        next unless err = request.env['sinatra.error']
-        heading = err.class.name + ' - ' + err.message.to_s
-        (<<-HTML).gsub(/^ {8}/, '')
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <style type="text/css">
-            body {font-family:verdana;color:#333}
-            #c {margin-left:20px}
-            h1 {color:#1D6B8D;margin:0;margin-top:-30px}
-            h2 {color:#1D6B8D;font-size:18px}
-            pre {border-left:2px solid #ddd;padding-left:10px;color:#000}
-            img {margin-top:10px}
-          </style>
-        </head>
-        <body>
-          <div id="c">
-            <img src="/__sinatra__/500.png">
-            <h1>#{escape_html(heading)}</h1>
-            <pre class='trace'>#{escape_html(err.backtrace.join("\n"))}</pre>
-            <h2>Params</h2>
-            <pre>#{escape_html(params.inspect)}</pre>
-          </div>
-        </body>
-        </html>
-        HTML
-      end
     end
   end
 
-  class Default < Base
-    set :raise_errors, false
+  # The top-level Application. All DSL methods executed on main are delegated
+  # to this class.
+  class Application < Base
+    set :raise_errors, Proc.new { test? }
+    set :show_exceptions, Proc.new { development? }
     set :dump_errors, true
     set :sessions, false
-    set :logging, true
+    set :logging, Proc.new { ! test? }
     set :methodoverride, true
     set :static, true
-    set :run, false
-    set :reload, Proc.new { app_file? && development? }
-
-    def self.reloading?
-      @reloading ||= false
-    end
-
-    def self.configure(*envs)
-      super unless reloading?
-    end
-
-    def self.call(env)
-      reload! if reload?
-      super
-    end
+    set :run, Proc.new { ! test? }
 
-    def self.reload!
-      @reloading = true
-      superclass.send :inherited, self
-      ::Kernel.load app_file
-      @reloading = false
+    def self.register(*extensions, &block) #:nodoc:
+      added_methods = extensions.map {|m| m.public_instance_methods }.flatten
+      Delegator.delegate(*added_methods)
+      super(*extensions, &block)
     end
-
-  end
-
-  class Application < Default
   end
 
-  module Delegator
-    METHODS = %w[
-      get put post delete head template layout before error not_found
-      configures configure set set_option set_options enable disable use
-      development? test? production? use_in_file_templates!
-    ]
-
-    METHODS.each do |method_name|
-      eval <<-RUBY, binding, '(__DELEGATE__)', 1
-        def #{method_name}(*args, &b)
-          ::Sinatra::Application.#{method_name}(*args, &b)
-        end
-        private :#{method_name}
-      RUBY
+  # Deprecated.
+  Default = Application
+
+  # Sinatra delegation mixin. Mixing this module into an object causes all
+  # methods to be delegated to the Sinatra::Application class. Used primarily
+  # at the top-level.
+  module Delegator #:nodoc:
+    def self.delegate(*methods)
+      methods.each do |method_name|
+        eval <<-RUBY, binding, '(__DELEGATE__)', 1
+          def #{method_name}(*args, &b)
+            ::Sinatra::Application.send(#{method_name.inspect}, *args, &b)
+          end
+          private #{method_name.inspect}
+        RUBY
+      end
     end
+
+    delegate :get, :put, :post, :delete, :head, :template, :layout, :before,
+             :error, :not_found, :configure, :set,
+             :enable, :disable, :use, :development?, :test?,
+             :production?, :use_in_file_templates!, :helpers
   end
 
+  # Create a new Sinatra application. The block is evaluated in the new app's
+  # class scope.
   def self.new(base=Base, options={}, &block)
     base = Class.new(base)
     base.send :class_eval, &block if block_given?
     base
   end
+
+  # Extend the top-level DSL with the modules provided.
+  def self.register(*extensions, &block)
+    Application.register(*extensions, &block)
+  end
+
+  # Include the helper modules provided in Sinatra's request context.
+  def self.helpers(*extensions, &block)
+    Application.helpers(*extensions, &block)
+  end
 end