roda 3.47.0 → 3.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cad702e3b962a1e1b64e631ef77ea1ccca4eb1c630f1ac2e73b5c169b505744
-  data.tar.gz: f6576f0bd8b1a921435121ce9043a04f04f5560eca7a2eb93f5f39500a62dc1b
+  metadata.gz: f935481900b15707f29c41122e9ba1101e4a1bb7b6e53ef6c7819f8e0113fb23
+  data.tar.gz: 3f4938ea16d81085a0b9ee365f1cc8d317fbafd06674f1cf0e8dda37b70f3b05
 SHA512:
-  metadata.gz: 7def8965cb5ce9b12c96d16f2edb4e4428b41367b91ebfb20132332b87b04fceba29fdb537ea91c25eda7cc72d07ba3d329d12c073746309b125275d8cc616ad
-  data.tar.gz: 7acab06b22c80a697e4e250b857544aa337fcdf9a1c2065adae61cac4d1d17171ea374300104855e192fc4700d39d5c8fb9ebe7e8ee2ebc5d00fd6776c7a9f64
+  metadata.gz: 00b35a151be77f3ed93ee0b664ce2b77162b1f14c02194e0228ec99969194c54c4ca0ddd538e0eb8bfcb4109ea6712428b554da06d69e572aaffa4d854e76559
+  data.tar.gz: ceb138da62c24fa2a3be1a57eda9187190f96b974483719894e0368ad47402258123d651403b373c09ff801d816cae2d0f9c88dcf154e2226fba4a864b9ed64d

data/CHANGELOG

@@ -1,3 +1,29 @@
+= 3.51.0 (2021-12-15)
+
+* Avoid method redefinition warning in error_handler plugin in verbose warning mode (jeremyevans)
+
+* Allow run in multi_run plugin to be called without an app to remove existing handler (jeremyevans)
+
+* Allow route in named_routes plugin to be called without a block to remove existing handler (jeremyevans)
+
+= 3.50.0 (2021-11-12)
+
+* Add capture_erb plugin for capturing ERB template blocks, instead of injecting them into the template output (jeremyevans)
+
+* Add inject_erb plugin for injecting content directly into ERB template output (jeremyevans)
+
+* Allow hash_branch and hash_path in hash_routes plugin to be called without a block to remove existing handler (jeremyevans)
+
+= 3.49.0 (2021-10-13)
+
+* Switch block_given? to defined?(yield) (jeremyevans)
+
+* Automatically optimize remaining r.is/r.get/r.post calls with a single argument (jeremyevans)
+
+= 3.48.0 (2021-09-13)
+
+* Extract named_routes plugin from multi_route plugin (jeremyevans)
+
 = 3.47.0 (2021-08-13)
 
 * Automatically optimize remaining r.on calls with a single argument (jeremyevans)

data/README.rdoc

@@ -12,7 +12,8 @@ maintainable web applications in ruby.
 Website :: http://roda.jeremyevans.net
 Source :: http://github.com/jeremyevans/roda
 Bugs :: http://github.com/jeremyevans/roda/issues
-Google Group :: http://groups.google.com/group/ruby-roda
+Discussion Forum (GitHub Discussions) :: https://github.com/jeremyevans/roda/discussions
+Alternate Discussion Forum (Google Group) :: http://groups.google.com/group/ruby-roda
 
 == Goals
 
@@ -1109,7 +1110,8 @@ Roda's plugin system is based on the plugin system used by
 Roda fully supports the currently supported versions of Ruby (MRI) and JRuby.  It may
 support unsupported versions of Ruby or JRuby, but such support may be dropped in any
 minor version if keeping it becomes a support issue.  The minimum Ruby version
-required to run the current version of Roda is 1.9.2.
+required to run the current version of Roda is 1.9.2, and the minimum JRuby version is
+9.0.0.0.
 
 == License
 

data/doc/release_notes/3.48.0.txt

@@ -0,0 +1,10 @@
+= New Features
+
+* A named_routes plugin has been added, for defining named route
+  blocks that you can dispatch to with r.route.  This feature was
+  previously available as part of the multi_route plugin, but there
+  are cases where the r.route method and support for named routes is
+  helpful even when the multi_route plugin is not used (such as when
+  the hash_routes plugin is used instead of the multi_route plugin).
+  The multi_route plugin now depends on the named_routes plugin, so
+  this change should not cause any backwards compatibility issues.

data/doc/release_notes/3.49.0.txt

