roda 3.67.0 → 3.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ea9212a800294ebf286d593e230ac925aced0d5e7c118fa7541b3fd6a5cc983
-  data.tar.gz: 9a591fdf0b2b481f71cbf871a70b3f83a8cac4bca4c3fe399348dfeee2447a13
+  metadata.gz: 2871ec8db3a18a77238fdae1aeb786c7a7eb93f14b0827428fab1b07f6e7bee8
+  data.tar.gz: 75db2ec79978055f407c2270cfd9119782322402c2c536a504fbfc08f4fedac7
 SHA512:
-  metadata.gz: 7f5887a701034ac935d6bb1f14a454f6dfe03751ec7842e383f401555f46d021d8bb502658959a5edae9d4199d8e8bfc785721d3386b76f0b6b280c7731fad3d
-  data.tar.gz: eb7de74ded26221a86664644ceddda6428e877bdf158acd988319c56bdc335955b506623cc9d8fb3c71376c877d4e00254c018c4341debd221a6439d9557e6ed
+  metadata.gz: 1ca4fdcac9bcba88309b8ccb4315ea2243530b08313135f97a643b81600b98821521fbbe08e9c7ab757732887326e8af492f0f3e883a3f54e7be73f0811d19e6
+  data.tar.gz: 6b313eecbd4f62d07bca53fa23db2325b4f53f3faf55344c86d8f543ff92c5dcba94235f963582ce227d3602e3ea8633e981393ef6aedcbe20fb8152e6409c08

data/CHANGELOG

@@ -1,3 +1,11 @@
+= 3.69.0 (2023-06-13)
+
+* Allow symbol_matcher in symbol_matchers plugin to take a block to allow type conversion (jeremyevans)
+
+= 3.68.0 (2023-05-11)
+
+* Make Roda.run in multi_run plugin accept blocks to allow autoloading the apps to dispatch to (jeremyevans)
+
 = 3.67.0 (2023-04-12)
 
 * Add custom_block_results plugin for registering custom block result handlers (jeremyevans)

data/doc/release_notes/3.68.0.txt

@@ -0,0 +1,21 @@
+= New Feature
+
+* Roda.run in the multi_run plugin now accepts blocks, to allow
+  autoloading of apps to dispatch to:
+
+    class App < Roda
+      plugin :multi_run
+
+      run("other_app"){OtherApp}
+
+      route do |r|
+        r.multi_run
+      end
+    end
+
+  With the above example, the block is not evaluated until a
+  request for the /other_app branch is received.  If OtherApp is
+  autoloaded, this can speed up application startup and partial
+  testing. When freezing the application (for production use),
+  the block is eagerly loaded, so that requests to the
+  /other_app branch do not call the block on every request.

data/doc/release_notes/3.69.0.txt

