erubi 1.10.0 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f504eb8d1ae0f89e098de29336a69d0251cd8659a1b6fe1ab86c7f23ed44d67
-  data.tar.gz: e54396a6eb2cf0c193089c9b2c3d5fa0f92daf5cf4f462fe09d0aea6dca49419
+  metadata.gz: 547aa741f72fd87ac7747c597614f457b3880d01d3b3aa161c24e62c93f00cc7
+  data.tar.gz: d465d4b57e9abe24de9cf5859773691dfee9198ca0c4d05a5ca8f0903b2acefd
 SHA512:
-  metadata.gz: 0a789b8a528548760ac4898867588477e03c3f1410bd930538c849e167c68a346202f8c168a2a71107485c961bb41a91d549f687a4d24ebf3614821bc15b4e73
-  data.tar.gz: 14e74f5fb8c452c0cbc15afbe51b8a86be572d8d585416f09f07d9227e06ad8d8c14d8681424dc53f9b7eaba1a1297ed72e8e7dc0c36afe6e2da1926bec742d0
+  metadata.gz: 109432844ed8df5daab8e5b6e6aa2404c314009f968129ec02c920f6c75094f4a484207751d34cb2255d6c3d5f286e14c369ba54dc398e06266d22e84e2f4e24
+  data.tar.gz: 5eab140a49714dd65c67b9eb7e196a86f25c9a3a59348b04dc3d7b57db8c0cbccbca28f94dae2ae69c04382e5ab6c4350c7f8dd99db2dbbd0121ba0759bd0ca1

data/CHANGELOG

@@ -1,3 +1,27 @@
+=== 1.13.1 (2024-12-19)
+
+* Avoid spurious frozen string literal warnings for chilled strings when using Ruby 3.4 (jeremyevans)
+
+=== 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)
+
+* Support :chain_appends option for chaining appends to the buffer variable (casperisfine, jeremyevans) (#32)
+
+* Avoid unnecessary defined? usage on Ruby 3+ when using the :ensure option (jeremyevans)
+
 === 1.10.0 (2020-11-13)
 
 * Improve template parsing, mostly by reducing allocations (jeremyevans)

data/MIT-LICENSE

@@ -1,5 +1,5 @@
 copyright(c) 2006-2011 kuwata-lab.com all rights reserved.
-copyright(c) 2016-2020 Jeremy Evans
+copyright(c) 2016-2021 Jeremy Evans
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

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
@@ -42,7 +42,7 @@ end
 
 spec = proc do |env|
   env.each{|k,v| ENV[k] = v}
-  sh "#{FileUtils::RUBY} test/test.rb"
+  sh "#{FileUtils::RUBY} #{'-w' if RUBY_VERSION >= '3'} #{'-W:strict_unused_block' if RUBY_VERSION >= '3.4'} test/test.rb"
   env.each{|k,v| ENV.delete(k)}
 end
 
@@ -57,11 +57,6 @@ desc "Run specs with coverage"
 task "spec_cov" do
   spec.call('COVERAGE'=>'1')
 end
-  
-desc "Run specs with -w, some warnings filtered"
-task "spec_w" do
-  sh "#{FileUtils::RUBY} test/test_w.rb"
-end
 
 ### Other
 

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

@@ -36,13 +36,19 @@ module Erubi
         rspace = nil if tailch && !tailch.empty?
         add_text(lspace) if lspace
         escape_capture = !((indicator == '|=') ^ @escape_capture)
-        src << "begin; (#{@bufstack} ||= []) << #{@bufvar}; #{@bufvar} = #{@bufval}; #{@bufstack}.last << #{@escapefunc if escape_capture}((" << code
+        terminate_expression
+        @src << "begin; (#{@bufstack} ||= []) << #{@bufvar}; #{@bufvar} = #{@bufval}; #{@bufstack}.last << #{@escapefunc if escape_capture}((" << code
+        @buffer_on_stack = false
         add_text(rspace) if rspace
       when '|'
         rspace = nil if tailch && !tailch.empty?
         add_text(lspace) if lspace
-        result = @yield_returns_buffer ? " #{@bufvar}; " : ""
-        src << result << code << ")).to_s; ensure; #{@bufvar} = #{@bufstack}.pop; end;"
+        if @yield_returns_buffer
+          terminate_expression
+          @src << " #{@bufvar}; "
+        end
+        @src << code << ")).to_s; ensure; #{@bufvar} = #{@bufstack}.pop; end;"
+        @buffer_on_stack = false
         add_text(rspace) if rspace
       else
         super

data/lib/erubi.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Erubi
-  VERSION = '1.10.0'
-  RANGE_ALL = 0..-1
+  VERSION = '1.13.1'
 
   # :nocov:
   if RUBY_VERSION >= '1.9'
@@ -13,38 +12,46 @@ module Erubi
     RANGE_LAST = -1..-1
   end
 
-  TEXT_END = RUBY_VERSION >= '2.1' ? "'.freeze;" : "';"
   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
-    else
-      def self.h(value)
-        value.to_s.gsub(/[&<>"']/){|s| ESCAPE_TABLE[s]}
+      # Escape characters with their HTML/XML equivalents.
+      def h(value)
+        CGI.escapeHTML(value.to_s)
+      end
+    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.
+    DEFAULT_REGEXP = /<%(={1,2}|-|\#|%)?(.*?)([-=])?%>([ \t]*\r?\n)?/m
+    
     # The frozen ruby source code generated from the template, which can be evaled.
     attr_reader :src
 
@@ -57,12 +64,22 @@ module Erubi
     # Initialize a new Erubi::Engine.  Options:
     # +:bufval+ :: The value to use for the buffer variable, as a string (default <tt>'::String.new'</tt>).
     # +:bufvar+ :: The variable name to use for the buffer variable, as a string.
+    # +:chain_appends+ :: Whether to chain <tt><<</t> calls to the buffer variable. Offers better
+    #                     performance, but can cause issues when the buffer variable is reassigned during
+    #                     template rendering (default +false+).
     # +:ensure+ :: Wrap the template in a begin/ensure block restoring the previous value of bufvar.
     # +:escapefunc+ :: The function to use for escaping, as a string (default: <tt>'::Erubi.h'</tt>).
     # +:escape+ :: Whether to make <tt><%=</tt> escape by default, and <tt><%==</tt> not escape by default.
     # +:escape_html+ :: Same as +:escape+, with lower priority.
     # +:filename+ :: The filename for the template.
-    # +:freeze+ :: Whether to enable frozen string literals in the resulting source code.
+    # +:freeze+ :: Whether to enable add a <tt>frozen_string_literal: true</tt> magic comment at the top of
+    #              the resulting source code.  Note this may cause problems if you are wrapping the resulting
+    #              source code in other code, because the magic comment only has an effect at the beginning of
+    #              the file, and having the magic comment later in the file can trigger warnings.
+    # +:freeze_template_literals+ :: Whether to suffix all literal strings for template code with <tt>.freeze</tt>
+    #                                (default: +true+ on Ruby 2.1+, +false+ on Ruby 2.0 and older).
+    #                                Can be set to +false+ on Ruby 2.3+ when frozen string literals are enabled
+    #                                in order to improve performance.
     # +:literal_prefix+ :: The prefix to output when using escaped tag delimiters (default <tt>'<%'</tt>).
     # +:literal_postfix+ :: The postfix to output when using escaped tag delimiters (default <tt>'%>'</tt>).
     # +:outvar+ :: Same as +:bufvar+, with lower priority.
@@ -77,20 +94,34 @@ module Erubi
       @filename  = properties[:filename]
       @bufvar = bufvar = properties[:bufvar] || properties[:outvar] || "_buf"
       bufval = properties[:bufval] || '::String.new'
-      regexp = properties[:regexp] || /<%(={1,2}|-|\#|%)?(.*?)([-=])?%>([ \t]*\r?\n)?/m
+      regexp = properties[:regexp] || DEFAULT_REGEXP
       literal_prefix = properties[:literal_prefix] || '<%'
       literal_postfix = properties[:literal_postfix] || '%>'
       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, FREEZE_TEMPLATE_LITERALS)
+        "'.freeze"
+      else
+        "'"
+      end
 
+      @buffer_on_stack = false
       @src = src = properties[:src] || String.new
       src << "# frozen_string_literal: true\n" if properties[:freeze]
-      src << "begin; __original_outvar = #{bufvar} if defined?(#{bufvar}); " if properties[:ensure]
+      if properties[:ensure]
+        src << "begin; __original_outvar = #{bufvar}"
+        if SKIP_DEFINED_FOR_INSTANCE_VARIABLE && /\A@[^@]/ =~ bufvar
+          src << "; "
+        else
+          src << " if defined?(#{bufvar}); "
+        end
+      end
 
       unless @escapefunc = properties[:escapefunc]
         if escape
           @escapefunc = '__erubi.h'
-          src << "__erubi = ::Erubi;"
+          src << "__erubi = ::Erubi; "
         else
           @escapefunc = '::Erubi.h'
         end
@@ -174,23 +205,35 @@ module Erubi
 
     private
 
+    if RUBY_VERSION >= '2.3'
+      def _dup_string_if_frozen(string)
+        +string
+      end
+    # :nocov:
+    else
+      def _dup_string_if_frozen(string)
+        string.frozen? ? string.dup : string
+      end
+    end
+    # :nocov:
+
     # Add raw text to the template.  Modifies argument if argument is mutable as a memory optimization.
     # Must be called with a string, cannot be called with nil (Rails's subclass depends on it).
     def add_text(text)
       return if text.empty?
 
-      if text.frozen?
-        text = text.gsub(/['\\]/, '\\\\\&')
-      else
-        text.gsub!(/['\\]/, '\\\\\&')
-      end
-      @src << " " << @bufvar << " << '" << text << TEXT_END
+      text = _dup_string_if_frozen(text)
+      text.gsub!(/['\\]/, '\\\\\&')
+
+      with_buffer{@src << " << '" << text << @text_end}
     end
 
     # Add ruby code to the template
     def add_code(code)
+      terminate_expression
       @src << code
       @src << ';' unless code[RANGE_LAST] == "\n"
+      @buffer_on_stack = false
     end
 
     # Add the given ruby expression result to the template,
@@ -205,23 +248,52 @@ module Erubi
 
     # Add the result of Ruby expression to the template
     def add_expression_result(code)
-      @src << ' ' << @bufvar << ' << (' << code << ').to_s;'
+      with_buffer{@src << ' << (' << code << ').to_s'}
     end
 
     # Add the escaped result of Ruby expression to the template
     def add_expression_result_escaped(code)
-      @src << ' ' << @bufvar << ' << ' << @escapefunc << '((' << code << '));'
+      with_buffer{@src << ' << ' << @escapefunc << '((' << code << '))'}
     end
 
     # Add the given postamble to the src.  Can be overridden in subclasses
     # to make additional changes to src that depend on the current state.
     def add_postamble(postamble)
-      src << postamble
+      terminate_expression
+      @src << postamble
     end
 
     # Raise an exception, as the base engine class does not support handling other indicators.
     def handle(indicator, code, tailch, rspace, lspace)
       raise ArgumentError, "Invalid indicator: #{indicator}"
     end
+
+    # Make sure the buffer variable is the target of the next append
+    # before yielding to the block. Mark that the buffer is the target
+    # of the next append after the block executes.
+    #
+    # This method should only be called if the block will result in
+    # code where << will append to the bufvar.
+    def with_buffer
+      if @chain_appends
+        unless @buffer_on_stack
+          @src << '; ' << @bufvar
+        end
+        yield
+        @buffer_on_stack = true
+      else
+        @src << ' ' << @bufvar
+        yield
+        @src << ';'
+      end
+    end
+
+    # Make sure that any current expression has been terminated.
+    # The default is to terminate all expressions, but when
+    # the chain_appends option is used, expressions may not be
+    # terminated.
+    def terminate_expression
+      @src << '; ' if @chain_appends
+    end
   end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: erubi
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.13.1
 platform: ruby
 authors:
 - Jeremy Evans
 - kuwata-lab.com
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-13 00:00:00.000000000 Z
+date: 2024-12-19 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.1.4
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Small ERB Implementation
 test_files: []