@@ -0,0 +1,18 @@
+= Improvements
+
+* The r.is optimization added in 3.46.0 has been extended to optimize
+  all single argument calls. This results in the following speedups
+  based on argument type:
+
+  * Hash/Class matching: 20%
+  * Symbol matching: 25%
+  * Array matching: 35%
+  * Proc matching: 50%
+  * false/nil matching: 65%
+
+* Roda now uses defined?(yield) instead of block_given? internally
+  for better performance on CRuby.  defined?(yield) is faster as it is
+  built into the VM, while block_given? is a regular method and has
+  the overhead of calling a regular method.  Note that defined?(yield)
+  is not implemented correctly on JRuby before 9.0.0.0, so this
+  release of Roda drops support for JRuby versions before 9.0.0.0.

data/doc/release_notes/3.50.0.txt

@@ -0,0 +1,21 @@
+= New Features
+
+* An inject_erb plugin has been added, adding an inject_erb method
+  that allows for injecting content directly into the template output
+  for the template currently being rendered.  This allows you to more
+  easily wrap blocks in templates, by calling methods that accept
+  template blocks and injecting content before and after the block.
+
+* A capture_erb plugin has been added, adding a capture_erb method
+  for capturing a template block in an erb template and returning
+  the content appended during the block as a string, instead of
+  having the content of the template block be included directly into
+  the template output.  This can be combined with the inject_erb
+  plugin to inject modified versions of captured blocks into template
+  output.
+
+* The hash_routes plugin now allows calling hash_branch and hash_path
+  without a block in order to remove the existing route handler. This
+  is designed to be used with code reloading libraries, so that if a
+  route file is deleted, the related hash branches/paths are also
+  removed, without having to reload all route files.

data/doc/release_notes/3.51.0.txt

@@ -0,0 +1,20 @@
+= New Features
+
+* The named_routes plugin now allows calling route without a block
+  to remove the existing route handler.  The multi_run plugin
+  now allows calling run without an app to remove an existing handler.
+  These changes are designed to better support code reloading
+  libraries, so that if the related file is deleted, the related
+  handlers are also removed, without having to reload the entire
+  application.
+
+= Other Improvements
+
+* The error_handler plugin now avoids a method redefinition warning
+  in verbose warning mode.
+
+= Other
+
+* Roda's primary discussion forum is now GitHub Discussions. The
+  ruby-roda Google Group is still available for users who would
+  prefer to use that instead.

data/lib/roda/plugins/_optimized_matching.rb

@@ -156,7 +156,21 @@ class Roda
                 always{yield(matchdata[1].to_i)}
               end
             else
-              if_match(args << TERM, &block)
+              path = @remaining_path
+              captures = @captures.clear
+              meth = :"_match_class_#{matcher}"
+              if respond_to?(meth, true)
+                # Allow calling private methods, as match methods are generally private
+                if send(meth, &block) && @remaining_path.empty?
+                  block_result(yield(*captures))
+                  throw :halt, response.finish
+                else
+                  @remaining_path = path
+                  false
+                end
+              else
+                unsupported_matcher(matcher)
+              end
             end
           when Regexp
             if (matchdata = self.class.cached_matcher(matcher){matcher}.match(@remaining_path)) && matchdata.post_match.empty?
@@ -165,8 +179,32 @@ class Roda
             end
           when true
             always(&block) if @remaining_path.empty?
+          when false, nil
+            # nothing
           else
-            if_match(args << TERM, &block)
+            path = @remaining_path
+            captures = @captures.clear
+
+            matched = case matcher
+            when Array
+              _match_array(matcher)
+            when Hash
+              _match_hash(matcher)
+            when Symbol
+              _match_symbol(matcher)
+            when Proc
+              matcher.call
+            else
+              unsupported_matcher(matcher)
+            end
+
+            if matched && @remaining_path.empty?
+              block_result(yield(*captures))
+              throw :halt, response.finish
+            else
+              @remaining_path = path
+              false
+            end
           end
         end
       end

data/lib/roda/plugins/capture_erb.rb

@@ -0,0 +1,41 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The capture_erb plugin allows you to capture the content of a block
+    # in an ERB template, and return it as a value, instead of
+    # injecting the template block into the template output.
+    #
+    #   <% value = capture_erb do %>
+    #     Some content here.
+    #   <% end %>
+    #
+    # +capture_erb+ can be used inside other methods that are called
+    # inside templates.  It can be combined with the inject_erb plugin
+    # to wrap template blocks with arbitrary output and then inject the
+    # wrapped output into the template.
+    module CaptureERB
+      def self.load_dependencies(app)
+        app.plugin :render
+      end
+
+      module InstanceMethods
+        # Temporarily replace the ERB output buffer
+        # with an empty string, and then yield to the block.
+        # Return the value of the block, converted to a string.
+        # Restore the previous ERB output buffer before returning.
+        def capture_erb
+          outvar = render_opts[:template_opts][:outvar]
+          buf_was = instance_variable_get(outvar)
+          instance_variable_set(outvar, String.new)
+          yield.to_s
+        ensure
+          instance_variable_set(outvar, buf_was) if outvar && buf_was
+        end
+      end
+    end
+
+    register_plugin(:capture_erb, CaptureERB)
+  end
+end

