sinatra 0.9.1.1 → 0.9.2

data/CHANGES

@@ -1,3 +1,84 @@
+= 0.9.2 / unreleased
+
+ * This version is compatible with Rack 1.0. [Rein Henrichs]
+
+ * The development-mode unhandled exception / error page has been
+   greatly enhanced, functionally and aesthetically. The error
+   page is used when the :show_exceptions option is enabled and an
+   exception propagates outside of a route handler or before filter.
+   [Simon Rozet / Matte Noble / Ryan Tomayko]
+
+ * Backtraces that move through templates now include filenames and
+   line numbers where possible. [#51 / S. Brent Faulkner]
+
+ * All templates now have an app-level option for setting default
+   template options (:haml, :sass, :erb, :builder). The app-level
+   option value must be a Hash if set and is merged with the
+   template options specified to the render method (Base#haml,
+   Base#erb, Base#builder). [S. Brent Faulkner, Ryan Tomayko]
+
+ * The method signature for all template rendering methods has
+   been unified: "def engine(template, options={}, locals={})".
+   The options Hash now takes the generic :views, :layout, and
+   :locals options but also any template-specific options. The
+   generic options are removed before calling the template specific
+   render method. Locals may be specified using either the
+   :locals key in the options hash or a second Hash option to the
+   rendering method. [#191 / Ryan Tomayko]
+
+ * The receiver is now passed to "configure" blocks. This
+   allows for the following idiom in top-level apps:
+   configure { |app| set :foo, app.root + '/foo' }
+   [TJ Holowaychuck / Ryan Tomayko]
+
+ * The "sinatra/test" lib is deprecated and will be removed in
+   Sinatra 1.0. This includes the Sinatra::Test module and
+   Sinatra::TestHarness class in addition to all the framework
+   test helpers that were deprecated in 0.9.1. The Rack::Test
+   lib should be used instead: http://gitrdoc.com/brynary/rack-test
+   [#176 / Simon Rozet]
+
+ * Development mode source file reloading has been removed. The
+   "shotgun" (http://rtomayko.github.com/shotgun/) program can be
+   used to achieve the same basic functionality in most situations.
+   Passenger users should use the "tmp/always_restart.txt"
+   file (http://tinyurl.com/c67o4h). [#166 / Ryan Tomayko]
+
+ * Auto-requiring template libs in the erb, builder, haml, and
+   sass methods is deprecated due to thread-safety issues. You must
+   require the template libs explicitly in your app file. [Simon Rozet]
+
+ * A new Sinatra::Base#route_missing method was added. route_missing
+   is sent when no route matches the request or all route handlers
+   pass.  The default implementation forwards the request to the
+   downstream app when running as middleware (i.e., "@app" is
+   non-nil), or raises a NotFound exception when no downstream app
+   is defined. Subclasses can override this method to perform custom
+   route miss logic. [Jon Crosby]
+
+ * A new Sinatra::Base#route_eval method was added. The method
+   yields to the block and throws :halt with the result. Subclasses
+   can override this method to tap into the route execution logic.
+   [TJ Holowaychuck]
+
+ * Fix the "-x" (enable request mutex / locking) command line
+   argument. Passing -x now properly sets the :lock option.
+   [S. Brent Faulkner, Ryan Tomayko]
+
+ * Fix writer ("foo=") and predicate ("foo?") methods in extension
+   modules not being added to the registering class.
+   [#172 / Pat Nakajima]
+
+ * Fix in-file templates when running alongside activesupport and
+   fatal errors when requiring activesupport before sinatra
+   [#178 / Brian Candler]
+
+ * Fix various issues running on Google AppEngine.
+   [Samuel Goebert, Simon Rozet]
+
+ * Fix in-file templates __END__ detection when __END__ exists with
+   other stuff on a line [Yoji Shidara]
+
 = 0.9.1.1 / 2009-03-09
 
  * Fix directory traversal vulnerability in default static files

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007 Blake Mizerany
+Copyright (c) 2007, 2008, 2009 Blake Mizerany
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.rdoc

@@ -109,18 +109,41 @@ directory. To use a different views directory:
 
   set :views, File.dirname(__FILE__) + '/templates'
 
+One important thing to remember is that you always have to reference
+templates with symbols, even if they're in a subdirectory (in this
+case use <tt>:'subdir/template'</tt>). Rendering methods will render
+any strings passed to them directly.
+
 === Haml Templates
 
 The haml gem/library is required to render HAML templates:
 
+  ## You'll need to require haml in your app
+  require 'haml'
+
   get '/' do
     haml :index
   end
 
 Renders <tt>./views/index.haml</tt>.
 
+{Haml's options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
+can be set globally through Sinatra's configurations,
+see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
+and overridden on an individual basis.
+
+  set :haml, {:format => :html5 } # default Haml format is :xhtml
+
+  get '/' do
+    haml :index, :haml_options => {:format => :html4 } # overridden
+  end
+
+
 === Erb Templates
 
+  ## You'll need to require erb in your app
+  require 'erb'
+
   get '/' do
     erb :index
   end
@@ -131,6 +154,9 @@ Renders <tt>./views/index.erb</tt>
 
 The builder gem/library is required to render builder templates:
 
+  ## You'll need to require builder in your app
+  require 'builder'
+
   get '/' do
     content_type 'application/xml', :charset => 'utf-8'
     builder :index
@@ -142,6 +168,9 @@ Renders <tt>./views/index.builder</tt>.
 
 The sass gem/library is required to render Sass templates:
 
+  ## You'll need to require haml or sass in your app
+  require 'sass'
+
   get '/stylesheet.css' do
     content_type 'text/css', :charset => 'utf-8'
     sass :stylesheet
@@ -149,6 +178,19 @@ The sass gem/library is required to render Sass templates:
 
 Renders <tt>./views/stylesheet.sass</tt>.
 
+{Sass' options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
+can be set globally through Sinatra's configurations,
+see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
+and overridden on an individual basis.
+
+  set :sass, {:style => :compact } # default Sass style is :nested
+
+  get '/stylesheet.css' do
+    content_type 'text/css', :charset => 'utf-8'
+    sass :stylesheet, :sass_options => {:style => :expanded } # overridden
+  end
+
+
 === Inline Templates
 
   get '/' do
@@ -285,13 +327,7 @@ A route can punt processing to the next matching route using <tt>pass</tt>:
 The route block is immediately exited and control continues with the next
 matching route. If no matching route is found, a 404 is returned.
 
-== Configuration and Reloading
-
-Sinatra supports multiple environments and reloading. Reloading happens
-before each request when running under the <tt>:development</tt>
-environment. Wrap your configurations (e.g., database connections, constants,
-etc.) in <tt>configure</tt> blocks to protect them from reloading or to
-target specific environments.
+== Configuration
 
 Run once, at startup, in any environment:
 
@@ -300,14 +336,14 @@ Run once, at startup, in any environment:
   end
 
 Run only when the environment (RACK_ENV environment variable) is set to
-<tt>:production</tt>.
+<tt>:production</tt>:
 
   configure :production do
     ...
   end
 
-Run when the environment (RACK_ENV environment variable) is set to
-either <tt>:production</tt> or <tt>:test</tt>.
+Run when the environment is set to either <tt>:production</tt> or
+<tt>:test</tt>:
 
   configure :production, :test do
     ...
@@ -401,34 +437,38 @@ typically don't have to +use+ them explicitly.
 
 == Testing
 
-The Sinatra::Test mixin and Sinatra::TestHarness class include a variety of
-helper methods for testing your Sinatra app:
+Sinatra tests can be written using any Rack-based testing library
+or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
+recommended:
 
   require 'my_sinatra_app'
-  require 'test/unit'
-  require 'sinatra/test'
+  require 'rack/test'
 
   class MyAppTest < Test::Unit::TestCase
-    include Sinatra::Test
+    include Rack::Test::Methods
+
+    def app
+      Sinatra::Application
+    end
 
     def test_my_default
       get '/'
-      assert_equal 'Hello World!', @response.body
+      assert_equal 'Hello World!', last_response.body
     end
 
     def test_with_params
-      get '/meet', {:name => 'Frank'}
-      assert_equal 'Hello Frank!', @response.body
+      get '/meet', :name => 'Frank'
+      assert_equal 'Hello Frank!', last_response.body
     end
 
     def test_with_rack_env
-      get '/', {}, :agent => 'Songbird'
-      assert_equal "You're using Songbird!", @response.body
+      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
+      assert_equal "You're using Songbird!", last_response.body
     end
   end
 
-See http://www.sinatrarb.com/testing.html for more on Sinatra::Test and using it
-with other test frameworks such as RSpec, Bacon, and test/spec.
+NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
+are deprecated as of the 0.9.2 release.
 
 == Command line
 
@@ -454,7 +494,7 @@ clone and run your app with the <tt>sinatra/lib</tt> directory on the
   git clone git://github.com/sinatra/sinatra.git
   ruby -Isinatra/lib myapp.rb
 
-Alternatively, you can add the <tt>sinatra/lib<tt> directory to the
+Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
 <tt>LOAD_PATH</tt> in your application:
 
   $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'

data/Rakefile

@@ -2,20 +2,33 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'fileutils'
 
-task :default => [:test]
+task :default => [:test, :compat]
 task :spec => :test
 
 # SPECS ===============================================================
 
+task(:test) { puts "==> Running main test suite" }
+
 Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/*_test.rb']
   t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
-desc 'Run compatibility specs (requires test/spec)'
-task :compat do |t|
-  pattern = ENV['TEST'] || '.*'
-  sh "specrb --testcase '#{pattern}' -Ilib:test compat/*_test.rb"
+desc "Run < 0.9.x compatibility specs"
+task :compat do
+  begin
+    require 'mocha'
+    require 'test/spec'
+    at_exit { exit 0 } # disable test-spec at_exit runner
+
+    puts "==> Running compat test suite"
+    Rake::TestTask.new(:compat) do |t|
+      t.test_files = FileList['compat/*_test.rb']
+      t.ruby_opts = ['-rubygems'] if defined? Gem
+    end
+  rescue LoadError
+    warn 'Skipping compat tests. mocha and/or test-spec gems not installed.'
+  end
 end
 
 # PACKAGING ============================================================
@@ -33,7 +46,7 @@ def spec
 end
 
 def package(ext='')
-  "dist/sinatra-#{spec.version}" + ext
+  "pkg/sinatra-#{spec.version}" + ext
 end
 
 desc 'Build packages'
@@ -44,15 +57,15 @@ task :install => package('.gem') do
   sh "gem install #{package('.gem')}"
 end
 
-directory 'dist/'
-CLOBBER.include('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|
+file package('.tar.gz') => %w[pkg/] + spec.files do |f|
   sh <<-SH
     git archive \
       --prefix=sinatra-#{source_version}/ \
@@ -64,7 +77,7 @@ end
 # Rubyforge Release / Publish Tasks ==================================
 
 desc 'Publish gem and tarball to rubyforge'
-task 'publish:gem' => [package('.gem'), package('.tar.gz')] do |t|
+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')}
@@ -95,12 +108,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
-
 # Gemspec Helpers ====================================================
 
 def source_version
@@ -108,12 +115,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/compat/haml_test.rb

@@ -183,13 +183,14 @@ context "Haml" do
       Sinatra.application = nil
     end
 
-    specify 'are empty be default' do
+    specify 'default to filename and line of caller' do
 
       get '/' do
         haml 'foo'
       end
 
-      Haml::Engine.expects(:new).with('foo', {}).returns(stub(:render => 'foo'))
+      Haml::Engine.expects(:new).with('foo', {:filename => __FILE__,
+        :line => (__LINE__-4)}).returns(stub(:render => 'foo'))
 
       get_it '/'
       should.be.ok
@@ -202,7 +203,8 @@ context "Haml" do
         haml 'foo', :options => {:format => :html4}
       end
 
-      Haml::Engine.expects(:new).with('foo', {:format => :html4}).returns(stub(:render => 'foo'))
+      Haml::Engine.expects(:new).with('foo', {:filename => __FILE__,
+        :line => (__LINE__-4), :format => :html4}).returns(stub(:render => 'foo'))
 
       get_it '/'
       should.be.ok
@@ -220,7 +222,8 @@ context "Haml" do
         haml 'foo'
       end
 
-      Haml::Engine.expects(:new).with('foo', {:format => :html4,
+      Haml::Engine.expects(:new).with('foo', {:filename => __FILE__,
+        :line => (__LINE__-4), :format => :html4,
         :escape_html => true}).returns(stub(:render => 'foo'))
 
       get_it '/'

data/compat/helper.rb

@@ -24,6 +24,9 @@ end
 
 class Test::Unit::TestCase
   include Sinatra::Test
+
+  PASSTHROUGH_EXCEPTIONS = [] unless const_defined?(:PASSTHROUGH_EXCEPTIONS)
+
   def setup
     @app = lambda { |env| Sinatra::Application.call(env) }
   end

data/compat/sass_test.rb

@@ -52,6 +52,16 @@ context "Sass" do
       body.should.equal "#sass {\n  background_color: #FFF; }\n"
     end
 
+    it "passes :sass option to the Sass engine" do
+      get '/' do
+        sass "#sass\n  :background-color #FFF\n  :color #000\n", :sass => {:style => :compact}
+      end
+
+      get_it '/'
+      should.be.ok
+      body.should.equal "#sass { background-color: #FFF; color: #000; }\n"
+    end
+
   end
 
 end

data/lib/sinatra/base.rb

@@ -3,9 +3,10 @@ require 'time'
 require 'uri'
 require 'rack'
 require 'rack/builder'
+require 'sinatra/showexceptions'
 
 module Sinatra
-  VERSION = '0.9.1.1'
+  VERSION = '0.9.2'
 
   # The request object. See Rack::Request for more info:
   # http://rack.rubyforge.org/doc/classes/Rack/Request.html
@@ -14,6 +15,7 @@ module Sinatra
       @env['HTTP_USER_AGENT']
     end
 
+    # Returns an array of acceptable media types for the response
     def accept
       @env['HTTP_ACCEPT'].to_s.split(',').map { |a| a.strip }
     end
@@ -31,16 +33,6 @@ module Sinatra
   # http://rack.rubyforge.org/doc/classes/Rack/Response.html
   # http://rack.rubyforge.org/doc/classes/Rack/Response/Helpers.html
   class Response < Rack::Response
-    def initialize
-      @status, @body = 200, []
-      @header = Rack::Utils::HeaderHash.new({'Content-Type' => 'text/html'})
-    end
-
-    def write(str)
-      @body << str.to_s
-      str
-    end
-
     def finish
       @body = block if block_given?
       if [204, 304].include?(status.to_i)
@@ -162,6 +154,8 @@ module Sinatra
       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
@@ -215,110 +209,141 @@ module Sinatra
   end
 
   # Template rendering methods. Each method takes a the name of a template
-  # to render as a Symbol and returns a String with the rendered output.
+  # 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 erb(template, options={})
-      require 'erb' unless defined? ::ERB
-      render :erb, template, options
+    def erb(template, options={}, locals={})
+      require_warn('ERB') unless defined?(::ERB)
+
+      render :erb, template, options, locals
     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
+    def haml(template, options={}, locals={})
+      require_warn('Haml') unless defined?(::Haml::Engine)
+
+      render :haml, template, options, locals
     end
 
-    def sass(template, options={}, &block)
-      require 'sass' unless defined? ::Sass
+    def sass(template, options={}, locals={})
+      require_warn('Sass') unless defined?(::Sass::Engine)
+
       options[:layout] = false
-      render :sass, template, options
+      render :sass, template, options, locals
     end
 
-    def builder(template=nil, options={}, &block)
-      require 'builder' unless defined? ::Builder
+    def builder(template=nil, options={}, locals={}, &block)
+      require_warn('Builder') unless defined?(::Builder)
+
       options, template = template, nil if template.is_a?(Hash)
       template = lambda { block } if template.nil?
-      render :builder, template, options
+      render :builder, template, options, locals
     end
 
   private
-    def render(engine, template, options={}) #:nodoc:
-      data   = lookup_template(engine, template, options)
-      output = __send__("render_#{engine}", template, data, options)
-      layout, data = lookup_layout(engine, options)
+    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}", template, 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}", layout, data, options, {}) { 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)
+          lookup_template(engine, cached[:template], views_dir, cached[:filename], cached[:line])
         else
-          ::File.read(template_path(engine, template, options))
+          path = ::File.join(views_dir, "#{template}.#{engine}")
+          [ ::File.read(path), path, 1 ]
         end
       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]
+    def lookup_layout(engine, template, views_dir)
+      lookup_template(engine, template, views_dir)
     rescue Errno::ENOENT
       nil
     end
 
-    def template_path(engine, template, options={})
-      views_dir =
-        options[:views_directory] || self.options.views || "./views"
-      "#{views_dir}/#{template}.#{engine}"
-    end
-
-    def render_erb(template, data, options, &block)
-      original_out_buf = @_out_buf
+    def render_erb(template, data, options, locals, &block)
+      original_out_buf = defined?(@_out_buf) && @_out_buf
       data = data.call if data.kind_of? Proc
 
       instance = ::ERB.new(data, nil, nil, '@_out_buf')
-      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
+      filename = options.delete(:filename) || '(__ERB__)'
+      line = options.delete(:line) || 1
+      line -= 1 if instance.src =~ /^#coding:/
+
+      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_haml(template, data, options, &block)
-      engine = ::Haml::Engine.new(data, options[:options] || {})
-      engine.render(self, options[:locals] || {}, &block)
+    def render_haml(template, data, options, locals, &block)
+      ::Haml::Engine.new(data, options).render(self, locals, &block)
     end
 
-    def render_sass(template, data, options, &block)
-      engine = ::Sass::Engine.new(data, options[:sass] || {})
-      engine.render
+    def render_sass(template, 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(template, 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
+
+    def require_warn(engine)
+      warn "Auto-require of #{engine} is deprecated; add require '#{engine}' to your app."
+      require engine.downcase
+    end
   end
 
   # Base class for all Sinatra applications and middleware.
@@ -368,13 +393,16 @@ module Sinatra
       self.class
     end
 
-    # Exit the current block and halt the response.
+    # Exit the current block, halts any further processing
+    # of the request, and returns the specified response.
     def 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
@@ -392,7 +420,13 @@ module Sinatra
   private
     # Run before filters and then locate and run a matching route.
     def route!
-      @params = nested_params(@request.params)
+      # enable nested params in Rack < 1.0; allow indifferent access
+      @params =
+        if Rack::Utils.respond_to?(:parse_nested_query)
+          indifferent_params(@request.params)
+        else
+          nested_params(@request.params)
+        end
 
       # before filters
       self.class.filters.each { |block| instance_eval(&block) }
@@ -426,14 +460,26 @@ module Sinatra
             catch(:pass) do
               conditions.each { |cond|
                 throw :pass if instance_eval(&cond) == false }
-              throw :halt, instance_eval(&block)
+              route_eval(&block)
             end
           end
         end
       end
 
-      # No matching route found or all routes passed -- forward downstream
-      # when running as middleware; 404 when running as normal app.
+      route_missing
+    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
@@ -441,6 +487,18 @@ module Sinatra
       end
     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
+
+    # Recursively replace the params hash with a nested indifferent
+    # hash. Rack 1.0 has a built in implementation of this method - remove
+    # this once Rack 1.0 is required.
     def nested_params(params)
       return indifferent_hash.merge(params) if !params.keys.join.include?('[')
       params.inject indifferent_hash do |res, (key,val)|
@@ -512,7 +570,7 @@ module Sinatra
       @env['sinatra.error'] = boom
 
       dump_errors!(boom) if options.dump_errors?
-      raise boom         if options.raise_errors?
+      raise boom         if options.raise_errors? || options.show_exceptions?
 
       @response.status = 500
       error_block! boom.class, Exception
@@ -553,12 +611,14 @@ module Sinatra
     @middleware = []
     @errors     = {}
     @prototype  = nil
+    @extensions = []
 
     class << self
       attr_accessor :routes, :filters, :conditions, :templates,
         :middleware, :errors
 
-    public
+      # 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)
@@ -574,14 +634,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) }
@@ -590,29 +655,38 @@ 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!
-        ignore = [/lib\/sinatra.*\.rb/, /\(.*\)/, /rubygems\/custom_require\.rb/]
-        file = caller.
-          map  { |line| line.sub(/:\d+.*$/, '') }.
-          find { |line| ignore.all? { |pattern| line !~ pattern } }
-        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
+        app, data =
+          ::IO.read(file).split(/^__END__$/, 2) rescue nil
+
+        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
@@ -627,10 +701,15 @@ 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
@@ -650,8 +729,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)}
 
@@ -667,6 +747,8 @@ module Sinatra
       end
 
     public
+      # Defining a `GET` handler also automatically defines
+      # a `HEAD` handler.
       def get(path, opts={}, &block)
         conditions = @conditions.dup
         route('GET', path, opts, &block)
@@ -675,16 +757,17 @@ module Sinatra
         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(verb, 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, []
@@ -698,16 +781,22 @@ module Sinatra
             lambda { unbound_method.bind(self).call }
           end
 
+        invoke_hook(:route_added, verb, path, block)
+
         (routes[verb] ||= []).
           push([pattern, keys, conditions, block]).last
       end
 
+      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 =
-            path.gsub(/((:\w+)|[\*#{special_chars.join}])/) do |match|
+            path.to_str.gsub(/((:\w+)|[\*#{special_chars.join}])/) do |match|
               case match
               when "*"
                 keys << 'splat'
@@ -720,6 +809,8 @@ module Sinatra
               end
             end
           [/^#{pattern}$/, keys]
+        elsif path.respond_to?(:keys) && path.respond_to?(:match)
+          [path, path.keys]
         elsif path.respond_to? :match
           [path, keys]
         else
@@ -728,33 +819,44 @@ module Sinatra
       end
 
     public
+      # 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?
+        include(*extensions) if extensions.any?
+      end
+
+      def extensions
+        (@extensions + (superclass.extensions rescue [])).uniq
       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 test? ; environment == :test ; end
-      def production? ; environment == :production ; 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)
-        return if reloading?
-        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)
         @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      = detect_rack_handler
@@ -783,30 +885,17 @@ module Sinatra
       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?
-        @middleware.each { |c, args, bk| builder.use(c, *args, &bk) }
+        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 call(env)
-        synchronize do
-          reload! if reload?
-          prototype.call(env)
-        end
-      end
-
-      def reloading?
-        @reloading
-      end
-
-      def reload!
-        @reloading = true
-        reset!
-        $LOADED_FEATURES.delete("sinatra.rb")
-        ::Kernel.load app_file
-        @reloading = false
+        synchronize { prototype.call(env) }
       end
 
       def reset!(base=superclass)
@@ -817,6 +906,7 @@ module Sinatra
         @errors     = base.errors.dup
         @middleware = base.middleware.dup
         @prototype  = nil
+        @extensions = []
       end
 
     protected
@@ -832,7 +922,7 @@ module Sinatra
         servers = Array(self.server)
         servers.each do |server_name|
           begin
-            return Rack::Handler.get(server_name)
+            return Rack::Handler.get(server_name.capitalize)
           rescue LoadError
           rescue NameError
           end
@@ -858,11 +948,36 @@ module Sinatra
         (class << self; self; end).
           send :define_method, message, &block
       end
+
+    public
+      CALLERS_TO_IGNORE = [
+        /lib\/sinatra.*\.rb$/, # all sinatra code
+        /\(.*\)/,              # generated code
+        /custom_require\.rb$/, # rubygems require hacks
+        /active_support/,      # active_support require hacks
+      ] unless self.const_defined?('CALLERS_TO_IGNORE')
+
+      # 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
 
     set :raise_errors, true
     set :dump_errors, false
     set :clean_trace, true
+    set :show_exceptions, Proc.new { development? }
     set :sessions, false
     set :logging, false
     set :methodoverride, false
@@ -878,8 +993,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') }
-    set :reload, Proc.new { app_file? && app_file !~ /\.ru$/i && development? }
-    set :lock, Proc.new { reload? }
+    set :lock, false
 
     # static files route
     get(/.*[^\/]$/) do
@@ -905,6 +1019,8 @@ module Sinatra
       end
 
       error NotFound do
+        content_type 'text/html'
+
         (<<-HTML).gsub(/^ {8}/, '')
         <!DOCTYPE html>
         <html>
@@ -926,35 +1042,6 @@ 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>#{escape_html(clean_backtrace(err.backtrace) * "\n")}</pre>
-            <h2>Params</h2>
-            <pre>#{escape_html(params.inspect)}</pre>
-          </div>
-        </body>
-        </html>
-        HTML
-      end
     end
   end
 
@@ -970,7 +1057,7 @@ module Sinatra
 
     def self.register(*extensions, &block) #:nodoc:
       added_methods = extensions.map {|m| m.public_instance_methods }.flatten
-      Delegator.delegate *added_methods
+      Delegator.delegate(*added_methods)
       super(*extensions, &block)
     end
   end
@@ -980,14 +1067,17 @@ module Sinatra
   class Application < Default
   end
 
+  # 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.#{method_name}(*args, &b)
+            ::Sinatra::Application.send(#{method_name.inspect}, *args, &b)
           end
-          private :#{method_name}
+          private #{method_name.inspect}
         RUBY
       end
     end
@@ -998,6 +1088,8 @@ module Sinatra
              :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?