123456789_123456789_123456789_123456789_123456789_

Class: ERB

Relationships & Source Files
Namespace Children
Modules:
Classes:
Inherits: Object
Defined in: lib/erb.rb,
ext/erb/escape/escape.c,
lib/erb/version.rb

Overview

:markup: markdown

Class ERB (the name stands for **Embedded Ruby**) is an easy-to-use, but also very powerful, [template processor][template processor].

Like method [sprintf], ERB can format run-time data into a string. ERB, however,s is *much more powerful*.

In simplest terms:

  • You can create an ERB object to store a text template that includes specially formatted tags; each tag specifies data that at run-time is to replace the tag in the produced result.

  • You can call instance method #result to get the result, which is the string formed by replacing each tag with run-time data.

ERB is commonly used to produce:

  • Customized or personalized email messages.

  • Customized or personalized web pages.

  • Software code (in code-generating applications).

Usage

Before you can use ERB, you must first require it (examples on this page assume that this has been done):

“‘ require ’erb’ “‘

In Brief

“‘

Expression tag: begins with ‘<%’, ends with ‘%>’.

This expression does not need the local binding.

.new(‘Today is <%= Date::DAYNAMES %>.’).result # => “Today is Monday.”

This expression tag does need the local binding.

magic_word = ‘xyzzy’ template.result(binding) # => “The magic word is xyzzy.”

Execution tag: begins with ‘<%=’, ends with ‘%>’. s = ‘<% File.write(“t.txt”, “Some stuff.”) %>’ .new(s).result File.read(‘t.txt’) # => “Some stuff.”

Comment tag: begins with ‘<%#’, ends with ‘%>’.

s = ‘Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.’ .new(s).result # => “Some stuff; more stuff.” “‘

Some Simple Examples

Here’s a simple example of ERB in action:

“‘ s = ’The time is <%= Time.now %>.‘ template = .new(s) template.result

=> “The time is 2025-09-09 10:49:26 -0500.”

“‘

Details:

  1. A plain-text string is assigned to variable s. Its embedded [expression tag][expression tags] ‘’<%= Time.now %>‘` includes a Ruby expression, Time.now.

  2. The string is put into a new ERB object, and stored in variable template.

  3. Method call template.result generates a string that contains the run-time value of Time.now, as computed at the time of the call.

The template may be re-used:

“‘ template.result

=> “The time is 2025-09-09 10:49:33 -0500.”

“‘

Another example:

“‘ s = ’The magic word is <%= magic_word %>.‘ template = .new(s) magic_word = ’abracadabra’

=> “abracadabra”

template.result(binding)

=> “The magic word is abracadabra.”

“‘

Details:

  1. As before, a plain-text string is assigned to variable s. Its embedded [expression tag][expression tags] ‘’<%= magic_word %>‘` has a variable name, magic_word.

  2. The string is put into a new ERB object, and stored in variable template; note that magic_word need not be defined before the ERB object is created.

  3. magic_word = 'abracadabra' assigns a value to variable magic_word.

  4. Method call template.result(binding) generates a string that contains the value of magic_word.

As before, the template may be re-used:

“‘ magic_word = ’xyzzy’ template.result(binding)

=> “The magic word is xyzzy.”

“‘

Bindings

The first example above passed no argument to method #result; the second example passed argument binding.

Here’s why:

  • The first example has tag <%= {Time.now} %>, which cites globally-defined constant ‘Time`; the default binding (details not needed here) includes the binding of global constant Time to its value.

  • The second example has tag <%= magic_word %>, which cites locally-defined variable ‘magic_word`; the passed argument binding (which is simply a call to method [Kernel#binding]) includes the binding of local variable magic_word to its value.

Tags

The examples above use expression tags. These are the tags available in ERB:

  • [Expression tag][expression tags]: the tag contains a Ruby exprssion; in the result, the entire tag is to be replaced with the run-time value of the expression.

  • [Execution tag][execution tags]: the tag contains Ruby code; in the result, the entire tag is to be replaced with the run-time value of the code.

  • [Comment tag][comment tags]: the tag contains comment code; in the result, the entire tag is to be omitted.

Expression Tags

You can embed a Ruby expression in a template using an *expression tag*.

Its syntax is <%= expression %>, where expression is any valid Ruby expression.

When you call method #result, the method evaluates the expression and replaces the entire expression tag with the expression’s value:

“‘ .new(’Today is <%= Date::DAYNAMES %>.‘).result

=> “Today is Monday.”

.new(‘Tomorrow will be <%= Date::DAYNAMES[Date.today.wday + 1] %>.’).result

=> “Tomorrow will be Tuesday.”

.new(‘Yesterday was <%= Date::DAYNAMES[Date.today.wday - 1] %>.’).result

=> “Yesterday was Sunday.”

“‘

Note that whitespace before and after the expression is allowed but not required, and that such whitespace is stripped from the result.

“‘ .new(’My appointment is on <%=Date::DAYNAMES[Date.today.wday + 2]%>.‘).result

=> “My appointment is on Wednesday.”

.new(‘My appointment is on <%= Date::DAYNAMES[Date.today.wday + 2] %>.’).result

=> “My appointment is on Wednesday.”

“‘

Execution Tags

You can embed Ruby executable code in template using an *execution tag*.

Its syntax is <% code %>, where code is any valid Ruby code.

When you call method #result, the method executes the code and removes the entire execution tag (generating no text in the result).

You can interleave text with execution tags to form a control structure such as a conditional, a loop, or a case statements.

Conditional:

“‘ s = <<EOT <% if verbosity %> An error has occurred. <% else %> Oops! <% end %> EOT template = .new(s) verbosity = true template.result(binding)

=> “nAn error has occurred.nn”

verbosity = false template.result(binding)

=> “nOops!nn”

“‘

Note that the interleaved text may itself contain expression tags:

Loop:

“‘ s = <<EOT <% Date::ABBR_DAYNAMES.each do |dayname| %> <%= dayname %> <% end %> EOT .new(s).result

=> “nSunnnMonnnTuennWednnThunnFrinnSatnn”

“‘

Other, non-control, lines of Ruby code may be interleaved with the text, and the Ruby code may itself contain regular Ruby comments:

“‘ s = <<EOT <% 3.times do %> <%= Time.now %> <% sleep(1) # Let’s make the times different. %> <% end %> EOT .new(s).result

=> “n2025-09-09 11:36:02 -0500nnn2025-09-09 11:36:03 -0500nnn2025-09-09 11:36:04 -0500nnn”

“‘

The execution tag may also contain multiple lines of code:

“‘ s = <<EOT <%

(0..2).each do |i|
  (0..2).each do |j|

%>

  • <%=i%>,<%=j%>

<%

  end
end

%> EOT .new(s).result

=> “n* 0,0nn* 0,1nn* 0,2nn* 1,0nn* 1,1nn* 1,2nn* 2,0nn* 2,1nn* 2,2nn”

“‘

Shorthand Format for Execution Tags

You can give trim_mode: '%' to enable a shorthand format for execution tags; this example uses the shorthand format % code instead of ‘<% code %>`:

“‘ s = <<EOT % priorities.each do |priority|

* <%= priority %>

% end EOT template = .new(s, trim_mode: ‘%’) priorities = [ ‘Run Ruby Quiz’,

'Document Modules',
'Answer Questions on Ruby Talk' ]

puts template.result(binding)

* Run Ruby Quiz
* Document Modules
* Answer Questions on Ruby Talk

“‘

Note that in the shorthand format, the character ‘%’ must be the first character in the code line (no leading whitespace).

Comment Tags

You can embed a comment in a template using a *comment tag*; its syntax is <%# text %>, where text is the text of the comment.

When you call method #result, it removes the entire comment tag (generating no text in the result).

Example:

“‘ s = ’Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.‘ .new(s).result # => “Some stuff; more stuff.” “`

A comment tag may appear anywhere in the template text.

Note that the beginning of the tag must be ‘<%#’, not '<% #'.

In this example, the tag begins with '<% #', and so is an execution tag, not a comment tag; the cited code consists entirely of a Ruby-style comment (which is of course ignored):

“‘ .new(’Some stuff;<% # Note to self: figure out what the stuff is. %> more stuff.‘).result

=> “Some stuff;”

“‘

Encodings

In general, an ERB result string (or Ruby code generated by ERB) has the same encoding as the string originally passed to ERB.new; see [Encoding].

You can specify the output encoding by adding a [magic comment][magic comments] at the top of the given string:

“‘ s = <<EOF <%#-*- coding: Big5 -*-%>

Some text. EOF

=> “<%#-*- coding: Big5 -*-%>nnSome text.n”

s.encoding

=> #<Encoding:UTF-8>

.new(s).result.encoding

=> #<Encoding:Big5>

“‘

Plain Text Example

Here’s a plain-text string; it uses the literal notation '%q{ ... }' to define the string (see [%q literals][%q literals]); this avoids problems with backslashes.

“‘ s = %q{ From: James Edward Gray II <james@grayproductions.net> To: <%= to %> Subject: Addressing Needs

<%= to %>:

Just wanted to send a quick note assuring that your needs are being addressed.

I want you to know that my team will keep working on the issues, especially:

<%# ignore numerous minor requests – focus on priorities %> % priorities.each do |priority|

* <%= priority %>

% end

Thanks for your patience.

James Edward Gray II } “‘

The template will need these:

“‘ to = ’Community Spokesman <spokesman@ruby_community.org>‘ priorities = [ ’Run Ruby Quiz’,

'Document Modules',
'Answer Questions on Ruby Talk' ]

“‘

Finally, make the template and get the result

“‘ template = .new(s, trim_mode: ’%<>‘) puts template.result(binding)

From: James Edward Gray II <james@grayproductions.net> To: Community Spokesman <spokesman@ruby_community.org> Subject: Addressing Needs

Community:

Just wanted to send a quick note assuring that your needs are being addressed.

I want you to know that my team will keep working on the issues, especially:

  • Run Ruby Quiz

  • Document Modules

  • Answer Questions on Ruby Talk

Thanks for your patience.

James Edward Gray II “‘

HTML Example

This example shows an HTML template.

First, here’s a custom class, Product:

“‘ class Product

def initialize(code, name, desc, cost)
  @code = code
  @name = name
  @desc = desc
  @cost = cost
  @features = []
end

def add_feature(feature)
  @features << feature
end

# Support templating of member data.
def get_binding
  binding
end

end “‘

The template below will need these values:

“‘ toy = Product.new(’TZ-1002’,

'Rubysapien',
"Geek's Best Friend!  Responds to Ruby commands...",
999.95
)

toy.add_feature(‘Listens for verbal commands in the Ruby language!’) toy.add_feature(‘Ignores Perl, Java, and all C variants.’) toy.add_feature(‘Karate-Chop Action!!!’) toy.add_feature(‘Matz signature on left leg.’) toy.add_feature(‘Gem studded eyes… Rubies, of course!’) “‘

Here’s the HTML:

“‘ s = <<EOT <html>

<head><title>Ruby Toys -- <%= @name %></title></head>
<body>
  <h1><%= @name %> (<%= @code %>)</h1>
  <p><%= @desc %></p>
  <ul>
    <% @features.each do |f| %>
      <li><b><%= f %></b></li>
    <% end %>
  </ul>
  <p>
    <% if @cost < 10 %>
      <b>Only <%= @cost %>!!!</b>
    <% else %>
       Call for a price, today!
    <% end %>
  </p>
</body>

</html> EOT “‘

Finally, build the template and get the result (omitting some blank lines):

“‘ template = .new(s) puts template.result(toy.get_binding) <html>

<head><title>Ruby Toys -- Rubysapien</title></head>
<body>
  <h1>Rubysapien (TZ-1002)</h1>
  <p>Geek's Best Friend!  Responds to Ruby commands...</p>
  <ul>
      <li><b>Listens for verbal commands in the Ruby language!</b></li>
      <li><b>Ignores Perl, Java, and all C variants.</b></li>
      <li><b>Karate-Chop Action!!!</b></li>
      <li><b>Matz signature on left leg.</b></li>
      <li><b>Gem studded eyes... Rubies, of course!</b></li>
  </ul>
  <p>
       Call for a price, today!
  </p>
</body>

</html> “‘

Other Template Processors

Various Ruby projects have their own template processors. The Ruby Processing System [RDoc], for example, has one that can be used elsewhere.

Other popular template processors may found in the [Template Engines][template engines] page of the Ruby Toolbox.

[binding object]: docs.ruby-lang.org/en/master/Binding.html [comment tags]: ERB@Comment+Tags [encoding]: docs.ruby-lang.org/en/master/Encoding.html [execution tags]: ERB@Execution+Tags [expression tags]: ERB@Expression+Tags [kernel#binding]: docs.ruby-lang.org/en/master/Kernel.html#method-i-binding [%q literals]: docs.ruby-lang.org/en/master/syntax/literals_rdoc.html#label-25q-3A+Non-Interpolable+String+Literals [magic comments]: docs.ruby-lang.org/en/master/syntax/comments_rdoc.html#label-Magic+Comments [rdoc]: ruby.github.io/rdoc [sprintf]: docs.ruby-lang.org/en/master/Kernel.html#method-i-sprintf [template engines]: www.ruby-toolbox.com/categories/template_engines [template processor]: en.wikipedia.org/wiki/Template_processor

Constant Summary

Class Method Summary

Instance Attribute Summary

  • #encoding readonly

    The encoding to eval.

  • #filename rw

    The optional filename argument passed to Kernel.eval when the ERB code is run.

  • #lineno rw

    The optional lineno argument passed to Kernel.eval when the ERB code is run.

  • #src readonly

    The Ruby code generated by ERB.

Instance Method Summary

Constructor Details

.new(string, trim_mode: nil, eoutvar: '_erbout') ⇒ ERB

:markup: markdown

Returns a new ERB object containing the given string.

For details about string, its embedded tags, and generated results, see ERB.

**Keyword Argument trim_mode**

When keyword argument trim_mode has a string value, that value may be one of:

  • ‘%’: Enable [shorthand format][shorthand format] for execution tags.

  • ‘-’: Omit each blank line ending with ‘%>’.

  • ‘>’: Omit newline for each line ending with ‘%>’.

  • ‘<>’: Omit newline for each line starting with ‘<%’ and ending with ‘%>’.

The value may also be certain combinations of the above.

  • ‘%-’: Enable shorthand and omit each blank line ending with ‘%>’.

  • ‘%>’: Enable shorthand and omit newline for each line ending with ‘%>’.

  • ‘%<>’: Enable shorthand and omit newline for each line starting with ‘<%’ and ending with ‘%>’.

**Keyword Argument eoutvar**

The string value of keyword argument eoutvar specifies the name of the variable that method #result uses to construct its result string. This is useful when you need to run multiple ERB templates through the same binding and/or when you want to control where output ends up.

It’s good practice to choose a variable name that begins with an underscore: ‘_’.

Backward Compatibility

The calling sequence given above – which is the one you should use – is a simplified version of the complete formal calling sequence, which is:

“‘ new(string, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: ’_erbout’) “‘

The second, third, and fourth positional arguments (those in the second line above) are deprecated; this method issues warnings if they are given.

However, their values, if given, are handled thus:

  • safe_level: ignored.

  • ‘legacy_trim_mode: overrides keyword argument trim_mode.

  • ‘legacy_eoutvar: overrides keyword argument eoutvar.

[shorthand format]: ERB@Shorthand+Format+for+Execution+Tags

[ GitHub ]

  
# File 'lib/erb.rb', line 586

def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: '_erbout')
  # Complex initializer for $SAFE deprecation at [Feature #14256]. Use keyword arguments to pass trim_mode or eoutvar.
  if safe_level != NOT_GIVEN
    warn 'Passing safe_level with the 2nd argument of ERB.new is deprecated. Do not use it, and specify other arguments as keyword arguments.', uplevel: 1
  end
  if legacy_trim_mode != NOT_GIVEN
    warn 'Passing trim_mode with the 3rd argument of ERB.new is deprecated. Use keyword argument like ERB.new(str, trim_mode: ...) instead.', uplevel: 1
    trim_mode = legacy_trim_mode
  end
  if legacy_eoutvar != NOT_GIVEN
    warn 'Passing eoutvar with the 4th argument of ERB.new is deprecated. Use keyword argument like ERB.new(str, eoutvar: ...) instead.', uplevel: 1
    eoutvar = legacy_eoutvar
  end

  compiler = make_compiler(trim_mode)
  set_eoutvar(compiler, eoutvar)
  @src, @encoding, @frozen_string = *compiler.compile(str)
  @filename = nil
  @lineno = 0
  @_init = self.class.singleton_class
end

Class Method Details

.version

Returns revision information for the erb.rb module.

[ GitHub ]

  
# File 'lib/erb.rb', line 525

def self.version
  VERSION
end

Instance Attribute Details

#encoding (readonly)

The encoding to eval

[ GitHub ]

  
# File 'lib/erb.rb', line 621

attr_reader :encoding

#filename (rw)

The optional filename argument passed to Kernel.eval when the ERB code is run

[ GitHub ]

  
# File 'lib/erb.rb', line 625

attr_accessor :filename

#lineno (rw)

The optional lineno argument passed to Kernel.eval when the ERB code is run

[ GitHub ]

  
# File 'lib/erb.rb', line 629

attr_accessor :lineno

#src (readonly)

The Ruby code generated by ERB

[ GitHub ]

  
# File 'lib/erb.rb', line 618

attr_reader :src

Instance Method Details

#def_class(superklass = Object, methodname = 'result')

Define unnamed class which has methodname as instance method, and return it.

example:

class MyClass_
  def initialize(arg1, arg2)
    @arg1 = arg1;  @arg2 = arg2
  end
end
filename = 'example.rhtml'  # @arg1 and @arg2 are used in example.rhtml
erb = ERB.new(File.read(filename))
erb.filename = filename
MyClass = erb.def_class(MyClass_, 'render()')
print MyClass.new('foo', 123).render()
[ GitHub ]

  
# File 'lib/erb.rb', line 751

def def_class(superklass=Object, methodname='result')
  cls = Class.new(superklass)
  def_method(cls, methodname, @filename || '(ERB)')
  cls
end

#def_method(mod, methodname, fname = '(ERB)')

Define methodname as instance method of mod from compiled Ruby source.

example:

filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
erb = ERB.new(File.read(filename))
erb.def_method(MyClass, 'render(arg1, arg2)', filename)
print MyClass.new.render('foo', 123)
[ GitHub ]

  
# File 'lib/erb.rb', line 715

def def_method(mod, methodname, fname='(ERB)')
  src = self.src.sub(/^(?!#|$)/) {"def #{methodname}\n"} << "\nend\n"
  mod.module_eval do
    eval(src, binding, fname, -1)
  end
end

#def_module(methodname = 'erb')

Create unnamed module, define methodname as instance method of it, and return it.

example:

filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
erb = ERB.new(File.read(filename))
erb.filename = filename
MyModule = erb.def_module('render(arg1, arg2)')
class MyClass
  include MyModule
end
[ GitHub ]

  
# File 'lib/erb.rb', line 732

def def_module(methodname='erb')
  mod = Module.new
  def_method(mod, methodname, @filename || '(ERB)')
  mod
end

#location=(filename, lineno)

Sets optional filename and line number that will be used in ERB code evaluation and error reporting. See also #filename= and #lineno=

erb = ERB.new('<%= some_x %>')
erb.render
# undefined local variable or method `some_x'
#   from (erb):1

erb.location = ['file.erb', 3]
# All subsequent error reporting would use new location
erb.render
# undefined local variable or method `some_x'
#   from file.erb:4
[ GitHub ]

  
# File 'lib/erb.rb', line 646

def location=((filename, lineno))
  @filename = filename
  @lineno = lineno if lineno
end

#make_compiler(trim_mode)

Creates a new compiler for ERB. See Compiler.new for details

[ GitHub ]

  
# File 'lib/erb.rb', line 613

def make_compiler(trim_mode)
  ERB::Compiler.new(trim_mode)
end

#new_toplevel(vars = nil) (private)

Returns a new binding each time near TOPLEVEL_BINDING for runs that do not specify a binding.

[ GitHub ]

  
# File 'lib/erb.rb', line 696

def new_toplevel(vars = nil)
  b = TOPLEVEL_BINDING
  if vars
    vars = vars.select {|v| b.local_variable_defined?(v)}
    unless vars.empty?
      return b.eval("tap {|;#{vars.join(',')}| break binding}")
    end
  end
  b.dup
end

#result(b = new_toplevel)

Executes the generated ERB code to produce a completed template, returning the results of that code.

b accepts a Binding object which is used to set the context of code evaluation.

[ GitHub ]

  
# File 'lib/erb.rb', line 675

def result(b=new_toplevel)
  unless @_init.equal?(self.class.singleton_class)
    raise ArgumentError, "not initialized"
  end
  eval(@src, b, (@filename || '(erb)'), @lineno)
end

#result_with_hash(hash)

Render a template on a new toplevel binding with local variables specified by a Hash object.

[ GitHub ]

  
# File 'lib/erb.rb', line 684

def result_with_hash(hash)
  b = new_toplevel(hash.keys)
  hash.each_pair do |key, value|
    b.local_variable_set(key, value)
  end
  result(b)
end

#run(b = new_toplevel)

Generate results and print them. (see #result)

[ GitHub ]

  
# File 'lib/erb.rb', line 664

def run(b=new_toplevel)
  print self.result(b)
end

#set_eoutvar(compiler, eoutvar = '_erbout')

Can be used to set eoutvar as described in .new. It’s probably easier to just use the constructor though, since calling this method requires the setup of an ERB compiler object.

[ GitHub ]

  
# File 'lib/erb.rb', line 656

def set_eoutvar(compiler, eoutvar = '_erbout')
  compiler.put_cmd = "#{eoutvar}.<<"
  compiler.insert_cmd = "#{eoutvar}.<<"
  compiler.pre_cmd = ["#{eoutvar} = +''"]
  compiler.post_cmd = [eoutvar]
end