data/lib/roda/plugins/content_for.rb

@@ -55,10 +55,10 @@ class Roda
     #
     #   plugin :content_for, append: false
     module ContentFor
-      # Depend on the render plugin, since this plugin only makes
-      # sense when the render plugin is used.
+      # Depend on the capture_erb plugin, since it uses capture_erb
+      # to capture the content.
       def self.load_dependencies(app, _opts = OPTS)
-        app.plugin :render
+        app.plugin :capture_erb
       end
 
       # Configure whether to append or overwrite if content_for
@@ -72,18 +72,12 @@ class Roda
         # under the given key.  If called without a block, retrieve
         # stored content with the given key, or return nil if there
         # is no content stored with that key.
-        def content_for(key, value=nil)
+        def content_for(key, value=nil, &block)
           append = opts[:append_content_for]
 
-          if block_given? || value
-            if block_given?
-              outvar = render_opts[:template_opts][:outvar]
-              buf_was = instance_variable_get(outvar)
-
-              # Use temporary output buffer for ERB-based rendering systems
-              instance_variable_set(outvar, String.new)
-              value = yield.to_s
-              instance_variable_set(outvar, buf_was)
+          if block || value
+            if block
+              value = capture_erb(&block)
             end
 
             @_content_for ||= {}

data/lib/roda/plugins/content_security_policy.rb

@@ -278,7 +278,7 @@ class Roda
           Policy.new
         end
 
-        yield policy if block_given?
+        yield policy if defined?(yield)
         policy.freeze
       end
 
@@ -287,7 +287,7 @@ class Roda
         # current content security policy.
         def content_security_policy
           policy = @_response.content_security_policy
-          yield policy if block_given?
+          yield policy if defined?(yield)
           policy
         end
       end

data/lib/roda/plugins/error_handler.rb

@@ -62,6 +62,7 @@ class Roda
         # the exception in the scope of the Roda instance.
         def error(&block)
           define_method(:handle_error, &block)
+          alias_method(:handle_error, :handle_error)
           private :handle_error
         end
       end

data/lib/roda/plugins/hash_routes.rb

@@ -394,20 +394,32 @@ class Roda
           dsl
         end
 
-        # Add branch handler for the given namespace and segment.
+        # Add branch handler for the given namespace and segment. If called without
+        # a block, removes the existing branch handler if it exists.
         def hash_branch(namespace='', segment, &block)
           segment = "/#{segment}"
           routes = opts[:hash_branches][namespace] ||= {}
-          routes[segment] = define_roda_method(routes[segment] || "hash_branch_#{namespace}_#{segment}", 1, &convert_route_block(block))
+          if block
+            routes[segment] = define_roda_method(routes[segment] || "hash_branch_#{namespace}_#{segment}", 1, &convert_route_block(block))
+          elsif meth = routes[segment]
+            routes.delete(segment)
+            remove_method(meth)
+          end
         end
 
         # Add path handler for the given namespace and path. When the
         # r.hash_paths method is called, checks the matching namespace
         # for the full remaining path, and dispatch to that block if
-        # there is one.
+        # there is one.  If called without a block, removes the existing
+        # path handler if it exists.
         def hash_path(namespace='', path, &block)
           routes = opts[:hash_paths][namespace] ||= {}
-          routes[path] = define_roda_method(routes[path] || "hash_path_#{namespace}_#{path}", 1, &convert_route_block(block))
+          if block
+            routes[path] = define_roda_method(routes[path] || "hash_path_#{namespace}_#{path}", 1, &convert_route_block(block))
+          elsif meth = routes[path]
+            routes.delete(path)
+            remove_method(meth)
+          end
         end
       end
 

data/lib/roda/plugins/inject_erb.rb

@@ -0,0 +1,33 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The inject_erb plugin allows you to inject content directly
+    # into the template output:
+    #
+    #   <% inject_erb("Some HTML Here") %>
+    #
+    # This will inject <tt>Some HTML Here</tt> into the template output,
+    # even though the tag being used is <tt><%</tt> and not <tt><%=</tt>.
+    #
+    # This method can be used inside methods, such as to wrap calls to
+    # methods that accept template blocks, to inject code before and after
+    # the template blocks.
+    module InjectERB
+      def self.load_dependencies(app)
+        app.plugin :render
+      end
+
+      module InstanceMethods
+        # Inject into the template output for the template currently being
+        # rendered.
+        def inject_erb(value)
+          instance_variable_get(render_opts[:template_opts][:outvar]) << value.to_s
+        end
+      end
+    end
+
+    register_plugin(:inject_erb, InjectERB)
+  end
+end

