HOME > Erubis > Erubis Users' Guide

Erubis Users' Guide

3   Enhancer

Enhancer is a module to add a certain feature into Erubis::Eruby class. Enhancer may be language-independent or only for Erubis::Eruby class.

To use enhancers, define subclass and include them. The folloing is an example to use EscapeEnhancer, PercentLineEnhancer, and BiPatternEnhancer.

class MyEruby < Erubis::Eruby
  include EscapeEnhancer
  include PercentLineEnhancer
  include BiPatternEnhancer
end

You can specify enhancers in command-line with option '-E'. The following is an example to use some enhancers in command-line.

$ erubis -xE Escape,PercentLine,BiPattern example.eruby

The following is the list of enhancers.

EscapeEnhander (language-independent)

Switch '<%= %>' to escaped and '<%== %>' to unescaped.

StdoutEnhancer (only for Eruby)

Use $stdout instead of array buffer.

PrintOutEnhancer (only for Eruby)

Use "print(...)" statement insead of "_buf << ...".

PrintEnabledEnhancer (only for Eruby)

Enable to use print() in '<% ... %>'.

ArrayEnhancer (only for Eruby)

Return array of string instead of returning string.

ArrayBufferEnhancer (only for Eruby)

Use array buffer. It is a little slower than StringBufferEnhancer.

StringBufferEnhancer (only for Eruby)

Use string buffer. This is included in Erubis::Eruby by default.

ErboutEnhancer (only for Eruby)

Set '_erbout = _buf = "";' to be compatible with ERB.

NoTextEnhancer (language-independent)

Print embedded code only and ignore normal text.

NoCodeEnhancer (language-independent)

Print normal text only and ignore code.

SimplifyEnhancer (language-independent)

Make compile faster but don't trim spaces around '<% %>'.

BiPatternEnhancer (language-independent)

[experimental] Enable to use another embedded pattern with '<% %>'.

PercentLineEnhancer (language-independent)

Regard lines starting with '%' as Ruby code. This is for compatibility with eruby and ERB.

HeaderFooterEnhancer (language-independent)

[experimental] Enable you to add header and footer in eRuby script.

InterpolationEnhancer (only for Eruby)

[experimental] convert '<p><%= text %></p>' into '_buf << %Q`<p>#{text}</p>`'.

DeleteIndentEnhancer (language-independent)

[experimental] delete indentation of HTML file and eliminate page size.

If you required 'erubis/engine/enhanced', Eruby subclasses which include each enhancers are defined. For example, class BiPatternEruby includes BiPatternEnhancer.

3-1   EscapeEnhancer

EscapeEnhancer switches '<%= ... %>' to escaped and '<%== ... %>' to unescaped.

<div>
<% for item in list %>
  <p><%= item %></p>
  <p><%== item %></p>
<% end %>
</div>

$ erubis -xE Escape example.eruby
_buf = ''; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
  <p>'; _buf << ( item ).to_s; _buf << '</p>
'; end 
 _buf << '</div>
';
_buf.to_s

EscapeEnhancer is language-independent.

3-2   StdoutEnhancer

StdoutEnhancer use $sdtdout instead of array buffer. Therefore, you can use 'print' statement in embedded ruby code.

$ erubis -xE Stdout example.eruby
_buf = $stdout; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
''

StdoutEnhancer is only for Eruby.

3-3   PrintOutEnhancer

PrintOutEnhancer makes compiled source code to use 'print(...)' instead of '_buf << ...'.

$ erubis -xE PrintOut example.eruby
 print '<div>
'; for item in list 
 print '  <p>'; print(( item ).to_s); print '</p>
  <p>'; print Erubis::XmlHelper.escape_xml( item ); print '</p>
'; end 
 print '</div>
';

PrintOutEnhancer is only for Eruby.

3-4   PrintEnabledEnhancer

PrintEnabledEnhancer enables you to use print() method in '<% ... %>'.

<% for item in @list %>
  <b><% print item %></b>
<% end %>

require 'erubis'
class PrintEnabledEruby < Erubis::Eruby
  include Erubis::PrintEnabledEnhancer
end
input = File.read('printenabled-example.eruby')
eruby = PrintEnabledEruby.new(input)
list = ['aaa', 'bbb', 'ccc']
print eruby.evaluate(:list=>list)

$ ruby printenabled-example.rb
  <b>aaa</b>
  <b>bbb</b>
  <b>ccc</b>

