Erubi

Erubi is a ERB template engine for ruby. It is a simplified fork of Erubis, using the same basic algorithm, with the following differences:

  • Handles postfix conditionals when using escaping (e.g. <%= foo if bar %>)
  • Supports frozen_string_literal: true in templates via :freeze option
  • Works with ruby's --enable-frozen-string-literal option
  • Automatically freezes strings for template text when ruby optimizes it (on ruby 2.1+)
  • Escapes ' (apostrophe) when escaping for better XSS protection
  • 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)

It is not designed with Erubis API compatibility in mind, though most Erubis ERB syntax works, with the following exceptions:

  • No support for <%=== for debug output

Installation

gem install erubi

Source Code

Source code is available on GitHub at https://github.com/jeremyevans/erubi

Usage

Erubi only has built in support for retrieving the generated source for a file:

require 'erubi'
eval(Erubi::Engine.new(File.read('filename.erb')).src)

Most users will probably use Erubi via Rails or Tilt. Erubi is the default 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. It currently ships with two implementations that allow it.

Erubi::CaptureBlockEngine

The recommended implementation can be required via erubi/capture_block, which allows capturing to work with normal <%= and <%== tags.

<%= form do %>
<input>
<% 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

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_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 <%= and <%== 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 <%|= and <%|== tags which are closed with a <%| 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)
before
<%|= form do %>
inside
<%| end %>
after
END

# Output:
# before
# <form>
# inside
# </form>
# after

Alternatively, passing the option :yield_returns_buffer => true will return the buffer captured by the block instead of the last expression in the block.

Reporting Bugs

The bug tracker is located at https://github.com/jeremyevans/erubi/issues

License

MIT

Authors

Jeremy Evans [email protected] kuwata-lab.com