data/lib/roda/plugins/module_include.rb

@@ -72,7 +72,7 @@ class Roda
           end
 
           if mod
-            raise RodaError, "can't provide both argument and block to response_module" if block_given?
+            raise RodaError, "can't provide both argument and block to response_module" if defined?(yield)
             klass.send(:include, mod)
           else
             if instance_variable_defined?(iv)

data/lib/roda/plugins/multi_route.rb

@@ -3,15 +3,10 @@
 #
 class Roda
   module RodaPlugins
-    # The multi_route plugin allows for multiple named routes, which the
-    # main route block can dispatch to by name at any point by calling +route+.
-    # If the named route doesn't handle the request, execution will continue,
-    # and if the named route does handle the request, the response returned by
-    # the named route will be returned.
-    #
-    # In addition, this plugin adds the +r.multi_route+ method, which will check
-    # if the first segment in the path matches a named route, and dispatch
-    # to that named route.
+    # The multi_route plugin builds on the named_routes plugin and allows for
+    # dispatching to multiple named routes # by calling the +r.multi_route+ method,
+    # which will check # if the first segment in the path matches a named route,
+    # and dispatch to that named route.
     #
     # The hash_routes plugin offers a +r.hash_routes+ method that is similar to
     # and performs better than the +r.multi_route+ method, and it is recommended
@@ -35,23 +30,14 @@ class Roda
     #
     #   route do |r|
     #     r.multi_route
-    #
-    #     # or
-    #
-    #     r.on "foo" do
-    #       r.route 'foo'
-    #     end
-    #
-    #     r.on "bar" do
-    #       r.route 'bar'
-    #     end
     #   end
     #
-    # Note that in multi-threaded code, you should not attempt to add a
-    # named route after accepting requests.
+    # Note that only named routes with string names will be dispatched to by the
+    # +r.multi_route+ method. Named routes with other names can be dispatched to
+    # using the named_routes plugin API, but will not be automatically dispatched
+    # to by +r.multi_route+.
     #
-    # If you want to use the +r.multi_route+ method, use string names for the
-    # named routes.  Also, you can provide a block to +r.multi_route+ that is
+    # You can provide a block to +r.multi_route+ that is
     # called if the route matches but the named route did not handle the
     # request:
     #
@@ -62,20 +48,10 @@ class Roda
     # If a block is not provided to multi_route, the return value of the named
     # route block will be used.
     #
-    # == Routing Files
-    #
-    # The convention when using the multi_route plugin is to have a single
-    # named route per file, and these routing files should be stored in
-    # a routes subdirectory in your application.  So for the above example, you
-    # would use the following files:
-    #
-    #   routes/bar.rb
-    #   routes/foo.rb
-    #
     # == Namespace Support
     #
     # The multi_route plugin also has support for namespaces, allowing you to
-    # use r.multi_route at multiple levels in your routing tree.  Example:
+    # use +r.multi_route+ at multiple levels in your routing tree.  Example:
     #
     #   route('foo') do |r|
     #     r.multi_route('foo')
@@ -103,81 +79,38 @@ class Roda
     #
     #   route do |r|
     #     r.multi_route
-    #
-    #     # or
-    #
-    #     r.on "foo" do
-    #       r.on("baz"){r.route("baz", "foo")}
-    #       r.on("quux"){r.route("quux", "foo")}
-    #     end
-    #
-    #     r.on "bar" do
-    #       r.on("baz"){r.route("baz", "bar")}
-    #       r.on("quux"){r.route("quux", "bar")}
-    #     end
     #   end
-    #
-    # === Routing Files
-    #
-    # The convention when using namespaces with the multi_route plugin is to
-    # store the routing files in subdirectories per namespace. So for the
-    # above example, you would have the following routing files:
-    #
-    #   routes/bar.rb
-    #   routes/bar/baz.rb
-    #   routes/bar/quux.rb
-    #   routes/foo.rb
-    #   routes/foo/baz.rb
-    #   routes/foo/quux.rb
     module MultiRoute
+      def self.load_dependencies(app)
+        app.plugin :named_routes
+      end
+
       # Initialize storage for the named routes.
       def self.configure(app)
-        app.opts[:namespaced_routes] ||= {}
         app::RodaRequest.instance_variable_set(:@namespaced_route_regexps, {})
       end
 
       module ClassMethods
-        # Freeze the namespaced routes and setup the regexp matchers so that there can be no thread safety issues at runtime.
+        # Freeze the multi_route regexp matchers so that there can be no thread safety issues at runtime.
         def freeze
