roda 2.26.0 → 2.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ac08181ea0c35fe056de0d73654c46acd01a541
-  data.tar.gz: bafe66a0feb7e5b3e4d461f8eb05fd3762ccf730
+  metadata.gz: e2d73336ee24aee0fa3afe57096ef4d2f47c14f5
+  data.tar.gz: 9c0dbc60da0f5d73a24ad48a807f413c0f84e300
 SHA512:
-  metadata.gz: '01974a864d4ba36f2173c6a166405f77359a8329e8ae8a7eba65ad1b28549377c52ca50fc4e61f61a828c2323fb5bb1d2dc80bcdb555449117c227144f8d3160'
-  data.tar.gz: bfec42253904890e2ba6104f9d07b47eae8a3ade1cb45e43f36f5def8280219bce70baec7322545e4040195d5d946ec8038002e6e73edfe15e18c48151d261bb
+  metadata.gz: d0e19332b1d9c17b18d4d9e3514a90389e65373508874b41521c3fb4fcfa4f0dc97da1fdfbb09273c9b84ac08addf4c286d85c4467538a1481e459a5307c6ae2
+  data.tar.gz: 4d7de5e3b2331e0e9a6c1983a2b79ba2a5f6d5e105b6d7fd8f5acf5d52128f34762cabf68627e5f2866415667fbfcd41b23f7fc315a0ea14ab52cb88b19217ba

data/CHANGELOG

