roda-cj 0.9.6 → 1.0.0

data/Rakefile

@@ -34,7 +34,7 @@ rescue LoadError
 end
 
 RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
-RDOC_FILES = %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb"
+RDOC_FILES = %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb" + Dir["doc/*.rdoc"] + Dir['doc/release_notes/*.txt']
 
 rdoc_task_class.new do |rdoc|
   rdoc.rdoc_dir = "rdoc"

data/doc/release_notes/1.0.0.txt

@@ -0,0 +1,329 @@
+= New Plugins
+
+* A csrf plugin has been added for CSRF prevention, using
+  Rack::Csrf.  It also adds helper methods for views such as
+  csrf_tag.
+
+* A symbol_matchers plugin has been added, for customizing
+  the regexps used per symbol.  This also affects the use
+  of embedded colons in strings.  This supports the following
+  symbol regexps by default:
+
+  :d :: (\d+), a decimal segment
+  :format :: (?:\.(\w+))?, an optional format/extension
+  :opt :: (?:\/([^\/]+))?, an optional segment
+  :optd :: (?:\/(\d+))?, an optional decimal segment
+  :rest :: (.*), all remaining characters, if any
+  :w :: (\w+), a alphanumeric segment
+
+  This allows you to write code such as:
+
+    plugin :symbol_matchers
+
+    route do |r|
+      r.is "track/:d" do
+      end
+    end
+
+  And have it only match routes such as /track/123, not
+  /track/abc.
+
+  Note that :opt, :optd, and :format are only going to make sense
+  when used as embedded colons in strings, due to how segment matching
+  works.
+
+  You can add your own symbol matchers using the symbol_matcher
+  class method:
+
+    plugin :symbol_matchers
+    symbol_matcher :slug, /([\w-]+)/
+
+    route do |r|
+      r.on :slug do
+      end
+    end
+
+* A symbol_views plugin has been added, which allows match blocks to
+  return symbols, which are interpreted as template names:
+
+    plugin :symbol_views
+
+    route do |r|
+      :template_name # same as view :template_name
+    end
+
+* A json plugin has been added, which allows match blocks to return
+  arrays or hashes, and uses a JSON version of them as the response
+  body:
+
+    plugin :json
+
+    route do |r|
+      {'a'=>[1,2,3]} # response: {"a":[1,2,3]}
+    end
+
+  This also sets the Content-Type of the response to application/json.
+
+  To convert additional object types to JSON, you can modify
+  json_response_classes:
+
+    plugin :json
+    json_response_classes << Sequel::Model
+
+* A view_subdirs plugin has been added for setting a default
+  subdirectory to use for views:
+
+    Roda.route do |r|
+      r.on "admin" do
+        set_view_subdir "admin"
+        
+        r.is do
+          view "index" # uses admin/index view
+        end
+      end
+    end
+
+* A render_each plugin has been added, for rendering the same
+  template for multiple objects, and returning the concatenation
+  of all of the output:
+
+    <%= render_each([1,2,3], 'number') %>
+
+  This renders the number template 3 times.  Each time the template
+  is rendered, a local variable named number will be present with
+  the current entry in the enumerable.  You can control the name of
+  the local variable using the :local option:
+
+    <%= render_each([1,2,3], 'number', :local=>:n) %>
+
+* A content_for plugin has been added, for storing content in one
+  template and retrieving that content in a different template (such
+  as the layout).  To set content, you call content_for with a block:
+
+    <% content_for :foo do %>
+      content for foo
+    <% end %>
+
+  To retrieve content, you call content_for without a block:
+
+    <%= content_for :foo %>
+
+  This plugin probably only works when using erb templates.
+
+* A not_allowed plugin has been added, for automatically returning 405
+  Method Not Allowed responses when a route is handled for a different
+  request method than the one used.  For this routing tree:
+
+    plugin :not_allowed
+
+    route do |r|
+      r.get "foo" do
+      end
+    end
+
+  If you submit a POST /foo request, it will return a 405 error
+  instead of a 404 error.
+
+  This also handles cases when multiple methods are supported for
+  a single path, so for this routing tree:
+
+    route do |r|
+      r.is "foo" do
+        r.get do
+        end
+        r.post do
+        end
+      end
+    end
+
+  If you submit a DELETE /foo request, it will return a 405 error
+  instead of a 404 error.
+
+* A head plugin has been added, automatically handling HEAD requests
+  the same as GET requests, except returning an empty body. So for
+  this routing tree:
+
+    plugin :head
+
+    route do |r|
+      r.get "foo" do
+      end
+    end
+
+  A request for HEAD /foo will return a 200 result instead of a 404
+  error.
+
+* A backtracking_array plugin has been added, which makes matching
+  backtrack to the next entry in an array if a later matcher fails.
+  For example, the following code does not match /foo/bar by
+  default in Roda:
+
+    r.is ['foo', 'foo/bar'] do
+    end
+
+  This is because the 'foo' entry in the array matches, so the
+  array matches.  However, after the array is matched, the terminal
+  matcher added by r.is fails to match.  That causes the routing
+  method not to match the request, so the match block is not called.
+
+  With the backtracking_array plugin, failures of later matchers after
+  an array matcher backtrack so the next entry in the array is tried.
+
+* A per_thread_caching plugin has been added, allowing you to change
+  from a thread-safe shared cache to a per-thread cache, which may
+  be faster on alternative ruby implementations, at the cost of
+  additional memory usage.
+
+= New Features
+
+* The hash_matcher class method has been added to make it easier to
+  define custom hash matchers:
+
+    hash_matcher(:foo) do |v|
+      self['foo'] == v
+    end
+    
+    route do |r|
+      r.on :foo=>'bar' do
+        # matches when param foo has value bar
+      end
+    end
+
+* An r.root routing method has been added for handling GET
+  requests where the current path is /.  This is basically
+  a faster and simpler version of r.get "", except it does
+  not consume the / from the path.
+
+* The r.halt method now works without an argument, in which
+  case it uses the current response.
+
+* The r.redirect method now works without an argument for non-GET
+  requests, redirecting to the current path.
+
+* An :all hash matcher has been added, which takes an array and
+  matches only if all of the elements match.  This is mainly
+  designed for usage inside an array matcher, so:
+
+    r.on ["foo", {:all=>["bar", :id]}] do
+    end
+
+  will match either /foo or /bar/123, but not /bar.
+
+* The render plugin's view method now accepts a :content option,
+  in which case it uses the content directly without running it
+  through the template engine.  This is useful if you have
+  arbitrary content you want rendered inside the layout.
+
+* The render plugin now accepts an :escape option, in which case
+  it will automatically set the default :engine_class for erb
+  templates to an Erubis::EscapedEruby subclass.  This changes the
+  behavior of erb templates such that:
+
+    <%= '<escaped>' %> # &lt;escaped&gt;
+    <%== '<not escaped>' %> # <not escaped>
+
+  This makes it easier to protect against XSS attacks in your
+  templates, as long as you only use <%== %> for content that has
+  already been escaped.
+
+  Note that similar behavior is available in Erubis by default,
+  using the :opts=>{:escape_html=>true} render option, but that
+  doesn't handle postfix conditionals in <%= %> tags.
+
+* The multi_route plugin now has an r.multi_route method, which
+  will attempt to dispatch to one of the named routes based on
+  first segment in the path.  So this routing tree:
+
+    plugin :multi_route
+
+    route "a" do |r|
+      r.is "c" do
+        "e"
+      end
+    end
+    route "b" do |r|
+      r.is "d" do
+        "f"
+      end
+    end
+
+    route do |r|
+      r.multi_route
+    end
+
+  will return "e" for /a/c and "f" for /b/d.
+
+* Plugins can now override request and response class methods
+  using RequestClassMethods and ResponseClassMethods modules.
+
+= Optimizations
+
+* String, hash, and symbol matchers are now much faster by caching
+  the underlying regexp.
+
+* String, hash, and symbol matchers are now faster by using a
+  regexp positive lookahead assertion instead of an additional
+  capture.
+
+* Terminal matching in the r.is, r.get, and r.post routing methods
+  is now faster, as it does not use a hash matcher internally.
+
+* The routing methods are now faster by reducing the number of
+  Array objects created.
+
+* Calling routing methods without arguments is now faster.
+
+* The r.get method is now faster by reducing the number of string
+  allocations.
+
+* Many request methods are faster by reducing the number of
+  method calls used.
+
+* Template caching no longer uses a mutex on MRI, since one is
+  not needed for thread safety there.
+
+= Other Improvements
+
+* The flash plugin now implements its own flash hash instead of
+  using sinatra-flash.  It is now slightly faster and handles nil
+  keys in #keep and #discard.
+
+* Roda's version is now stored in roda/version.rb so that it can be
+  required without requiring Roda itself.
+
+= Backwards Compatibility
+
+* The multi_route plugin's route instance method has been changed
+  to a request method.  So the new usage is:
+
+    plugin :multi_route
+
+    route "a" do |r|
+    end
+
+    route do |r|
+      r.route "a" # instead of: route "a"
+    end
+
+* The session key used for the flash hash in the flash plugin is
+  now :_flash, not :flash.
+
+* The :extension matcher now longer forces a terminal match, use
+  one of the routing methods that forces a terminal match if you
+  want that behavior.
+
+* The :term hash matcher has been removed.
+
+* The r.consume private method now takes the exact regexp to use
+  to search the current path, it no longer enforces a preceeding
+  slash and that the match end on a segment boundary.
+
+* Dynamically constructing match patterns is now a potential
+  memory leak due to them being cached.  So you shouldn't do
+  things like:
+
+    r.on r['param'] do
+    end
+
+* Many private routing methods were changed or removed, if you were
+  using them, you'll probably need to update your code.

data/lib/roda.rb

@@ -51,9 +51,10 @@ class Roda
     @roda_class = ::Roda
   end
 
-  @builder = ::Rack::Builder.new
+  @app = nil
   @middleware = []
   @opts = {}
+  @route_block = nil
 
   # Module in which all Roda plugins should be stored. Also contains logic for
   # registering and loading plugins.
@@ -75,7 +76,9 @@ class Roda
     end
 
     # Register the given plugin with Roda, so that it can be loaded using #plugin
-    # with a symbol.  Should be used by plugin files.
+    # with a symbol.  Should be used by plugin files. Example:
+    #
+    #   Roda::RodaPlugins.register_plugin(:plugin_name, PluginModule)
     def self.register_plugin(name, mod)
       @plugins[name] = mod
     end
@@ -92,6 +95,9 @@ class Roda
         # The settings/options hash for the current class.
         attr_reader :opts
 
+        # The route block that this class uses.
+        attr_reader :route_block
+
         # Call the internal rack application with the given environment.
         # This allows the class itself to be used as a rack application.
         # However, for performance, it's better to use #app to get direct
@@ -104,21 +110,30 @@ class Roda
         # block, so that using a hash key in a request match method will
         # call the block.  The block should return nil or false to not
         # match, and anything else to match.
+        #
+        #   class App < Roda
+        #     hash_matcher(:foo) do |v|
+        #       self['foo'] == v
+        #     end
+        #
+        #     route do
+        #       r.on :foo=>'bar' do
+        #         # matches when param foo has value bar
+        #       end
+        #     end
+        #   end
         def hash_matcher(key, &block)
           request_module{define_method(:"match_#{key}", &block)}
         end
 
-        # When inheriting Roda, setup a new rack app builder, copy the
-        # default middleware and opts into the subclass, and set the
-        # request and response classes in the subclasses to be subclasses
-        # of the request and responses classes in the parent class.  This
-        # makes it so child classes inherit plugins from their parent,
-        # but using plugins in child classes does not affect the parent.
+        # When inheriting Roda, copy the shared data into the subclass,
+        # and setup the request and response subclasses.
         def inherited(subclass)
           super
-          subclass.instance_variable_set(:@builder, ::Rack::Builder.new)
           subclass.instance_variable_set(:@middleware, @middleware.dup)
           subclass.instance_variable_set(:@opts, opts.dup)
+          subclass.instance_variable_set(:@route_block, @route_block)
+          subclass.send(:build_rack_app)
           
           request_class = Class.new(self::RodaRequest)
           request_class.roda_class = subclass
@@ -133,6 +148,9 @@ class Roda
         # Load a new plugin into the current class.  A plugin can be a module
         # which is used directly, or a symbol represented a registered plugin
         # which will be required and then used.
+        #
+        #   Roda.plugin PluginModule
+        #   Roda.plugin :csrf
         def plugin(mixin, *args, &block)
           if mixin.is_a?(Symbol)
             mixin = RodaPlugins.load_plugin(mixin)
@@ -168,24 +186,58 @@ class Roda
 
         # Include the given module in the request class. If a block
         # is provided instead of a module, create a module using the
-        # the block.
+        # the block. Example:
+        #
+        #   Roda.request_module SomeModule
+        #
+        #   Roda.request_module do
+        #     def description
+        #       "#{request_method} #{path_info}"
+        #     end
+        #   end
+        #
+        #   Roda.route do |r|
+        #     r.description
+        #   end
         def request_module(mod = nil, &block)
           module_include(:request, mod, &block)
         end
     
         # Include the given module in the response class. If a block
         # is provided instead of a module, create a module using the
-        # the block.
+        # the block. Example:
+        #
+        #   Roda.response_module SomeModule
+        #
+        #   Roda.response_module do
+        #     def error!
+        #       self.status = 500
+        #     end
+        #   end
+        #
+        #   Roda.route do |r|
+        #     response.error!
+        #   end
         def response_module(mod = nil, &block)
           module_include(:response, mod, &block)
         end
 
-        # Setup route definitions for the current class, and build the
-        # rack application using the stored middleware.
+        # Setup routing tree for the current Roda application, and build the
+        # underlying rack application using the stored middleware. Requires
+        # a block, which is yielded the request.  By convention, the block
+        # argument should be named +r+.  Example:
+        #
+        #   Roda.route do |r|
+        #     r.root do
+        #       "Root"
+        #     end
+        #   end
+        #
+        # This should only be called once per class, and if called multiple
+        # times will overwrite the previous routing.
         def route(&block)
-          @middleware.each{|a, b| @builder.use(*a, &b)}
-          @builder.run lambda{|env| new.call(env, &block)}
-          @app = @builder.to_app
+          @route_block = block
+          build_rack_app
         end
 
         # A new thread safe cache instance.  This is a method so it can be
@@ -195,13 +247,26 @@ class Roda
         end
 
         # Add a middleware to use for the rack application.  Must be
-        # called before calling #route.
+        # called before calling #route to have an effect. Example:
+        #
+        #   Roda.use Rack::Session::Cookie, :secret=>ENV['secret']
         def use(*args, &block)
           @middleware << [args, block]
+          build_rack_app
         end
 
         private
 
+        # Build the rack app to use
+        def build_rack_app
+          if block = @route_block
+            builder = Rack::Builder.new
+            @middleware.each{|a, b| builder.use(*a, &b)}
+            builder.run lambda{|env| new.call(env, &block)}
+            @app = builder.to_app
+          end
+        end
+
         # Backbone of the request_module and response_module support.
         def module_include(type, mod)
           if type == :response
@@ -234,25 +299,34 @@ class Roda
 
         # Create a request and response of the appopriate
         # class, the instance_exec the route block with
-        # the request, handling any halts.
+        # the request, handling any halts.  This is not usually
+        # called directly.
         def call(env, &block)
           @_request = self.class::RodaRequest.new(self, env)
           @_response = self.class::RodaResponse.new
           _route(&block)
         end
 
-        # The environment for the current request.
+        # The environment hash for the current request. Example:
+        #
+        #   env['REQUEST_METHOD'] # => 'GET'
         def env
           request.env
         end
 
         # The class-level options hash.  This should probably not be
-        # modified at the instance level.
+        # modified at the instance level. Example:
+        #
+        #   Roda.plugin :render
+        #   Roda.route do |r|
+        #     opts[:render_opts].inspect
+        #   end
         def opts
           self.class.opts
         end
 
         # The instance of the request class related to this request.
+        # This is the same object yielded by Roda.route.
         def request
           @_request
         end
@@ -363,7 +437,12 @@ class Roda
         end
 
         # As request routing modifies SCRIPT_NAME and PATH_INFO, this exists
-        # as a helper method to get the full request of the path info.
+        # as a helper method to get the full path of the request.
+        #
+        #   r.env['SCRIPT_NAME'] = '/foo'
+        #   r.env['PATH_INFO'] = '/bar'
+        #   r.full_path_info
+        #   # => '/foo/bar'
         def full_path_info
           "#{@env[SCRIPT_NAME]}#{@env[PATH_INFO]}"
         end
@@ -371,13 +450,20 @@ class Roda
         # Immediately stop execution of the route block and return the given
         # rack response array of status, headers, and body.  If no argument
         # is given, uses the current response.
+        #
+        #   r.halt [200, {'Content-Type'=>'text/html'}, ['Hello World!']]
+        #   
+        #   response.status = 200
+        #   response['Content-Type'] = 'text/html'
+        #   response.write 'Hello World!'
+        #   r.halt
         def halt(res=response.finish)
           throw :halt, res
         end
 
-        # Whether this request is a get request.  Similar to the default
-        # Rack::Request get? method, but can be overridden without changing
-        # rack's behavior.
+        # Optimized method for whether this request is a +GET+ request.
+        # Similar to the default Rack::Request get? method, but can be
+        # overridden without changing rack's behavior.
         def is_get?
           @env[REQUEST_METHOD] == GET_REQUEST_METHOD
         end
@@ -393,12 +479,56 @@ class Roda
 
         # Show information about current request, including request class,
         # request method and full path.
+        #
+        #   r.inspect
+        #   # => '#<Roda::RodaRequest GET /foo/bar>'
         def inspect
           "#<#{self.class.inspect} #{@env[REQUEST_METHOD]} #{full_path_info}>"
         end
 
-        # Does a terminal match on the input, matching only if the arguments
-        # have fully matched the patch.
+        # Does a terminal match on the current path, matching only if the arguments
+        # have fully matched the path.  If it matches, the match block is
+        # executed, and when the match block returns, the rack response is
+        # returned.
+        # 
+        #   r.path_info
+        #   # => "/foo/bar"
+        #
+        #   r.is 'foo' do
+        #     # does not match, as path isn't fully matched (/bar remaining)
+        #   end
+        #
+        #   r.is 'foo/bar' do
+        #     # matches as path is empty after matching
+        #   end
+        #
+        # If no arguments are given, matches if the path is already fully matched.
+        # 
+        #   r.on 'foo/bar' do
+        #     r.is do
+        #       # matches as path is already empty
+        #     end
+        #   end
+        #
+        # Note that this matches only if the path after matching the arguments
+        # is empty, not if it still contains a trailing slash:
+        #
+        #   r.path_info
+        #   # =>  "/foo/bar/"
+        #
+        #   r.is 'foo/bar' do
+        #     # does not match, as path isn't fully matched (/ remaining)
+        #   end
+        # 
+        #   r.is 'foo/bar/' do
+        #     # matches as path is empty after matching
+        #   end
+        # 
+        #   r.on 'foo/bar' do
+        #     r.is "" do
+        #       # matches as path is empty after matching
+        #     end
+        #   end
         def is(*args, &block)
           if args.empty?
             if @env[PATH_INFO] == EMPTY_STRING
@@ -410,11 +540,33 @@ class Roda
           end
         end
 
-        # Attempts to match on all of the arguments.  If all of the
-        # arguments match, control is yielded to the block, and after
-        # the block returns, the rack response will be returned.
-        # If any of the arguments fails, ensures the request state is
-        # returned to that before matches were attempted.
+        # Does a match on the path, matching only if the arguments
+        # have matched the path.  Because this doesn't fully match the
+        # path, this is usually used to setup branches of the routing tree,
+        # not for final handling of the request.
+        # 
+        #   r.path_info
+        #   # => "/foo/bar"
+        #
+        #   r.on 'foo' do
+        #     # matches, path is /bar after matching
+        #   end
+        #
+        #   r.on 'bar' do
+        #     # does not match
+        #   end
+        #
+        # Like other routing methods, If it matches, the match block is
+        # executed, and when the match block returns, the rack response is
+        # returned.  However, in general you will call another routing method
+        # inside the match block that fully matches the path and does the
+        # final handling for the request:
+        #
+        #   r.on 'foo' do
+        #     r.is 'bar' do
+        #       # handle /foo/bar request
+        #     end
+        #   end
         def on(*args, &block)
           if args.empty?
             always(&block)
@@ -423,26 +575,104 @@ class Roda
           end
         end
 
-        # The response related to the current request.
+        # The response related to the current request.  See ResponseMethods for
+        # instance methods for the response, but in general the most common usage
+        # is to override the response status and headers:
+        #
+        #   response.status = 200
+        #   response['Header-Name'] = 'Header value'
         def response
           scope.response
         end
 
-        # Immediately redirect to the given path.
+        # Immediately redirect to the path using the status code.  This ends
+        # the processing of the request:
+        #
+        #   r.redirect '/page1', 301 if r['param'] == 'value1'
+        #   r.redirect '/page2' # uses 302 status code
+        #   response.status = 404 # not reached
+        #   
+        # If you do not provide a path, by default it will redirect to the same
+        # path if the request is not a +GET+ request.  This is designed to make
+        # it easy to use where a +POST+ request to a URL changes state, +GET+
+        # returns the current state, and you want to show the current state
+        # after changing:
+        #
+        #   r.is "foo" do
+        #     r.get do
+        #       # show state
+        #     end
+        #   
+        #     r.post do
+        #       # change state
+        #       r.redirect
+        #     end
+        #   end
         def redirect(path=default_redirect_path, status=302)
           response.redirect(path, status)
           throw :halt, response.finish
         end
 
-        # If this is a GET request for the root ("/"), yield to the match block.
+        # Routing matches that only matches +GET+ requests where the current
+        # path is +/+.  If it matches, the match block is executed, and when
+        # the match block returns, the rack response is returned.
+        #
+        #   [r.request_method, r.path_info]
+        #   # => ['GET', '/']
+        #
+        #   r.root do
+        #     # matches
+        #   end
+        #
+        # This is usuable inside other match blocks:
+        #
+        #   [r.request_method, r.path_info]
+        #   # => ['GET', '/foo/']
+        #
+        #   r.on 'foo' do
+        #     r.root do
+        #       # matches
+        #     end
+        #   end
+        #
+        # Note that this does not match non-+GET+ requests:
+        #
+        #   [r.request_method, r.path_info]
+        #   # => ['POST', '/']
+        #
+        #   r.root do
+        #     # does not match
+        #   end
+        #
+        # Use <tt>r.post ""</tt> for +POST+ requests where the current path
+        # is +/+.
+        # 
+        # Nor does it match empty paths:
+        #
+        #   [r.request_method, r.path_info]
+        #   # => ['GET', '/foo']
+        #
+        #   r.on 'foo' do
+        #     r.root do
+        #       # does not match
+        #     end
+        #   end
+        #
+        # Use <tt>r.get true</tt> to handle +GET+ requests where the current
+        # path is empty.
         def root(&block)
           if @env[PATH_INFO] == SLASH && is_get?
             always(&block)
           end
         end
 
-        # Call the given rack app with the environment and immediately return
-        # the response as the response for this request.
+        # Call the given rack app with the environment and return the response
+        # from the rack app as the response for this request.  This ends
+        # the processing of the request:
+        #
+        #   r.run(proc{[403, {}, []]}) unless r['letmein'] == '1'
+        #   r.run(proc{[404, {}, []]})
+        #   response.status = 404 # not reached
         def run(app)
           throw :halt, app.call(@env)
         end
@@ -599,7 +829,7 @@ class Roda
         # Match files with the given extension.  Requires that the
         # request path end with the extension.
         def match_extension(ext)
-          consume(self.class.cached_matcher([:extension, ext]){"([^\\/]+?)\.#{ext}\\z"})
+          consume(self.class.cached_matcher([:extension, ext]){/([^\\\/]+)\.#{ext}/})
         end
 
         # Match by request method.  This can be an array if you want
@@ -664,12 +894,16 @@ class Roda
           @length  = 0
         end
 
-        # Return the response header with the given key.
+        # Return the response header with the given key. Example:
+        #
+        #   response['Content-Type'] # => 'text/html'
         def [](key)
           @headers[key]
         end
 
         # Set the response header with the given key to the given value.
+        #
+        #   response['Content-Type'] = 'application/json'
         def []=(key, value)
           @headers[key] = value
         end
@@ -687,19 +921,29 @@ class Roda
         # Modify the headers to include a Set-Cookie value that
         # deletes the cookie.  A value hash can be provided to
         # override the default one used to delete the cookie.
+        # Example:
+        #
+        #   response.delete_cookie('foo')
+        #   response.delete_cookie('foo', :domain=>'example.org')
         def delete_cookie(key, value = {})
           ::Rack::Utils.delete_cookie_header!(@headers, key, value)
         end
 
         # Whether the response body has been written to yet.  Note
         # that writing an empty string to the response body marks
-        # the response as not empty.
+        # the response as not empty. Example:
+        #
+        #   response.empty? # => true
+        #   response.write('a')
+        #   response.empty? # => false
         def empty?
           @body.empty?
         end
 
         # Return the rack response array of status, headers, and body
-        # for the current response.
+        # for the current response. Example:
+        #
+        #   response.finish # => [200, {'Content-Type'=>'text/html'}, []]
         def finish
           b = @body
           s = (@status ||= b.empty? ? 404 : 200)
@@ -707,19 +951,28 @@ class Roda
         end
 
         # Set the Location header to the given path, and the status
-        # to the given status.
+        # to the given status.  Example:
+        #
+        #   response.redirect('foo', 301)
+        #   response.redirect('bar')
         def redirect(path, status = 302)
           @headers[LOCATION] = path
           @status  = status
         end
 
         # Set the cookie with the given key in the headers.
+        #
+        #   response.set_cookie('foo', 'bar')
+        #   response.set_cookie('foo', :value=>'bar', :domain=>'example.org')
         def set_cookie(key, value)
           ::Rack::Utils.set_cookie_header!(@headers, key, value)
         end
 
         # Write to the response body.  Updates Content-Length header
-        # with the size of the string written.  Returns nil.
+        # with the size of the string written.  Returns nil. Example:
+        #
+        #   response.write('foo')
+        #   response['Content-Length'] # =>'3'
         def write(str)
           s = str.to_s