-          opts[:namespaced_routes].freeze.each do |k,v|
-            v.freeze
+          super
+          opts[:namespaced_routes].each_key do |k|
             self::RodaRequest.named_route_regexp(k)
           end
           self::RodaRequest.instance_variable_get(:@namespaced_route_regexps).freeze
-          super
         end
 
         # Copy the named routes into the subclass when inheriting.
         def inherited(subclass)
           super
-          nsr = subclass.opts[:namespaced_routes]
-          opts[:namespaced_routes].each{|k, v| nsr[k] = v.dup}
           subclass::RodaRequest.instance_variable_set(:@namespaced_route_regexps, {})
         end
 
-        # The names for the currently stored named routes
-        def named_routes(namespace=nil)
-          unless routes = opts[:namespaced_routes][namespace]
-            raise RodaError, "unsupported multi_route namespace used: #{namespace.inspect}"
-          end
-          routes.keys
-        end
-
-        # Return the named route with the given name.
-        def named_route(name, namespace=nil)
-          opts[:namespaced_routes][namespace][name]
-        end
-
-        # If the given route has a name, treat it as a named route and
-        # store the route block.  Otherwise, this is the main route, so
-        # call super.
+        # Clear the multi_route regexp matcher for the namespace.
         def route(name=nil, namespace=nil, &block)
+          super
           if name
-            routes = opts[:namespaced_routes][namespace] ||= {}
-            routes[name] = define_roda_method(routes[name] || "multi_route_#{namespace}_#{name}", 1, &convert_route_block(block))
             self::RodaRequest.clear_named_route_regexp!(namespace)
-          else
-            super(&block)
           end
         end
       end
@@ -206,19 +139,14 @@ class Roda
         # is given, yield to the block.
         def multi_route(namespace=nil)
           on self.class.named_route_regexp(namespace) do |section|
-            r = route(section, namespace)
-            if block_given?
+            res = route(section, namespace)
+            if defined?(yield)
               yield
             else
-              r
+              res
             end
           end
         end
-
-        # Dispatch to the named route with the given name.
-        def route(name, namespace=nil)
-          scope.send(roda_class.named_route(name, namespace), self)
-        end
       end
     end
 

data/lib/roda/plugins/multi_run.rb

@@ -45,6 +45,9 @@ class Roda
     # 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.
     module MultiRun
       # Initialize the storage for the dispatched applications
       def self.configure(app)
@@ -67,8 +70,12 @@ class Roda
 
         # Add a rack application to dispatch to for the given prefix when
         # r.multi_run is called.
-        def run(prefix, app)
-          multi_run_apps[prefix.to_s] = app
+        def run(prefix, app=nil)
+          if app
+            multi_run_apps[prefix.to_s] = app
+          else
+            multi_run_apps.delete(prefix.to_s)
+          end
           self::RodaRequest.refresh_multi_run_regexp!
         end
       end
@@ -91,7 +98,7 @@ class Roda
         # dispatch the request to the stored rack application.
         def multi_run
           on self.class.multi_run_regexp do |prefix|
-            yield prefix if block_given?
+            yield prefix if defined?(yield)
             run scope.class.multi_run_apps[prefix]
           end
         end

data/lib/roda/plugins/named_routes.rb

