erubi 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0cae36e4fa5e180f0934c68f04a936a6f51df57e8ef1a4436a907ab408a85a7
-  data.tar.gz: ceaeb0da7540a786c6e65cf8bb1c72ad60bf7309f0a9f0cdf460c32236d80a2c
+  metadata.gz: 9364047dc0b7365bae5a6f9ee75c748a0ef02bf4e516331c2d0533da9fe49e04
+  data.tar.gz: 9416aeee2c6c4556c3f19f7b918819cbe076493601efd9470815870fac1a2625
 SHA512:
-  metadata.gz: 3c2a45e5cbd23b6f85257fcb7139e92cd116b0854fb5386b73331b05314aa0020725ac1bd918e4156e253df1cf7f5f58e6db86874f3180dabc5d8e38d1d910d3
-  data.tar.gz: 54a5c8d8d72bfcc8344f9f4224d36070d90d61817deaa601f25dfee24edc4b6f408f5a00b09891075959a1a41d6fa67046594c5e5e3b65707e24f737777de716
+  metadata.gz: ecd851eb258b2a0302d6a46b747722100aad3a145c4c22b6d1d14f856f094507ebbc84e151a1b9cd9795bb59b0154866e38a08798c75e9726c45b4d987ec48e5
+  data.tar.gz: 0c1f32494ca8a192de037c1497065e1f0901cf646fbb090972de215bf66f0fbf2e0774fa38309c50eab288d60dfe59a634e431395912275ec75a2aa3bf4c66be

data/CHANGELOG

@@ -1,3 +1,9 @@
+=== 1.13.0 (2024-06-13)
+
+* Define Erubi.h as a module function (jeremyevans)
+
+* Add erubi/capture_block, supporting capturing block output via standard <%= and <%== tags (jeremyevans)
+
 === 1.12.0 (2022-12-22)
 
 * Use erb/escape for faster html escaping if available (jeremyevans)

data/README.rdoc

@@ -8,7 +8,7 @@ the same basic algorithm, with the following differences:
 * Works with ruby's <tt>--enable-frozen-string-literal</tt> option
 * Automatically freezes strings for template text when ruby optimizes it (on ruby 2.1+)
 * Escapes <tt>'</tt> (apostrophe) when escaping for better XSS protection 
-* Has 6x faster escaping on ruby 2.3+ by using cgi/escape
+* Has 15x-6x faster escaping by using erb/escape or cgi/escape
 * Has 81% smaller memory footprint (calculated using +ObjectSpace.memsize_of_all+)
 * Does no monkey patching (Erubis adds a method to Kernel)
 * Uses an immutable design (all options passed to the constructor, which returns a frozen object)
@@ -42,33 +42,75 @@ erb template handler in Tilt 2.0.6+ and Rails 5.1+.
 == Capturing
 
 Erubi does not support capturing block output into the template by default.
-However, it comes with an +erubi/capture_end+ file that supports capturing
-via <tt><%|=</tt> and <tt><%|==</tt> tags which are closed with a
-<tt><%|</tt> tag:
+It currently ships with two implementations that allow it.
 
-  <%|= form do %>
+=== Erubi::CaptureBlockEngine
+
+The recommended implementation can be required via +erubi/capture_block+,
+which allows capturing to work with normal <tt><%=</tt> and <tt><%==</tt>
+tags.
+
+  <%= form do %>
     <input>
-  <%| end %>
+  <% end %>
+
+When using the capture_block support, capture methods should just return
+the text it emit into the template, and call +capture+ on the buffer value.
+Since the buffer variable is a local variable and not an instance variable
+by default, you'll probably want to set the +:bufvar+ variable when using
+the capture_block support to an instance variable, and have any methods
+used call capture on that instance variable.  Example:
+
+  def form(&block)
+    "<form>#{@_buf.capture(&block)}</form>"
+  end
 
