README.rdoc in erubi-1.12.0 vs README.rdoc in erubi-1.13.0

@@ -6,11 +6,11 @@
 * Handles postfix conditionals when using escaping (e.g. <tt><%= foo if bar %></tt>)
 * Supports frozen_string_literal: true in templates via :freeze option
 * 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)
 * Has simpler internals (1 file, <150 lines of code)
 * Is not dead (Erubis hasn't been updated since 2011)
@@ -40,45 +40,87 @@
 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 %>
 
-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.
+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:
 
-To use the capture_end support with tilt:
+  def form(&block)
+    "<form>#{@_buf.capture(&block)}</form>"
+  end
 
+  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_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
 
-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:
+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, 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>"
     yield
     @_buf << "</form>"
     @_buf
   end
 
-  puts eval(Erubi::CaptureEndEngine.new(<<-END, :bufvar=>:@_buf).src)
+  puts eval(Erubi::CaptureEndEngine.new(<<-END, bufvar: '@_buf').src)
   before
   <%|= form do %>
   inside
   <%| end %>
   after