roda 3.90.0 → 3.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c42c5f4d45d0f7fe64602e9d2a32bec3c690606c98709f7bd0bde537dd7a6463
-  data.tar.gz: c5f4edfdf88244770bd0184220df443ea5183c017f11c7342b4192db158d8d6c
+  metadata.gz: e89aa3dd4e7c27d33d8b989c87a661a42e28c771aa8c96109279cc8131a4c5f5
+  data.tar.gz: e54282de7adf4827dcda2e29c82bbec6d8d76bbbefe29185d3d35b92f3390a50
 SHA512:
-  metadata.gz: 19ccf7e44d75f36bc372f2dcad01bb9bf23831c12397d142ea94d1e5f10d0cfe1be3f62f8f45e584ab9e4d0510c8d6acba7dd13e5d9df0680dece3838a43f5a6
-  data.tar.gz: 48e7c8fc21d75df1adfb616fa5fa88c2b410b290168b2fa1b14ab2c53f8f33167e039f310007dc19831e0571c4ce2b2d34c023b8b88c07d4ff666afe4b426ce9
+  metadata.gz: a403baf3ca83c6e636c59c1a598319aa41254ad8bffb6e18ba0f81eebf1260674c30f3954b471da60be605d397496d0c2bb96ff286d5e094ea17a4745dc67f82
+  data.tar.gz: 2caeb451da13d935c1e14e7009304a16e256942926237704cd80baf32f9fa9d534b58830d8d4092cefec4940cc40fe90e01b33152183d43877900d479135e710

data/lib/roda/plugins/capture_erb.rb

@@ -21,26 +21,66 @@ class Roda
     # used as the template engine), this will call +capture+ on the
     # output buffer object, instead of setting the output buffer object
     # temporarily to a new object.
+    #
+    # By default, capture_erb returns the value of the block, converted
+    # to a string.  However, that can cause issues with code such as:
+    #
+    #   <% value = capture_erb do %>
+    #     Some content here.
+    #     <% if something %>
+    #       Some more content here.
+    #     <% end %>
+    #   <% end %>
+    #
+    # In this case, the block may return nil, instead of the content of
+    # the template.  To handle this case, you can provide the
+    # <tt>returns: :buffer</tt> option when calling the method (to handle
+    # that specific call, or when loading the plugin (to default to that
+    # behavior). Note that if the output buffer object responds to
+    # +capture+ and is not an instance of String, the <tt>returns: :buffer</tt>
+    # behavior is the default and cannot be changed.
     module CaptureERB
-      def self.load_dependencies(app)
+      def self.load_dependencies(app, opts=OPTS)
         app.plugin :render
       end
 
+      # Support <tt>returns: :buffer</tt> to default to returning buffer
+      # object.
+      def self.configure(app, opts=OPTS)
+        # RODA4: make returns: :buffer the default behavior
+        app.opts[:capture_erb_returns] = opts[:returns] if opts.has_key?(:returns)
+      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(&block)
+        #
+        # Options:
+        # :returns :: If set to :buffer, returns the value of the
+        #             template output variable, instead of the return
+        #             value of the block converted to a string. This
+        #             is the default behavior if the template output
+        #             variable supports the +capture+ method and is not
+        #             a String instance.
+        def capture_erb(opts=OPTS, &block)
           outvar = render_opts[:template_opts][:outvar]
           buf_was = instance_variable_get(outvar)
 
           if buf_was.respond_to?(:capture) && !buf_was.instance_of?(String)
             buf_was.capture(&block)
           else
+            returns = opts.fetch(:returns) { self.opts[:capture_erb_returns] }
+
             begin
               instance_variable_set(outvar, String.new)
-              yield.to_s
+              if returns == :buffer
+                yield
+                instance_variable_get(outvar).to_s
+              else
+                yield.to_s
+              end
             ensure
               instance_variable_set(outvar, buf_was) if outvar && buf_was
             end

data/lib/roda/plugins/render_each.rb

@@ -15,6 +15,38 @@ class Roda
     # is rendered, the local variable +foo+ will contain the given
     # value (e.g. on the first rendering +foo+ is 1).
     #