@@ -1,3 +1,11 @@
+= 2.27.0 (2017-06-14)
+
+* Add class_matchers plugin for matching other classes (in addition to String/Integer), with user specified regexps and type conversion (jeremyevans)
+
+* Support String class matcher for non-empty segments, same behavior as symbol matchers but more intuitive and DRY (jeremyevans)
+
+* Support Integer class matcher for \d+ segments, yielding matched values as integers (jeremyevans)
+
 = 2.26.0 (2017-05-16)
 
 * Support :skip_middleware option to csrf plugin to add only the methods and not add the middleware (luciusgone) (#118)

data/README.rdoc

@@ -227,12 +227,12 @@ Here's an example showcasing how different matchers work:
       end
 
       # GET /post/2011/02/16/hello
-      r.get "post", :y, :m, :d, :slug do |y, m, d, slug|
-        "#{y}-#{m}-#{d} #{slug}" #=> "2011-02-16 hello"
+      r.get "post", Integer, Integer, Integer, String do |year, month, day, slug|
+        "#{year}-#{month}-#{day} #{slug}" #=> "2011-02-16 hello"
       end
 
       # GET /username/foobar branch
-      r.on "username", :username, :method=>:get do |username|
+      r.on "username", String, :method=>:get do |username|
         user = User.find_by_username(username)
 
         # GET /username/foobar/posts
@@ -300,8 +300,8 @@ You can use multiple colons in a string:
 Note that instead of using colons in strings, it is recommended to use separate
 symbol arguments, as it is faster and simpler:
 
-  "foo", :id # instead of "foo/:id"
-  :x, :y     # instead of ":x/:y"
+  "foo", String # instead of "foo/:id"
+  String, String     # instead of ":x/:y"
 
 It is possible in future versions of Roda, colons will not be treated specially
 in strings, and will just match a literal colon character.
@@ -325,6 +325,25 @@ If any patterns are captured by the Regexp, they are yielded:
   /foo\w+/   # matches "/foobar", yields nothing
   /foo(\w+)/ # matches "/foobar", yields "bar" 
 
+=== Class
+
+There are two classes that are supported as matchers, String
+and Integer.
+
+String :: matches any non-empty segment
+Integer :: matches any segment of 0-9, returns matched values as integers
+
+Using String and Integer is the recommended way to handle
+arbitrary segments
+
+  String # matches "/foo", yields "foo"
+  String # matches "/1", yields "1"
+  String # does not match "/"
+
+  Integer # does not match "/foo"
+  Integer # matches "/1", yields 1
+  Integer # does not match "/"
+
 === Symbol
 
 Symbols match any nonempty segment,
@@ -333,6 +352,11 @@ yielding the segment except for the preceding slash:
   :id # matches "/foo" yields "foo"
   :id # does not match "/"
 
+Symbol matchers operate the same as the class String matcher,
+and is the historical way to do arbitrary segment matching.
+It is recommended to use the class String matcher in new code
+as it is a bit more intuitive.
+
 === Proc
 
 Procs match unless they return false or nil:
@@ -381,20 +405,20 @@ allows for easily defining your own:
 
 The +:all+ matcher matches if all of the entries in the given array match, so
 
-  r.on :all=>[:a, :b] do
+  r.on :all=>[String, String] do
     # ...
   end
 
 is the same as:
 
-  r.on :a, :b do
+  r.on String, String do
     # ...
   end
 
 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
+  r.on ['foo', {:all=>['foos', Integer]}] do
   end
 
 would match +/foo+ and +/foos/10+, but not +/foos+.
@@ -413,7 +437,9 @@ If +false+ or +nil+ is given directly as a matcher, it doesn't match anything.
 
 === Everything else
 
-Everything else matches anything.
+Everything else matches anything.  Note that future versions of Roda will probably
+raise exceptions for unsupported matchers, so it is not recommended to rely on this
+behavior.
 
 == Optional segments
 
@@ -424,11 +450,11 @@ the item's id, and 456 being some optional data.
 The simplest way to handle this is by treating this as two separate routes with a
 shared branch:
 
-  r.on "items", :id do |item_id|
+  r.on "items", String do |item_id|
     # Shared code for branch here
 
     # /items/123/456
-    r.is :opt_data do |optional_data|
+    r.is String do |optional_data|
     end
 
     # /items/123
@@ -440,7 +466,7 @@ This works well for many cases, but there are also cases where you really want t
 treat it as one route with an optional segment.  One simple way to do that is to
 use a parameter instead of an optional segment (e.g. +/items/123?opt=456+).
 
-  r.is "items", :id do |item_id|
+  r.is "items", Integer do |item_id|
     optional_data = r['opt']
   end
 
@@ -448,7 +474,7 @@ However, if you really do want to use a optional segment, there are a couple dif
 ways to use matchers to do so.  One is using an array matcher where the last element
 is true:
 
-  r.is "items", :id, [:opt_data, true] do |item_id, optional_data|
+  r.is "items", Integer, [String, true] do |item_id, optional_data|
   end
 
 Note that this technically yields only one argument instead of two arguments if the

data/doc/release_notes/2.27.0.txt

@@ -0,0 +1,56 @@
+= New Features
+
+* String and Integer class matchers have been added.  The
+  String class matches any non-empty segment and yields it as a
+  string.  This is the same as the behavior of the symbol matchers,
+  but without the duplication.  So instead of:
+
+    r.is "album", :album_name do |album_name|
+    end
+
+  you can now do:
+
+    r.is "album", String do |album_name|
+    end
+
+  This makes it a bit more intuitive that you want to match
+  any string, and avoids the redundancy between the symbol
+  name and block argument name.
+
+  The Integer class matches any integer segment (\d+) and yields it
+  as an integer:
+
+    r.is "album", Integer do |album_id|
+      # does not match "/albums/foo"
+      # matches "/albums/1", yielding 1 (not "1")
+    end
+
+  Previously, the :d matcher in the symbol_matchers plugin could
+  be used to only match integer segments, but it yielded results
+  as strings and not integers, so you still needed to convert the
+  type manually.  Using Integer is a bit more intuitive than
+  using :d, and it handles the type conversion for you.
+
+* A class_matchers plugin has been added for matching additional
+  classes, with user-specified regexps and type conversion.  For
+  example, if you want to match YYYY-MM-DD segments and yield
+  them to the match blocks as ruby Date objects, you can do:
+
+    plugin :class_matchers
+
+    class_matcher(Date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
+      [Date.new(y.to_i, m.to_i, d.to_i)]
+    end
+
+  and then in your routing tree, you can do:
+
+    r.on "posts", Date do |date|
+      # does not match "/posts/foo" or "/posts/2017-01"
+      # matches "/posts/2017-01-13", yielding Date.new(2017, 1, 13)
+    end
+
+= Backwards Compatibility
+
+* If you were using the Integer and String classes as matchers
+  before and expected them to always match, you'll need to
+  change your code to use true instead.

data/lib/roda.rb

@@ -687,11 +687,31 @@ class Roda
           end
         end
 
+        # Match the given class.  Currently, the following classes
+        # are supported by default:
+        # Integer :: Match an integer segment, yielding result to block as an integer
+        # String :: Match any non-empty segment, yielding result to block as a string
+        def _match_class(klass)
+          meth = :"_match_class_#{klass}"
+          if respond_to?(meth, true)
+            send(meth)
+          else
+            unsupported_matcher(klass)
+          end
+        end
+
         # Match the given hash if all hash matchers match.
         def _match_hash(hash)
           hash.all?{|k,v| send("match_#{k}", v)}
         end
 
+        # Match integer segment, and yield resulting value as an
+        # integer.
+        def _match_class_Integer
+          consume(/\A\/(\d+)(?=\/|\z)/){|i| [i.to_i]}
+        end
+
+        # Match only if all of the arguments in the given array match.
         # Match the given regexp exactly if it matches a full segment.
         def _match_regexp(re)
           consume(self.class.cached_matcher(re){re})
@@ -725,7 +745,7 @@ class Roda
         end
 
         # Match the given symbol if any segment matches.
-        def _match_symbol(sym)
+        def _match_symbol(sym=nil)
           rp = @remaining_path
           if rp[0, 1] == SLASH
             if last = rp.index('/', 1)
@@ -740,6 +760,9 @@ class Roda
           end
         end
 
+        # Match any nonempty segment.  This should be called without an argument.
+        alias _match_class_String _match_symbol
+
         # The regular expression to use for matching symbols.  By default, any non-empty
         # segment matches.
         def _match_symbol_regexp(s)
@@ -791,7 +814,9 @@ class Roda
         def consume(pattern)
           if matchdata = remaining_path.match(pattern)
             @remaining_path = matchdata.post_match
-            @captures.concat(matchdata.captures)
+            captures = matchdata.captures
+            captures = yield(*captures) if block_given?
+            @captures.concat(captures)
           end
         end
 
@@ -836,17 +861,19 @@ class Roda
             false
           end
         end
-        
+
         # Attempt to match the argument to the given request, handling
         # common ruby types.
         def match(matcher)
           case matcher
           when String
             _match_string(matcher)
-          when Symbol
-            _match_symbol(matcher)
+          when Class
+            _match_class(matcher)
           when TERM
             empty_path?
+          when Symbol
+            _match_symbol(matcher)
           when Regexp
             _match_regexp(matcher)
           when Hash
@@ -858,10 +885,7 @@ class Roda
           when true, false, nil
             matcher
           else
-            if roda_class.opts[:unsupported_matcher] == :raise
-              raise RodaError, "unsupported matcher: #{matcher.inspect}"
-            end
-            matcher
+            unsupported_matcher(matcher)
           end
         end
 
@@ -885,6 +909,14 @@ class Roda
         def placeholder_string_matcher?
           !roda_class.opts[:verbatim_string_matcher]
         end
+
+        # Handle an unsupported matcher.
+        def unsupported_matcher(matcher)
+          if roda_class.opts[:unsupported_matcher] == :raise
+            raise RodaError, "unsupported matcher: #{matcher.inspect}"
+          end
+          matcher
+        end
       end
 
       # Class methods for RodaResponse

data/lib/roda/plugins/caching.rb

@@ -8,7 +8,7 @@ class Roda
     # For proper caching, you should use either the +last_modified+ or
     # +etag+ request methods.  
     #
-    #   r.get 'albums', :d do |album_id|
+    #   r.get 'albums', Integer do |album_id|
     #     @album = Album[album_id]
     #     r.last_modified @album.updated_at
     #     view('album')
@@ -16,7 +16,7 @@ class Roda
     #
     #   # or
     #
-    #   r.get 'albums', :d do |album_id|
+    #   r.get 'albums', Integer do |album_id|
     #     @album = Album[album_id]
     #     r.etag @album.sha1
     #     view('album')

data/lib/roda/plugins/chunked.rb

@@ -44,7 +44,7 @@ class Roda
     # block will be delayed until rendering the content template.  This is
     # useful if you want to delay execution for all routes under a branch:
     #
-    #   r.on 'albums', :d do |album_id|
+    #   r.on 'albums', Integer do |album_id|
     #     delay do
     #       @album = Album[album_id]
     #     end

data/lib/roda/plugins/class_matchers.rb

@@ -0,0 +1,51 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The class_matchers plugin allows you do define custom regexps and
+    # conversion procs to use for specific classes.  For example, if you
+    # have multiple routes similar to:
+    #
+    #   r.on /(\d\d\d\d)-(\d\d)-(\d\d)/ do |y, m, d|
+    #     date = Date.new(y.to_i, m.to_i, d.to_i)
+    #     # ...
+    #   end
+    #
+    # You can register a Date class matcher for that regexp (note that
+    # the block must return an array):
+    #
+    #   class_matcher(Date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
+    #     [Date.new(y.to_i, m.to_i, d.to_i)]
+    #   end
+    #
+    # And then use the Date class as a matcher, and it will yield a Date object:
+    #
+    #   r.on Date do |date|
+    #     # ...
+    #   end
+    #
+    # This is useful to DRY up code if you are using the same type of pattern and
+    # type conversion in multiple places in your application.
+    #
+    # This plugin does not work with the params capturing plugin, as it does not
+    # offer the ability to associate block arguments with named keys.
+    module ClassMatchers
+      module ClassMethods
+        # Set the regexp to use for the given class.  The block given will be
+        # called with all matched values from the regexp, and should return an
+        # array with the captures to yield to the match block.
+        def class_matcher(klass, re, &block)
+          meth = :"_match_class_#{klass}"
+          self::RodaRequest.class_eval do
+            consume_re = consume_pattern(re)
+            define_method(meth){consume(consume_re, &block)}
+            private meth
+          end
+        end
+      end
+    end
+
+    register_plugin(:class_matchers, ClassMatchers)
+  end
+end

data/lib/roda/plugins/mailer.rb

@@ -60,8 +60,8 @@ class Roda
     # email bodies, you can use all of Roda's usual routing tree features
     # to DRY up your code:
     #
-    #   r.on "albums", :d do |album_id|
-    #     @album = Album[album_id.to_i]
+    #   r.on "albums", Integer do |album_id|
+    #     @album = Album[album_id]
     #     from 'from@example.com'
     #     to 'to@example.com'
     #
@@ -92,7 +92,7 @@ class Roda
     # If while preparing the email you figure out you don't want to send an
     # email, call +no_mail!+:
     #
-    #  r.mail 'welcome', :d do |id| 
+    #  r.mail 'welcome', Integer do |id| 
     #    no_mail! unless user = User[id]
     #    # ...
     #  end

data/lib/roda/plugins/path_rewriter.rb

@@ -36,9 +36,9 @@ class Roda
     # Patterns can be rewritten dynamically by providing a block accepting a MatchData
     # object and evaluating to the replacement.
     #
-    #   rewrite_path(/\A\/a/(\w+)/){|match| "/a/#{match[1].capitalize}"}
+    #   rewrite_path(/\A\/a\/(\w+)/){|match| "/a/#{match[1].capitalize}"}
     #   # PATH_INFO '/a/moo' => remaining_path '/a/Moo'
-    #   rewrite_path(/\A\/a/(\w+)/, :path_info => true){|match| "/a/#{match[1].capitalize}"}
+    #   rewrite_path(/\A\/a\/(\w+)/, :path_info => true){|match| "/a/#{match[1].capitalize}"}
     #   # PATH_INFO '/a/moo' => PATH_INFO '/a/Moo'
     #
     # All path rewrites are applied in order, so if a path is rewritten by one rewrite,

data/lib/roda/plugins/shared_vars.rb

@@ -18,7 +18,7 @@ class Roda
     #     plugin :shared_vars
     #
     #     route do |r|
-    #       r.on :user_id do |user_id|
+    #       r.on Integer do |user_id|
     #         shared[:user] = User[user_id]
     #         r.run API
     #       end
@@ -29,7 +29,7 @@ class Roda
     # vars with the content of the hash:
     #
     #   route do |r|
-    #     r.on :user_id do |user_id|
+    #     r.on Integer do |user_id|
     #       shared(:user => User[user_id])
     #       r.run API
     #     end
@@ -40,7 +40,7 @@ class Roda
     # previous shared variables afterward:
     #
     #   route do |r|
-    #     r.on :user_id do |user_id|
+    #     r.on Integer do |user_id|
     #       shared(:user => User[user_id]) do
     #         r.run API
     #       end

data/lib/roda/plugins/view_options.rb

@@ -39,7 +39,7 @@ class Roda
     #     r.on "users" do
     #       set_view_subdir 'users'
     #       
-    #       r.get :id do
+    #       r.get Integer do |id|
     #         append_view_subdir 'profile'
     #         view 'index' # uses ./views/users/profile/index.erb
     #       end

data/lib/roda/plugins/websockets.rb

@@ -27,7 +27,7 @@ class Roda
     #   end
     #
     #   route do |r|
-    #     r.get "room", :d do |room_id|
+    #     r.get "room", Integer do |room_id|
     #       room = sync{ROOMS[room_id] ||= []}
     #
     #       r.websocket do |ws|

data/lib/roda/version.rb

@@ -4,7 +4,7 @@ class Roda
   RodaMajorVersion = 2
 
   # The minor version of Roda, updated for new feature releases of Roda.
-  RodaMinorVersion = 26
+  RodaMinorVersion = 27
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

data/spec/matchers_spec.rb

@@ -1,7 +1,7 @@
 require File.expand_path("spec_helper", File.dirname(__FILE__))
 
 describe "capturing" do
-  it "doesn't yield the verb" do
+  it "doesn't yield the verb for verb matcher" do
     app do |r|
       r.get do |*args|
         args.size.to_s
@@ -11,7 +11,7 @@ describe "capturing" do
     body.must_equal '0'
   end
 
-  it "doesn't yield the path" do
+  it "doesn't yield the path for string matcher" do
     app do |r|
       r.get "home" do |*args|
         args.size.to_s
@@ -21,7 +21,7 @@ describe "capturing" do
     body('/home').must_equal '0'
   end
 
-  it "yields the segment" do
+  it "yields the segment for symbol matcher" do
     app do |r|
       r.get "user", :id do |id|
         id
@@ -31,7 +31,7 @@ describe "capturing" do
     body("/user/johndoe").must_equal 'johndoe'
   end
 
-  it "yields a number" do
+  it "yields an integer segment as a string when using symbol matcher" do
     app do |r|
       r.get "user", :id do |id|
         id
@@ -41,7 +41,7 @@ describe "capturing" do
     body("/user/101").must_equal '101'
   end
 
-  it "yields a segment per nested block" do
+  it "yields a segment per nested block for symbol matcher" do
     app do |r|
       r.on :one do |one|
         r.on :two do |two|
@@ -55,7 +55,17 @@ describe "capturing" do
     body("/one/two/three").must_equal "onetwothree"
   end
 
-  it "regex captures in regex format" do
+  it "yields a segment per argument for symbol matcher" do
+    app do |r|
+      r.on :one, :two, :three do |one, two, three|
+        one + two + three
+      end
+    end
+
+    body("/one/two/three").must_equal "onetwothree"
+  end
+
+  it "yields regex captures as separate arguments" do
     app do |r|
       r.get %r{posts/(\d+)-(.*)} do |id, slug|
         id + slug
@@ -64,6 +74,28 @@ describe "capturing" do
 
     body("/posts/123-postal-service").must_equal "123postal-service"
   end
+
+  it "yields an integer segment as an integer when using Integer matcher " do
+    app do |r|
+      r.get "user", Integer do |id|
+        "#{id}-#{id.is_a?(Integer)}"
+      end
+      "b"
+    end
+
+    body("/user/101").must_equal '101-true'
+    body("/user/a").must_equal 'b'
+  end
+
+  it "yields the segment for symbol matcher" do
+    app do |r|
+      r.get "user", String do |id|
+        id
+      end
+    end
+
+    body("/user/johndoe").must_equal 'johndoe'
+  end
 end
 
 describe "r.is" do 

data/spec/plugin/class_matchers_spec.rb

@@ -0,0 +1,40 @@
+require File.expand_path("spec_helper", File.dirname(File.dirname(__FILE__)))
+require 'date'
+
+describe "class_matchers plugin" do 
+  it "allows class specific regexps with type conversion for class matchers" do
+    app(:bare) do
+      plugin :class_matchers
+      class_matcher(Date, /(\d\d\d\d)-(\d\d)-(\d\d)/){|y,m,d| [Date.new(y.to_i, m.to_i, d.to_i)]}
+      class_matcher(Array, /(\w+)\/(\w+)/){|a, b| [[a, 1], [b, 2]]}
+      class_matcher(Hash, /(\d+)\/(\d+)/){|a, b| [{a.to_i=>b.to_i}]}
+
+      route do |r|
+        r.on Array do |(a,b), (c,d)|
+          r.get Date do |date|
+            [date.year, date.month, date.day, a, b, c, d].join('-')
+          end
+          r.get Hash do |h|
+            [h.inspect, a, b, c, d].join('-')
+          end
+          r.get Array do |(a1,b1), (c1,d1)|
+            [a1, b1, c1, d1, a, b, c, d].join('-')
+          end
+          r.is do
+            [a, b, c, d].join('-')
+          end
+          "array"
+        end
+        ""
+      end
+    end
+
+    body("/c").must_equal ''
+    body("/c/d").must_equal 'c-1-d-2'
+    body("/c/d/e").must_equal 'array'
+    body("/c/d/2009-10-a").must_equal 'array'
+    body("/c/d/2009-10-01").must_equal '2009-10-1-c-1-d-2'
+    body("/c/d/1/2").must_equal '{1=>2}-c-1-d-2'
+    body("/c/d/e/f").must_equal 'e-1-f-2-c-1-d-2'
+  end
+end

data/spec/plugin/error_mail_spec.rb

@@ -23,7 +23,7 @@ describe "error_mail plugin" do
     end
   end
 
-  before do
+  after do
     Mail::TestMailer.deliveries.clear
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 2.26.0
+  version: 2.27.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-16 00:00:00.000000000 Z
+date: 2017-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -206,6 +206,7 @@ extra_rdoc_files:
 - doc/release_notes/2.24.0.txt
 - doc/release_notes/2.25.0.txt
 - doc/release_notes/2.26.0.txt
+- doc/release_notes/2.27.0.txt
 files:
 - CHANGELOG
 - MIT-LICENSE
@@ -236,6 +237,7 @@ files:
 - doc/release_notes/2.24.0.txt
 - doc/release_notes/2.25.0.txt
 - doc/release_notes/2.26.0.txt
+- doc/release_notes/2.27.0.txt
 - doc/release_notes/2.3.0.txt
 - doc/release_notes/2.4.0.txt
 - doc/release_notes/2.5.0.txt
@@ -253,6 +255,7 @@ files:
 - lib/roda/plugins/caching.rb
 - lib/roda/plugins/chunked.rb
 - lib/roda/plugins/class_level_routing.rb
+- lib/roda/plugins/class_matchers.rb
 - lib/roda/plugins/content_for.rb
 - lib/roda/plugins/cookies.rb
 - lib/roda/plugins/csrf.rb
@@ -344,6 +347,7 @@ files:
 - spec/plugin/caching_spec.rb
 - spec/plugin/chunked_spec.rb
 - spec/plugin/class_level_routing_spec.rb
+- spec/plugin/class_matchers_spec.rb
 - spec/plugin/content_for_spec.rb
 - spec/plugin/cookies_spec.rb
 - spec/plugin/csrf_spec.rb