roda 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75b82517a1e80d73d99ea7d25a8bd543ba958e7c
-  data.tar.gz: 4bcb31a61b7f2658092fe80fb339a8651b718edd
+  metadata.gz: 3d246589728bb46404806737bb7e67819956f167
+  data.tar.gz: e57198e8df759bd70039ff42f94d86583c75c2f8
 SHA512:
-  metadata.gz: a8d8776bd1e9c282dc6d5df795a790a2272103421125233ffe5f6112c77c99d00f37f364c7879b73eb03aafd2c946e45e123c0e261f3ff7f1b576936a986e1ee
-  data.tar.gz: f8b85158682a132cd00d2a929532bb466a15c502f94abd54afcdaad35dde2fab96a2e2ff6d5b180b62220a6e0944de5ac824c0c25285bd04a8e8d39f959ad171
+  metadata.gz: 3127e9f7b7525780556555366e82b0e9f565216e62dacdd5e3e7a69e3440a47771ddad5472b94f7c09d15cf6acb49c7bcdb54fb1d469f68569eb5cf77e589dca
+  data.tar.gz: f6dd7cda1372931ce0bf92934d584e084f8b1b84d5a181ce1b28bcf951983adce7c477e6b4bdabdad9a8f0038cacafa49ba87948b46a38de0ad23b0b1330d86c

data/CHANGELOG