@@ -0,0 +1,168 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The named_routes plugin allows for multiple named routes, which the
+    # main route block can dispatch to by name at any point by calling +r.route+.
+    # If the named route doesn't handle the request, execution will continue,
+    # and if the named route does handle the request, the response returned by
+    # the named route will be returned.
+    #
+    # Example:
+    #
+    #   plugin :multi_route
+    #
+    #   route('foo') do |r|
+    #     r.is 'bar' do
+    #       '/foo/bar'
+    #     end
+    #   end
+    #
+    #   route('bar') do |r|
+    #     r.is 'foo' do
+    #       '/bar/foo'
+    #     end
+    #   end
+    #
+    #   route do |r|
+    #     r.on "foo" do
+    #       r.route 'foo'
+    #     end
+    #
+    #     r.on "bar" do
+    #       r.route 'bar'
+    #     end
+    #   end
+    #
+    # Note that in multi-threaded code, you should not attempt to add a
+    # named route after accepting requests.
+    #
+    # To handle development environments that reload code, you can call the
+    # +route+ class method without a block to remove an existing named route.
+    #
+    # == Routing Files
+    #
+    # The convention when using the named_routes plugin is to have a single
+    # named route per file, and these routing files should be stored in
+    # a routes subdirectory in your application.  So for the above example, you
+    # would use the following files:
+    #
+    #   routes/bar.rb
+    #   routes/foo.rb
+    #
+    # == Namespace Support
+    #
+    # The named_routes plugin also has support for namespaces, allowing you to
+    # use +r.route+ at multiple levels in your routing tree.  Example:
+    #
+    #   route('foo') do |r|
+    #     r.on("baz"){r.route("baz", "foo")}
+    #     r.on("quux"){r.route("quux", "foo")}
+    #   end
+    #
+    #   route('bar') do |r|
+    #     r.on("baz"){r.route("baz", "bar")}
+    #     r.on("quux"){r.route("quux", "bar")}
+    #   end
+    #
+    #   route('baz', 'foo') do |r|
+    #     # handles /foo/baz prefix
+    #   end
+    #
+    #   route('quux', 'foo') do |r|
+    #     # handles /foo/quux prefix
+    #   end
+    #
+    #   route('baz', 'bar') do |r|
+    #     # handles /bar/baz prefix
+    #   end
+    #
+    #   route('quux', 'bar') do |r|
+    #     # handles /bar/quux prefix
+    #   end
+    #
+    #   route do |r|
+    #     r.on "foo" do
+    #       r.route("foo")
+    #     end
+    #
+    #     r.on "bar" do
+    #       r.route("bar")
+    #     end
+    #   end
+    #
+    # === Routing Files
+    #
+    # The convention when using namespaces with the multi_route plugin is to
+    # store the routing files in subdirectories per namespace. So for the
+    # above example, you would have the following routing files:
+    #
+    #   routes/bar.rb
+    #   routes/bar/baz.rb
+    #   routes/bar/quux.rb
+    #   routes/foo.rb
+    #   routes/foo/baz.rb
+    #   routes/foo/quux.rb
+    module NamedRoutes
+      # Initialize storage for the named routes.
+      def self.configure(app)
+        app.opts[:namespaced_routes] ||= {}
+      end
+
+      module ClassMethods
+        # Freeze the namespaced routes so that there can be no thread safety issues at runtime.
+        def freeze
+          opts[:namespaced_routes].freeze.each_value(&:freeze)
+          super
+        end
+
+        # Copy the named routes into the subclass when inheriting.
+        def inherited(subclass)
+          super
+          nsr = subclass.opts[:namespaced_routes]
+          opts[:namespaced_routes].each{|k, v| nsr[k] = v.dup}
+        end
+
+        # The names for the currently stored named routes
+        def named_routes(namespace=nil)
+          unless routes = opts[:namespaced_routes][namespace]
+            raise RodaError, "unsupported named_routes namespace used: #{namespace.inspect}"
+          end
+          routes.keys
+        end
+
+        # Return the named route with the given name.
+        def named_route(name, namespace=nil)
+          opts[:namespaced_routes][namespace][name]
+        end
+
+        # If the given route has a name, treat it as a named route and
+        # store the route block.  Otherwise, this is the main route, so
+        # call super.
+        def route(name=nil, namespace=nil, &block)
+          if name
+            routes = opts[:namespaced_routes][namespace] ||= {}
+            if block
+              routes[name] = define_roda_method(routes[name] || "named_routes_#{namespace}_#{name}", 1, &convert_route_block(block))
+            elsif meth = routes[name]
+              routes.delete(name)
+              remove_method(meth)
+            end
+          else
+            super(&block)
+          end
+        end
+      end
+
+      module RequestMethods
+        # Dispatch to the named route with the given name.
+        def route(name, namespace=nil)
+          scope.send(roda_class.named_route(name, namespace), self)
+        end
+      end
+    end
+
+    register_plugin(:named_routes, NamedRoutes)
+  end
+end

data/lib/roda/plugins/path.rb

@@ -41,12 +41,12 @@ class Roda
     #     end
     #
     #     r.post 'baz' do
-    #       bar = Baz[1]
+    #       baz = Baz[1]
     #       r.redirect path(baz, 'c', 'd') # /baz/1/c/d
     #     end
     #
     #     r.post 'quux' do
-    #       bar = Quux[1]
+    #       quux = Quux[1]
     #       r.redirect url(quux, '/bar') # http://example.com/quux/1/bar
     #     end
     #   end

data/lib/roda/plugins/render.rb

@@ -47,7 +47,7 @@ class Roda
     # The following plugin options are supported:
     #
     # :allowed_paths :: Set the template paths to allow.  Attempts to render paths outside
-    #                   of this directory will raise an error.  Defaults to the +:views+ directory.
+    #                   of these paths will raise an error.  Defaults to the +:views+ directory.
     # :cache :: nil/false to explicitly disable premanent template caching.  By default, permanent
     #           template caching is disabled by default if RACK_ENV is development.  When permanent
     #           template caching is disabled, for templates with paths in the file system, the