@@ -0,0 +1,33 @@
+= New Feature
+
+* The symbol_matcher method in the symbol_matchers plugin now
+  supports a block to allow for type conversion of matched
+  segments:
+
+    symbol_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
+  
+    route do |r|
+      r.on :date do |date|
+        # date is an instance of Date
+      end
+    end
+
+  As shown above, the block should return an array of objects to yield
+  to the match block.
+ 
+  If you have a segment match the passed regexp, but decide during block
+  processing that you do not want to treat it as a match, you can have the
+  block return nil or false.  This is useful if you want to make sure you
+  are using valid data:
+  
+    symbol_matcher(:date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
+      y = y.to_i
+      m = m.to_i
+      d = d.to_i
+      [Date.new(y, m, d)] if Date.valid_date?(y, m, d)
+    end
+  
+  When providing a block when using the symbol_matchers method, that
+  symbol may not work with the params_capturing plugin.

data/lib/roda/plugins/class_matchers.rb

@@ -33,7 +33,7 @@ class Roda
     # block return nil or false.  This is useful if you want to make sure you
     # are using valid data:
     #
-    #   class_matcher(Date, /(\dd\d)-(\d\d)-(\d\d)/) do |y, m, d|
+    #   class_matcher(Date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
     #     y = y.to_i
     #     m = m.to_i
     #     d = d.to_i

data/lib/roda/plugins/multi_run.rb

@@ -17,7 +17,7 @@ class Roda
     #   App.run "ro", OtherRodaApp
     #   App.run "si", SinatraApp
     #
-    # Inside your route block, you can call r.multi_run to dispatch to all
+    # Inside your route block, you can call +r.multi_run+ to dispatch to all
     # three rack applications based on the prefix:
     #
     #   App.route do |r|
@@ -28,7 +28,7 @@ class Roda
     # starting with +/ro+ to +OtherRodaApp+, and routes starting with +/si+ to
     # SinatraApp.
     #
-    # You can pass a block to +multi_run+ that will be called with the prefix,
+    # You can pass a block to +r.multi_run+ that will be called with the prefix,
     # before dispatching to the rack app:
     #
     #   App.route do |r|
@@ -39,12 +39,26 @@ class Roda
     #
     # This is useful for modifying the environment before passing it to the rack app.
     #
-    # The multi_run plugin is similar to the multi_route plugin, with the difference
-    # being the multi_route plugin keeps all routing subtrees in the same Roda app/class,
-    # while multi_run dispatches to other rack apps.  If you want to isolate your routing
-    # subtrees, multi_run is a better approach, but it does not let you set instance
-    # variables in the main Roda app and have those instance variables usable in
-    # the routing subtrees.
+    # You can also call +Roda.run+ with a block:
+    #
+    #   App.run("ra"){PlainRackApp}
+    #   App.run("ro"){OtherRodaApp}
+    #   App.run("si"){SinatraApp}
+    #
+    # When called with a block, Roda will call the block to get the app to dispatch to
+    # every time the block is called.  The expected usage is with autoloaded classes,
+    # so that the related classes are not loaded until there is a request for the
+    # related route.  This can sigficantly speedup startup or testing a subset of the
+    # application.  When freezing an application, the blocks are called once to get the
+    # app to dispatch to, and that is cached, to ensure the any autoloads are completed
+    # before the application is frozen.
+    #
+    # The multi_run plugin is similar to the hash_branches and multi_route plugins, with
+    # the difference being the hash_branches and multi_route plugins keep all routing
+    # subtrees in the same Roda app/class, while multi_run dispatches to other rack apps.
+    # If you want to isolate your routing subtrees, multi_run is a better approach, but
+    # it does not let you set instance variables in the main Roda app and have those
+    # instance variables usable in the routing subtrees.
     #
     # To handle development environments that reload code, you can call the
     # +run+ class method without an app to remove dispatching for the prefix.
@@ -52,12 +66,21 @@ class Roda
       # Initialize the storage for the dispatched applications
       def self.configure(app)
         app.opts[:multi_run_apps] ||= {}
+        app.opts[:multi_run_app_blocks] ||= {}
       end
 
       module ClassMethods
+        # Convert app blocks into apps by calling them, in order to force autoloads
+        # and to speed up subsequent calls.
         # Freeze the multi_run apps so that there can be no thread safety issues at runtime.
         def freeze
-          opts[:multi_run_apps].freeze
+          app_blocks = opts[:multi_run_app_blocks]
+          apps = opts[:multi_run_apps]
+          app_blocks.each do |prefix, block|
+            apps[prefix] = block.call
+          end
+          app_blocks.clear.freeze
+          apps.freeze
           self::RodaRequest.refresh_multi_run_regexp!
           super
         end
@@ -69,12 +92,22 @@ class Roda
         end
 
         # Add a rack application to dispatch to for the given prefix when
-        # r.multi_run is called.
-        def run(prefix, app=nil)
-          if app
-            multi_run_apps[prefix.to_s] = app
+        # r.multi_run is called. If a block is given, it is called every time
+        # there is a request for the route to get the app to call. If neither
+        # a block or an app is provided, any stored route for the prefix is
+        # removed.  It is an error to provide both an app and block in the same call.
+        def run(prefix, app=nil, &block)
+          prefix = prefix.to_s
+          if app 
+            raise Roda::RodaError, "cannot provide both app and block to Roda.run" if block
+            opts[:multi_run_apps][prefix] = app
+            opts[:multi_run_app_blocks].delete(prefix)
+          elsif block
+            opts[:multi_run_apps].delete(prefix)
+            opts[:multi_run_app_blocks][prefix] = block
           else
-            multi_run_apps.delete(prefix.to_s)
+            opts[:multi_run_apps].delete(prefix)
+            opts[:multi_run_app_blocks].delete(prefix)
           end
           self::RodaRequest.refresh_multi_run_regexp!
         end
@@ -84,7 +117,7 @@ class Roda
         # Refresh the multi_run_regexp, using the stored route prefixes,
         # preferring longer routes before shorter routes.
         def refresh_multi_run_regexp!
-          @multi_run_regexp = /(#{Regexp.union(roda_class.multi_run_apps.keys.sort.reverse)})/
+          @multi_run_regexp = /(#{Regexp.union((roda_class.opts[:multi_run_apps].keys + roda_class.opts[:multi_run_app_blocks].keys).sort.reverse)})/
         end
 
         # Refresh the multi_run_regexp if it hasn't been loaded yet.
@@ -95,11 +128,12 @@ class Roda
 
       module RequestMethods
         # If one of the stored route prefixes match the current request,
-        # dispatch the request to the stored rack application.
+        # dispatch the request to the appropriate rack application.
         def multi_run
           on self.class.multi_run_regexp do |prefix|
             yield prefix if defined?(yield)
-            run scope.class.multi_run_apps[prefix]
+            opts = scope.opts
+            run(opts[:multi_run_apps][prefix] || opts[:multi_run_app_blocks][prefix].call)
           end
         end
       end

data/lib/roda/plugins/symbol_matchers.rb

@@ -37,6 +37,35 @@ class Roda
     #
     # If using this plugin with the params_capturing plugin, this plugin should
     # be loaded first.
+    #
+    # You can provide a block when calling +symbol_matcher+, and it will be called
+    # for all matches to allow for type conversion.  The block must return an
+    # array:
+    #
+    #   symbol_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
+    #
+    #   route do |r|
+    #     r.on :date do |date|
+    #       # date is an instance of Date
+    #     end
+    #   end
+    #
+    # If you have a segment match the passed regexp, but decide during block
+    # processing that you do not want to treat it as a match, you can have the
+    # block return nil or false.  This is useful if you want to make sure you
+    # are using valid data:
+    #
+    #   symbol_matcher(:date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
+    #     y = y.to_i
+    #     m = m.to_i
+    #     d = d.to_i
+    #     [Date.new(y, m, d)] if Date.valid_date?(y, m, d)
+    #   end
+    #
+    # However, if providing a block to the symbol_matchers plugin, the symbol may 
+    # not work with the params_capturing plugin.
     module SymbolMatchers
       def self.load_dependencies(app)
         app.plugin :_symbol_regexp_matchers
@@ -50,9 +79,10 @@ class Roda
 
       module ClassMethods
         # Set the regexp to use for the given symbol, instead of the default.
-        def symbol_matcher(s, re)
+        def symbol_matcher(s, re, &block)
           meth = :"match_symbol_#{s}"
-          self::RodaRequest.send(:define_method, meth){re}
+          array = [re, block].freeze
+          self::RodaRequest.send(:define_method, meth){array}
           self::RodaRequest.send(:private, meth)
         end
       end
@@ -67,8 +97,8 @@ class Roda
           meth = :"match_symbol_#{s}"
           if respond_to?(meth, true)
             # Allow calling private match methods
-            re = send(meth)
-            consume(self.class.cached_matcher(re){re})
+            re, block = send(meth)
+            consume(self.class.cached_matcher(re){re}, &block)
           else
             super
           end
@@ -80,7 +110,8 @@ class Roda
           meth = :"match_symbol_#{s}"
           if respond_to?(meth, true)
             # Allow calling private match methods
-            send(meth)
+            re, = send(meth)
+            re
           else
             super
           end

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 = 67
+  RodaMinorVersion = 69
 
   # 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.67.0
+  version: 3.69.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-12 00:00:00.000000000 Z
+date: 2023-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -240,6 +240,8 @@ extra_rdoc_files:
 - doc/release_notes/3.65.0.txt
 - doc/release_notes/3.66.0.txt
 - doc/release_notes/3.67.0.txt
+- doc/release_notes/3.68.0.txt
+- doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
@@ -314,6 +316,8 @@ files:
 - doc/release_notes/3.65.0.txt
 - doc/release_notes/3.66.0.txt
 - doc/release_notes/3.67.0.txt
+- doc/release_notes/3.68.0.txt
+- doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt