roda 3.70.0 → 3.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d8ea04ca767f8be110f6ba14d1fd877a389a2e733e2925020f2ac589f6a9571
-  data.tar.gz: c9a2d26f41724c05ea1de5e8fb0058093e5fad34fb0c6479dd74badcfea67016
+  metadata.gz: d5460d6cecb4f9b9acfedd05f5b14793bb9aefa2df2a8c29c559da319df87ee4
+  data.tar.gz: 75c3c8803abef4e27cac592a88597e8f9cd098be39bf1d0c1b1192175fd1f8e2
 SHA512:
-  metadata.gz: 288a793976f389dfa2fe8fd55fb649590748cbe7ebb9da48f351117bb93da33ceee5848077f53c73430fd943b6be5b69a6d189e8b7424fe9ec60892dbaacff56
-  data.tar.gz: 3cad6d6823a2fbcd5534521b6e5fbcc7b85c04d1a80e9ca758cac6ab9b4b967a5f019b653de7d4de3c1d32069832f362fd2564ec219252b0f2dd8ccf1c0785c1
+  metadata.gz: 6efc49bb205012a7ce50bc3c300d924a149de33416a35870f11efed492251c331804b970c967e47a481b0ddb0a83507c5926c1dc32069941b4edd2bd56df09e5
+  data.tar.gz: 698b7e7daae4cd0712a20a1e3e274f7ba3cdb9068eefdeb3bb5f043f2d437cdd5dda961ce91d88794e22a8ca3ef5825e3f8bd3f92ff933eab772c352dd17c2ee

data/CHANGELOG

@@ -1,3 +1,7 @@
+= 3.71.0 (2023-08-14)
+
+* Add match_hook_args plugin, similar to match_hooks but support matchers and block args as hook arguments (jeremyevans)
+
 = 3.70.0 (2023-07-12)
 
 * Add plain_hash_response_headers plugin, using a plain hash for response headers on Rack 3 for much better performance (jeremyevans)

data/doc/release_notes/3.71.0.txt

@@ -0,0 +1,33 @@
+= New Feature
+
+* A match_hook_args plugin has been added.  This is similar to the
+  existing match_hook plugin, but passes through the matchers and
+  block arguments (values yielded to the match block). Example:
+
+    plugin :match_hook_args
+ 
+    add_match_hook do |matchers, block_args|
+      logger.debug("matchers: #{matchers.inspect}. #{block_args.inspect} yielded.")
+    end
+
+    # Term is an implicit matcher used for terminating matches, and
+    # will be included in the array of matchers yielded to the match hook
+    # if a terminating match is used.
+    term = self.class::RodaRequest::TERM
+
+    route do |r|
+      r.root do
+        # for a request for /
+        # matchers: nil, block_args: nil
+      end
+
+      r.on 'a', ['b', 'c'], Integer do |segment, id|
+        # for a request for /a/b/1
+        # matchers: ["a", ["b", "c"], Integer], block_args: ["b", 1]
+      end
+
+      r.get 'd' do
+        # for a request for /d
+        # matchers: ["d", term], block_args: []
+      end
+    end

data/lib/roda/plugins/json.rb

@@ -52,6 +52,9 @@ class Roda
     # using the +:content_type+ option:
     #
     #   plugin :json, content_type: 'application/xml'
+    #
+    # This plugin depends on the custom_block_results plugin, and therefore does
+    # not support treating String, FalseClass, or NilClass values as JSON.
     module Json
       # Set the classes to automatically convert to JSON, and the serializer to use.
       def self.configure(app, opts=OPTS)

data/lib/roda/plugins/mail_processor.rb

@@ -379,7 +379,7 @@ class Roda
         end
 
         # Perform the processing of mail for this request, first considering
-        # routes defined via the the class-level +rcpt+ method, and then the
+        # routes defined via the class-level +rcpt+ method, and then the
         # normal routing tree passed in as the block.
         def process_mail(&block)
           if string_routes = opts[:mail_processor_string_routes]

data/lib/roda/plugins/match_hook.rb

@@ -4,7 +4,9 @@
 class Roda
   module RodaPlugins
     # The match_hook plugin adds hooks that are called upon a successful match