Notice to use Eruby#evaluate() and not to use Eruby#result(), because print() method in '<% ... %>' invokes not Kernel#print() but PrintEnabledEnhancer#print().

PrintEnabledEnhancer is only for Eruby.

3-5   ArrayEnhancer

ArrayEnhancer makes Eruby to return an array of strings.

$ erubis -xE Array example.eruby
_buf = []; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
_buf

ArrayEnhancer is only for Eruby.

3-6   ArrayBufferEnhancer

ArrayBufferEnhancer makes Eruby to use array buffer. Array buffer is a litte slower than String buffer.

ArrayBufferEnhancer is only for Eruby.

$ erubis -xE ArrayBuffer example.eruby
_buf = []; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
_buf.join

3-7   StringBufferEnhancer

StringBufferEnhancer makes Eruby to use string buffer. String buffer is a little faster than array buffer. Erubis::Eruby includes this enhancer by default.

$ erubis -xE StringBuffer example.eruby
_buf = ''; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
_buf.to_s

StringBufferEnhancer is only for Eruby.

3-8   ErboutEnhancer

ErboutEnhancer makes Eruby to be compatible with ERB. This is useful especially for Ruby on Rails.

$ erubis -xE Erbout example.eruby
_erbout = _buf = ''; _buf << '<div>
'; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
_buf.to_s

ErboutEnhancer is only for Eruby.

3-9   NoTextEnhancer

NoTextEnhancer suppress output of text and prints only embedded code. This is useful especially when debugging a complex eRuby script.

<h3>List</h3>
<% if !@list || @list.empty? %>
<p>not found.</p>
<% else %>
<table>
  <tbody>
    <% @list.each_with_index do |item, i| %>
    <tr bgcolor="<%= i%2 == 0 ? '#FFCCCC' : '#CCCCFF' %>">
      <td><%= item %></td>
    </tr>
    <% end %>
  </tbody>
</table>
<% end %>

$ erubis -xE NoText notext-example.eruby
_buf = '';
 if !@list || @list.empty? 

 else 


     @list.each_with_index do |item, i| 
                  _buf << ( i%2 == 0 ? '#FFCCCC' : '#CCCCFF' ).to_s;
           _buf << ( item ).to_s;

     end 


 end 
_buf.to_s

NoTextEnhancer is language-independent. It is useful even if you are PHP user, see this section.

3-10   NoCodeEnhancer

NoCodeEnhancer suppress output of embedded code and prints only normal text. This is useful especially when validating HTML tags.

<h3>List</h3>
<% if !@list || @list.empty? %>
<p>not found.</p>
<% else %>
<table>
  <tbody>
    <% @list.each_with_index do |item, i| %>
    <tr bgcolor="<%= i%2 == 0 ? '#FFCCCC' : '#CCCCFF' %>">
      <td><%= item %></td>
    </tr>
    <% end %>
  </tbody>
</table>
<% end %>

$ erubis -xE NoCode notext-example.eruby
<h3>List</h3>

<p>not found.</p>

<table>
  <tbody>

    <tr bgcolor="">
      <td></td>
    </tr>

  </tbody>
</table>

NoCodeEnhancer is language-independent. It is useful even if you are PHP user, see this section.

3-11   SimplifyEnhancer

SimplifyEnhancer makes compiling a little faster but don't trim spaces around '<% %>'.

$ erubis -xE Simplify example.eruby
_buf = ''; _buf << '<div>
'; for item in list ; _buf << '
  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end ; _buf << '
</div>
';
_buf.to_s

SimplifyEnhancer is language-independent.

3-12   BiPatternEnhancer

BiPatternEnhancer enables to use another embedded pattern with '<% %>'. By Default, '[= ... =]' is available for expression. You can specify pattern by :bipattern property.

<% for item in list %>
  <b>[= item =]</b>
  <b>[== item =]</b>
<% end %>

$ erubis -xE BiPattern bipattern-example.rhtml
_buf = ''; for item in list 
 _buf << '  <b>'; _buf << ( item ).to_s; _buf << '</b>
  <b>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</b>
'; end 
_buf.to_s

BiPatternEnhancer is language-independent.

3-13   PercentLineEnhancer

PercentLineEnhancer regards lines starting with '%' as Ruby code. This is for compatibility with eruby and ERB.

<ul>
% for item in list
  <li><%= item %></li>
% end
</ul>
%% lines with '%%'

$ erubis -xE PercentLine percentline-example.rhtml
_buf = ''; _buf << '<ul>
'; for item in list
 _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