@@ -59,9 +59,9 @@ class Roda
     #            templates, defaults to 'erb'.
     # :escape :: Use Erubi as the ERB template engine, and enable escaping by default,
     #            which makes <tt><%= %></tt> escape output and  <tt><%== %></tt> not escape output.
-    #            If given, sets the <tt>:escape=>true</tt> option for all template engines, which
+    #            If given, sets the <tt>escape: true</tt> option for all template engines, which
     #            can break some non-ERB template engines.  You can use a string or array of strings
-    #            as the value for this option to only set the <tt>:escape=>true</tt> option for those
+    #            as the value for this option to only set the <tt>escape: true</tt> option for those
     #            specific template engines.
     # :layout :: The base name of the layout file, defaults to 'layout'.  This can be provided as a hash
     #            with the :template or :inline options.
@@ -130,6 +130,84 @@ class Roda
     # only argument, you can speed things up by specifying a +:cache_key+ option in
     # the hash, making sure the +:cache_key+ is unique to the template you are
     # rendering.
+    #
+    # = Accepting Template Blocks in Methods
+    #
+    # If you are used to Rails, you may be surprised that this type of template code
+    # doesn't work in Roda:
+    #
+    #   <%= some_method do %>
+    #     Some HTML
+    #   <% end %>
+    #
+    # The reason this doesn't work is that this is not valid ERB syntax, it is Rails syntax,
+    # and requires attempting to parse the <tt>some_method do</tt> Ruby code with a regular
+    # expression.  Since Roda uses ERB syntax, it does not support this.
+    #
+    # In general, these methods are used to wrap the content of the block and
+    # inject the content into the output. To get similar behavior with Roda, you have
+    # a few different options you can use.
+    #
+    # == Directly Inject Template Output
+    #
+    # You can switch from a <tt><%=</tt> tag to using a <tt><%</tt> tag:
+    #
+    #   <% some_method do %>
+    #     Some HTML
+    #   <% end %>
+    #
+    # While this would output <tt>Some HTML</tt> into the template, it would not be able
+    # to inject content before or after the block.  However, you can use the inject_erb_plugin
+    # to handle the injection:
+    #
+    #   def some_method
+    #     inject_erb "content before block"
+    #     yield
+    #     inject_erb "content after block"
+    #   end
+    #
+    # If you need to modify the captured block before injecting it, you can use the
+    # capture_erb plugin to capture content from the template block, and modify that content,
+    # then use inject_erb to inject it into the template output:
+    #
+    #   def some_method(&block)
+    #     inject_erb "content before block"
+    #     inject_erb capture_erb(&block).upcase
+    #     inject_erb "content after block"
+    #   end
+    #
+    # This is the recommended approach for handling this type of method, if you want to keep
+    # the template block in the same template.
+    #
+    # == Separate Block Output Into Separate Template
+    #
+    # By moving the <tt>Some HTML</tt> into a separate template, you can render that
+    # template inside the block:
+    #
+    #  <%= some_method{render('template_name')} %>
+    #
+    # It's also possible to use an inline template:
+    #
+    #   <%= some_method do render(:inline=><<-END)
+    #     Some HTML
+    #     END
+    #   end %>
+    #
+    # This approach is useful if it makes sense to separate the template block into its
+    # own template. You lose the ability to use local variable from outside the
+    # template block inside the template block with this approach.
+    #
+    # == Separate Header and Footer
+    #
+    # You can define two separate methods, one that outputs the content before the block,
+    # and one that outputs the content after the block, and use those instead of a single
+    # call:
+    #
+    #   <%= some_method_before %>
+    #     Some HTML
+    #   <%= some_method_after %>
+    #
+    # This is the simplest option to setup, but it is fairly tedious to use.
     module Render
       # Support for using compiled methods directly requires Ruby 2.3 for the
       # method binding to work, and Tilt 1.2 for Tilt::Template#compiled_method.

data/lib/roda/plugins/run_handler.rb

@@ -34,7 +34,7 @@ class Roda
         # routing normally.
         def run(app, opts=OPTS)
           res = catch(:halt){super(app)}
-          yield res if block_given?
+          yield res if defined?(yield)
           throw(:halt, res) unless opts[:not_found] == :pass && res[0] == 404
         end
       end

data/lib/roda/plugins/shared_vars.rb

@@ -61,7 +61,7 @@ class Roda
         def shared(vars=nil)
           h = env['roda.shared'] ||= {}
 
-          if block_given?
+          if defined?(yield)
             if vars
               begin
                 env['roda.shared'] = h.merge(vars)

data/lib/roda/plugins/sinatra_helpers.rb

@@ -384,7 +384,7 @@ class Roda
 
         # Set or retrieve the response body. When a block is given,
         # evaluation is deferred until the body is needed.
