roda 3.49.0 → 3.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d3b9688bae8b0013acedfc6a5bcb45c374e0a73fd30e56985f0ebeee942ef8c
-  data.tar.gz: acb8215250d1615f007a2ec01d2b6546376414d2fea23a4f2341af9efd951110
+  metadata.gz: b9da24f38f427b9256f05e92f40d67fe98bbdefb86419e5b8c13243f88418f8a
+  data.tar.gz: 3acabff7d8879126d6fdf2199e0935c96d0ea1c975feef874122d67d2afe7315
 SHA512:
-  metadata.gz: 3a5434bdcb6926d6c5e656c25b46e16b035ad54d74ed16bdc1cf46005b8ef605b3371a628cae52d65803064aa3d2eac8a56c2e8e1e55b6f3a82c04a74c636855
-  data.tar.gz: 9dc3773fae04325373adb8a7a57d52166bb65c238b959999adf6f6f17a3be29fcdedcea677eeeaaa84f6a01b5accb4aff2594817165b8a77a45106a3d4a9dea3
+  metadata.gz: 7535b67bed981d52d337643c24f13b206163392594b3f969e611b79020a8578994b934a34abc186cf07850725c1ce8a99fbcb859b58cce289b8138b329ca4c68
+  data.tar.gz: 3fdbb4aa63d1cd82a7f6cbdfe01a9804388ab8b4461f9dda825332f030a1179737a21be4ea59c9e52fa856f6952d77578e972263397c62de4c42680340472313

data/CHANGELOG

@@ -1,3 +1,11 @@
+= 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)

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/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 defined?(yield) || value
-            if defined?(yield)
-              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/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/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/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/version.rb

@@ -4,7 +4,7 @@ class Roda
   RodaMajorVersion = 3
 
   # The minor version of Roda, updated for new feature releases of Roda.
-  RodaMinorVersion = 49
+  RodaMinorVersion = 50
 
   # 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.49.0
+  version: 3.50.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-13 00:00:00.000000000 Z
+date: 2021-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -221,6 +221,7 @@ extra_rdoc_files:
 - 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.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -277,6 +278,7 @@ files:
 - 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.6.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
@@ -294,6 +296,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
@@ -329,6 +332,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