sinatra 1.0 → 1.1.a

data/README.rdoc

@@ -4,16 +4,16 @@ Sinatra is a DSL for quickly creating web applications in Ruby with minimal
 effort:
 
   # myapp.rb
-  require 'rubygems'
   require 'sinatra'
+  
   get '/' do
     'Hello world!'
   end
 
 Install the gem and run with:
 
-  sudo gem install sinatra
-  ruby myapp.rb
+  gem install sinatra
+  ruby -rubygems myapp.rb
 
 View at: http://localhost:4567
 
@@ -81,6 +81,8 @@ Or with a block parameter:
     "Hello, #{c}!"
   end
 
+=== Conditions
+
 Routes may include a variety of matching conditions, such as the user agent:
 
   get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
@@ -91,6 +93,57 @@ Routes may include a variety of matching conditions, such as the user agent:
     # Matches non-songbird browsers
   end
 
+Other available conditions are +host_name+ and +provides+:
+
+  get '/', :host_name => /^admin\./ do
+    "Admin Area, Access denied!"
+  end
+
+  get '/', :provides => 'html' do
+    haml :index
+  end
+  
+  get '/', :provides => ['rss', 'atom', 'xml'] do
+    builder :feed
+  end
+
+You can easily define your own conditions:
+
+  set(:probability) { |value| condition { rand <= value } }
+  
+  get '/win_a_car', :probability => 0.1 do
+    "You won!"
+  end
+  
+  get '/win_a_car' do
+    "Sorry, you lost."
+  end
+
+=== Return values
+
+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
+also accepted.
+
+You can return any object that would either be a valid Rack response, Rack
+body object or HTTP status code:
+
+* An Array with three elements: <tt>[status (Fixnum), headers (Hash), response body (responds to #each)]</tt>
+* An Array with two elements: <tt>[status (Fixnum), response body (responds to #each)]</tt>
+* 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:
+
+    class Stream
+      def each
+        100.times { |i| yield "#{i}\n" }
+      end
+    end
+
+    get('/') { Stream.new }
+
 == Static Files
 
 Static files are served from the <tt>./public</tt> directory. You can specify
@@ -111,8 +164,9 @@ 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>). Rendering methods will render
-any strings passed to them directly.
+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
 
@@ -127,15 +181,15 @@ The haml gem/library is required to render HAML templates:
 
 Renders <tt>./views/index.haml</tt>.
 
-{Haml's options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
+{Haml's options}[http://haml-lang.com/docs/yardoc/file.HAML_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.
 
-  set :haml, {:format => :html5 } # default Haml format is :xhtml
+  set :haml, :format => :html5 # default Haml format is :xhtml
 
   get '/' do
-    haml :index, :haml_options => {:format => :html4 } # overridden
+    haml :index, :format => :html4 # overridden
   end
 
 
@@ -152,7 +206,7 @@ Renders <tt>./views/index.erb</tt>
 
 === Erubis
 
-The erubis gem/library is required to render builder templates:
+The erubis gem/library is required to render erubis templates:
 
   ## You'll need to require erubis in your app
   require 'erubis'
@@ -171,12 +225,24 @@ The builder gem/library is required to render builder templates:
   require 'builder'
 
   get '/' do
-    content_type 'application/xml', :charset => 'utf-8'
     builder :index
   end
 
 Renders <tt>./views/index.builder</tt>.
 
+=== Nokogiri Templates
+
+The nokogiri gem/library is required to render nokogiri templates:
+
+  ## You'll need to require nokogiri in your app
+  require 'nokogiri'
+
+  get '/' do
+    nokogiri :index
+  end
+
+Renders <tt>./views/index.nokogiri</tt>.
+
 === Sass Templates
 
 The sass gem/library is required to render Sass templates:
@@ -185,24 +251,46 @@ The sass gem/library is required to render Sass templates:
   require 'sass'
 
   get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
     sass :stylesheet
   end
 
 Renders <tt>./views/stylesheet.sass</tt>.
 
-{Sass' options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
+{Sass' 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.
 
-  set :sass, {:style => :compact } # default Sass style is :nested
+  set :sass, :style => :compact # default Sass style is :nested
 
   get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
     sass :stylesheet, :style => :expanded # overridden
   end
 
+=== Scss Templates
+
+The sass gem/library is required to render Scss templates:
+
+  ## You'll need to require haml or sass in your app
+  require 'sass'
+
+  get '/stylesheet.css' do
+    scss :stylesheet
+  end
+
+Renders <tt>./views/stylesheet.scss</tt>.
+
+{Scss' 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.
+
+  set :scss, :style => :compact # default Scss style is :nested
+
+  get '/stylesheet.css' do
+    scss :stylesheet, :style => :expanded # overridden
+  end
+
 === Less Templates
 
 The less gem/library is required to render Less templates:
@@ -211,12 +299,141 @@ The less gem/library is required to render Less templates:
   require 'less'
 
   get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
     less :stylesheet
   end
 
 Renders <tt>./views/stylesheet.less</tt>.
 
+=== Liquid Templates
+
+The liquid gem/library is required to render Liquid templates:
+
+  ## You'll need to require liquid in your app
+  require 'liquid'
+
+  get '/' do
+    liquid :index
+  end
+
+Renders <tt>./views/index.liquid</tt>.
+
+Since you cannot call Ruby methods (except for +yield+) from a Liquid
+template, you almost always want to pass locals to it:
+
+  liquid :index, :locals => { :key => 'value' }
+
+=== Markdown Templates
+
+The rdiscount gem/library is required to render Markdown templates:
+
+  ## You'll need to require rdiscount in your app
+  require "rdiscount"
+  
+  get '/' do
+    markdown :index
+  end
+
+Renders <tt>./views/index.markdown</tt> (+md+ and +mkd+ are also valid file
+extensions).
+
+It is not possible to call methods from markdown, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+
+  erb :overview, :locals => { :text => markdown(:introduction) }
+
+Note that you may also call the markdown method from within other templates:
+
+  %h1 Hello From Haml!
+  %p= markdown(:greetings)
+
+=== Textile Templates
+
+The RedCloth gem/library is required to render Textile templates:
+
+  ## You'll need to require redcloth in your app
+  require "redcloth"
+
+  get '/' do
+    textile :index
+  end
+
+Renders <tt>./views/index.textile</tt>.
+
+It is not possible to call methods from textile, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+
+  erb :overview, :locals => { :text => textile(:introduction) }
+
+Note that you may also call the textile method from within other templates:
+
+  %h1 Hello From Haml!
+  %p= textile(:greetings)
+
+=== RDoc Templates
+
+The RDoc gem/library is required to render RDoc templates:
+
+  ## You'll need to require rdoc in your app
+  require "rdoc"
+
+  get '/' do
+    rdoc :index
+  end
+
+Renders <tt>./views/index.rdoc</tt>.
+
+It is not possible to call methods from rdoc, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+
+  erb :overview, :locals => { :text => rdoc(:introduction) }
+
+Note that you may also call the rdoc method from within other templates:
+
+  %h1 Hello From Haml!
+  %p= rdoc(:greetings)
+
+=== Radius Templates
+
+The radius gem/library is required to render Radius templates:
+
+  ## You'll need to require radius in your app
+  require 'radius'
+
+  get '/' do
+    radius :index
+  end
+
+Renders <tt>./views/index.radius</tt>.
+
+Since you cannot call Ruby methods (except for +yield+) from a Radius
+template, you almost always want to pass locals to it:
+
+  radius :index, :locals => { :key => 'value' }
+
+=== Markaby Templates
+
+The markaby gem/library is required to render Markaby templates:
+
+  ## You'll need to require markaby in your app
+  require 'markaby'
+
+  get '/' do
+    markaby :index
+  end
+
+Renders <tt>./views/index.mab</tt>.
+
+=== CoffeeScript Templates
+
+The coffee-script gem/library and the `coffee` binary are required to render
+CoffeeScript templates:
+
+  ## You'll need to require coffee-script in your app
+  require 'coffee-script'
+
+  get '/application.js' do
+    coffee :application
+  end
+
+Renders <tt>./views/application.coffee</tt>.
+
 === Inline Templates
 
   get '/' do
@@ -249,7 +466,6 @@ other templates.
 
 Templates may be defined at the end of the source file:
 
-  require 'rubygems'
   require 'sinatra'
 
   get '/' do
@@ -265,8 +481,8 @@ Templates may be defined at the end of the source file:
   @@ index
   %div.title Hello world!!!!!
 
-NOTE: Inline templates defined in the source file that requires sinatra
-are automatically loaded. Call `enable :inline_templates` explicitly if you
+NOTE: Inline templates defined in the source file that requires sinatra are
+automatically loaded. Call <tt>enable :inline_templates</tt> explicitly if you
 have inline templates in other source files.
 
 === Named Templates
@@ -309,9 +525,9 @@ route handlers and templates:
 
 == Filters
 
-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:
+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!'
@@ -323,33 +539,44 @@ filters are accessible by routes and templates:
     params[:splat] #=> 'bar/baz'
   end
 
-After filter are evaluated after each request within the context of the
-request and can also modify the request and response. Instance variables
-set in before filters and routes are accessible by after filters:
+After filter 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:
 
   after do
     puts response.status
   end
 
+Filters optionally taking a pattern, causing them to be evaluated only if the
+request path matches that pattern:
+
+  before '/protected/*' do
+    authenticate!
+  end
+
+  after '/create/:slug' do |slug|
+    session[:last_slug] = slug
+  end
+
 == Halting
 
 To immediately stop a request within a filter or route use:
 
   halt
 
-You can also specify the status when halting ...
+You can also specify the status when halting:
 
   halt 410
 
-Or the body ...
+Or the body:
 
   halt 'this will be the body'
 
-Or both ...
+Or both:
 
   halt 401, 'go away!'
 
-With headers ...
+With headers:
 
   halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
 
@@ -369,6 +596,53 @@ 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
+
+The incoming request object can be accessed from request level (filter, routes, error handlers) through the `request` method:
+
+  # app running on http://example.com/example
+  get '/foo' do
+    request.body              # request body sent by the client (see below)
+    request.scheme            # "http"
+    request.script_name       # "/example"
+    request.path_info         # "/foo"
+    request.port              # 80
+    request.request_method    # "GET"
+    request.query_string      # ""
+    request.content_length    # length of request.body
+    request.media_type        # media type of request.body
+    request.host              # "example.com"
+    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.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
+    requuest.env              # raw env hash handed in by Rack
+  end
+
+Some options, like <tt>script_name</tt> or <tt>path_info</tt> can also be
+written:
+
+  before { request.path_info = "/" }
+  
+  get "/" do
+    "all requests end up here"
+  end
+
+The <tt>request.body</tt> is an IO or StringIO object:
+
+  post "/api" do
+    request.body.rewind  # in case someone already read it
+    data = JSON.parse request.body.read
+    "Hello #{data['name']}!"
+  end
+
 == Configuration
 
 Run once, at startup, in any environment:
@@ -394,8 +668,8 @@ Run when the environment is set to either <tt>:production</tt> or
 == Error handling
 
 Error handlers run within the same context as routes and before filters, which
-means you get all the goodies it has to offer, like <tt>haml</tt>, <tt>erb</tt>,
-<tt>halt</tt>, etc.
+means you get all the goodies it has to offer, like <tt>haml</tt>,
+<tt>erb</tt>, <tt>halt</tt>, etc.
 
 === Not Found
 
@@ -403,7 +677,7 @@ When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
 code is 404, the <tt>not_found</tt> handler is invoked:
 
   not_found do
-    'This is nowhere to be found'
+    'This is nowhere to be found.'
   end
 
 === Error
@@ -504,6 +778,7 @@ or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
 recommended:
 
   require 'my_sinatra_app'
+  require 'test/unit'
   require 'rack/test'
 
   class MyAppTest < Test::Unit::TestCase
@@ -535,7 +810,7 @@ are deprecated as of the 0.9.2 release.
 == Sinatra::Base - Middleware, Libraries, and Modular Apps
 
 Defining your app at the top-level works well for micro-apps but has
-considerable drawbacks when building reuseable components such as Rack
+considerable drawbacks when building reusable 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
@@ -570,17 +845,131 @@ Sinatra::Base components with two modifications:
 * Put your app's routes, error handlers, filters, and options in a subclass
   of Sinatra::Base.
 
-+Sinatra::Base+ is a blank slate. Most options are disabled by default,
+<tt>Sinatra::Base</tt> 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.
 
-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
+=== Using Sinatra as Middleware
+
+Not only is Sinatra able to use other Rack middleware, any Sinatra application
+can in turn be added in front of any Rack endpoint as middleware itself. This
+endpoint could be another Sinatra application, or any other Rack-based
+application (Rails/Ramaze/Camping/...).
+
+  require 'sinatra/base'
+  
+  class LoginScreen < Sinatra::Base
+    enable :session
+    
+    get('/login') { haml :login }
+    
+    post('/login') do
+      if params[:name] = 'admin' and params[:password] = 'admin'
+        session['user_name'] = params[:name]
+      else
+        redirect '/login'
+      end
+    end
+  end
+  
+  class MyApp < Sinatra::Base
+    # middleware will run before filters
+    use LoginScreen
+    
+    before do
+      unless session['user_name']
+        halt "Access denied, please <a href='/login'>login</a>."
+      end
+    end
+    
+    get('/') { "Hello #{session['user_name']}." }
+  end
+
+== Scopes and Binding
+
+The scope you are currently in determines what methods and variables are
+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
+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
+for all requests.
+
+Options created via `set` are methods at class level:
+
+    class MyApp << Sinatra::Base
+      # Hey, I'm in the application scope!
+      set :foo, 42
+      foo # => 42
+      
+      get '/foo' do
+        # Hey, I'm no longer in the application scope!
+      end
+    end
+
+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`
+
+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
+
+=== 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:
+
+  class MyApp << Sinatra::Base
+    # Hey, I'm in the application scope!
+    get '/define_route/:name' do
+      # Request scope for '/define_route/:name'
+      @value = 42
+      
+      settings.get("/#{params[:name]}") do
+        # Request scope for "/#{params[:name]}"
+        @value # => nil (not the same request)
+      end
+      
+      "Route defined!"
+    end
+  end
+
+You have the request scope binding inside:
+
+* get/head/post/put/delete blocks
+* before/after filters
+* helper methods
+* templates/views
+
+=== 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
+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>.
+
+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
+
+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]
-being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]
+being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28].
 
 == Command line
 
@@ -629,8 +1018,7 @@ To update the Sinatra sources in the future:
   news, and links to other resources.
 * {Contributing}[http://www.sinatrarb.com/contributing] - Find a bug? Need
   help? Have a patch?
-* {Lighthouse}[http://sinatra.lighthouseapp.com] - Issue tracking and release
-  planning.
+* {Issue tracker}[http://github.com/sinatra/sinatra/issues]
 * {Twitter}[http://twitter.com/sinatra]
 * {Mailing List}[http://groups.google.com/group/sinatrarb/topics]
 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net