sinatra 1.2.0.c → 1.2.0.d

data/README.fr.rdoc

@@ -374,8 +374,8 @@ Notez que vous pouvez également appeler la méthode textile au sein d'autres te
 
 Le gem RDoc est nécessaire pour utiliser la fonction de rendu RDoc:
 
-  # Chargez la bibliothèque rdoc dans votre application
-  require "rdoc"
+  # Chargez la bibliothèque rdoc/markup/to_html dans votre application
+  require "rdoc/markup/to_html"
 
   get '/' do
     rdoc :index

data/README.jp.rdoc

@@ -369,8 +369,8 @@ textileからメソッドを呼び出すことも、localsに変数を渡すこ
 
 RDocテンプレートを使うにはRDocライブラリが必要です:
 
-  # rdocを読み込みます
-  require "rdoc"
+  # rdoc/markup/to_htmlを読み込みます
+  require "rdoc/markup/to_html"
 
   get '/' do
     rdoc :index

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
@@ -127,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
@@ -138,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
@@ -148,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
@@ -168,8 +212,8 @@ 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
@@ -271,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.
@@ -295,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.
@@ -447,8 +491,8 @@ template) with <tt>./views/post.haml</tt> as layout.
 
 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
@@ -571,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])
@@ -643,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:
 
@@ -662,9 +706,9 @@ learn more about Tilt.
 
 == 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!'
@@ -676,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:
 
@@ -688,7 +732,7 @@ 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
@@ -724,6 +768,37 @@ route handlers and templates:
     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:
@@ -777,19 +852,19 @@ of calling another route. Simply use +call+ to achieve this:
   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>.
+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 and Status Code
+=== 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 arbritary point in the execution flow. You can do so with the
+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:
 
@@ -801,15 +876,34 @@ access the body:
     puts body
   end
 
-It is also possible to pass a block to body, that will be executed by the rack
-handler (this can be used to implement streaming, see
-"Return Values").
+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:
+Similar to the body, you can also set the status code and headers:
 
   get '/foo' do
     status 418
-    halt "I'm a tea pot!"
+    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
@@ -821,8 +915,7 @@ Haml:
 
 It takes reverse proxies and Rack routers into account, if present.
 
-This method is also aliased to +to+ (see below) for an
-example).
+This method is also aliased to +to+ (see below for an example).
 
 === Browser Redirect
 
@@ -866,6 +959,62 @@ Or use a session:
     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:
@@ -874,14 +1023,14 @@ For sending files, you can use the <tt>send_file</tt> helper method:
     send_file 'foo.png'
   end
 
-It also take a couple of options:
+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.
+  file name, in response, defaults to the real file name.
 
 [last_modified]
   value for Last-Modified header, defaults to the file's mtime.
@@ -891,7 +1040,7 @@ The options are:
 
 [disposition]
   used for Content-Disposition, possible values: +nil+ (default),
-  <tt>:attachement</tt> and <tt>:inline</tt>
+  <tt>:attachment</tt> and <tt>:inline</tt>
 
 [length]
   Content-Length header, defaults to file size.
@@ -920,18 +1069,19 @@ error handlers) through the <tt>request</tt> method:
     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 = "/" }
@@ -948,6 +1098,23 @@ 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:
@@ -1057,20 +1224,20 @@ You can access those options via <tt>settings</tt>:
                         settings.add_charsets << "application/foobar"
 
 [app_file]            main application file, used to detect project root,
-                      views and public folder and inline templates
+                      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>)
+                      (defaults to <tt>"utf-8"</tt>).
 
-[dump_errors]         display errors in the log
+[dump_errors]         display errors in the log.
 
 [environment]         current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
-                      or <tt>"development"</tt> if not available
+                      or <tt>"development"</tt> if not available.
 
-[logging]             use the logger
+[logging]             use the logger.
 
 [lock]                Places a lock around every request, only running
                       processing on request per Ruby process concurrently.
@@ -1079,7 +1246,7 @@ You can access those options via <tt>settings</tt>:
                       Disabled per default.
 
 [method_override]     use <tt>_method</tt> magic to allow put/delete forms in
-                      browsers that don't support it
+                      browsers that don't support it.
 
 [port]                Port to listen on. Only used for built-in server.
 
@@ -1088,17 +1255,17 @@ You can access those options via <tt>settings</tt>:
                       <tt>redirect '/foo'</tt> would behave like
                       <tt>redirect to('/foo')</tt>. Disabled per default.
 
-[public]              folder public files are server from
+[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)
+                      Enabled in development mode and on Ruby 1.8.6 (to
+                      compensate a bug in Ruby causing a memory leak).
 
-[root]                project root folder
+[root]                project root folder.
 
-[raise_errors]        raise exceptions (will stop application)
+[raise_errors]        raise exceptions (will stop application).
 
-[run]                 if enabled, Sinatra will handle starting the webserver,
+[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?
@@ -1108,16 +1275,16 @@ You can access those options via <tt>settings</tt>:
                       defaults to ['thin', 'mongrel', 'webrick'], order indicates
                       priority.
 
-[sessions]            enable cookie based sessions
+[sessions]            enable cookie based sessions.
 
-[show_exceptions]     show a stacktrace in the browser
+[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
+[views]               views folder.
 
 == Error Handling
 
@@ -1160,7 +1327,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'
@@ -1179,17 +1346,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
@@ -1222,7 +1378,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
@@ -1286,7 +1442,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
@@ -1298,15 +1454,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.
@@ -1325,7 +1481,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
@@ -1425,7 +1581,7 @@ 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
@@ -1488,8 +1644,8 @@ 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
 <tt>Sinatra::Delegator.delegate :method_name</tt>.
@@ -1518,6 +1674,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.
@@ -1530,13 +1737,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"
@@ -1546,7 +1753,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:
@@ -1555,7 +1762,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