-        def body(value = (return @body unless block_given?; nil), &block)
+        def body(value = (return @body unless defined?(yield); nil), &block)
           if block
             @body = DelayedBody.new(&block)
           else

data/lib/roda/plugins/status_303.rb

@@ -6,8 +6,7 @@ class Roda
     # The status_303 plugin sets the default redirect status to be 303
     # rather than 302 when the request is not a GET and the
     # redirection occurs on an HTTP 1.1 connection as per RFC 7231.
-    # The author knows of no cases where this actually matters in
-    # practice.
+    # There are some frontend frameworks that require this behavior.
     #
     # Example:
     #

data/lib/roda/plugins/typecast_params.rb

@@ -564,7 +564,7 @@ class Roda
           end
 
           v = @obj[key]
-          v = yield if v.nil? && block_given?
+          v = yield if v.nil? && defined?(yield)
 
           begin
             sub = self.class.nest(v, Array(@nesting) + [key])
@@ -580,7 +580,7 @@ class Roda
         # Return the nested value for key. If there is no nested_value for +key+,
         # calls the block to return the value, or returns nil if there is no block given.
         def fetch(key)
-          send(:[], key){return(yield if block_given?)}
+          send(:[], key){return(yield if defined?(yield))}
         end
 
         # Captures conversions inside the given block, and returns a hash of all conversions,

data/lib/roda/request.rb

@@ -520,7 +520,7 @@ class Roda
           if matchdata = pattern.match(@remaining_path)
             @remaining_path = matchdata.post_match
             captures = matchdata.captures
-            captures = yield(*captures) if block_given?
+            captures = yield(*captures) if defined?(yield)
             @captures.concat(captures)
           end
         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 = 47
+  RodaMinorVersion = 51
 
   # 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.47.0
+  version: 3.51.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-13 00:00:00.000000000 Z
+date: 2021-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -218,7 +218,11 @@ extra_rdoc_files:
 - doc/release_notes/3.45.0.txt
 - doc/release_notes/3.46.0.txt
 - doc/release_notes/3.47.0.txt
+- doc/release_notes/3.48.0.txt
+- doc/release_notes/3.49.0.txt
 - doc/release_notes/3.5.0.txt
+- doc/release_notes/3.50.0.txt
+- doc/release_notes/3.51.0.txt
 - doc/release_notes/3.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -272,7 +276,11 @@ files:
 - doc/release_notes/3.45.0.txt
 - doc/release_notes/3.46.0.txt
 - doc/release_notes/3.47.0.txt
+- doc/release_notes/3.48.0.txt
+- doc/release_notes/3.49.0.txt
 - doc/release_notes/3.5.0.txt
+- doc/release_notes/3.50.0.txt
+- doc/release_notes/3.51.0.txt
 - doc/release_notes/3.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -290,6 +298,7 @@ files:
 - lib/roda/plugins/backtracking_array.rb
 - lib/roda/plugins/branch_locals.rb
 - lib/roda/plugins/caching.rb
+- lib/roda/plugins/capture_erb.rb
 - lib/roda/plugins/chunked.rb
 - lib/roda/plugins/class_level_routing.rb
 - lib/roda/plugins/class_matchers.rb
@@ -325,6 +334,7 @@ files:
 - lib/roda/plugins/hooks.rb
 - lib/roda/plugins/host_authorization.rb
 - lib/roda/plugins/indifferent_params.rb
+- lib/roda/plugins/inject_erb.rb
 - lib/roda/plugins/json.rb
 - lib/roda/plugins/json_parser.rb
 - lib/roda/plugins/mail_processor.rb
@@ -339,6 +349,7 @@ files:
 - lib/roda/plugins/multi_run.rb
 - lib/roda/plugins/multi_view.rb
 - lib/roda/plugins/multibyte_string_matcher.rb
+- lib/roda/plugins/named_routes.rb
 - lib/roda/plugins/named_templates.rb
 - lib/roda/plugins/not_allowed.rb
 - lib/roda/plugins/not_found.rb
@@ -397,7 +408,7 @@ metadata:
   bug_tracker_uri: https://github.com/jeremyevans/roda/issues
   changelog_uri: http://roda.jeremyevans.net/rdoc/files/CHANGELOG.html
   documentation_uri: http://roda.jeremyevans.net/documentation.html
-  mailing_list_uri: https://groups.google.com/forum/#!forum/ruby-roda
+  mailing_list_uri: https://github.com/jeremyevans/roda/discussions
   source_code_uri: https://github.com/jeremyevans/roda
 post_install_message: 
 rdoc_options: []
@@ -414,7 +425,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.2.32
 signing_key: 
 specification_version: 4
 summary: Routing tree web toolkit