@@ -1,3 +1,73 @@
+= 1.2.0 (2014-12-17)
+
+* Don't override explicit nil :default_encoding template option in the render plugin (jeremyevans)
+
+* Add remaining_path and matched_path request methods (jeremyevans)
+
+* Add slash_path_emty plugin, for considering a path of "/" as empty when doing a terminal match (jeremyevans)
+
+* Remove def_verb_method request class method (jeremyevans)
+
+* Support :add_script_name, :name, :url, and :url_only options when creating named paths in the path plugin (jeremyevans)
+
+* Add match_affix plugin, for overriding default prefix/suffix used in match patterns (jeremyevans)
+
+* Add empty_root plugin, for making root matcher also match empty string (jeremyevans)
+
+* Add roda_class instance methods to RodaRequest and RodaResponse, to DRY up plugin code (jeremyevans)
+
+* Add sinatra_helpers plugin, porting Sinatra::Helpers methods not covered by other plugins (jeremyevans)
+
+* Don't set the default headers until the response is finished (jeremyevans)
+
+* Add RodaRequest#default_redirect_status, so plugins can override the default status used for redirects (jeremyevans)
+
+* Add drop_body plugin, for automatically dropping body and Content-{Length,Type} headers based on response status (jeremyevans)
+
+* Add clear_middleware! class method, for clearing the current middleware (jeremyevans)
+
+* Add inherit_middleware class accessor, allowing users to turn off middleware inheritance (jeremyevans)
+
+* Add multi_run plugin, for dispatching to multiple rack applications based on the request path prefix (jeremyevans)
+
+* Add environments plugin, for handling development/test/production environments (jeremyevans)
+
+* Do not cache templates by default if RACK_ENV is development (jeremyevans)
+
+* Add delay_build plugin, to delay building the rack app until Roda.app is called (jeremyevans)
+
+* Add :user_agent hash matcher to the header_matchers plugin (jeremyevans)
+
+* Fix caching of templates in the render plugin when :opts or :template_class is used (jeremyevans)
+
+* Require loading the render plugin again if you want to change the default layout (jeremyevans)
+
+* Pass :css_opts and :js_opts as template options (via :opts) instead of render options when rendering (jeremyevans)
+
+* Only pass :opts hash to template class during rendering, instead of all render/view options (jeremyevans)
+
+* Support :template_class option in the render plugin for overriding template class to use (jeremyevans)
+
+* Automatically dup unfrozen Array/Hash opts values when subclassing (jeremyevans)
+
+* Add named_templates plugin, for creating inline templates by name, instead of storing them in the file system (jeremyevans)
+
+* Support :template option in for render/view to specify template to use, instead of requiring separate argument (jeremyevans)
+
+* Add class_level_routing plugin, for a DSL similar to Sinatra (jeremyevans)
+
+* Make RodaRequest.consume_pattern not capture pattern by default (jeremyevans)
+
+* Add static_path_info plugin, making Roda not modify PATH_INFO or SCRIPT_NAME during routing (jeremyevans)
+
+* Use local/instance variable lookups instead of method calls to improve performance (jeremyevans)
+
+* Add RodaRequest#session, and have #session delegate to that (jeremyevans)
+
+* Add delegate plugin, for easily creating methods that delegate to request or response (jeremyevans)
+
+* Add mailer plugin, allowing use of a routing tree for email instead of web responses (jeremyevans)
+
 = 1.1.0 (2014-11-11)
 
 * Add assets plugin, for rendering assets on the fly, or compiling them to a single compressed file (cj, jeremyevans) (#5)

data/README.rdoc

@@ -1,6 +1,6 @@
 = Roda
 
-Roda is a routing tree web framework.
+Roda is a routing tree web framework toolkit.
 
 = Installation
 
@@ -17,10 +17,11 @@ IRC :: irc://chat.freenode.net/#roda
 == Inspiration
 
 Roda was inspired by {Sinatra}[http://www.sinatrarb.com] and {Cuba}[http://cuba.is],
-two other Ruby web frameworks.  It started out as a fork of Cuba, from which it borrows
-the idea of using a routing tree (which Cuba in turn took from
-{Rum}[https://github.com/chneukirchen/rum]).  From Sinatra it takes the ideas that
-route blocks should return the request bodies and that routes should be canonical.
+two other Ruby web frameworks.
+It started out as a fork of Cuba, from which it borrows the idea of using a routing tree
+(which Cuba in turn took from {Rum}[https://github.com/chneukirchen/rum]).
+From Sinatra, it takes the ideas that route blocks should return the request bodies
+and that routes should be canonical.
 It pilfers the idea for an extensible plugin system from the Ruby database library
 {Sequel}[http://sequel.jeremyevans.net].
 
@@ -67,77 +68,77 @@ Here's a simple application, showing how the routing tree works:
 
   run App.app
 
-Here's a breakdown of what is going on in the above block:
+Here's a breakdown of what is going on in the block above:
 
-After requiring the library and subclassing Roda, the +use+ method
-is called, which loads a rack middleware into the current
-application.
+After requiring the library and subclassing Roda, the +use+ method is called.
+This loads a Rack middleware into the current application.
 
-The +route+ block is called whenever a new request comes in, 
-and it is yielded an instance of a subclass of <tt>Rack::Request</tt>
-with some additional methods for matching routes.  By
-convention, this argument should be named +r+.
+The +route+ block is called whenever a new request comes in. 
+It is yielded an instance of a subclass of <tt>Rack::Request</tt>
+with some additional methods for matching routes.
+By convention, this argument should be named +r+.
 
 The primary way routes are matched in Roda is by calling
-+r.on+, +r.is+, +r.root+, +r.get+, or +r.post+.  These methods are
-calling the routing methods, and each of them takes a block. The
-block is referred to as a match block.
++r.on+, +r.is+, +r.root+, +r.get+, or +r.post+.
+Each of these "routing methods" takes a "match block".
 
 Each routing method takes each of the arguments (called matchers)
-given and tries to match them to the current request.  If it is
-able to match all of the arguments, it yields to the match block,
-otherwise the block is skipped and execution continues.
-
-+r.on+ matches if all of the arguments match.
-+r.is+ matches if all of the arguments match, and there are no
-further entries in the path after matching.
-+r.get+ when called without arguments matches any +GET+ request.
-+r.get+ when called with any arguments matches only if the
-current request is a +GET+ request and there are no further entries
-in the path after matching.
-+r.root+ only matches a +GET+ request where the current path is +/+.
-
-If a routing method matches and control is yielded to the match
-block, whenever the match block returns, Roda will return the
-rack response array of status, headers, and body, to the caller.
-
-If the match block returns a string and the response body hasn't
-already been written to, the block return value will interpreted
-as the body for the response.  If none of the routing methods match
-and the route block returns a string, it will be interpreted as the
-body for the response.
-
-+r.redirect+ immediately returns the response, allowing for
-code such as <tt>r.redirect(path) if some_condition</tt>. If
-called without arguments, it redirects to the current path if
-the current request method is not +GET+.
-
-The +.app+ at the end is an optimization, which you can leave
-off, but which saves a few methods call for every response.
+that is given and tries to match it to the current request.
+If the method is able to match all of the arguments, it yields to the match block;
+otherwise, the block is skipped and execution continues.
+
+- +r.on+ matches if all of the arguments match.
+- +r.is+ matches if all of the arguments match and there are no
+  further entries in the path after matching.
+- +r.get+ matches any +GET+ request when called without arguments.
+- +r.get+ (when called with any arguments) matches only if the
+  current request is a +GET+ request and there are no further entries
+  in the path after matching.
+- +r.root+ only matches a +GET+ request where the current path is +/+.
+
+If a routing method matches and control is yielded to the match block,
+whenever the match block returns, Roda will return the Rack response array
+(containing status, headers, and body) to the caller.
+
+If the match block returns a string
+and the response body hasn't already been written to,
+the block return value will be interpreted as the body for the response.
+If none of the routing methods match and the route block returns a string,
+it will be interpreted as the body for the response.
+
++r.redirect+ immediately returns the response,
+allowing for code such as <tt>r.redirect(path) if some_condition</tt>.
+If +r.redirect+ is called without arguments
+and the current request method is not +GET+, it redirects to the current path.
+
+The +.app+ at the end is an (optional) optimization.
+It saves a few method calls for every response.
 
 == The Routing Tree
 
-Roda is called a routing tree web framework because the way most
-sites are structured, routing takes the form of a tree based on the
-URL structure of the site.  In general, +r.on+ is used to split the
-tree into different branches, and +r.is+ is finalizes the routing,
-where the request is actually handled.
+Roda is called a routing tree web framework because the way most sites are structured,
+routing takes the form of a tree (based on the URL structure of the site).
+In general:
 
-So a simple routing tree may look something like this:
+- +r.on+ is used to split the tree into different branches.
+- +r.is+ finalizes the routing path.
+- +r.get+ and +r.post+ handle specific request methods.
+
+So, a simple routing tree might look something like this:
 
   r.on "a" do           # /a branch
     r.on "b" do         # /a/b branch
       r.is "c" do       # /a/b/c request
-        r.get do end    # GET /a/b/c request
+        r.get do end    # GET  /a/b/c request
         r.post do end   # POST /a/b/c request
       end
-      r.get "d" do end  # GET /a/b/d request
+      r.get "d" do end  # GET  /a/b/d request
       r.post "e" do end # POST /a/b/e request
     end
   end
 
-It's also possible to handle the same requests, but structure the
-routing tree by first branching on the request method:
+It's also possible to handle the same requests,
+but structure the routing tree by first branching on the request method:
 
   r.get do              # GET 
     r.on "a" do         # GET /a branch
@@ -157,42 +158,40 @@ routing tree by first branching on the request method:
     end
   end
 
-This allows you to easily separate your +GET+ request handling from
-your +POST+ request handling.  If you only have a small number of
-+POST+ request URLs and a large number of +GET+ request URLs, this
-may make things easier.
+This allows you to easily separate your +GET+ request handling
+from your +POST+ request handling.
+If you only have a small number of +POST+ request URLs
+and a large number of +GET+ request URLs, this may make things easier.
 
-However, in general routing first by the path and last by the
-request method is likely to lead to simpler and DRYer code. This
-is because at any point during the routing, you can act on the
-request.  For example, if all requests in the +/a+ branch need
-need access permission +A+ and all requests in the +/a/b+ branch
-need access permission +B+, you can easily handle this in the
-routing tree:
+However, routing first by the path and last by the request method
+is likely to lead to simpler and DRYer code.
+This is because you can act on the request at any point during the routing.
+For example, if all requests in the +/a+ branch need access permission +A+
+and all requests in the +/a/b+ branch need access permission +B+,
+you can easily handle this in the routing tree:
 
   r.on "a" do           # /a branch
     check_perm(:A)  
     r.on "b" do         # /a/b branch
       check_perm(:B)  
       r.is "c" do       # /a/b/c request
-        r.get do end    # GET /a/b/c request
+        r.get do end    # GET  /a/b/c request
         r.post do end   # POST /a/b/c request
       end
-      r.get "d" do end  # GET /a/b/d request
+      r.get "d" do end  # GET  /a/b/d request
       r.post "e" do end # POST /a/b/e request
     end
   end
 
-Being able to operate on the request at any point during the
-the routing is one of the major advantages of Roda compared
-to other web frameworks that do not use a routing tree.
+Being able to operate on the request at any point during the routing
+is one of the major advantages of Roda, as compared to frameworks
+that do not use a routing tree.
 
 == Matchers
 
-Other than +r.root+, the routing methods all take arguments called
-matchers.  If all of the matchers match, the routing method yields to
-the match block.  Here's an example showcasing how different
-matchers work:
+Other than +r.root+, the routing methods all take arguments called matchers.
+If all of the matchers match, the routing method yields to the match block.
+Here's an example showcasing how different matchers work:
 
   class App < Roda
     route do |r|
@@ -258,29 +257,28 @@ matchers work:
     end
   end
 
-Here's a description of the matchers.  Note that segment as used
-here means one part of the path preceeded by a +/+.  So a path such
-as +/foo/bar//baz+ has 4 segments, +/foo+, +/bar+, +/+ and +/baz+.
+Here's a description of the matchers.
+Note that "segment", as used here, means one part of the path preceded by a +/+.
+So, a path such as +/foo/bar//baz+ has four segments: +/foo+, +/bar+, +/+, and +/baz+.
 The +/+ here is considered the empty segment.
 
 === String
 
-If it does not contain a colon or slash, it matches single segment
-with the text of the string, preceeded by a slash.
+If a string does not contain a colon or slash, it matches a single segment
+containing the text of the string, preceded by a slash.
 
   ""    # matches "/"
   "foo" # matches "/foo"
   "foo" # does not match "/food"
 
-If it contains any slashes, it matches one additional segment for
-each slash:
+If a string contains any slashes, it matches one additional segment for each slash:
 
   "foo/bar" # matches "/foo/bar"
   "foo/bar" # does not match "/foo/bard"
 
-If it contains a colon followed by any <tt>\\w</tt> characters, the colon and
-remaing <tt>\\w</tt> characters matches any nonempty segment that contains at
-least one character:
+If a string contains a colon followed by any <tt>\\w</tt> characters,
+the colon and remaining <tt>\\w</tt> characters match any nonempty segment
+that contains at least one character:
 
   "foo/:id" # matches "/foo/bar", "/foo/baz", etc.
   "foo/:id" # does not match "/fo/bar"
@@ -295,8 +293,8 @@ You can prefix colons:
   "foo:x/bar:y" # matches "/food/bard", "/fool/bart", etc.
   "foo:x/bar:y" # does not match "/foo/bart", "/fool/bar", etc.
 
-If any colons are used, the block will yield one argument for
-each segment matched containing the matched text.  So:
+If any colons are used, the block will yield one argument
+for each segment matched containing the matched text, so:
 
   "foo:x/:y" # matching "/fool/bar" yields "l", "bar"
 
@@ -304,29 +302,28 @@ Colons that are not followed by a <tt>\\w</tt> character are matched literally:
 
   ":/a" # matches "/:/a"
 
-Note that strings are regexp escaped before being used in a regular
-expression, so:
+Note that strings must be escaped before being used in a regular expression, so:
 
   "\\d+(/\\w+)?" # matches "/\d+(/\w+)?"
   "\\d+(/\\w+)?" # does not match "/123/abc"
 
 === Regexp
 
-Regexps match one or more segments by looking for the pattern preceeded by a
-slash:
+Regexps match one or more segments by looking for the pattern,
+preceded by a slash:
 
   /foo\w+/ # matches "/foobar"
   /foo\w+/ # does not match "/foo/bar"
 
-If any patterns are captured by the regexp, they are yielded:
+If any patterns are captured by the Regexp, they are yielded:
 
   /foo\w+/   # matches "/foobar", yields nothing
   /foo(\w+)/ # matches "/foobar", yields "bar" 
 
 === Symbol
 
-Symbols match any nonempty segment, yielding the segment except for the
-preceeding slash:
+Symbols match any nonempty segment,
+yielding the segment except for the preceding slash:
 
   :id # matches "/foo" yields "foo"
   :id # does not match "/"
@@ -338,15 +335,15 @@ Procs match unless they return false or nil:
   proc{true}  # matches anything
   proc{false} # does not match anything
 
-Procs don't capture anything by default, but they can if you add
-the captured text to +r.captures+.
+Procs don't capture anything by default,
+but they can do so if you add the captured text to +r.captures+.
 
 === Arrays
 
-Arrays match when any of their elements matches.  If multiple matchers
-are given to +r.on+, they all must match (an AND condition), while
-if an array of matchers is given, only one needs to match (an OR
-condition).  Evaluation stops at the first matcher that matches.
+Arrays match when any of their elements match.
+If multiple matchers are given to +r.on+, they all must match (an AND condition).
+If an array of matchers is given, only one needs to match (an OR condition).
+Evaluation stops at the first matcher that matches.
 
 Additionally, if the matched object is a String, the string is yielded.
 This makes it easy to handle multiple strings without a Regexp:
@@ -376,7 +373,7 @@ block will be called with the value of the hash.
 
 ==== :all
 
-The :all matcher matches if all of the entries in the given array matches. So
+The +:all+ matcher matches if all of the entries in the given array match, so
 
   r.on :all=>[:a, :b] do
     # ...
@@ -388,48 +385,48 @@ is the same as:
     # ...
   end
 
-The reason it also exists as a separate hash matcher is so you can use it inside
-an array matcher. so:
+The reason it also exists as a separate hash matcher
+is so you can use it inside an array matcher, so:
 
   r.on ['foo', {:all=>['foos', :id]}] do
   end
 
-Would match +/foo+ and +/foos/10+, but not +/foos+.
+would match +/foo+ and +/foos/10+, but not +/foos+.
 
 ==== :extension
 
-The :extension matcher matches any nonempty path ending with the given extension:
+The +:extension+ matcher matches any nonempty path ending with the given extension:
 
   {:extension => "css"} # matches "/foo.css", "/bar.css"
   {:extension => "css"} # does not match "/foo.css/x", "/foo.bar", "/.css"
 
-This matcher yields the part before the extension.
+This matcher yields the part found before the period and extension (e.g., +foo+).
 
 ==== :method
 
-This matches the method of the request.  You can provide an array to specify multiple
-request methods and match on any of them:
+The +:method+ matcher matches the method of the request.
+You can provide an array to specify multiple request methods and match on any of them:
 
   {:method => :post}             # matches POST
   {:method => ['post', 'patch']} # matches POST and PATCH
 
 ==== :param
 
-The :param matcher matches if the given parameter is present, even if empty.
+The +:param+ matcher matches if the given parameter is present (even if it is empty).
 
   {:param => "user"} # matches "/foo?user=bar", "/foo?user="
   {:param => "user"} # does not matches "/foo"
 
 ==== :param!
 
-The :param! matcher matches if the given parameter is present and not empty.
+The +:param!+ matcher matches if the given parameter is present and not empty.
 
   {:param! => "user"} # matches "/foo?user=bar"
   {:param! => "user"} # does not matches "/foo", "/foo?user="
 
 === false, nil
 
-If false or nil is given directly as a matcher, it doesn't match anything.
+If +false+ or +nil+ is given directly as a matcher, it doesn't match anything.
 
 === Everything else
 
@@ -437,14 +434,15 @@ Everything else matches anything.
 
 == Status codes
 
-When it comes time to finalize a response, if a status code has not
-been set manually, it will use a 200 status code if anything has been
-written to the response, otherwise it will use a 404 status code.
-This enables the principle of least surprise to work, where if you
-don't handle an action, a 404 response is assumed.
+When it comes time to finalize a response,
+if a status code has not been set manually and anything has been written to the response,
+the response will use a 200 status code.
+Otherwise, it will use a 404 status code.
+This enables the principle of least surprise to work:
+if you don't handle an action, a 404 response is assumed.
 
-You can always set the status code manually via the status attribute
-for the response.
+You can always set the status code manually,
+via the +status+ attribute for the response.
 
   route do |r|
     r.get "hello" do
@@ -454,9 +452,10 @@ for the response.
 
 == Verb Methods
 
-The main match method is +r.on+, but as displayed above, you can also
-use +r.get+ or +r.post+.  When called without any arguments, these
-match as long as the request has the appropriate method, so:
+The main match method is +r.on+, but as displayed above,
+you can also use +r.get+ or +r.post+.
+When called without any arguments, these match as long
+as the request has the appropriate method, so:
 
   r.get do end
 
@@ -468,7 +467,7 @@ matches any +POST+ request
 
 If any arguments are given to the method, these match only
 if the request method matches, all arguments match, and
-only the path has been fully matched by the arguments.  So:
+only the path has been fully matched by the arguments, so:
 
   r.post "" do end
 
@@ -478,89 +477,91 @@ matches only +POST+ requests where the current path is +/+.
 
 matches only +GET+ requests where the current path is +/a/b+.
 
-The reason for this difference in behavior is that if you are not
-providing any arguments, you probably don't want to to also test
-for an exact match with the current path.  If that is something
-you do want, you can provide true as an argument:
+The reason for this difference in behavior is that
+if you are not providing any arguments, you probably don't want
+to also test for an exact match with the current path.
+If that is something you do want, you can provide +true+ as an argument:
 
   r.on "foo" do
     r.get true do # Matches GET /foo, not GET /foo/.*
     end
   end
 
-If you want to match the request method and do a partial match
-on the request path instead of a full match, you need to use
-+r.on+ with the <tt>:method</tt> hash matcher:
+If you want to match the request method
+and do only a partial match on the request path,
+you need to use +r.on+ with the <tt>:method</tt> hash matcher:
 
   r.on "foo", :method=>:get do # Matches GET /foo(/.*)?
   end
 
 == Root Method
 
-As displayed above, you can also use +r.root+ as a match method.  This
-method matches +GET+ requests where the current path +/+.  +r.root+ is
-similar to <tt>r.get ""</tt>, except that it does not consume the +/+ from the path.
+As displayed above, you can also use +r.root+ as a match method.
+This method matches +GET+ requests where the current path is +/+.
++r.root+ is similar to <tt>r.get ""</tt>,
+except that it does not consume the +/+ from the path.
 
 Unlike the other matching methods, +r.root+ takes no arguments.
 
-Note that +r.root+ does not match if the path is empty, you should use
-<tt>r.get true</tt> for that.  If you want to match either the
-the empty path or +/+, you can use <tt>r.get ["", true]</tt>.
+Note that +r.root+ does not match if the path is empty;
+you should use <tt>r.get true</tt> for that.
+If you want to match either the the empty path or +/+,
+you can use <tt>r.get ["", true]</tt>.
 
-Note that +r.root+ does not match non-GET requests, so to handle
-<tt>POST /</tt> requests, use <tt>r.post ''</tt>.
+Note that +r.root+ only matches +GET+ requests.
+So, to handle <tt>POST /</tt> requests, use <tt>r.post ''</tt>.
 
 == Request and Response
 
-While the request object is yielded to the route block, it is also
-available via the +request+ method.  Likewise, the response object
-is available via the +response+ method.
+While the request object is yielded to the +route+ block,
+it is also available via the +request+ method.
+Likewise, the response object is available via the +response+ method.
 
-The request object is an instance of a subclass of <tt>Rack::Request</tt>
-with some additional methods, and the response object is an
-instance of a subclass of <tt>Rack::Response</tt> with some additional
-methods.
+The request object is an instance of a subclass of <tt>Rack::Request</tt>,
+with some additional methods.
+The response object is an instance of a subclass of <tt>Rack::Response</tt>,
+with some additional methods.
 
-If you want to extend the request and response objects with additional
-modules, you can do so via the +request_module+ or +response_module+
-methods, or via plugins.
+If you want to extend the request and response objects with additional modules,
+you can do so via the +request_module+ or +response_module+ methods, or via plugins.
 
 == Pollution
 
-Roda tries very hard to avoid polluting the scope of the +route+
-block.  The only instance variables defined by default in the scope of
-the +route+ block are <tt>@_request</tt> and <tt>@_response</tt>.  The only methods defined
-(beyond the default methods for +Object+) are: +env+, +opts+, +request+,
-+response+, +call+, +session+, and +_route+ (private). Constants inside the
-Roda namespace are all prefixed with +Roda+ (e.g. <tt>Roda::RodaRequest</tt>).  This
-should make it unlikely that Roda will cause a namespace issue with your
-application code.
+Roda tries very hard to avoid polluting the scope of the +route+ block.
+This should make it unlikely that Roda will cause namespace issues
+with your application code:
+
+- The only instance variables defined by default in the scope of the +route+ block
+  are <tt>@_request</tt> and <tt>@_response</tt>.
+- The only methods defined (beyond the default methods for +Object+) are:
+  +env+, +opts+, +request+, +response+, +call+, +session+, and +_route+ (private).
+- Constants inside the Roda namespace are all prefixed with +Roda+
+  (e.g., <tt>Roda::RodaRequest</tt>).
 
 == Captures
 
-You may have noticed that some matchers yield a value to the block. The rules
-for determining if a matcher will yield a value are simple:
+You may have noticed that some matchers yield a value to the block.
+The rules for determining if a matcher will yield a value are simple:
 
 1. Regexp captures: <tt>/posts\/(\d+)-(.*)/</tt> will yield two values, corresponding to each capture.
 2. String placeholders: <tt>"users/:id"</tt> will yield the value in the position of +:id+.
 3. Symbols: +:foobar+ will yield if a segment is available.
 4. File extensions: <tt>:extension=>"css"</tt> will yield the basename of the matched file.
-5. Parameters: <tt>:param=>"user"</tt> will yield the value of the parameter user, if present.
+5. Parameters: <tt>:param=>"user"</tt> will yield the value of the parameter +user+, if present.
 
-The first case is important because it shows the underlying effect of regex
-captures.
+The first case is important because it shows the underlying effect of Regexp captures.
 
-In the second case, the substring +:id+ gets replaced by <tt>([^\\/]+)</tt> and the
-regexp becomes <tt>/users\/([^\/]+)/</tt> before performing the match, thus it reverts
-to the first form we saw.
+In the second case, the substring +:id+ gets replaced by <tt>([^\\/]+)</tt>
+and the Regexp becomes <tt>/users\/([^\/]+)/</tt> before performing the match.
+Thus, it reverts to the first form we saw.
 
-In the third case, the symbol, no matter what it says, gets replaced
-by <tt>/([^\\/]+)/</tt>, and again we are in presence of case 1.
+In the third case, the symbol, no matter what it says,
+gets replaced by <tt>/([^\\/]+)/</tt>, and again we are in presence of case 1.
 
 The fourth case, again, reverts to the basic matcher: it generates the string
 <tt>/([^\/]+?)\.#{ext}\z/</tt> before performing the match.
 
-The fifth case is different: it checks if the the parameter supplied is present
+The fifth case is different: it checks if the parameter supplied is present
 in the request (via POST or QUERY_STRING) and it pushes the value as a capture.
 
 == Composition
@@ -588,19 +589,19 @@ inside a Roda app, using +r.run+:
 
   run App.app
 
-This will take any path starting with +/api+ and send it to +API+.  In this
-example, +API+ is a Roda app, but it could easily be a Sinatra, Rails, or
-other Rack app.
+This will take any path starting with +/api+ and send it to +API+.
+In this example, +API+ is a Roda app, but it could easily be
+a Sinatra, Rails, or other Rack app.
 
-When you use +r.run+, Roda calls the given Rack app (+API+ in this
-case), and whatever the Rack app returns will be returned as the response
-for the current application.
+When you use +r.run+, Roda calls the given Rack app (+API+ in this case);
+whatever the Rack app returns will be returned
+as the response for the current application.
 
 === multi_route plugin
 
-If you are just looking to split up the main route block up by branches, you
-should use the +multi_route+ plugin, which keeps the current scope of
-the route block:
+If you are just looking to split up the main route block up by branches,
+you should use the +multi_route+ plugin,
+which keeps the current scope of the +route+ block:
 
   class App < Roda
     plugin :multi_route
@@ -620,20 +621,20 @@ the route block:
 
   run App.app
 
-This allows you to set instance variables in the main route block, and still
-have access to them inside the +api+ route block.
+This allows you to set instance variables in the main +route+ block
+and still have access to them inside the +api+ +route+ block.
 
 == Testing
 
 It is very easy to test Roda with {Rack::Test}[https://github.com/brynary/rack-test]
-or {Capybara}[https://github.com/jnicklas/capybara]. Roda's own tests use
-{RSpec}[http://rspec.info].  The default rake task will run the specs for Roda, if
-RSpec is installed.
+or {Capybara}[https://github.com/jnicklas/capybara].
+Roda's own tests use {RSpec}[http://rspec.info].
+The default Rake task will run the specs for Roda, if RSpec is installed.
 
 == Settings
 
-Each Roda app can store settings in the +opts+ hash. The settings are
-inherited if you happen to subclass +Roda+.  
+Each Roda app can store settings in the +opts+ hash.
+The settings are inherited if you happen to subclass +Roda+.  
 
   Roda.opts[:layout] = "guest"
 
@@ -645,26 +646,27 @@ inherited if you happen to subclass +Roda+.
   Users.opts[:layout] # => 'guest'
   Admin.opts[:layout] # => 'admin'
 
-Feel free to store whatever you find convenient.  Note that when subclassing,
-Roda only does a shallow clone of the settings.  If you store nested structures
-and plan to mutate them in subclasses, it is your responsibility to dup the nested
-structures inside +Roda.inherited+ (making sure to call +super+).  The
-plugins that ship with Roda all handle this.  Also, note that this means that
-future modifications to the parent class after subclassing do not affect the
-subclass.
+Feel free to store whatever you find convenient.
+Note that when subclassing, Roda only does a shallow clone of the settings.
+If you store nested structures and plan to mutate them in subclasses,
+it is your responsibility to dup the nested structures inside +Roda.inherited+
+(making sure to call +super+).
+The plugins that ship with Roda all handle this.
+Also, note that this means that modifications to the parent class
+made after subclassing do _not_ affect the subclass.
 
 == Rendering
 
-Roda ships with a +render+ plugin that provides helpers for rendering templates. It uses
-{Tilt}[https://github.com/rtomayko/tilt], a gem that interfaces with many template
-engines. The +erb+ engine is used by default.
+Roda ships with a +render+ plugin that provides helpers for rendering templates.
+It uses {Tilt}[https://github.com/rtomayko/tilt],
+a gem that interfaces with many template engines.
+The +erb+ engine is used by default.
 
-Note that in order to use this plugin you need to have Tilt installed, along
-with the templating engines you want to use.
+Note that in order to use this plugin you need to have Tilt installed,
+along with the templating engines you want to use.
 
 This plugin adds the +render+ and +view+ methods, for rendering templates.
-The difference between +render+ and +view+ is that +view+ will by default
-attempt to render the template inside the default layout template, where
+By default, +view+ will render the template inside the default layout template;
 +render+ will just render the template.
 
   class App < Roda
@@ -674,8 +676,8 @@ attempt to render the template inside the default layout template, where
       @var = '1'
 
       r.is "render" do
-        # Renders the views/home.erb template, which will have access to the
-        # instance variable @var, as well as local variable content
+        # Renders the views/home.erb template, which will have access to
+        # the instance variable @var, as well as local variable content.
         render("home", :locals=>{:content => "hello, world"})
       end
 
@@ -706,9 +708,10 @@ You can override the default rendering options by passing a hash to the plugin:
 
 == Sessions
 
-By default, Roda doesn't turn on sessions, but most users are going to
-want to turn on session support, and the simplest way to do that is to
-use the <tt>Rack::Session::Cookie</tt> middleware that comes with rack:
+By default, Roda doesn't turn on sessions,
+but most users are going to want to turn on session support.
+The simplest way to do this is to use the <tt>Rack::Session::Cookie</tt> middleware
+that comes with Rack:
 
   require "roda"
 
@@ -718,39 +721,39 @@ use the <tt>Rack::Session::Cookie</tt> middleware that comes with rack:
 
 == Security
 
-Web application security is a very large topic, but here are some
-things you can do with Roda to prevent some common web application
-vulnerabilities.
+Web application security is a very large topic,
+but here are some things you can do with Roda
+to prevent some common web application vulnerabilities.
 
 === Session Security
 
-If you are using sessions, you should also always set a session
-secret using the +:secret+ option as shown above.  Make sure this
-secret is not disclosed, because if an attacker knows the +:secret+
-value, they can inject arbitrary session values, which in the worst case
-scenario can lead to remote code execution.
+If you are using sessions, you should also always set a session secret,
+using the +:secret+ option as shown above.
+Make sure that this secret is not disclosed,
+because if an attacker knows the +:secret+ value,
+they can inject arbitrary session values.
+In the worst case scenario, this can lead to remote code execution.
 
-Keep in mind that with <tt>Rack::Session::Cookie</tt>, the content in
-the session cookie is not encrypted, just signed to prevent tampering.
-This means you should not store any data in the session that itself is
-secret.
+Keep in mind that with <tt>Rack::Session::Cookie</tt>,
+the content in the session cookie is not encrypted,
+just signed to prevent tampering.
+This means you should not store any secret data in the session.
 
 === Cross Site Request Forgery (CSRF)
 
 CSRF can be prevented by using the +csrf+ plugin that ships with Roda,
-which uses the {rack_csrf}[https://github.com/baldowl/rack_csrf]
-library.  Just make sure that you include the CSRF token tags in your
-html as appropriate.
+which uses the {rack_csrf}[https://github.com/baldowl/rack_csrf] library.
+Just make sure that you include the CSRF token tags in your HTML, as appropriate.
 
-It's also possible to use the <tt>Rack::Csrf</tt> middleware directly,
+It's also possible to use the <tt>Rack::Csrf</tt> middleware directly;
 you don't have to use the +csrf+ plugin.
 
 === Cross Site Scripting (XSS)
 
 The easiest way to prevent XSS with Roda is to use a template library
-that automatically escapes output by default.  The +:escape+ option
-to the render plugin sets the ERB template processor to escape by
-default, so that in your templates:
+that automatically escapes output by default.
+The +:escape+ option to the +render+ plugin sets the ERb template processor
+to escape by default, so that in your templates:
 
   <%= '<>' %>  # outputs &lt;&gt; 
   <%== '<>' %> # outputs <>
@@ -759,10 +762,10 @@ This support requires {Erubis}[http://www.kuwata-lab.com/erubis/].
 
 === Other
 
-For prevention of some other vulnerabilities, such as click-jacking,
-directory traversal, session hijacking, and IP spoofing, consider using
-{Rack::Protection}[https://github.com/rkh/rack-protection], which is
-a rack middleware that can be added the usual way:
+For prevention of some other vulnerabilities,
+such as click-jacking, directory traversal, session hijacking, and IP spoofing,
+consider using {Rack::Protection}[https://github.com/rkh/rack-protection].
+This is a Rack middleware that can be added in the usual way:
 
   require 'roda'
   require 'rack/protection'
@@ -773,63 +776,17 @@ a rack middleware that can be added the usual way:
 
 == Plugins
 
-Roda provides a way to extend its functionality with plugins.  Plugins can
-override any Roda method and call +super+ to get the default behavior.
-
-=== Included Plugins
-
-These plugins ship with roda:
-
-all_verbs :: Adds routing methods to the request for all http verbs.
-assets :: Adds support for rendering CSS/JS javascript assets on the fly
-          in development, or compiling them into a single compressed file
-          in production.
-backtracking_array :: Allows array matchers to backtrack if later matchers
-                      do not match.
-caching :: Adds request and response methods related to http caching.
-chunked :: Adds support for streaming template responses using
-           Transfer-Encoding: chunked.
-content_for :: Allows storage of content in one template and retrieval of
-               that content in a different template.
-csrf :: Adds CSRF protection and helper methods using
-        {rack_csrf}[https://github.com/baldowl/rack_csrf].
-default_headers :: Override the default response headers used.
-error_email :: Adds an +error_email+ method that can be used to email when
-               an exception is raised.
-error_handler :: Adds a +error+ block that is called for all responses that
-                 raise exceptions.
-flash :: Adds a flash handler.
-h :: Adds h method for html escaping.
-halt :: Augments request#halt method to take status and/or body or status,
-        headers, and body.
-head :: Treat HEAD requests like GET requests with an empty response body.
-header_matchers :: Adds host, header, and accept hash matchers.
-hooks :: Adds before and after methods to run code before and after requests.
-indifferent_params :: Adds params method with indifferent access to params,
-                      allowing use of symbol keys for accessing params.
-json :: Allows match blocks to return arrays and hashes, using a json
-        representation as the response body.
-middleware :: Allows the Roda app to be used as a rack middleware, calling the
-              next middleware if no route matches.
-multi_route :: Adds the ability for multiple named route blocks, with the
-               ability to dispatch to them add any point in the main route block.
-not_allowed :: Adds support for automatically returning 405 Method Not Allowed
-               responses.
-not_found :: Adds a +not_found+ block that is called for all 404 responses
-             without bodies.
-pass :: Adds a pass method allowing you to skip the current +r.on+ block as if
-        it did not match.
-path :: Adds support for named paths.
-per_thread_caching :: Switches the thread-safe cache from a shared cache to a
-                      per-thread cache.
-render :: Adds support for rendering templates via tilt, as described above.
-render_each :: Render a template for each value in an enumerable.
-streaming :: Adds support for streaming responses.
-symbol_matchers :: Adds support for symbol-specific matching regexps.
-symbol_views :: Allows match blocks to return template name symbols, uses the
-                template view as the response body.
-view_subdirs :: Allows for setting a view subdirectory to use on a per-request
-                basis.
+By design, Roda has a very small core, providing only the essentials.
+All nonessential features are added via plugins.
+This is why Roda is referred to as a routing tree web framework toolkit.
+Using a combination of Roda plugins,
+you can build the routing tree web framework that needs your needs.
+
+Roda's plugins can override any Roda method and call +super+
+to get the default behavior, which makes Roda very extensible.
+
+{Roda ships with a large number of plugins}[http://roda.jeremyevans.net/documentation.html#included-plugins],
+and {some other libraries ship with support for Roda}[http://roda.jeremyevans.net/documentation.html#external].
 
 === External Plugins
 
@@ -841,8 +798,8 @@ autoforme :: Adds support for easily creating a simple administrative front
 
 === How to create plugins
 
-Authoring your own plugins is pretty straightforward.  Plugins are just modules,
-which may contain any of the following modules:
+Authoring your own plugins is pretty straightforward.
+Plugins are just modules, which may contain any of the following modules:
 
 InstanceMethods :: module included in the Roda class
 ClassMethods :: module that extends the Roda class
@@ -851,16 +808,16 @@ RequestClassMethods :: module extending the class of the request
 ResponseMethods :: module included in the class of the response
 ResponseClassMethods :: module extending the class of the response
 
-If the plugin responds to +load_dependencies+, it will be called first, and should
-be used if the plugin depends on another plugin.
+If the plugin responds to +load_dependencies+, it will be called first,
+and should be used if the plugin depends on another plugin.
 
-If the plugin responds to +configure+, it will be called last, and should be
-used to configure the plugin.
+If the plugin responds to +configure+, it will be called last,
+and should be used to configure the plugin.
 
-Both +load_dependencies+ and +configure+ are called with the additional arguments
-and block given to the plugin call.
+Both +load_dependencies+ and +configure+ are called
+with the additional arguments and block that was given to the plugin call.
 
-So a simple plugin to add an instance method would be:
+So, a simple plugin to add an instance method would be:
 
   module MarkdownHelper
     module InstanceMethods
@@ -874,14 +831,15 @@ So a simple plugin to add an instance method would be:
 
 === Registering plugins
 
-If you want to ship a Roda plugin in a gem, but still have
-Roda load it automatically via <tt>Roda.plugin :plugin_name</tt>, you should
-place it where it can be required via +roda/plugins/plugin_name+, and
-then have the file register it as a plugin via
-<tt>Roda::RodaPlugins.register_plugin</tt>.  It's recommended but not required
-that you store your plugin module in the <tt>Roda::RodaPlugins</tt> namespace:
+If you want to ship a Roda plugin in a gem,
+but still have Roda load it automatically via <tt>Roda.plugin :plugin_name</tt>,
+you should place it where it can be required via +roda/plugins/plugin_name+
+and then have the file register it as a plugin via
+<tt>Roda::RodaPlugins.register_plugin</tt>.
+It's recommended, but not required, that you store your plugin module
+in the <tt>Roda::RodaPlugins</tt> namespace:
 
-  module Roda
+  class Roda
     module RodaPlugins
       module Markdown
         module InstanceMethods
@@ -895,10 +853,11 @@ that you store your plugin module in the <tt>Roda::RodaPlugins</tt> namespace:
     end
   end
 
-You should avoid creating your module directly in the +Roda+ namespace
-to avoid polluting the namespace.  Additionally, any instance variables
-created inside InstanceMethods should be prefixed with an underscore
-(e.g. <tt>@_variable</tt>) to avoid polluting the scope.
+To avoid namespace pollution,
+you should avoid creating your module directly in the +Roda+ namespace.
+Additionally, any instance variables created inside +InstanceMethods+
+should be prefixed with an underscore (e.g., <tt>@_variable</tt>)
+to avoid polluting the scope.
 
 == License