erubi 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0424c43d37611204a83153f9cffb1e259027a0f1a1edd16b3b5cfef09ec7b137
-  data.tar.gz: 796b2b90f46c80297fdf05b3070f9bad10fc9199946878c0bfbfe7435ce5466c
+  metadata.gz: 9364047dc0b7365bae5a6f9ee75c748a0ef02bf4e516331c2d0533da9fe49e04
+  data.tar.gz: 9416aeee2c6c4556c3f19f7b918819cbe076493601efd9470815870fac1a2625
 SHA512:
-  metadata.gz: 8833bc8ec00db215ef73c71271c97e668861f920c339de7df658f1cf464761b62b2811845a062b681bb30966b7797beec708674929aa9400159e1bfdce3c31dd
-  data.tar.gz: 74fa7a9107f056dbcb3bb2efedb858a7f120d8c36d378da1eb425783c75e2a398ffd4b301c1e300cc684b98155d9b67abb07d1589f1be9786282756a0140449b
+  metadata.gz: ecd851eb258b2a0302d6a46b747722100aad3a145c4c22b6d1d14f856f094507ebbc84e151a1b9cd9795bb59b0154866e38a08798c75e9726c45b4d987ec48e5
+  data.tar.gz: 0c1f32494ca8a192de037c1497065e1f0901cf646fbb090972de215bf66f0fbf2e0774fa38309c50eab288d60dfe59a634e431395912275ec75a2aa3bf4c66be

data/CHANGELOG

@@ -1,3 +1,15 @@
+=== 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)
+
+* Default :freeze_template_literals option to false if running with --enable-frozen-string-literal (casperisfine) (#35)
+
 === 1.11.0 (2022-08-02)
 
 * Support :freeze_template_literals option for configuring whether to add .freeze to template literal strings (casperisfine) (#33)

data/README.rdoc

@@ -8,8 +8,8 @@ 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 86% smaller memory footprint
+* 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)
 * Has simpler internals (1 file, <150 lines of code)
@@ -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.11.0'
+  VERSION = '1.13.0'
 
   # :nocov:
   if RUBY_VERSION >= '1.9'
@@ -14,34 +14,39 @@ module Erubi
 
   MATCH_METHOD = RUBY_VERSION >= '2.4' ? :match? : :match
   SKIP_DEFINED_FOR_INSTANCE_VARIABLE = RUBY_VERSION > '3'
+  FREEZE_TEMPLATE_LITERALS = !eval("''").frozen? && RUBY_VERSION >= '2.1'
   # :nocov:
 
   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)
-      CGI.escapeHTML(value.to_s)
-    end
+    require 'erb/escape'
+    define_method(:h, ERB::Escape.instance_method(:html_escape))
+  # :nocov:
   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)
-        value.to_s.gsub(/[&<>"']/, ESCAPE_TABLE)
+    begin
+      require 'cgi/escape'
+      unless CGI.respond_to?(:escapeHTML) # work around for JRuby 9.1
+        CGI = Object.new
+        CGI.extend(defined?(::CGI::Escape) ? ::CGI::Escape : ::CGI::Util)
+      end
+      # Escape characters with their HTML/XML equivalents.
+      def h(value)
+        CGI.escapeHTML(value.to_s)
       end
-    else
-      def self.h(value)
-        value.to_s.gsub(/[&<>"']/){|s| ESCAPE_TABLE[s]}
+    rescue LoadError
+      ESCAPE_TABLE = {'&' => '&amp;'.freeze, '<' => '&lt;'.freeze, '>' => '&gt;'.freeze, '"' => '&quot;'.freeze, "'" => '&#39;'.freeze}.freeze
+      if RUBY_VERSION >= '1.9'
+        def h(value)
+          value.to_s.gsub(/[&<>"']/, ESCAPE_TABLE)
+        end
+      else
+        def h(value)
+          value.to_s.gsub(/[&<>"']/){|s| ESCAPE_TABLE[s]}
+        end
       end
     end
-    # :nocov:
   end
+  # :nocov:
+  module_function :h
 
   class Engine
     # The default regular expression used for scanning.
@@ -95,7 +100,7 @@ module Erubi
       preamble   = properties[:preamble] || "#{bufvar} = #{bufval};"
       postamble  = properties[:postamble] || "#{bufvar}.to_s\n"
       @chain_appends = properties[:chain_appends]
-      @text_end = if properties.fetch(:freeze_template_literals, RUBY_VERSION >= '2.1')
+      @text_end = if properties.fetch(:freeze_template_literals, FREEZE_TEMPLATE_LITERALS)
         "'.freeze"
       else
         "'"

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: erubi
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Jeremy Evans
 - kuwata-lab.com
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-02 00:00:00.000000000 Z
+date: 2024-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -53,15 +53,17 @@ files:
 - README.rdoc
 - Rakefile
 - lib/erubi.rb
+- lib/erubi/capture_block.rb
 - lib/erubi/capture_end.rb
 homepage: https://github.com/jeremyevans/erubi
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jeremyevans/erubi/issues
+  mailing_list_uri: https://github.com/jeremyevans/erubi/discussions
   changelog_uri: https://github.com/jeremyevans/erubi/blob/master/CHANGELOG
   source_code_uri: https://github.com/jeremyevans/erubi
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--quiet"
 - "--line-numbers"
@@ -83,8 +85,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.5.9
+signing_key:
 specification_version: 4
 summary: Small ERB Implementation
 test_files: []