roda-cj 0.9.6 → 1.0.0

data/CHANGELOG

@@ -1,5 +1,21 @@
 = HEAD
 
+* Support adding middleware after the route block has been added (jeremyevans)
+
+* Allow Roda subclasses to use route block from superclass (jeremyevans)
+
+* Have r.multi_route ignore non-String named routes (jeremyevans)
+
+* Pick up newly added named routes while running in the multi_route plugin, useful for development (jeremyevans)
+
+* Add path plugin, for named path support (jeremyevans) (#4)
+
+* Add error_email plugin, for easily emailing an error notification for an exception (jeremyevans)
+
+= 1.0.0 (2014-08-19)
+
+* Don't have :extension hash matcher force a terminal match (jeremyevans)
+
 * Add :content option to view method in render plugin to use given content instead of rendering a template (jeremyevans)
 
 * Add :escape option to render plugin for using erb templates where <%= %> escapes and <%== %> does not (jeremyevans)

data/README.rdoc

@@ -35,25 +35,30 @@ Here's a simple application, showing how the routing tree works:
     use Rack::Session::Cookie, :secret => ENV['SECRET']
 
     route do |r|
-      # matches any GET request
-      r.get do
+      # GET / request
+      r.root do
+        r.redirect "/hello"
+      end
 
-        # matches GET /
-        r.root do
-          r.redirect "/hello"
-        end
+      # /hello branch
+      r.on "hello" do
 
-        # matches GET /hello or GET /hello/.*
-        r.on "hello" do
+        # GET /hello/world request
+        r.get "world" do
+          "Hello world!"
+        end
 
-          # matches GET /hello/world
-          r.is "world" do
-            "Hello world!"
+        # /hello request
+        r.is do
+          # GET /hello request
+          r.get do
+            "Hello!"
           end
 
-          # matches GET /hello
-          r.is do
-            "Hello!"
+          # POST /hello request
+          r.post do
+            puts "Someone said hello!"
+            r.redirect
           end
         end
       end
@@ -62,8 +67,6 @@ Here's a simple application, showing how the routing tree works:
 
   run App.app
 
-You can now run +rackup+ and enjoy what you have just created.
-
 Here's a breakdown of what is going on in the above block:
 
 After requiring the library and subclassing Roda, the +use+ method
@@ -76,34 +79,120 @@ 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+, or a method like +r.get+ or +r.is+ which calls +r.on+.
-+r.on+ takes each of the arguments given and tries to match them to
-the current request.  If it is able to successfully match
-all of the arguments, it yields to the +r.on+ block, otherwise
-it returns immediately.
-
-+r.get+ is a shortcut that matches any GET request, and
-+r.is+ is a shortcut that ensures the the exact route is
-matched and there are no further entries in the path.
-
-If +r.on+ matches and control is yielded to the block, whenever
-the block returns, the response will be returned.  If the 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 +r.on+ blocks match and the
-route block returns a string, it will be interpreted as the body
-for the response.
++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.
+
+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>.
+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.
 
+== 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.
+
+So a simple routing tree may 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.post do end   # POST /a/b/c request
+      end
+      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:
+
+  r.get do              # GET 
+    r.on "a" do         # GET /a branch
+      r.on "b" do       # GET /a/b branch
+        r.is "c" do end # GET /a/b/c request
+        r.is "d" do end # GET /a/b/d request
+      end
+    end
+  end
+
+  r.post do             # POST
+    r.on "a" do         # POST /a branch
+      r.on "b" do       # POST /a/b branch
+        r.is "c" do end # POST /a/b/c request
+        r.is "e" do end # POST /a/b/e request
+      end
+    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.
+
+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:
+
+  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.post do end   # POST /a/b/c request
+      end
+      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.
+
 == Matchers
 
-Here's an example showcasing how different matchers work.  Matchers
-are arguments passed to +r.on+.
+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|
@@ -136,7 +225,6 @@ are arguments passed to +r.on+.
 
           # /username/foobar/posts
           r.is "posts" do
-
             # You can access user here, because the blocks are closures.
             "Total Posts: #{user.posts.size}" #=> "Total Posts: 6"
           end
@@ -158,7 +246,7 @@ are arguments passed to +r.on+.
         r.is "login" do
 
           # POST /login, user: foo, pass: baz
-          r.on {:param=>"user"}, {:param=>"pass"} do |user, pass|
+          r.on({:param=>"user"}, {:param=>"pass"}) do |user, pass|
             "#{user}:#{pass}" #=> "foo:baz"
           end
 
@@ -180,75 +268,75 @@ The +/+ here is considered the empty segment.
 If it does not contain a colon or slash, it matches single segment
 with the text of the string, preceeded by a slash.
 
-  "" matches "/"
-  "foo" matches "/foo"
-  "foo" does not match "/food"
+  ""    # matches "/"
+  "foo" # matches "/foo"
+  "foo" # does not match "/food"
 
 If it contains any slashes, it matches one additional segment for
 each slash:
 
-  "foo/bar" matches "/foo/bar"
-  "foo/bar" does not match "/foo/bard"
+  "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:
 
-  "foo/:id" matches "/foo/bar", "/foo/baz", etc.
-  "foo/:id" does not match "/fo/bar"
+  "foo/:id" # matches "/foo/bar", "/foo/baz", etc.
+  "foo/:id" # does not match "/fo/bar"
 
 You can use multiple colons in a string:
 
-  ":x/:y" matches "/foo/bar", "/bar/foo" etc.
-  ":x/:y" does not match "/foo", "/bar/"
+  ":x/:y" # matches "/foo/bar", "/bar/foo" etc.
+  ":x/:y" # does not match "/foo", "/bar/"
 
 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.
+  "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:
 
-  "foo:x/:y" matching "/fool/bar" yields "l", "bar"
+  "foo:x/:y" # matching "/fool/bar" yields "l", "bar"
 
 Colons that are not followed by a <tt>\\w</tt> character are matched literally:
 
-  ":/a" matches "/:/a"
+  ":/a" # matches "/:/a"
 
 Note that strings are regexp escaped before being used in a regular
 expression, so:
 
-  "\\d+(/\\w+)?" matches "\d+(/\w+)?"
-  "\\d+/\\w+" does not match "123/abc"
+  "\\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:
 
-  /foo\w+/ matches "/foobar"
-  /foo\w+/ does not match "/foo/bar"
+  /foo\w+/ # matches "/foobar"
+  /foo\w+/ # does not match "/foo/bar"
 
 If any patterns are captured by the regexp, they are yielded:
 
-  /foo\w+/ matches "/foobar", yields nothing
-  /foo(\w+)/ matches "/foobar", yields "bar" 
+  /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:
 
-  :id matches "/foo" yields "foo"
-  :id does not match "/"
+  :id # matches "/foo" yields "foo"
+  :id # does not match "/"
 
 === Proc
 
 Procs match unless they return false or nil:
 
-  proc{true} matches anything
-  proc{false} does not match anything
+  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+.
@@ -263,8 +351,8 @@ 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:
 
-  %w'page1 page2' matches "/page1", "/page2"
-  [] does not match anything
+  ['page1', 'page2'] # matches "/page1", "/page2"
+  []                 # does not match anything
 
 === Hash
 
@@ -276,12 +364,12 @@ block will be called with the value of the hash.
 
   class App < Roda
     hash_matcher(:foo) do |v|
-      ...
+      # ...
     end
     
     route do |r|
       r.on :foo=>'bar' do
-        ...
+        # ...
       end
     end
   end
@@ -291,13 +379,13 @@ block will be called with the value of the hash.
 The :all matcher matches if all of the entries in the given array matches. So
 
   r.on :all=>[:a, :b] do
-    ...
+    # ...
   end
 
 is the same as:
 
   r.on :a, :b do
-    ...
+    # ...
   end
 
 The reason it also exists as a separate hash matcher is so you can use it inside
@@ -312,34 +400,32 @@ Would match +/foo+ and +/foos/10+, but not +/foos+.
 
 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"
+  {: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.  Note that unlike other
-matchers, this matcher assumes terminal behavior, it doesn't match if there
-are additional segments.
+This matcher yields the part before the extension.
 
 ==== :method
 
 This 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 => %w'post patch' matches POST and PATCH
+  {: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.
 
-  :param => "user" matches "/foo?user=bar", "/foo?user="
-  :param => "user" does not matches "/foo"
+  {: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.
 
-  :param! => "user" matches "/foo?user=bar"
-  :param! => "user" does not matches "/foo", "/foo?user="
+  {:param! => "user"} # matches "/foo?user=bar"
+  {:param! => "user"} # does not matches "/foo", "/foo?user="
 
 === false, nil
 
@@ -361,10 +447,8 @@ You can always set the status code manually via the status attribute
 for the response.
 
   route do |r|
-    r.get do
-      r.is "hello" do
-        response.status = 200
-      end
+    r.get "hello" do
+      response.status = 200
     end
   end
 
@@ -372,22 +456,27 @@ for the response.
 
 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
-call +r.on+ as long as the request has the appropriate method, so:
+match as long as the request has the appropriate method, so:
+
+  r.get do end
 
-    r.get{}
+matches any +GET+ request, and
 
-is syntax sugar for:
+  r.post do end
 
-    r.on{} if r.get? 
+matches any +POST+ request
 
-If any arguments are given to the method, these call +r.is+ as long as
-the request has the appropriate method, so:
+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:
 
-    r.post(""){}
+  r.post "" do end
 
-is syntax sugar for:
+matches only +POST+ requests where the current path is +/+.
 
-    r.is(""){} if r.post?
+  r.get "a/b" do end
+
+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
@@ -400,17 +489,17 @@ you do want, you can provide true as an argument:
   end
 
 If you want to match the request method and do a partial match
-on the request path, you need to use +r.on+ with the <tt>:method</tt>
-hash matcher:
+on the request path instead of a full match, you need to use
++r.on+ with the <tt>:method</tt> hash matcher:
 
   r.on "foo", :method=>:get do # Matches GET /foo(/.*)?
-  edn
+  end
 
 == Root Method
 
 As displayed above, you can also use +r.root+ as a match method.  This
-method matches <tt>GET /</tt> requests.  +r.root+ is similar to <tt>r.get ""</tt>,
-except that it does not consume the +/+ from the path.
+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.
 
 Unlike the other matching methods, +r.root+ takes no arguments.
 
@@ -438,8 +527,8 @@ methods, or via plugins.
 
 == Pollution
 
-Roda tries very hard to avoid polluting the scope in which the +route+
-block operates.  The only instance variables defined by default in the scope of
+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
@@ -476,8 +565,8 @@ in the request (via POST or QUERY_STRING) and it pushes the value as a capture.
 
 == Composition
 
-You can mount a Roda app, along with middlewares, inside another Roda app,
-via +r.run+:
+You can mount any Rack app (including another Roda app), with its own middlewares,
+inside a Roda app, using +r.run+:
 
   class API < Roda
     use SomeMiddleware
@@ -499,13 +588,24 @@ via +r.run+:
 
   run App.app
 
-You can also use the +multi_route+ plugin, which keeps the current scope of
+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.
+
+=== 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:
 
   class App < Roda
     plugin :multi_route
 
-    route :api do |r|
+    route "api" do |r|
       r.is do
         # ...
       end
@@ -513,13 +613,16 @@ the route block:
 
     route do |r|
       r.on "api" do
-        route :api
+        r.route "api"
       end
     end
   end
 
   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.
+
 == Testing
 
 It is very easy to test Roda with {Rack::Test}[https://github.com/brynary/rack-test]
@@ -656,6 +759,8 @@ Note that unlike most other render options, the :escape option
 must be passed to the <tt>plugin :render</tt> call, it won't be
 respected if added later.
 
+This support requires {Erubis}[http://www.kuwata-lab.com/erubis/].
+
 === Other
 
 For prevention of some other vulnerabilities, such as click-jacking,
@@ -687,6 +792,8 @@ content_for :: Allows storage of content in one template and retrieval of
 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.
@@ -710,6 +817,7 @@ 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.