ErbParser

ErbParser is a Ruby gem for parsing ERB templates. It takes an ERB template as a string and returns either an array of tokens or a transformed XML document, depending on your preference.

Basic usage synopsis

Pass in an ERB template as a string:

result = ErbParser.parse(
  'Plain text <% 5.times {} %><%= 2 + 3 %><%# Comment %>
)

# 'Plain text'
puts result[0]

# ' 5.times {} '
puts result[0].ruby_code

puts result[0].to_s
# '<% 5.times {} %>'

# ' 2 + 3 '
puts result[1].ruby_code

# '<%= 2 + 3 %>'
puts result[1].to_s

# ' Comment '
puts result[2].ruby_code

# '<%# Comment" %>'
puts result[2].to_s

The above usage sets result to an array of tokens.

The :map option

Often, you'll want to parse an ERB template, apply some transformation function to all the ERB tags, and get back a new string. That's what the :map option is for:

result = ErbParser.parse(
  'This is a<% TSET %>',
  :map => lambda { |t| t.ruby_code.reverse.downcase }
)

# 'This is a test '
puts result

As in the above example, the :map option must be a proc. The proc will be passed an ErbTag as its only parameter. It must return a string. The returned string will be inserted into the output where the ERB tag used to be.

:map was called :transform in version 0.0.0. :transform is still available but deprecated.

XML/HTML usage synopsis

Alternatively, you may pass in an XML/HTML document or fragment and have the ERB tags transformed to valid XML elements:

ErbParser.transform_xml(%Q(
  <p>
    Plain text
    <% 5.times {} %>
    <%= 2 + 3 %>
    <%# Comment %>
  </p>
))

The above would return a fragment equivalent to:

<p>
  Plain text
  <erb> 5.times {} </erb>
  <erb interpolated="true"> 2 + 3 </erb>
  <erb comment="true">Comment</erb>
</p>

Customizing XML/HTML output

You can customize the XML tags that replace the ERB tags:

# '<custom-tag> 5.times {} </custom-tag>'
ErbParser.transform_xml '<% 5.times {} %>', :tag => 'custom-tag'

# '<erb apple="orange"> Time.now.to_s </erb>'
ErbParser.transform_xml '<%= Time.now.to_s %>', :interp_attr => {'apple' => 'orange'}

# '<erb> Time.now.to_s </erb>'
ErbParser.transform_xml '<%= Time.now.to_s %>', :interp_attr => false

# '<erb apple="orange"> Comment </erb>'
ErbParser.transform_xml '<%# Comment %>', :comment_attr => {'apple' => 'orange'}

# '<erb> Comment </erb>'
ErbParser.transform_xml '<%# Comment %>', :comment_attr => false

FAQ

Can ErbParser handle all valid Ruby code?

No it cannot. Ruby has a very complex syntax. In a library like this, it would be a fool's errand to try to handle every weird syntactic construct that could technically be considered valid Ruby. Instead, this library is designed to handle only the constructs that would commonly appear inside ERB tags. In other words, the basics of the language.

Just avoid exotic syntactic constructs, and you should be fine. (You shouldn't do anything syntactically fancy in an ERB template anyway--it's bad coding style.) In particular, you must avoid Ruby's weirder string literals, such as the following:

%q!This is a valid string literal, but you must not use this syntax.!

Also be wary of tricky escape sequences. If you absolutely must use unusual syntax, and it breaks ErbParser, consider moving the offending code into a class or module external to the ERB template.

Nonetheless, the library does account for and allow the following string literal formats:

"string"
'string'
%q(string (string) string)
%Q(string (string) string)
%(string (string) string)
%q{string {string} string}
%Q{string {string} string}
%{string {string} string}

This parser is not hardened against malicious input. But then, you shouldn't be accepting ERB as untrusted input anyway, because ERB allows arbitrary code execution.

What does ErbParser do with invalid ERB or Ruby code?

If you pass code containing a syntax error, the parsing behavior is undefined. You may get an exception, or you may just get nonsensical results. It depends on the type of the syntax error.