'; end
 _buf << '</ul>
% lines with \'%%\'
';
_buf.to_s

PercentLineEnhancer is language-independent.

3-14   PrefixedLineEnhancer

PrefixedlineEnhancer regards lines starting with '%' as Ruby code. It is similar to PercentLineEnhancer, but there are some differences.

• PrefixedlineEnhancer allows to indent lines starting with '%', but PercentLineEnhancer doesn't.
• PrefixedlineEnhancer allows to change prefixed character (default '%'), but PercentLineEnhancer doesn't.

<ul>
  ! for item in list
  <li><%= item %></li>
  ! end
</ul>
  !! lines with '!!'

require 'erubis'

class PrefixedLineEruby < Erubis::Eruby
  include Erubis::PrefixedLineEnhancer
end

input = File.read('prefixedline-example.rhtml')
eruby = PrefixedLineEruby.new(input, :prefixchar=>'!')  # default '%'
print eruby.src

$ ruby prefixedline-example.rb
_buf = ''; _buf << '<ul>
';   for item in list
 _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
';   end
 _buf << '</ul>
  ! lines with \'!!\'
';
_buf.to_s

PrefixedLineEnhancer is language-independent.

3-15   HeaderFooterEnhancer

[experimental]

HeaderFooterEnhancer enables you to add header and footer in eRuby script.

<!--#header:
def list_items(items)
#-->
<% for item in items %>
  <b><%= item %></b>
<% end %>
<!--#footer:
end
#-->

$ erubis -xE HeaderFooter headerfooter-example.eruby

def list_items(items)

_buf = ''; for item in items 
 _buf << '  <b>'; _buf << ( item ).to_s; _buf << '</b>
'; end 
_buf.to_s

end

Compare to the following:

<%
def list_items(items)
%>
<% for item in items %>
<li><%= item %></li>
<% end %>
<%
end
%>

$ erubis -x normal-eruby-test.eruby
_buf = '';
def list_items(items)

 for item in items 
 _buf << '<li>'; _buf << ( item ).to_s; _buf << '</li>
'; end 

end

_buf.to_s

Header and footer can be in any position in eRuby script, that is, header is no need to be in the head of eRuby script.

<?xml version="1.0"?>
<html>
<!--#header:
def page(list)
#-->
 :
<!--#footer:
end
#-->
</html>

$ erubis -xE HeaderFooter headerfooter-example2.rhtml

def page(list)

_buf = ''; _buf << '<?xml version="1.0"?>
<html>
'; _buf << ' :
'; _buf << '</html>
';
_buf.to_s

end

HeaderFooterEnhancer is experimental and is language-independent.

3-16   InterpolationEnhancer

[experimental]

InterpolationEnhancer converts "<h1><%= title %></h1>" into "_buf << %Q`<h1>#{ title }</h1>`". This makes Eruby a litter faster because method call of String#<< are eliminated by expression interpolations.

## Assume that input is '<a href="<%=url%>"><%=name%></a>'.
## Eruby convert input into the following code.  String#<< is called 5 times.
_buf << '<a href="'; _buf << (url).to_s; _buf << '">'; _buf << (name).to_s; _buf << '</a>';

## If InterpolationEnhancer is used, String#<< is called only once.
_buf << %Q`<a href="#{url}">#{name}</a>`;

$ erubis -xE Interpolation example.eruby
_buf = ''; _buf << %Q`<div>\n`
 for item in list 
 _buf << %Q`  <p>#{ item }</p>
  <p>#{Erubis::XmlHelper.escape_xml( item )}</p>\n`
 end 
 _buf << %Q`</div>\n`
_buf.to_s

Erubis provides Erubis::FastEruby class which includes InterpolationEnhancer. You can use Erubis::FastEruby class instead of Erubis::Eruby class.

InterpolationEnhancer is only for Eruby.

3-17   DeleteIndentEnhancer

[experimental] DeleteIndentEnhancer deletes indentation of HTML file.

$ erubis -xE DeleteIndent example.eruby
_buf = ''; _buf << '<div>
'; for item in list 
 _buf << '<p>'; _buf << ( item ).to_s; _buf << '</p>
<p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
'; end 
 _buf << '</div>
';
_buf.to_s

Notice that DeleteIndentEnhancer isn't intelligent. It deletes indentations even if they are in <PRE></PRE>.

DeleteIndentEnhancer is language-independent.