-This offers similar functionality to that offered by Rails' <tt><%=</tt>
-tags, but without the corner cases with that approach (which are due to
-attempting to parse ruby code via a regexp).  Similar to the <tt><%=</tt>
-and <tt><%==</tt> tags, <tt><%|=</tt> captures by default and
-<tt><%|==</tt> captures and escapes by default, but this can be reversed
-via the +:escape_capture+ or +:escape+ options.
+  puts eval(Erubi::CaptureBlockEngine.new(<<-END, bufvar: '@_buf', trim: false).src)
+  before
+  <%= form do %>
+  inside
+  <% end %>
+  after
+  END
+
+  # Output:
+  # before
+  # <form>
+  # inside
+  # </form>
+  # after
 
-To use the capture_end support with tilt:
+To use the capture_block support with tilt:
 
   require 'tilt'
-  require 'erubi/capture_end'
-  Tilt.new("filename.erb", :engine_class=>Erubi::CaptureEndEngine).render
+  require 'erubi/capture_block'
+  Tilt.new("filename.erb", :engine_class=>Erubi::CaptureBlockEngine).render
+
+Note that the capture_block support, while very compatible with the default
+support, is not 100% compatible.  One area where behavior differs is when
+using multiple statements inside <tt><%=</tt> and <tt><%==</tt> tags:
+
+  <%= 1; 2 %>
+
+The default support will output 2, but the capture_block support will output
+1.
+
+=== Erubi::CaptureEndEngine
+
+An alternative capture implementation can be required via +erubi/capture_end+,
+which supports it via <tt><%|=</tt> and <tt><%|==</tt> tags which are
+closed with a <tt><%|</tt> tag:
+
+  <%|= form do %>
+    <input>
+  <%| end %>
+
+It is only recommended to use +erubi/capture_end+ for backwards
+compatibilty.
 
-When using the capture_end support, any methods (such as +form+ in the example
-above) should return the (potentially modified) buffer.  Since the buffer
-variable is a local variable and not an instance variable by default, you'll
-probably want to set the +:bufvar+ variable when using the capture_end
-support to an instance variable, and have any methods used access that
-instance variable.  Example:
+When using the capture_end support, capture methods (such as +form+ in the example
+above) should return the (potentially modified) buffer. Similar to the
+capture_block support, using an instance variable is recommended. Example:
 
   def form
     @_buf << "<form>"
@@ -77,7 +119,7 @@ instance variable.  Example:
     @_buf
   end
 
-  puts eval(Erubi::CaptureEndEngine.new(<<-END, :bufvar=>:@_buf).src)
+  puts eval(Erubi::CaptureEndEngine.new(<<-END, bufvar: '@_buf').src)
   before
   <%|= form do %>
   inside

data/Rakefile

@@ -16,7 +16,7 @@ end
 RDOC_DEFAULT_OPTS = ["--line-numbers", "--inline-source", '--title', 'Erubi: Small ERB Implementation']
 
 begin
-  gem 'hanna-nouveau'
+  gem 'hanna'
   RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
 rescue Gem::LoadError
 end

