roda 3.90.0 → 3.92.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c42c5f4d45d0f7fe64602e9d2a32bec3c690606c98709f7bd0bde537dd7a6463
-  data.tar.gz: c5f4edfdf88244770bd0184220df443ea5183c017f11c7342b4192db158d8d6c
+  metadata.gz: 63e0c8b5dc16e1652a1bbe309c046b681c8f11a90a31c2b2bd8368baa1b85f43
+  data.tar.gz: b81857ea9bc5ac7667f19fb730982d7b1259e95e1ff1b049d0c619fddf08a1be
 SHA512:
-  metadata.gz: 19ccf7e44d75f36bc372f2dcad01bb9bf23831c12397d142ea94d1e5f10d0cfe1be3f62f8f45e584ab9e4d0510c8d6acba7dd13e5d9df0680dece3838a43f5a6
-  data.tar.gz: 48e7c8fc21d75df1adfb616fa5fa88c2b410b290168b2fa1b14ab2c53f8f33167e039f310007dc19831e0571c4ce2b2d34c023b8b88c07d4ff666afe4b426ce9
+  metadata.gz: ca7712b09048602d91378cdb22ecf30e2d03cf43a215ad52d6aa697151abd88fe4873f4e162b617782f89b434f733d0230f7a3b8bacf252880450dc65308e4ac
+  data.tar.gz: 625b03ba51df7bc895b69e09a739584ae5ff6c15f7701e98a5e55fec301ed0e97353f503565811ae335534c1e6e0634916246fae99493851e472148c5c666789

data/lib/roda/plugins/assets.rb

@@ -60,7 +60,7 @@ class Roda
     #   <%= assets(:css, media: 'print') %>
     #
     # The assets method will respect the application's +:add_script_name+ option,
-    # if it set it will automatically prefix the path with the +SCRIPT_NAME+ for
+    # if it is set it will automatically prefix the path with the +SCRIPT_NAME+ for
     # the request.
     #
     # == Asset Paths

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/each_part.rb

@@ -0,0 +1,87 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The each_part plugin adds an each_part method, which is a
+    # render_each-like method that treats all keywords as locals.
+    #
+    #   # Can replace this:
+    #   render_each(enum, :template, locals: {foo: 'bar'})
+    #
+    #   # With this:
+    #   each_part(enum, :template, foo: 'bar')
+    #
+    # On Ruby 2.7+, the part method takes a keyword splat, so you
+    # must pass keywords and not a positional hash for the locals.
+    #
+    # If you are using the :assume_fixed_locals render plugin option,
+    # template caching is enabled, you are using Ruby 3+, and you
+    # are freezing your Roda application, in addition to providing a
+    # simpler API, this also provides a performance improvement.
+    module EachPart
+      def self.load_dependencies(app)
+        app.plugin :render_each
+      end
+
+      module ClassMethods
+        # When freezing, optimize the part method if assuming fixed locals
+        # and caching templates.
+        def freeze
+          if render_opts[:assume_fixed_locals] && !render_opts[:check_template_mtime]
+            include AssumeFixedLocalsInstanceMethods
+          end
+
+          super
+        end
+      end
+
+      module InstanceMethods
+        if RUBY_VERSION >= '2.7'
+          class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+            def each_part(enum, template, **locals, &block)
+              render_each(enum, template, :locals=>locals, &block)
+            end
+          RUBY
+        # :nocov:
+        else
+          def each_part(enum, template, locals=OPTS, &block)
+            render_each(enum, template, :locals=>locals, &block)
+          end
+        end
+        # :nocov:
+      end
+
+      module AssumeFixedLocalsInstanceMethods
+        # :nocov:
+        if RUBY_VERSION >= '3.0'
+        # :nocov:
+          class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+            def each_part(enum, template, **locals, &block)
+              if optimized_method = _cached_render_each_template_method(template)
+                optimized_method = optimized_method[0]
+                as = render_each_default_local(template)
+                if defined?(yield)
+                  enum.each do |v|
+                    locals[as] = v
+                    yield send(optimized_method, **locals)
+                  end
+                  nil
+                else
+                  enum.map do |v|
+                    locals[as] = v
+                    send(optimized_method, **locals)
+                  end.join
+                end
+              else
+                render_each(enum, template, :locals=>locals, &block)
+              end
+            end
+          RUBY
+        end
+      end
+    end
+
+    register_plugin(:each_part, EachPart)
+  end
+end

data/lib/roda/plugins/mailer.rb

@@ -103,7 +103,7 @@ class Roda
     # 
     #  Mailer.sendmail('/welcome/1', 'foo@example.com')
     #
-    #  r.mail 'welcome' do |user_id, mail_from| 
+    #  r.mail 'welcome', Integer do |user_id, mail_from| 
     #    from mail_from
     #    to User[user_id].email
     #    # ...

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,36 +77,48 @@ 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
 
           if as
             opts = opts.dup
-            if locals = opts[:locals]
-              locals = opts[:locals] = Hash[locals]
+            if locals
+              opts[:locals] = locals
             else
-              locals = opts[:locals] = {}
+              locals = opts[:locals] = if locals = opts[:locals]
+                Hash[locals]
+              else
+                {}
+              end
+              locals[as] = nil
             end
-            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
@@ -94,7 +138,8 @@ class Roda
             case template
             when String, Symbol
               if (method_cache = render_opts[:template_method_cache])
-                _cached_template_method_lookup(method_cache, [:_render_locals, template, [template.to_sym]])
+                key = render_opts[:assume_fixed_locals] ? template : [:_render_locals, template, [template.to_sym]]
+                _cached_template_method_lookup(method_cache, key)
               end
             else
               false
@@ -103,10 +148,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 = 92
 
   # 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.92.0
 platform: ruby
 authors:
 - Jeremy Evans
 bindir: bin
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -200,6 +200,7 @@ files:
 - lib/roda/plugins/direct_call.rb
 - lib/roda/plugins/disallow_file_uploads.rb
 - lib/roda/plugins/drop_body.rb
+- lib/roda/plugins/each_part.rb
 - lib/roda/plugins/early_hints.rb
 - lib/roda/plugins/empty_root.rb
 - lib/roda/plugins/environments.rb
@@ -326,7 +327,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Routing tree web toolkit
 test_files: []