sinatra 1.1.4 → 1.2.0

data/README.rdoc

@@ -17,9 +17,12 @@ Install the gem and run with:
 
 View at: http://localhost:4567
 
+It is recommended to also run <tt>gem install thin</tt>, which Sinatra will
+pick up if available.
+
 == Routes
 
-In Sinatra, a route is an HTTP method paired with an URL matching pattern.
+In Sinatra, a route is an HTTP method paired with a URL-matching pattern.
 Each route is associated with a block:
 
   get '/' do
@@ -37,6 +40,10 @@ Each route is associated with a block:
   delete '/' do
     .. annihilate something ..
   end
+  
+  options '/' do
+    .. appease something ..
+  end
 
 Routes are matched in the order they are defined. The first route that
 matches the request is invoked.
@@ -123,7 +130,7 @@ You can easily define your own conditions:
 
 The return value of a route block determines at least the response body passed
 on to the HTTP client, or at least the next middleware in the Rack stack.
-Most commonly this is a string, as in the above examples. But other values are
+Most commonly, this is a string, as in the above examples. But other values are
 also accepted.
 
 You can return any object that would either be a valid Rack response, Rack
@@ -134,7 +141,7 @@ body object or HTTP status code:
 * An object that responds to <tt>#each</tt> and passes nothing but strings to the given block
 * A Fixnum representing the status code
 
-That way we can for instance easily implement a streaming example:
+That way we can, for instance, easily implement a streaming example:
 
     class Stream
       def each
@@ -144,6 +151,47 @@ That way we can for instance easily implement a streaming example:
 
     get('/') { Stream.new }
 
+=== Custom Route Matchers
+
+As shown above, Sinatra ships with built-in support for using String patterns
+and regular expressions as route matches. However, it does not stop there. You
+can easily define your own matchers:
+
+  class AllButPattern
+    Match = Struct.new(:captures)
+
+    def initialize(except)
+      @except   = except
+      @caputres = Match.new([])
+    end
+
+    def match(str)
+      @caputres unless @except === str
+    end
+  end
+
+  def all_but(pattern)
+    AllButPattern.new(pattern)
+  end
+
+  get all_but("/index") do
+    # ...
+  end
+
+Note that the above example might be over-engineered, as it can also be
+expressed as:
+
+  get // do
+    pass if request.path_info == "/index"
+    # ...
+  end
+
+Or, using negative look ahead:
+
+  get %r{^(?!/index$)} do
+    # ...
+  end
+
 == Static Files
 
 Static files are served from the <tt>./public</tt> directory. You can specify
@@ -164,15 +212,15 @@ directory. To use a different views directory:
 
 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>). You must use a symbol because 
-otherwise rendering methods will render any strings passed to them 
+case, use <tt>:'subdir/template'</tt>). You must use a symbol because
+otherwise rendering methods will render any strings passed to them
 directly.
 
 === Haml Templates
 
 The <tt>haml</tt> gem/library is required to render HAML templates:
 
-  ## You'll need to require haml in your app
+  # You'll need to require haml in your app
   require 'haml'
 
   get '/' do
@@ -195,7 +243,7 @@ and overridden on an individual basis.
 
 === Erb Templates
 
-  ## You'll need to require erb in your app
+  # You'll need to require erb in your app
   require 'erb'
 
   get '/' do
@@ -208,7 +256,7 @@ Renders <tt>./views/index.erb</tt>.
 
 The <tt>erubis</tt> gem/library is required to render Erubis templates:
 
-  ## You'll need to require erubis in your app
+  # You'll need to require erubis in your app
   require 'erubis'
 
   get '/' do
@@ -232,7 +280,7 @@ Renders <tt>./views/index.erb</tt> with Erubis.
 
 The <tt>builder</tt> gem/library is required to render builder templates:
 
-  ## You'll need to require builder in your app
+  # You'll need to require builder in your app
   require 'builder'
 
   get '/' do
@@ -245,7 +293,7 @@ Renders <tt>./views/index.builder</tt>.
 
 The <tt>nokogiri</tt> gem/library is required to render nokogiri templates:
 
-  ## You'll need to require nokogiri in your app
+  # You'll need to require nokogiri in your app
   require 'nokogiri'
 
   get '/' do
@@ -258,7 +306,7 @@ Renders <tt>./views/index.nokogiri</tt>.
 
 The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Sass templates:
 
-  ## You'll need to require haml or sass in your app
+  # You'll need to require haml or sass in your app
   require 'sass'
 
   get '/stylesheet.css' do
@@ -267,7 +315,7 @@ The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Sass templa
 
 Renders <tt>./views/stylesheet.sass</tt>.
 
-{Sass' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
+{Sass's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
 can be set globally through Sinatra's configurations,
 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
 and overridden on an individual basis.
@@ -282,7 +330,7 @@ and overridden on an individual basis.
 
 The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Scss templates:
 
-  ## You'll need to require haml or sass in your app
+  # You'll need to require haml or sass in your app
   require 'sass'
 
   get '/stylesheet.css' do
@@ -291,7 +339,7 @@ The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Scss templa
 
 Renders <tt>./views/stylesheet.scss</tt>.
 
-{Scss' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
+{Scss's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
 can be set globally through Sinatra's configurations,
 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
 and overridden on an individual basis.
@@ -306,7 +354,7 @@ and overridden on an individual basis.
 
 The <tt>less</tt> gem/library is required to render Less templates:
 
-  ## You'll need to require less in your app
+  # You'll need to require less in your app
   require 'less'
 
   get '/stylesheet.css' do
@@ -319,7 +367,7 @@ Renders <tt>./views/stylesheet.less</tt>.
 
 The <tt>liquid</tt> gem/library is required to render Liquid templates:
 
-  ## You'll need to require liquid in your app
+  # You'll need to require liquid in your app
   require 'liquid'
 
   get '/' do
@@ -337,7 +385,7 @@ template, you almost always want to pass locals to it:
 
 The <tt>rdiscount</tt> gem/library is required to render Markdown templates:
 
-  ## You'll need to require rdiscount in your app
+  # You'll need to require rdiscount in your app
   require "rdiscount"
   
   get '/' do
@@ -358,6 +406,28 @@ Note that you may also call the +markdown+ method from within other templates:
   %h1 Hello From Haml!
   %p= markdown(:greetings)
 
+Since you cannot call Ruby from Markdown, you cannot use layouts written in
+Markdown. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    markdown :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.md</tt> with <tt>./views/layout.erb</tt> as
+layout.
+
+Remember that you can set such rendering options globally:
+
+  set :markdown, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    markdown :index
+  end
+
+This will render <tt>./views/index.md</tt> (and any other Markdown template)
+with <tt>./views/post.haml</tt> as layout.
+
 It is also possible to parse Markdown with BlueCloth rather than RDiscount:
 
   require 'bluecloth'
@@ -376,7 +446,7 @@ Renders <tt>./views/index.md</tt> with BlueCloth.
 
 The <tt>RedCloth</tt> gem/library is required to render Textile templates:
 
-  ## You'll need to require redcloth in your app
+  # You'll need to require redcloth in your app
   require "redcloth"
 
   get '/' do
@@ -395,12 +465,34 @@ Note that you may also call the +textile+ method from within other templates:
   %h1 Hello From Haml!
   %p= textile(:greetings)
 
+Since you cannot call Ruby from Textile, you cannot use layouts written in
+Textile. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    textile :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.textile</tt> with
+<tt>./views/layout.erb</tt> as layout.
+
+Remember that you can set such rendering options globally:
+
+  set :textile, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    textile :index
+  end
+
+This will render <tt>./views/index.textile</tt> (and any other Textile
+template) with <tt>./views/post.haml</tt> as layout.
+
 === RDoc Templates
 
 The <tt>rdoc</tt> gem/library is required to render RDoc templates:
 
-  ## You'll need to require rdoc in your app
-  require "rdoc"
+  # You'll need to require rdoc/markup/to_html in your app
+  require "rdoc/markup/to_html"
 
   get '/' do
     rdoc :index
@@ -418,11 +510,33 @@ Note that you may also call the +rdoc+ method from within other templates:
   %h1 Hello From Haml!
   %p= rdoc(:greetings)
 
+Since you cannot call Ruby from RDoc, you cannot use layouts written in
+RDoc. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    rdoc :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.rdoc</tt> with <tt>./views/layout.erb</tt> as
+layout.
+
+Remember that you can set such rendering options globally:
+
+  set :rdoc, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    rdoc :index
+  end
+
+This will render <tt>./views/index.rdoc</tt> (and any other RDoc template)
+with <tt>./views/post.haml</tt> as layout.
+
 === Radius Templates
 
 The <tt>radius</tt> gem/library is required to render Radius templates:
 
-  ## You'll need to require radius in your app
+  # You'll need to require radius in your app
   require 'radius'
 
   get '/' do
@@ -440,7 +554,7 @@ template, you almost always want to pass locals to it:
 
 The <tt>markaby</tt> gem/library is required to render Markaby templates:
 
-  ## You'll need to require markaby in your app
+  # You'll need to require markaby in your app
   require 'markaby'
 
   get '/' do
@@ -449,6 +563,25 @@ The <tt>markaby</tt> gem/library is required to render Markaby templates:
 
 Renders <tt>./views/index.mab</tt>.
 
+You may also use inline Markaby:
+
+  get '/' do
+    markaby { h1 "Welcome!" }
+  end
+
+=== Slim Templates
+
+The <tt>slim</tt> gem/library is required to render Slim templates:
+
+  # You'll need to require slim in your app
+  require 'slim'
+
+  get '/' do
+    slim :index
+  end
+
+Renders <tt>./views/index.slim</tt>.
+
 === CoffeeScript Templates
 
 The <tt>coffee-script</tt> gem/library and at least <b>one</b> of the
@@ -462,7 +595,7 @@ See http://github.com/josh/ruby-coffee-script for an updated list of options.
 
 Now you can render CoffeeScript templates:
 
-  ## You'll need to require coffee-script in your app
+  # You'll need to require coffee-script in your app
   require 'coffee-script'
 
   get '/application.js' do
@@ -482,7 +615,7 @@ Renders the embedded template string.
 === Accessing Variables in Templates
 
 Templates are evaluated within the same context as route handlers. Instance
-variables set in route handlers are direcly accessible by templates:
+variables set in route handlers are directly accessible by templates:
 
   get '/:id' do
     @foo = Foo.find(params[:id])
@@ -554,7 +687,7 @@ To associate a file extension with a template engine, use
 
   Tilt.register :tt, Tilt[:textile]
 
-=== Adding You Own Template Engine
+=== Adding Your Own Template Engine
 
 First, register your engine with Tilt, then create a rendering method:
 
@@ -571,26 +704,11 @@ First, register your engine with Tilt, then create a rendering method:
 Renders <tt>./views/index.myat</tt>. See https://github.com/rtomayko/tilt to
 learn more about Tilt.
 
-== Helpers
-
-Use the top-level <tt>helpers</tt> method to define helper methods for use in
-route handlers and templates:
-
-  helpers do
-    def bar(name)
-      "#{name}bar"
-    end
-  end
-
-  get '/:name' do
-    bar(params[:name])
-  end
-
 == Filters
 
-Before filters are evaluated before each request within the same context as
-the routes will be and can modify the request and response. Instance variables
-set in filters are accessible by routes and templates:
+Before filters are evaluated before each request within the same
+context as the routes will be and can modify the request and response. Instance
+variables set in filters are accessible by routes and templates:
 
   before do
     @note = 'Hi!'
@@ -602,7 +720,7 @@ set in filters are accessible by routes and templates:
     params[:splat] #=> 'bar/baz'
   end
 
-After filter are evaluated after each request within the same context and can
+After filters are evaluated after each request within the same context and can
 also modify the request and response. Instance variables set in before filters
 and routes are accessible by after filters:
 
@@ -610,11 +728,11 @@ and routes are accessible by after filters:
     puts response.status
   end
 
-Note: Unless you use the `body` method rather than just returning a String from
+Note: Unless you use the +body+ method rather than just returning a String from
 the routes, the body will not yet be available in the after filter, since it is
 generated later on.
 
-Filters optionally taking a pattern, causing them to be evaluated only if the
+Filters optionally take a pattern, causing them to be evaluated only if the
 request path matches that pattern:
 
   before '/protected/*' do
@@ -625,7 +743,63 @@ request path matches that pattern:
     session[:last_slug] = slug
   end
 
-== Halting
+Like routes, filters also take conditions:
+
+  before :agent => /Songbird/ do
+    # ...
+  end
+  
+  after '/blog/*', :host_name => 'example.com' do
+    # ...
+  end
+
+== Helpers
+
+Use the top-level <tt>helpers</tt> method to define helper methods for use in
+route handlers and templates:
+
+  helpers do
+    def bar(name)
+      "#{name}bar"
+    end
+  end
+
+  get '/:name' do
+    bar(params[:name])
+  end
+
+=== Using Sessions
+
+A session is used to keep state during requests. If activated, you have one
+session hash per user session:
+
+  enable :sessions
+
+  get '/' do
+    "value = " << session[:value].inspect
+  end
+
+  get '/:value' do
+    session[:value] = params[:value]
+  end
+
+Note that <tt>enable :sessions</tt> actually stores all data in a cookie. This
+might not always be what you want (storing lots of data will increase your
+traffic, for instance). You can use any Rack session middleware, in order to
+do so, do *not* call <tt>enable :sessions</tt>, but instead pull in your
+middleware of choice how you would any other middleware:
+
+  use Rack::Session::Pool, :expire_after => 2592000
+
+  get '/' do
+    "value = " << session[:value].inspect
+  end
+
+  get '/:value' do
+    session[:value] = params[:value]
+  end
+
+=== Halting
 
 To immediately stop a request within a filter or route use:
 
@@ -647,7 +821,11 @@ With headers:
 
   halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
 
-== Passing
+It is of course possible to combine a template with +halt+:
+
+  halt erb(:error)
+
+=== Passing
 
 A route can punt processing to the next matching route using <tt>pass</tt>:
 
@@ -663,9 +841,222 @@ 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.
 
-== Accessing the Request Object
+=== Triggering Another Route
+
+Sometimes +pass+ is not what you want, instead you would like to get the result
+of calling another route. Simply use +call+ to achieve this:
+
+  get '/foo' do
+    status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
+    [status, body.upcase]
+  end
+
+  get '/bar' do
+    "bar"
+  end
+
+Note that in the example above, you would ease testing and increase performance
+by simply moving <tt>"bar"</tt> into a helper used by both <tt>/foo</tt>
+and <tt>/bar</tt>.
+
+If you want the request to be sent to the same application instance rather than
+a duplicate, use <tt>call!</tt> instead of <tt>call</tt>.
+
+Check out the Rack specification if you want to learn more about <tt>call</tt>.
+
+=== Setting Body, Status Code and Headers
+
+It is possible and recommended to set the status code and response body with the
+return value of the route block. However, in some scenarios you might want to
+set the body at an arbitrary point in the execution flow. You can do so with the
++body+ helper method. If you do so, you can use that method from there on to
+access the body:
+
+  get '/foo' do
+    body "bar"
+  end
+  
+  after do
+    puts body
+  end
+
+It is also possible to pass a block to +body+, which will be executed by the Rack
+handler (this can be used to implement streaming, see "Return Values").
+
+Similar to the body, you can also set the status code and headers:
+
+  get '/foo' do
+    status 418
+    headers \
+      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN"
+      "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
+    body "I'm a tea pot!"
+  end
+
+Like +body+, +headers+ and +status+ with no arguments can be used to access
+their current values.
+
+=== Mime Types
+
+When using <tt>send_file</tt> or static files you may have mime types Sinatra
+doesn't understand. Use +mime_type+ to register them by file extension:
+
+  mime_type :foo, 'text/foo'
+
+You can also use it with the +content_type+ helper:
+
+  get '/' do
+    content_type :foo
+    "foo foo foo"
+  end
+
+=== Generating URLs
+
+For generating URLs you should use the +url+ helper method, for instance, in
+Haml:
+
+  %a{:href => url('/foo')} foo
+
+It takes reverse proxies and Rack routers into account, if present.
+
+This method is also aliased to +to+ (see below for an example).
+
+=== Browser Redirect
+
+You can trigger a browser redirect with the +redirect+ helper method:
+
+  get '/foo' do
+    redirect to('/bar')
+  end
+
+Any additional parameters are handled like arguments passed to +halt+:
+
+  redirect to('/bar'), 303
+  redirect 'http://google.com', 'wrong place, buddy'
+
+You can also easily redirect back to the page the user came from with
+<tt>redirect back</tt>:
+
+  get '/foo' do
+    "<a href='/bar'>do something</a>"
+  end
+
+  get '/bar' do
+    do_something
+    redirect back
+  end
+
+To pass arguments with a redirect, either add them to the query:
+
+  redirect to('/bar?sum=42')
+
+Or use a session:
+
+  enable :session
+  
+  get '/foo' do
+    session[:secret] = 'foo'
+    redirect to('/bar')
+  end
+  
+  get '/bar' do
+    session[:secret]
+  end
+
+=== Cache Control
+
+Setting your headers correctly is the foundation for proper HTTP caching.
+
+You can easily set the Cache-Control header with like this:
+
+  get '/' do
+    cache_control :public
+    "cache it!"
+  end
+
+Pro tip: Set up caching in a before filter.
+
+  before do
+    cache_control :public, :must_revalidate, :max_age => 60
+  end
+
+If you are using the +expires+ helper to set the corresponding header,
+<tt>Cache-Control</tt> will be set automatically for you:
+
+  before do
+    expires 500, :public, :must_revalidate
+  end
+
+To properly use caches, you should consider using +etag+ and +last_modified+.
+It is recommended to call those helpers *before* doing heavy lifting, as they
+will immediately flush a response if the client already has the current
+version in its cache.
+
+  get '/article/:id' do
+    @article = Article.find params[:id]
+    last_modified @article.updated_at
+    etag @article.sha1
+    erb :article
+  end
+
+It is also possible to use a
+{weak ETag}[http://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation]:
+
+  etag @article.sha1, :weak
+
+These helpers will not do any caching for you, but rather feed the necessary
+information to your cache. If you are looking for a quick caching solutions, try
+{rack-cache}[http://rtomayko.github.com/rack-cache/]:
+
+  require "rack/cache"
+  require "sinatra"
+  
+  use Rack::Cache
+  
+  get '/' do
+    cache_control :public, :max_age => 36000
+    sleep 5
+    "hello"
+  end
+
+=== Sending Files
+
+For sending files, you can use the <tt>send_file</tt> helper method:
+
+  get '/' do
+    send_file 'foo.png'
+  end
+
+It also takes a couple of options:
+
+  send_file 'foo.png', :type => :jpg
+
+The options are:
+
+[filename]
+  file name, in response, defaults to the real file name.
+
+[last_modified]
+  value for Last-Modified header, defaults to the file's mtime.
+
+[type]
+  content type to use, guessed from the file extension if missing.
+
+[disposition]
+  used for Content-Disposition, possible values: +nil+ (default),
+  <tt>:attachment</tt> and <tt>:inline</tt>
+
+[length]
+  Content-Length header, defaults to file size.
+
+If supported by the Rack handler, other means than streaming from the Ruby
+process will be used. If you use this helper method, Sinatra will automatically
+handle range requests.
+
+=== Accessing the Request Object
 
-The incoming request object can be accessed from request level (filter, routes, error handlers) through the `request` method:
+The incoming request object can be accessed from request level (filter, routes,
+error handlers) through the <tt>request</tt> method:
 
   # app running on http://example.com/example
   get '/foo' do
@@ -682,18 +1073,19 @@ The incoming request object can be accessed from request level (filter, routes,
     request.get?              # true (similar methods for other verbs)
     request.form_data?        # false
     request["SOME_HEADER"]    # value of SOME_HEADER header
-    request.referer           # the referer of the client or '/'
+    request.referrer          # the referrer of the client or '/'
     request.user_agent        # user agent (used by :agent condition)
     request.cookies           # hash of browser cookies
     request.xhr?              # is this an ajax request?
     request.url               # "http://example.com/example/foo"
     request.path              # "/example/foo"
     request.ip                # client IP address
-    request.secure?           # false
+    request.secure?           # false (would be true over ssl)
+    request.forwarded?        # true (if running behind a reverse proxy)
     request.env               # raw env hash handed in by Rack
   end
 
-Some options, like <tt>script_name</tt> or <tt>path_info</tt> can also be
+Some options, like <tt>script_name</tt> or <tt>path_info</tt>, can also be
 written:
 
   before { request.path_info = "/" }
@@ -710,6 +1102,64 @@ The <tt>request.body</tt> is an IO or StringIO object:
     "Hello #{data['name']}!"
   end
 
+=== Attachments
+
+You can use the +attachment+ helper to tell the browser the response should be
+stored on disk rather than displayed in the browser.
+
+  get '/' do
+    attachment
+    "store it!"
+  end
+
+You can also pass it a file name:
+
+  get '/' do
+    attachment "info.txt"
+    "store it!"
+  end
+
+=== Looking Up Template Files
+
+The <tt>find_template</tt> helper is used to find template files for rendering:
+
+  find_template settings.views, 'foo', Tilt[:haml] do |file|
+    puts "could be #{file}"
+  end
+
+This is not really useful. But it is useful that you can actually override this
+method to hook in your own lookup mechanism. For instance, if you want to be
+able to use more than one view directory:
+
+  set :views, ['views', 'templates']
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      Array(views).each { |v| super(v, name, engine, &block) }
+    end
+  end
+
+Another example would be using different directories for different engines:
+
+  set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      _, folder = views.detect { |k,v| engine == Tilt[k] }
+      folder ||= views[:default]
+      super(folder, name, engine, &block)
+    end
+  end
+
+You can also easily wrap this up in an extension and share with others!
+
+Note that <tt>find_template</tt> does not check if the file really exists but
+rather calls the given block for all possible paths. This is not a performance
+issue, since +render+ will use +break+ as soon as a file is found. Also,
+template locations (and content) will be cached if you are not running in
+development mode. You should keep that in mind if you write a really crazy
+method.
+
 == Configuration
 
 Run once, at startup, in any environment:
@@ -757,6 +1207,89 @@ You can access those options via <tt>settings</tt>:
     ...
   end
 
+=== Available Settings
+
+[absolute_redirects]  If disabled, Sinatra will allow relative redirects,
+                      however, Sinatra will no longer conform with RFC 2616
+                      (HTTP 1.1), which only allows absolute redirects.
+                      
+                      Enable if your app is running behind a reverse proxy that
+                      has not been set up properly. Note that the +url+ helper
+                      will still produce absolute URLs, unless you pass in
+                      +false+ as second parameter.
+                      
+                      Disabled per default.
+
+[add_charsets]        mime types the <tt>content_type</tt> helper will
+                      automatically add the charset info to.
+                      
+                      You should add to it rather than overriding this option:
+                      
+                        settings.add_charsets << "application/foobar"
+
+[app_file]            main application file, used to detect project root,
+                      views and public folder and inline templates.
+
+[bind]                IP address to bind to (default: 0.0.0.0).
+                      Only used for built-in server.
+
+[default_encoding]    encoding to assume if unknown
+                      (defaults to <tt>"utf-8"</tt>).
+
+[dump_errors]         display errors in the log.
+
+[environment]         current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
+                      or <tt>"development"</tt> if not available.
+
+[logging]             use the logger.
+
+[lock]                Places a lock around every request, only running
+                      processing on request per Ruby process concurrently.
+                      
+                      Enabled if your app is not thread-safe.
+                      Disabled per default.
+
+[method_override]     use <tt>_method</tt> magic to allow put/delete forms in
+                      browsers that don't support it.
+
+[port]                Port to listen on. Only used for built-in server.
+
+[prefixed_redirects]  Whether or not to insert <tt>request.script_name</tt> into
+                      redirects if no absolute path is given. That way
+                      <tt>redirect '/foo'</tt> would behave like
+                      <tt>redirect to('/foo')</tt>. Disabled per default.
+
+[public]              folder public files are served from
+
+[reload_templates]    whether or not to reload templates between requests.
+                      Enabled in development mode and on Ruby 1.8.6 (to
+                      compensate a bug in Ruby causing a memory leak).
+
+[root]                project root folder.
+
+[raise_errors]        raise exceptions (will stop application).
+
+[run]                 if enabled, Sinatra will handle starting the web server,
+                      do not enable if using rackup or other means.
+
+[running]             is the built-in server running now?
+                      do not change this setting!
+
+[server]              server or list of servers to use for built-in server.
+                      defaults to ['thin', 'mongrel', 'webrick'], order indicates
+                      priority.
+
+[sessions]            enable cookie based sessions.
+
+[show_exceptions]     show a stack trace in the browser.
+
+[static]              Whether Sinatra should handle serving static files.
+                      Disable when using a Server able to do this on its own.
+                      Disabling will boost performance.
+                      Enabled per default.
+
+[views]               views folder.
+
 == Error Handling
 
 Error handlers run within the same context as routes and before filters, which
@@ -798,7 +1331,7 @@ You get this:
 
   So what happened was... something bad
 
-Alternatively, you can install error handler for a status code:
+Alternatively, you can install an error handler for a status code:
 
   error 403 do
     'Access forbidden'
@@ -817,17 +1350,6 @@ Or a range:
 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
 running under the development environment.
 
-== Mime Types
-
-When using <tt>send_file</tt> or static files you may have mime types Sinatra
-doesn't understand. Use +mime_type+ to register them by file extension:
-
-  mime_type :foo, 'text/foo'
-
-You can also use it with the +content_type+ helper:
-
-  content_type :foo
-
 == Rack Middleware
 
 Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
@@ -860,7 +1382,7 @@ accepts multiple/variable args as well as blocks:
 
 Rack is distributed with a variety of standard middleware for logging,
 debugging, URL routing, authentication, and session handling. Sinatra uses
-many of of these components automatically based on configuration so you
+many of these components automatically based on configuration so you
 typically don't have to +use+ them explicitly.
 
 == Testing
@@ -924,7 +1446,7 @@ 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+;
+* Your file should require <tt>sinatra/base</tt> 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
@@ -936,15 +1458,15 @@ for details on available options and their behavior.
 
 === Modular vs. Classic Style
 
-Contrary to common believes, there is nothing wrong with classic style. If it
+Contrary to common belief, there is nothing wrong with classic style. If it
 suits your application, you do not have to switch to a modular application.
 
-There are only two downsides compared to modulare style:
+There are only two downsides compared with modular style:
 
-* You may only have one Sinatra application per Ruby process - if you plan to
+* You may only have one Sinatra application per Ruby process. If you plan to
   use more, switch to modular style.
 
-* Classic style pollutes Object with delegator methods - if you plan to ship
+* Classic style pollutes Object with delegator methods. If you plan to ship
   your application in a library/gem, switch to modular style.
 
 There is no reason you cannot mix modular and classic style.
@@ -963,7 +1485,7 @@ differences in the setting:
 
 === Serving a Modular Application
 
-There are two common options for starting a modular app, activly starting with
+There are two common options for starting a modular app, actively starting with
 <tt>run!</tt>:
 
   # my_app.rb
@@ -1063,13 +1585,13 @@ available.
 === Application/Class Scope
 
 Every Sinatra application corresponds to a subclass of Sinatra::Base. If you
-are using the top level DSL (<tt>require 'sinatra'</tt>), then this class is
+are using the top-level DSL (<tt>require 'sinatra'</tt>), then this class is
 Sinatra::Application, otherwise it is the subclass you created explicitly. At
-class level you have methods like `get` or `before`, but you cannot access the
-`request` object or the `session`, as there only is a single application class
+class level you have methods like +get+ or +before+, but you cannot access the
++request+ object or the +session+, as there only is a single application class
 for all requests.
 
-Options created via `set` are methods at class level:
+Options created via +set+ are methods at class level:
 
     class MyApp < Sinatra::Base
       # Hey, I'm in the application scope!
@@ -1085,21 +1607,21 @@ You have the application scope binding inside:
 
 * Your application class body
 * Methods defined by extensions
-* The block passed to `helpers`
-* Procs/blocks used as value for `set`
+* The block passed to +helpers+
+* Procs/blocks used as value for +set+
 
 You can reach the scope object (the class) like this:
 
 * Via the object passed to configure blocks (<tt>configure { |c| ... }</tt>)
-* `settings` from within request scope
+* +settings+ from within request scope
 
 === Request/Instance Scope
 
 For every incoming request, a new instance of your application class is
 created and all handler blocks run in that scope. From within this scope you
-can access the `request` and `session` object or call rendering methods like
-`erb` or `haml`. You can access the application scope from within the request
-scope via the `settings` helper:
+can access the +request+ and +session+ object or call rendering methods like
++erb+ or +haml+. You can access the application scope from within the request
+scope via the +settings+ helper:
 
   class MyApp < Sinatra::Base
     # Hey, I'm in the application scope!
@@ -1118,7 +1640,7 @@ scope via the `settings` helper:
 
 You have the request scope binding inside:
 
-* get/head/post/put/delete blocks
+* get/head/post/put/delete/options blocks
 * before/after filters
 * helper methods
 * templates/views
@@ -1126,16 +1648,16 @@ You have the request scope binding inside:
 === Delegation Scope
 
 The delegation scope just forwards methods to the class scope. However, it
-does not behave 100% like the class scope, as you do not have the class'
-binding: Only methods explicitly marked for delegation are available and you
+does not behave 100% like the class scope, as you do not have the class
+binding. Only methods explicitly marked for delegation are available and you
 do not share variables/state with the class scope (read: you have a different
-`self`). You can explicitly add method delegations by calling
++self+). You can explicitly add method delegations by calling
 <tt>Sinatra::Delegator.delegate :method_name</tt>.
 
 You have the delegate scope binding inside:
 
 * The top level binding, if you did <tt>require "sinatra"</tt>
-* An object extended with the `Sinatra::Delegator` mixin
+* An object extended with the <tt>Sinatra::Delegator</tt> mixin
 
 Have a look at the code for yourself: here's the
 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
@@ -1156,6 +1678,57 @@ Options are:
   -s # specify rack server/handler (default is thin)
   -x # turn on the mutex lock (default is off)
 
+== Requirements
+
+It is recommended to install Sinatra on Ruby 1.8.7, 1.9.2, JRuby or Rubinius.
+
+The following Ruby versions are officially supported:
+
+[ Ruby 1.8.6 ]
+  It is not recommended to use 1.8.6 for Sinatra. However, it will be
+  officially supported until Sinatra 1.3.0 is released. RDoc and CoffeScript
+  templates are not supported by this Ruby version. 1.8.6 includes a major
+  memory leak in its Hash implementation, which is triggered by Sinatra
+  versions prior to 1.1.1. The current version explicitly prevents this leak
+  at the cost of performance. You will have to downgrade Rack to 1.1.x, as
+  Rack >= 1.2 no longer supports 1.8.6.
+
+[ Ruby 1.8.7 ]
+  1.8.7 is fully supported, however, if nothing is keeping you from it, we
+  recommend upgrading to 1.9.2 or switching to JRuby or Rubinius.
+
+[ Ruby 1.9.2 ]
+  1.9.2 is supported and recommended. Note that Radius and Markaby are
+  currently not 1.9 compatible. Do not use 1.9.2p0, it is known to cause
+  segmentation faults when using Sinatra.
+
+[ Rubinius ]
+  Rubinius is officially supported (Rubinius >= 1.2.2), with the exception
+  of Textile templates.
+
+[ JRuby ]
+  JRuby is officially supported (JRuby >= 1.5.6). No issues with third party
+  template libraries are known, however, if you choose to use JRuby, please
+  look into JRuby rack handlers, as the Thin web server is not (yet) supported
+  on JRuby.
+
+We also keep an eye on upcoming Ruby versions.
+
+The following Ruby implementations are not officially supported but still are
+known to run Sinatra:
+
+* Older versions of JRuby and Rubinius
+* MacRuby
+* Maglev
+* IronRuby
+* Ruby 1.9.0 and 1.9.1
+
+Not being officially supported means if things only break there and not on a
+supported platform, we assume it's not our issue but theirs.
+
+Sinatra should work on any operating system supported by the chosen Ruby
+implementation.
+
 == The Bleeding Edge
 If you would like to use Sinatra's latest bleeding code, feel free to run your
 application against the master branch, it should be rather stable.
@@ -1168,13 +1741,13 @@ To get some of the latest features.
 
 === With Bundler
 If you want to run your application with the latest Sinatra, using
-{Bundler}[http://gembundler.com/] is the recommend way.
+{Bundler}[http://gembundler.com/] is the recommended way.
 
 First, install bundler, if you haven't:
 
   gem install bundler
 
-Then, in you project directory, create a +Gemfile+:
+Then, in your project directory, create a +Gemfile+:
 
   source :rubygems
   gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
@@ -1184,7 +1757,7 @@ Then, in you project directory, create a +Gemfile+:
   gem 'activerecord', '~> 3.0'  # maybe you also need ActiveRecord 3.x
 
 Note that you will have to list all your applications dependencies in there.
-Sinatra's direct dependencies (Rack and Tilt) will however be automatically
+Sinatra's direct dependencies (Rack and Tilt) will, however, be automatically
 fetched and added by Bundler.
 
 Now you can run your app like this:
@@ -1193,7 +1766,7 @@ Now you can run your app like this:
 
 === Roll Your Own
 Create a local clone and run your app with the <tt>sinatra/lib</tt> directory
-on the <tt>LOAD_PATH</tt>:
+on the <tt>$LOAD_PATH</tt>:
 
   cd myapp
   git clone git://github.com/sinatra/sinatra.git