+    # If you provide a block when calling the method, it will yield
+    # each rendering instead of returning a concatentation of the
+    # renderings. This is useful if you want to wrap each rendering in
+    # something else.  For example, instead of calling +render+ multiple
+    # times in a loop:
+    #
+    #   <% [1,2,3].each do |v| %>
+    #     <p><%= render(:foo, locals: {foo: v}) %></p>
+    #   <% end %>
+    #  
+    # You can use +render_each+, allowing for simpler and more optimized
+    # code:
+    #
+    #   <% render_each([1,2,3], :foo) do |text| %>
+    #     <p><%= text %></p>
+    #   <% end %>
+    #
+    # You can also provide a block to avoid excess memory usage.  For
+    # example, if you are calling the method inside an erb template,
+    # instead of doing:
+    #
+    #   <%= render_each([1,2,3], :foo) %>
+    #
+    # You can do:
+    #
+    #   <% render_each([1,2,3], :foo) %><%= body %><% end %>
+    #
+    # This results in the same behavior, but avoids building a large
+    # intermediate string just to concatenate to the template result.
+    #
+    # When passing a block, +render_each+ returns +nil+.
+    #
     # You can pass additional render options via an options hash:
     #
     #   render_each([1,2,3], :foo, views: 'partials')
@@ -45,15 +77,15 @@ class Roda
         # :local :: The local variable to use for the current enum value
         #           inside the template.  An explicit +nil+ value does not
         #           set a local variable.  If not set, uses the template name.
-        def render_each(enum, template, opts=(no_opts = true; optimized_template = _cached_render_each_template_method(template); OPTS))
+        def render_each(enum, template, opts=(no_opts = true; optimized_template = _cached_render_each_template_method(template); OPTS), &block)
           if optimized_template
-            return _optimized_render_each(enum, optimized_template, render_each_default_local(template), {})
+            return _optimized_render_each(enum, optimized_template, render_each_default_local(template), {}, &block)
           elsif opts.has_key?(:local)
             as = opts[:local]
           else
             as = render_each_default_local(template)
             if no_opts && optimized_template.nil? && (optimized_template = _optimized_render_method_for_locals(template, (locals = {as=>nil})))
-              return _optimized_render_each(enum, optimized_template, as, locals)
+              return _optimized_render_each(enum, optimized_template, as, locals, &block)
             end
           end
 
@@ -67,14 +99,22 @@ class Roda
             locals[as] = nil
 
             if (opts.keys - ALLOWED_KEYS).empty? && (optimized_template = _optimized_render_method_for_locals(template, locals))
-              return _optimized_render_each(enum, optimized_template, as, locals)
+              return _optimized_render_each(enum, optimized_template, as, locals, &block)
             end
           end
 
-          enum.map do |v|
-            locals[as] = v if as
-            render_template(template, opts)
-          end.join
+          if defined?(yield)
+            enum.each do |v|
+              locals[as] = v if as
+              yield render_template(template, opts)
+            end
+            nil
+          else
+            enum.map do |v|
+              locals[as] = v if as
+              render_template(template, opts)
+            end.join
+          end
         end
         
         private
@@ -103,10 +143,18 @@ class Roda
 
           # Use an optimized render for each value in the enum.
           def _optimized_render_each(enum, optimized_template, as, locals)
-            enum.map do |v|
-              locals[as] = v
-              _call_optimized_template_method(optimized_template, locals)
-            end.join
+            if defined?(yield)
+              enum.each do |v|
+                locals[as] = v
+                yield _call_optimized_template_method(optimized_template, locals)
+              end
+              nil
+            else
+              enum.map do |v|
+                locals[as] = v
+                _call_optimized_template_method(optimized_template, locals)
+              end.join
+            end
           end
         else
           def _cached_render_each_template_method(template)

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 = 90
+  RodaMinorVersion = 91
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.90.0
+  version: 3.91.0
 platform: ruby
 authors:
 - Jeremy Evans
 bindir: bin
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack