Class: ERB

: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*.

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

Here’s how ERB works:

• You can create an ERB object (a template) to store text that includes specially formatted tags.

• You can call instance method #result to get the result.

ERB supports tags of three kinds:

• [Expression tags][expression tags]: each begins with ‘<%’, ends with ‘’%>‘`; contains a Ruby expression; in the result, the value of the expression replaces the entire tag:

      magic_word = 'xyzzy'
      template.result(binding) # => "The magic word is xyzzy."
  
      ERB.new('Today is <%= Date::DAYNAMES[Date.today.wday] %>.').result # => "Today is Monday."
  
  The first call to #result passes argument {binding},
  which contains the binding of variable {magic_word} to its string value {'xyzzy'}.
  
  The second call need not pass a binding,
  because its expression {Date::DAYNAMES} is globally defined.

• [Execution tags][execution tags]: each begins with ‘<%=’, ends with ‘’%>‘`; contains Ruby code to be executed:

  s = '<% File.write("t.txt", "Some stuff.") %>'
  ERB.new(s).result
  File.read('t.txt') # => "Some stuff."

• [Comment tags][comment tags]: each begins with ‘<%#’, ends with ‘’%>‘`; contains comment text; in the result, the entire tag is omitted.

  s = 'Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.'
  ERB.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

A call to method #result, which produces the formatted result string, requires a [Binding object][binding object] as its argument.

The binding object provides the bindings for expressions in [expression tags][expression tags].

There are three ways to provide the required binding:

• [Default binding][default binding].

• [Local binding][local binding].

• Augmented binding][augmented binding

Default Binding

When you pass no binding argument to method #result, the method uses its default binding: the one returned by method #new_toplevel. This binding has the bindings defined by Ruby itself, which are those for Ruby’s constants and variables.

That binding is sufficient for an expression tag that refers only to Ruby’s constants and variables; these expression tags refer only to Ruby’s global constant RUBY_COPYRIGHT and global variable $0:

“‘ s = <<EOT The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>. The current process is <%= $0 %>. EOT puts .new(s).result The Ruby copyright is “ruby - Copyright © 1993-2025 Yukihiro Matsumoto”. The current process is irb. “`

(The current process is irb because that’s where we’re doing these examples!)

Local Binding

The default binding is not sufficient for an expression that refers to a a constant or variable that is not defined there:

“‘ Foo = 1 # Defines local constant Foo. foo = 2 # Defines local variable foo. s = <<EOT The current value of constant Foo is <%= Foo %>. The current value of variable foo is <%= foo %>. The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>. The current process is <%= $0 %>. EOT “`

This call raises NameError because although Foo and foo are defined locally, they are not defined in the default binding:

“‘ .new(s).result # Raises NameError. “`

To make the locally-defined constants and variables available, you can call #result with the local binding:

“‘ puts .new(s).result(binding) The current value of constant Foo is 1. The current value of variable foo is 2. The Ruby copyright is “ruby - Copyright © 1993-2025 Yukihiro Matsumoto”. The current process is irb. “`

Augmented Binding

Another way to make variable bindings (but not constant bindings) available is to use method #result_with_hash(hash); the passed hash has name/value pairs that are to be used to define and assign variables in a copy of the default binding:

“‘ s = <<EOT The current value of variable bar is <%= bar %>. The current value of variable baz is <%= baz %>. The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>. The current process is <%= $0 %>. “`

Both of these calls raise NameError, because bar and baz are not defined in either the default binding or the local binding.

“‘ puts .new(s).result # Raises NameError. puts .new(s).result(binding) # Raises NameError. “`

This call passes a hash that causes bar and baz to be defined in a new binding (derived from #new_toplevel):

“‘ hash = 3, baz: 4

=> 3, baz: 4

.new(s).result_with_hash(hash) puts .new(s).result_with_hash(variables) The current value of variable bar is 3. The current value of variable baz is 4. The Ruby copyright is “ruby - Copyright © 1993-2025 Yukihiro Matsumoto”. The current process is irb. EOT “‘

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):

“‘ .new(’foo <% Dir.chdir(“C:/”) %> bar’).result # => “foo bar” “‘

Whitespace before and after the embedded code is optional:

“‘ .new(’foo <%Dir.chdir(“C:/”)%> bar’).result # => “foo bar” “‘

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 use keyword argument 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).

Suppressing Unwanted Blank Lines

With keyword argument trim_mode not given, all blank lines go into the result:

“‘ s = <<EOT <% if true %> <%= RUBY_VERSION %> <% end %> EOT .new(s).result.lines.each {|line| puts line.inspect } “n” “3.4.5n” “n” “`

You can give trim_mode: '-', you can suppress each blank line whose source line ends with -%> (instead of %>):

“‘ s = <<EOT <% if true -%> <%= RUBY_VERSION %> <% end -%> EOT .new(s, trim_mode: ’-‘).result.lines.each {|line| puts line.inspect } “3.4.5n” “`

It is an error to use the trailing ‘-%>’ notation without ‘trim_mode: ’-‘`:

“‘ .new(s).result.lines.each {|line| puts line.inspect } # Raises SyntaxError. “`

Suppressing Unwanted Newlines

Consider this input string:

“‘ s = <<EOT <% RUBY_VERSION %> <%= RUBY_VERSION %> foo <% RUBY_VERSION %> foo <%= RUBY_VERSION %> EOT “`

With keyword argument trim_mode not given, all newlines go into the result:

“‘ .new(s).result.lines.each {|line| puts line.inspect } “n” “3.4.5n” “foo n” “foo 3.4.5n” “`

You can give trim_mode: '>' to suppress the trailing newline for each line that ends with ‘%<’ (regardless of its beginning):

“‘ .new(s, trim_mode: ’>‘).result.lines.each {|line| puts line.inspect } “3.4.5foo foo 3.4.5” “`

You can give trim_mode: '<>' to suppress the trailing newline for each line that both begins with ‘<%’ and ends with ‘%>’:

“‘ .new(s, trim_mode: ’<>‘).result.lines.each {|line| puts line.inspect } “3.4.5foo n” “foo 3.4.5n” “`

Combining Trim Modes

You can combine certain trim modes:

• ‘%-’: 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 ‘%>’.

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

An ERB template has an [encoding], which is by default the encoding of the source string; the result string will also have that encoding.

“‘ s = <<EOT <%# Comment. %> EOT template = .new(s) s.encoding # => #<Encoding:UTF-8> template.encoding # => #<Encoding:UTF-8> template.result.encoding # => #<Encoding:UTF-8> “`

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

“‘ s = <<EOT <%#-*- coding: Big5 -*-%> <%# Comment. %> EOT template = .new(s) s.encoding # => #<Encoding:UTF-8> template.encoding # => #<Encoding:Big5> template.result.encoding # => #<Encoding:Big5> “`

Error Reporting

Consider this template (containing an error):

“‘ s = ’<%= nosuch %>‘ template = .new(s) “`

When ERB reports an error, it includes a file name (if available) and a line number; the file name comes from method #filename, the line number from method #lineno.

Initially, those values are nil and 0, respectively; these initial values are reported as '(erb)' and 1, respectively:

“‘ template.filename # => nil template.lineno # => 0 template.result (erb):1:in ’<main>‘: undefined local variable or method ’nosuch’ for main (NameError) “‘

You can use methods #filename= and #lineno= to assign values that are more meaningful in your context:

“‘ template.filename = ’t.txt’

=> “t.txt”

template.lineno = 555

=> 555

template.result t.txt:556:in ‘<main>’: undefined local variable or method ‘nosuch’ for main (NameError) “‘

You can use method #location= to set both values:

“‘ template.location = [’u.txt’, 999] template.result u.txt:1000:in ‘<main>’: undefined local variable or method ‘nosuch’ for main (NameError) “‘

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.

[%q literals]: docs.ruby-lang.org/en/master/syntax/literals_rdoc.html#label-25q-3A+Non-Interpolable+String+Literals [augmented binding]: ERB@Augmented+Binding [binding object]: docs.ruby-lang.org/en/master/Binding.html [comment tags]: ERB@Comment+Tags [default binding]: ERB@Default+Binding [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 [local binding]: ERB@Local+Binding [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