-    # by any of the matchers.
+    # by any of the matchers.  The hooks do not take any arguments.  If you would
+    # like hooks that pass the arguments/matchers and values yielded to the route block,
+    # use the match_hook_args plugin.
     #
     #   plugin :match_hook
     #

data/lib/roda/plugins/match_hook_args.rb

@@ -0,0 +1,93 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The match_hook_args plugin adds hooks that are called upon a successful match
+    # by any of the matchers. It is similar to the match_hook plugin, but it allows
+    # for passing the matchers and block arguments for each match method.
+    #
+    #   plugin :match_hook_args
+    #
+    #   add_match_hook do |matchers, block_args|
+    #     logger.debug("matchers: #{matchers.inspect}. #{block_args.inspect} yielded.")
+    #   end
+    #
+    #   # Term is an implicit matcher used for terminating matches, and
+    #   # will be included in the array of matchers yielded to the match hook 
+    #   # if a terminating match is used.
+    #   term = self.class::RodaRequest::TERM
+    #
+    #   route do |r|
+    #     r.root do
+    #       # for a request for /
+    #       # matchers: nil, block_args: nil
+    #     end
+    #
+    #     r.on 'a', ['b', 'c'], Integer do |segment, id|
+    #       # for a request for /a/b/1
+    #       # matchers: ["a", ["b", "c"], Integer], block_args: ["b", 1]
+    #     end
+    #
+    #     r.get 'd' do
+    #       # for a request for /d
+    #       # matchers: ["d", term], block_args: []
+    #     end
+    #   end
+    module MatchHookArgs
+      def self.configure(app)
+        app.opts[:match_hook_args] ||= []
+      end
+
+      module ClassMethods
+        # Freeze the array of hook methods when freezing the app
+        def freeze
+          opts[:match_hook_args].freeze
+          super
+        end
+
+        # Add a match hook that will be called with matchers and block args.
+        def add_match_hook(&block)
+          opts[:match_hook_args] << define_roda_method("match_hook_args", :any, &block)
+
+          if opts[:match_hook_args].length == 1
+            class_eval("alias _match_hook_args #{opts[:match_hook_args].first}", __FILE__, __LINE__)
+          else
+            class_eval("def _match_hook_args(v, a); #{opts[:match_hook_args].map{|m| "#{m}(v, a)"}.join(';')} end", __FILE__, __LINE__)
+          end
+
+          public :_match_hook_args
+
+          nil
+        end
+      end
+
+      module InstanceMethods
+        # Default empty method if no match hooks are defined.
+        def _match_hook_args(matchers, block_args)
+        end
+      end
+
+      module RequestMethods
+        private
+
+        # Call the match hook with matchers and block args if yielding to the block before yielding to the block.
+        def if_match(v)
+          super do |*a|
+            scope._match_hook_args(v, a)
+            yield(*a)
+          end
+        end
+
+        # Call the match hook with nil matchers and blocks before yielding to the block
+        def always
+          scope._match_hook_args(nil, nil)
+          super
+        end
+      end
+    end
+
+    register_plugin :match_hook_args, MatchHookArgs
+  end
+end
+

data/lib/roda/plugins/typecast_params.rb

@@ -346,7 +346,7 @@ class Roda
         end
 
         # The reason behind this error.  If this error was caused by a conversion method,
-        # this will be the the conversion method symbol.  If this error was caused
+        # this will be the conversion method symbol.  If this error was caused
         # because a value was missing, then it will be +:missing+.  If this error was
         # caused because a value was not the correct type, then it will be +:invalid_type+.
         attr_accessor :reason

data/lib/roda/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.70.0
+  version: 3.71.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-12 00:00:00.000000000 Z
+date: 2023-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -244,6 +244,7 @@ extra_rdoc_files:
 - doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.70.0.txt
+- doc/release_notes/3.71.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
 files:
@@ -321,6 +322,7 @@ files:
 - doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.70.0.txt
+- doc/release_notes/3.71.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
 - lib/roda.rb
@@ -391,6 +393,7 @@ files:
 - lib/roda/plugins/mailer.rb
 - lib/roda/plugins/match_affix.rb
 - lib/roda/plugins/match_hook.rb
+- lib/roda/plugins/match_hook_args.rb
 - lib/roda/plugins/middleware.rb
 - lib/roda/plugins/middleware_stack.rb
 - lib/roda/plugins/module_include.rb