adamwiggins-sinatra 0.8.9 → 0.10.1

data/AUTHORS

@@ -1,13 +1,13 @@
 Sinatra was designed and developed by Blake Mizerany (bmizerany) in
 California. Continued development would not be possible without the ongoing
-financial support provided by Heroku <heroku.com> and the emotional support
-provided by Adam Wiggins (adamwiggins), Chris Wanstrath (defunkt), PJ Hyett (pjhyett), and
-the rest of the Github crew.
+financial support provided by [Heroku](http://heroku.com) and the emotional
+support provided by Adam Wiggins (adamwiggins) of Heroku, Chris Wanstrath (defunkt),
+PJ Hyett (pjhyett), and the rest of the GitHub crew.
 
 Special thanks to the following extraordinary individuals, who-out which
 Sinatra would not be possible:
 
-* Ryan Tomayko (rtomayko) for constantly fixing whitespace errors 60d5006
+* Ryan Tomayko (rtomayko) for constantly fixing whitespace errors 60d5006   
 * Ezra Zygmuntowicz (ezmobius) for initial help and letting Blake steal
   some of merbs internal code.
 * Christopher Schneid (cschneid) for The Book, the blog (gittr.com),
@@ -16,7 +16,7 @@ Sinatra would not be possible:
   the README, and hanging in there when times were rough.
 * Simon Rozet (sr) for a ton of doc patches, HAML options, and all that
   advocacy stuff he's going to do for 1.0.
-* Erik Kastner (kastner) for fixing MIME_TYPES under Rack 0.5.
+* Erik Kastner (kastner) for fixing `MIME_TYPES` under Rack 0.5.
 * Ben Bleything (bleything) for caring about HTTP status codes and doc fixes.
 * Igal Koshevoy (igal) for root path detection under Thin/Passenger.
 * Jon Crosby (jcrosby) for coffee breaks, doc fixes, and just because, man.
@@ -27,12 +27,13 @@ Sinatra would not be possible:
 * Victor Hugo Borja (vic) for splat'n routes specs and doco.
 * Avdi Grimm (avdi) for basic RSpec support.
 * Jack Danger Canty for a more accurate root directory and for making me
-  watch this just now: http://www.youtube.com/watch?v=ueaHLHgskkw.
+  watch [this](http://www.youtube.com/watch?v=ueaHLHgskkw) just now.
 * Mathew Walker for making escaped paths work with static files.
 * Millions of Us for having the problem that led to Sinatra's conception.
 * Songbird for the problems that helped Sinatra's future become realized.
-* Rick Olsen (technoweenie) for the killer plug at RailsConf '08.
+* Rick Olson (technoweenie) for the killer plug at RailsConf '08.
 * Steven Garcia for the amazing custom artwork you see on 404's and 500's
+* Pat Nakajima (nakajima) for fixing non-nested params in nested params Hash's.
 
 and last but not least:
 

data/CHANGES

@@ -1,4 +1,192 @@
-= 0.9.0 (unreleased)
+= 1.0 / unreleased
+
+ * 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.
+
+= 0.9.2 / 2009-05-18
+
+ * 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
+   route. See [#177] for more info.
+
+= 0.9.1 / 2009-03-01
+
+ * Sinatra now runs under Ruby 1.9.1 [#61]
+
+ * Route patterns (splats, :named, or Regexp captures) are now
+   passed as arguments to the block. [#140]
+
+ * The "helpers" method now takes a variable number of modules
+   along with the normal block syntax. [#133]
+
+ * New request-level #forward method for middleware components: passes
+   the env to the downstream app and merges the response status, headers,
+   and body into the current context. [#126]
+
+ * Requests are now automatically forwarded to the downstream app when
+   running as middleware and no matching route is found or all routes
+   pass.
+
+ * New simple API for extensions/plugins to add DSL-level and
+   request-level methods. Use Sinatra.register(mixin) to extend
+   the DSL with all public methods defined in the mixin module;
+   use Sinatra.helpers(mixin) to make all public methods defined
+   in the mixin module available at the request level. [#138]
+   See http://www.sinatrarb.com/extensions.html for details.
+
+ * Named parameters in routes now capture the "." character. This makes
+   routes like "/:path/:filename" match against requests like
+   "/foo/bar.txt"; in this case, "params[:filename]" is "bar.txt".
+   Previously, the route would not match at all.
+
+ * Added request-level "redirect back" to redirect to the referring
+   URL.
+
+ * Added a new "clean_trace" option that causes backtraces dumped
+   to rack.errors and displayed on the development error page to
+   omit framework and core library backtrace lines. The option is
+   enabled by default. [#77]
+
+ * The ERB output buffer is now available to helpers via the @_out_buf
+   instance variable.
+
+ * It's now much easier to test sessions in unit tests by passing a
+   ":session" option to any of the mock request methods. e.g.,
+       get '/', {}, :session => { 'foo' => 'bar' }
+
+ * The testing framework specific files ('sinatra/test/spec',
+   'sinatra/test/bacon', 'sinatra/test/rspec', etc.) have been deprecated.
+   See http://sinatrarb.com/testing.html for instructions on setting up
+   a testing environment with these frameworks.
+
+ * The request-level #send_data method from Sinatra 0.3.3 has been added
+   for compatibility but is deprecated.
+
+ * Fix :provides causing crash on any request when request has no
+   Accept header [#139]
+
+ * Fix that ERB templates were evaluated twice per "erb" call.
+
+ * Fix app-level middleware not being run when the Sinatra application is
+   run as middleware.
+
+ * Fixed some issues with running under Rack's CGI handler caused by
+   writing informational stuff to stdout.
+
+ * Fixed that reloading was sometimes enabled when starting from a
+   rackup file [#110]
+
+ * Fixed that "." in route patterns erroneously matched any character
+   instead of a literal ".". [#124]
+
+= 0.9.0.4 / 2009-01-25
+
+ * Using halt with more than 1 args causes ArgumentError [#131]
+ * using halt in a before filter doesn't modify response [#127]
+ * Add deprecated Sinatra::EventContext to unbreak plugins [#130]
+ * Give access to GET/POST params in filters [#129]
+ * Preserve non-nested params in nested params hash [#117]
+ * Fix backtrace dump with Rack::Lint [#116]
+
+= 0.9.0.3 / 2009-01-21
+
+ * Fall back on mongrel then webrick when thin not found. [#75]
+ * Use :environment instead of :env in test helpers to
+   fix deprecation warnings coming from framework.
+ * Make sinatra/test/rspec work again [#113]
+ * Fix app_file detection on windows [#118]
+ * Fix static files with Rack::Lint in pipeline [#121]
+
+= 0.9.0.2 / 2009-01-18
+
+ * Halting a before block should stop processing of routes [#85]
+ * Fix redirect/halt in before filters [#85]
+
+= 0.9.0 / 2009-01-18
 
  * Works with and requires Rack >= 0.9.1
 
@@ -8,6 +196,10 @@
    Documentation on using these features is forth-coming; the following
    provides the basic gist: http://gist.github.com/38605
 
+ * Parameters with subscripts are now parsed into a nested/recursive
+   Hash structure. e.g., "post[title]=Hello&post[body]=World" yields
+   params: {'post' => {'title' => 'Hello', 'body' => 'World'}}.
+
  * Regular expressions may now be used in route pattens; captures are
    available at "params[:captures]".
 
@@ -41,6 +233,20 @@
    has the status code specified. It's also possible to register an error
    page for a range of status codes: "error(500..599)".
 
+ * In-file templates are now automatically imported from the file that
+   requires 'sinatra'. The use_in_file_templates! method is still available
+   for loading templates from other files.
+
+ * Sinatra's testing support is no longer dependent on Test::Unit. Requiring
+   'sinatra/test' adds the Sinatra::Test module and Sinatra::TestHarness
+   class, which can be used with any test framework. The 'sinatra/test/unit',
+   'sinatra/test/spec', 'sinatra/test/rspec', or 'sinatra/test/bacon' files
+   can be required to setup a framework-specific testing environment. See the
+   README for more information.
+
+ * Added support for Bacon (test framework). The 'sinatra/test/bacon' file
+   can be required to setup Sinatra test helpers on Bacon::Context.
+
  * Deprecated "set_option" and "set_options"; use "set" instead.
 
  * Deprecated the "env" option ("options.env"); use "environment" instead.
@@ -65,6 +271,10 @@
    treated as internal server errors and result in a 500 response
    status.
 
+ * Deprecated the "get_it", "post_it", "put_it", "delete_it", and "head_it"
+   test helper methods. Use "get", "post", "put", "delete", and "head",
+   respectively, instead.
+
  * Removed Event and EventContext classes. Applications are defined in a
    subclass of Sinatra::Base; each request is processed within an
    instance.

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

@@ -1,6 +1,6 @@
 = Sinatra
 
-Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
+Sinatra is a DSL for quickly creating web applications in Ruby with minimal
 effort:
 
   # myapp.rb
@@ -10,12 +10,20 @@ effort:
     'Hello world!'
   end
 
-Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
+Install the gem and run with:
 
-== HTTP Methods
+  sudo gem install sinatra
+  ruby myapp.rb
+
+View at: http://localhost:4567
+
+== Routes
+
+In Sinatra, a route is an HTTP method paired with an URL matching pattern.
+Each route is associated with a block:
 
   get '/' do
-    .. show things ..
+    .. show something ..
   end
 
   post '/' do
@@ -30,26 +38,24 @@ Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
     .. annihilate something ..
   end
 
-== Routes
-
-Routes are matched based on the order of declaration. The first route that
+Routes are matched in the order they are defined. The first route that
 matches the request is invoked.
 
-Basic routes:
-
-  get '/hi' do
-    ...
-  end
-
 Route patterns may include named parameters, accessible via the
 <tt>params</tt> hash:
 
-  get '/:name' do
-    # matches "GET /foo" and "GET /bar"
+  get '/hello/:name' do
+    # matches "GET /hello/foo" and "GET /hello/bar"
     # params[:name] is 'foo' or 'bar'
     "Hello #{params[:name]}!"
   end
 
+You can also access named parameters via block parameters:
+
+  get '/hello/:name' do |n|
+    "Hello #{n}!"
+  end
+
 Route patterns may also include splat (or wildcard) parameters, accessible
 via the <tt>params[:splat]</tt> array.
 
@@ -69,6 +75,12 @@ Route matching with Regular Expressions:
     "Hello, #{params[:captures].first}!"
   end
 
+Or with a block parameter:
+
+  get %r{/hello/([\w]+)} do |c|
+    "Hello, #{c}!"
+  end
+
 Routes may include a variety of matching conditions, such as the user agent:
 
   get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
@@ -86,25 +98,52 @@ a different location by setting the <tt>:public</tt> option:
 
   set :public, File.dirname(__FILE__) + '/static'
 
+Note that the public directory name is not included in the URL. A file
+<tt>./public/css/style.css</tt> is made available as
+<tt>http://example.com/css/style.css</tt>.
+
 == Views / Templates
 
-Templates are assumed to be located directly under a <tt>./views</tt>
+Templates are assumed to be located directly under the <tt>./views</tt>
 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
@@ -115,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
@@ -126,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
@@ -133,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
@@ -141,10 +199,10 @@ Renders <tt>./views/stylesheet.sass</tt>.
 
 Renders the inlined template string.
 
-=== Accessing Variables
+=== Accessing Variables in Templates
 
-Templates are evaluated within the same context as the route blocks. Instance
-variables set in route blocks are available in templates:
+Templates are evaluated within the same context as route handlers. Instance
+variables set in route handlers are direcly accessible by templates:
 
   get '/:id' do
     @foo = Foo.find(params[:id])
@@ -165,12 +223,13 @@ other templates.
 
 Templates may be defined at the end of the source file:
 
+  require 'rubygems'
+  require 'sinatra'
+
   get '/' do
     haml :index
   end
 
-  use_in_file_templates!
-
   __END__
 
   @@ layout
@@ -180,8 +239,13 @@ Templates may be defined at the end of the source file:
   @@ index
   %div.title Hello world!!!!!
 
-It's also possible to define named templates using the top-level template
-method:
+NOTE: In-file templates defined in the source file that requires sinatra
+are automatically loaded. Call the <tt>use_in_file_templates!</tt>
+method explicitly if you have in-file templates in other source files.
+
+=== Named Templates
+
+Templates may also be defined using the top-level <tt>template</tt> method:
 
   template :layout do
     "%html\n  =yield\n"
@@ -205,7 +269,7 @@ is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
 == Helpers
 
 Use the top-level <tt>helpers</tt> method to define helper methods for use in
-route blocks and templates:
+route handlers and templates:
 
   helpers do
     def bar(name)
@@ -221,7 +285,7 @@ route blocks and templates:
 
 Before filters are evaluated before each request within the context of the
 request and can modify the request and response. Instance variables set in
-filters are accessible by routes and templates.
+filters are accessible by routes and templates:
 
   before do
     @note = 'Hi!'
@@ -243,14 +307,13 @@ You can also specify a body when halting ...
 
   halt 'this will be the body'
 
-Set the status and body ...
+Or set the status and body ...
 
   halt 401, 'go away!'
 
 == Passing
 
-A route can punt processing to the next matching route using the <tt>pass</tt>
-statement:
+A route can punt processing to the next matching route using <tt>pass</tt>:
 
   get '/guess/:who' do
     pass unless params[:who] == 'Frank'
@@ -264,13 +327,7 @@ statement:
 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:
 
@@ -279,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
     ...
@@ -311,7 +368,7 @@ code is 404, the <tt>not_found</tt> handler is invoked:
 
 The +error+ handler is invoked any time an exception is raised from a route
 block or before filter. The exception object can be obtained from the
-'sinatra.error' Rack variable:
+<tt>sinatra.error</tt> Rack variable:
 
   error do
     'Sorry there was a nasty error - ' + env['sinatra.error'].name
@@ -333,8 +390,8 @@ You get this:
 
   So what happened was... something bad
 
-Sinatra installs special not_found and error handlers when running under
-the development environment.
+Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
+running under the development environment.
 
 == Mime types
 
@@ -380,150 +437,137 @@ typically don't have to +use+ them explicitly.
 
 == Testing
 
-=== Test/Unit
+Sinatra tests can be written using any Rack-based testing library
+or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
+recommended:
 
-  require 'rubygems'
-  require 'sinatra'
-  require 'sinatra/test/unit'
   require 'my_sinatra_app'
+  require 'rack/test'
 
   class MyAppTest < Test::Unit::TestCase
+    include Rack::Test::Methods
 
-    def test_my_default
-      get_it '/'
-      assert_equal 'My Default Page!', @response.body
+    def app
+      Sinatra::Application
     end
 
-    def test_with_agent
-      get_it '/', :agent => 'Songbird'
-      assert_equal 'You're in Songbird!', @response.body
+    def test_my_default
+      get '/'
+      assert_equal 'Hello World!', last_response.body
     end
 
-    ...
+    def test_with_params
+      get '/meet', :name => 'Frank'
+      assert_equal 'Hello Frank!', last_response.body
+    end
 
+    def test_with_rack_env
+      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
+      assert_equal "You're using Songbird!", last_response.body
+    end
   end
 
-=== Test/Spec
+NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
+are deprecated as of the 0.9.2 release.
 
-  require 'rubygems'
-  require 'sinatra'
-  require 'sinatra/test/spec'
-  require 'my_sinatra_app'
+== Sinatra::Base - Middleware, Libraries, and Modular Apps
 
-  describe 'My app' do
+Defining your app at the top-level works well for micro-apps but has
+considerable drawbacks when building reuseable components such as Rack
+middleware, Rails metal, simple libraries with a server component, or
+even Sinatra extensions. The top-level DSL pollutes the Object namespace
+and assumes a micro-app style configuration (e.g., a single application
+file, ./public and ./views directories, logging, exception detail page,
+etc.). That's where Sinatra::Base comes into play:
 
-    it "should show a default page" do
-      get_it '/'
-      should.be.ok
-      body.should.equal 'My Default Page!'
-    end
+  require 'sinatra/base'
 
-    ...
+  class MyApp < Sinatra::Base
+    set :sessions, true
+    set :foo, 'bar'
 
+    get '/' do
+      'Hello world!'
+    end
   end
 
-=== RSpec
+The MyApp class is an independent Rack component that can act as
+Rack middleware, a Rack application, or Rails metal. You can +use+ or
++run+ this class from a rackup +config.ru+ file; or, control a server
+component shipped as a library:
 
-  require 'rubygems'
-  require 'spec'
-  require 'sinatra'
-  require 'sinatra/test/rspec'
-  require 'my_sinatra_app'
+   MyApp.run! :host => 'localhost', :port => 9090
 
-  describe 'My app' do
-    it 'should show a default page' do
-      get_it '/'
-      @response.should be_ok
-      @response.body.should == 'My Default Page!'
-    end
+The methods available to Sinatra::Base subclasses are exactly as those
+available via the top-level DSL. Most top-level apps can be converted to
+Sinatra::Base components with two modifications:
 
-    ...
+* Your file should require +sinatra/base+  instead of +sinatra+;
+  otherwise, all of Sinatra's DSL methods are imported into the main
+  namespace.
+* Put your app's routes, error handlers, filters, and options in a subclass
+  of Sinatra::Base.
 
-  end
++Sinatra::Base+ is a blank slate. Most options are disabled by default,
+including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
+for details on available options and their behavior.
 
-See Sinatra::Test::Methods for more information on +get_it+, +post_it+,
-+put_it+, and friends.
+SIDEBAR: Sinatra's top-level DSL is implemented using a simple delegation
+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].
 
 == Command line
 
 Sinatra applications can be run directly:
 
-  ruby myapp.rb [-h] [-x] [-p PORT] [-e ENVIRONMENT]
+  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-s HANDLER]
 
 Options are:
 
   -h # help
   -p # set the port (default is 4567)
   -e # set the environment (default is development)
+  -s # specify rack server/handler (default is thin)
   -x # turn on the mutex lock (default is off)
 
-== Contributing
-
-=== Tools
-
-Besides Ruby itself, you only need a text editor, preferably one that supports
-Ruby syntax hilighting. VIM and Emacs are a fine choice on any platform, but
-feel free to use whatever you're familiar with.
-
-Sinatra uses the Git source code management system. If you're unfamiliar with
-Git, you can find more information and tutorials on http://git.or.cz/ as well
-as http://git-scm.com/.  Scott Chacon created a great series of introductory
-screencasts about Git, which you can find here: http://www.gitcasts.com/
+== The Bleeding Edge
 
-=== First Time: Cloning The Sinatra Repo
+If you would like to use Sinatra's latest bleeding code, create a local
+clone and run your app with the <tt>sinatra/lib</tt> directory on the
+<tt>LOAD_PATH</tt>:
 
-  cd where/you/keep/your/projects
-  git clone git://github.com/bmizerany/sinatra.git
-  cd sinatra
-  cd path/to/your_project
-  ln -s ../sinatra/
+  cd myapp
+  git clone git://github.com/sinatra/sinatra.git
+  ruby -Isinatra/lib myapp.rb
 
-=== Updating Your Existing Sinatra Clone
-
-  cd where/you/keep/sinatra
-  git pull
-
-=== Using Edge Sinatra in Your App
-
-at the top of your sinatra_app.rb file:
+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'
+  require 'rubygems'
   require 'sinatra'
 
   get '/about' do
-    "I'm running on Version " + Sinatra::VERSION
+    "I'm running version " + Sinatra::VERSION
   end
 
-=== Contributing a Patch
+To update the Sinatra sources in the future:
 
-There are several ways to do this. Probably the easiest (and preferred) way is
-to fork Sinatra on GitHub (http://github.com/bmizerany/sinatra), push your
-changes to your Sinatra repo, and then send Blake Mizerany (bmizerany on
-GitHub) a pull request.
-
-You can also create a patch file and attach it to a feature request or bug fix
-on the issue tracker (see below) or send it to the mailing list (see Community
-section).
-
-=== Issue Tracking and Feature Requests
-
-http://sinatra.lighthouseapp.com/
-
-== Community
-
-=== Mailing List
-
-http://groups.google.com/group/sinatrarb
-
-If you have a problem or question, please make sure to include all the
-relevant information in your mail, like the Sinatra version you're using, what
-version of Ruby you have, and so on.
-
-=== IRC Channel
-
-You can find us on the Freenode network in the channel #sinatra
-(irc://chat.freenode.net/#sinatra)
+  cd myproject/sinatra
+  git pull
 
-There's usually someone online at any given time, but we cannot pay attention
-to the channel all the time, so please stick around for a while after asking a
-question.
+== More
+
+* {Project Website}[http://sinatra.github.com/] - Additional documentation,
+  news, and links to other resources.
+* {Contributing}[http://sinatra.github.com/contributing.html] - 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]
+* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net