data/lib/erubi/capture_block.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'erubi'
+
+module Erubi
+  # An engine class that supports capturing blocks via the <tt><%=</tt> and <tt><%==</tt> tags:
+  #
+  #   <%= upcase_form do %>
+  #     <%= 'foo' %>
+  #   <% end %>
+  #
+  # Where +upcase_form+ is defined like:
+  #
+  #   def upcase_form(&block)
+  #     "<form>#{@bufvar.capture(&block).upcase}</form>"
+  #   end
+  #
+  # With output being:
+  #
+  #   <form>
+  #     FOO
+  #   </form>
+  #
+  # This requires using a string subclass as the buffer value, provided by the
+  # CaptureBlockEngine::Buffer class.
+  #
+  # This engine does not support the :escapefunc option.  To change the escaping function,
+  # use a subclass of CaptureBlockEngine::Buffer and override the #| method.
+  #
+  # This engine does not support the :chain_appends option, and ignores it if present.
+  class CaptureBlockEngine < Engine
+    class Buffer < ::String
+    
+      # Convert argument to string when concatening
+      def <<(v)
+        concat(v.to_s)
+      end
+
+      # Escape argument using Erubi.h then then concatenate it to the receiver.
+      def |(v)
+        concat(h(v))
+      end
+
+      # Temporarily clear the receiver before yielding to the block, yield the
+      # given args to the block, return any data captured by the receiver, and
+      # restore the original data the receiver contained before returning.
+      def capture(*args)
+        prev = dup
+        replace("") # 1.8 support!
+        yield(*args)
+        dup
+      ensure
+        replace(prev)
+      end
+
+      private
+
+      if RUBY_VERSION >= '2'
+        define_method(:h, ::Erubi.instance_method(:h))
+      # :nocov:
+      else
+        def h(v)
+          ::Erubi.h(v)
+        end
+      end
+      # :nocov:
+    end
+
+    def initialize(input, properties={})
+      properties = Hash[properties]
+      properties[:bufval] ||= '::Erubi::CaptureBlockEngine::Buffer.new'
+      properties[:chain_appends] = false
+      super
+    end
+
+    private
+
+    def add_expression_result(code)
+      add_expression_op(' <<= ', code)
+    end
+
+    def add_expression_result_escaped(code)
+      add_expression_op(' |= ', code)
+    end
+
+    def add_expression_op(op, code)
+      check = /\A\s*\z/.send(MATCH_METHOD, code) ? "''" : ''
+      with_buffer{@src << op  << check << code}
+    end
+  end
+end

data/lib/erubi.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Erubi
-  VERSION = '1.12.0'
+  VERSION = '1.13.0'
 
   # :nocov:
   if RUBY_VERSION >= '1.9'
@@ -19,37 +19,34 @@ module Erubi
 
   begin
     require 'erb/escape'
-    # :nocov:
-    define_singleton_method(:h, ERB::Escape.instance_method(:html_escape))
-    # :nocov:
+    define_method(:h, ERB::Escape.instance_method(:html_escape))
+  # :nocov:
   rescue LoadError
     begin
       require 'cgi/escape'
-      # :nocov:
       unless CGI.respond_to?(:escapeHTML) # work around for JRuby 9.1
         CGI = Object.new
         CGI.extend(defined?(::CGI::Escape) ? ::CGI::Escape : ::CGI::Util)
       end
-      # :nocov:
       # Escape characters with their HTML/XML equivalents.
-      def self.h(value)
+      def h(value)
         CGI.escapeHTML(value.to_s)
       end
     rescue LoadError
-      # :nocov:
       ESCAPE_TABLE = {'&' => '&amp;'.freeze, '<' => '&lt;'.freeze, '>' => '&gt;'.freeze, '"' => '&quot;'.freeze, "'" => '&#39;'.freeze}.freeze
       if RUBY_VERSION >= '1.9'
-        def self.h(value)
+        def h(value)
           value.to_s.gsub(/[&<>"']/, ESCAPE_TABLE)
         end
       else
-        def self.h(value)
+        def h(value)
           value.to_s.gsub(/[&<>"']/){|s| ESCAPE_TABLE[s]}
         end
       end
-      # :nocov:
     end
   end
+  # :nocov:
+  module_function :h
 
   class Engine
     # The default regular expression used for scanning.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: erubi
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Jeremy Evans
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-22 00:00:00.000000000 Z
+date: 2024-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -53,6 +53,7 @@ files:
 - README.rdoc
 - Rakefile
 - lib/erubi.rb
+- lib/erubi/capture_block.rb
 - lib/erubi/capture_end.rb
 homepage: https://github.com/jeremyevans/erubi
 licenses:
@@ -84,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Small ERB Implementation