path: root/doc/users-guide.txt

.=title:	Erubis Users' Guide
.#.?version:	$Release$
.#.?release:	$Release$
.#.?lastupdate:	$Date$
.?stylesheet:	docstyle.css

release: $Release$



.$ Preface		| preface*

Erubis is an implementation of eRuby.
It has the following features.
.* Very fast, almost three times faster than ERB and about ten percent faster than eruby (implemented in C)
.* File caching of converted Ruby script support
.* Auto escaping support
.* Auto trimming spaces around '<% %>'
.* Embedded pattern changeable (default '<% %>')
.* Enable to handle Processing Instructions (PI) as embedded pattern (ex. '<?rb ... ?>')
.* Multi-language support (Ruby/PHP/C/Java/Scheme/Perl/Javascript)
.* Context object available and easy to combine eRuby template with YAML datafile
.* Print statement available
.* Easy to expand and customize in subclass
.* {{<Ruby on Rails support|#rails>}}
.* mod_ruby support|#topcs-modruby
.#.* {{<Very fast|#topics-benchmark>}}, almost three times faster than ERB and about ten percent faster than eruby (implemented in C)
.#.* {{<File caching of converted Ruby script support|#topics-caching>}}
.#.* {{<Auto escaping support|#tut-escape>}}
.#.* {{<Auto trimming spaces around '<% %>'|#tut-trim>}}
.#.* {{<Embedded pattern changeable|#tut-pattern>}} (default '<% %>')
.#.* {{<Enable to handle Processing Instructions (PI) as embedded pattern|#tut-pi>}} (ex. '<?rb ... ?>')
.#.* {{<Multi-language support|#lang>}} (Ruby/PHP/C/Java/Scheme/Perl/Javascript)
.#.* {{<Context object available|#tut-context>}} and {{<easy to combine eRuby template with YAML datafile|#tut-datafile>}}
.#.* {{<Print statement available|#printenabled-enhancer>}}
.#.* {{<Easy to expand and customize in subclass|#enhancer>}}
.#.* {{<Ruby on Rails support|#topics-rails>}}
.#.* {{<mod_ruby support|#topcs-modruby>}}

Erubis is implemented in pure Ruby.  It requires Ruby 1.8 or higher.
Erubis now supports Ruby 1.9.



.$$ Table of Contents	| toc*

.<<< users-guide.toc



.$ Installation		| install

.* If you have installed RubyGems, just type {{,gem install --remote erubis,}}.
	.====================
	$ sudo gem install --remote erubis
	.====================

.* Else install {{<abstract|http://rubyforge.org/projects/erubis/>}} at first,
   and download erubis_X.X.X.tar.bz2 and install it by setup.rb.
	.====================
	$ tar xjf abstract_X.X.X.tar.bz2
	$ cd abstract_X.X.X/
	$ sudo ruby setup.rb
	$ cd ..
	$ tar xjf erubis_X.X.X.tar.bz2
	$ cd erubis_X.X.X/
	$ sudo ruby setup.rb
	.====================

.#.* Or if you can be root user, download erubis_X.X.X.tar.bz2 and install by setup.rb.
.#	.====================
.#	$ tar xjf erubis-X.X.X.tar.bz2
.#	$ cd erubis_X.X.X/
.#	$ ruby setup.rb
.#	.#$ ruby setup.rb config
.#	.#$ ruby setup.rb setup
.#	.#$ sudo ruby setup.rb install
.#	.====================
.#
.#.* Else you should copy 'lib/erubis.rb', 'lib/erubis/', and 'bin/erubis' into proper directory manually.
.#	.====================
.#	$ tar xjf erubis-X.X.X.tar.bz2
.#	$ cd erubis_X.X.X/
.#	$ cp -r lib/erubis.rb lib/erubis /usr/local/lib/ruby/site_ruby/1.8
.#	$ cp bin/erubis /usr/local/bin
.#	.====================

.* (Optional) 'contrib/inline-require' enables you to merge 'lib/**/*.rb' into 'bin/erubis'.
	.====================
	$ tar xjf erubis_X.X.X.tar.bz2
	$ cd erubis_X.X.X/
	$ unset RUBYLIB
	$ contrib/inline-require -I lib bin/erubis > contrib/erubis
	.====================



.$ Tutorial		| tutorial



.$$ Basic Example	| tut-basic

Here is a basic example of Erubis.

.? example1.eruby
.-------------------- example1.eruby
<ul>
  {{*<% for item in list %>*}}
  <li>{{*<%= item %>*}}</li>
  {{*<% end %>*}}
  {{*<%# here is ignored because starting with '#' %>*}}
</ul>
.--------------------

.? example1.rb
.-------------------- example1.rb
require 'erubis'
input = File.read('example1.eruby')
eruby = {{*Erubis::Eruby.new(input)*}}    # create Eruby object

puts "---------- script source ---"
puts {{*eruby.src*}}                      # print script source

puts "---------- result ----------"
list = ['aaa', 'bbb', 'ccc']
puts {{*eruby.result(binding())*}}        # get result
## or puts eruby.result({{*:list=>list*}})  # or pass Hash instead of Binding

## # or
## eruby = Erubis::Eruby.new
## input = File.read('example1.eruby')
## src = eruby.convert(input)
## eval src
.--------------------

.? output
.==================== example1.result
$ ruby example1.rb
.#.<<<:! (cd guide.d; ruby example1.rb)
---------- script source ---
_buf = ''; _buf << '<ul>
';   for item in list 
 _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
';   end 

 _buf << '</ul>
';
_buf.to_s
---------- result ----------
<ul>
  <li>aaa</li>
  <li>bbb</li>
  <li>ccc</li>
</ul>
.====================

Erubis has command 'erubis'.  Command-line option '-x' shows the compiled source code of eRuby script.

.? example of command-line option '-x'
.==================== example1_x.result
$ erubis {{*-x*}} example1.eruby
.#.<<<:! (cd guide.d; erubis -x example1.eruby)
_buf = ''; _buf << '<ul>
';   for item in list 
 _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
';   end 

 _buf << '</ul>
';
_buf.to_s
.====================



.$$ Trimming Spaces	| tut-trim

Erubis deletes spaces around '<% %>' automatically, while it leaves spaces around '<%= %>'.

.? example2.eruby
.-------------------- example2.eruby.comment_filter
<ul>
  <% for item in list %>      # trimmed
  <li>
    <%= item %>               # not trimmed
  </li>
  <% end %>                   # trimmed
</ul>
.--------------------

.? compiled source code
.==================== example2_x.result
$ erubis -x example2.eruby
.#.<<<:! (ruby -pi.bak -e 'sub! /\s*\#.*$/, ""' guide.d/example2.eruby; erubis -x guide.d/example2.eruby)
_buf = ''; _buf << '<ul>
';   for item in list 
 _buf << '  <li>
    '; _buf << ( item ).to_s; _buf << '
'; _buf << '  </li>
';   end 
 _buf << '</ul>
';
_buf.to_s
.====================

If you want leave spaces around '<% %>', add command-line property '--trim=false'.

.? compiled source code with command-line property '--trim=false'
.==================== example2_trim.result
$ erubis -x {{*--trim=false*}} example2.eruby
.#.<<<:! erubis -x --trim=false guide.d/example2.eruby
_buf = ''; _buf << '<ul>
'; _buf << '  '; for item in list ; _buf << '
'; _buf << '  <li>
    '; _buf << ( item ).to_s; _buf << '
'; _buf << '  </li>
'; _buf << '  '; end ; _buf << '
'; _buf << '</ul>
';
_buf.to_s
.====================

Or add option {{,:trim=>false,}} to Erubis::Eruby.new().

.? example2.rb
.-------------------- example2.rb
require 'erubis'
input = File.read('example2.eruby')
eruby = Erubis::Eruby.new(input{{*, :trim=>false*}})

puts "----- script source ---"
puts eruby.src                            # print script source

puts "----- result ----------"
list = ['aaa', 'bbb', 'ccc']
puts eruby.result(binding())              # get result
.--------------------

.? output
.==================== example2.result
$ ruby example2.rb
.#.<<<:! (cd guide.d; ruby example2.rb)
----- script source ---
_buf = ''; _buf << '<ul>
'; {{*_buf << '  ';*}} for item in list ; _buf << '
'; _buf << '  <li>
    '; _buf << ( item ).to_s; _buf << '
'; _buf << '  </li>
'; {{*_buf << '  ';*}} end ; _buf << '
'; _buf << '</ul>
';
_buf.to_s
----- result ----------
<ul>
  
  <li>
    aaa
  </li>
  
  <li>
    bbb
  </li>
  
  <li>
    ccc
  </li>
  
</ul>
.====================



.$$ Escape		| tut-escape

Erubis has ability to escape (sanitize) expression.
Erubis::Eruby class act as the following:
.* {{,<%= {{/expr/}} %>,}} -  not escaped.
.* {{,<%== {{/expr/}} %>,}} - escaped.
.* {{,<%=== {{/expr/}} %>,}} - out to $stderr.
.* {{,<%==== {{/expr/}} %>,}} - ignored.

Erubis::EscapedEruby{{(Erubis::EscapedEruby class includes Erubis::EscapeEnhancer which swtches the action of '<%= %>' and '<%== %>'.)}} class handle '<%= %>' as escaped and '<%== %>' as not escaped.
It means that using Erubis::EscapedEruby you can escape expression by default.
Also Erubis::XmlEruby class (which is equivalent to Erubis::EscapedEruby) is provided for compatibility with Erubis 1.1.

.? example3.eruby
.-------------------- example3.eruby
<% for item in list %>
  <p>{{*<%=*}} item {{*%>*}}</p>
  <p>{{*<%==*}} item {{*%>*}}</p>
  <p>{{*<%===*}} item {{*%>*}}</p>

<% end %>
.--------------------

.? example3.rb
.-------------------- example3.rb
require 'erubis'
input = File.read('example3.eruby')
eruby = Erubis::{{*EscapedEruby*}}.new(input)    # or Erubis::XmlEruby

puts "----- script source ---"
puts eruby.src                             # print script source

puts "----- result ----------"
{{*list = ['<aaa>', 'b&b', '"ccc"']*}}
puts eruby.result(binding())               # get result
.--------------------

.? output
.==================== example3.result.split_filter
$ ruby example3.rb 2> stderr.log
.#.<<<:! (cd guide.d; ruby example3.rb  2> stderr.log)  | ruby -pe 'sub! /_buf << [E(].*?;|\$stderr.*?;/, "{{*\\&*}}"'
----- script source ---
_buf = ''; for item in list 
 _buf << '  <p>'; {{*_buf << Erubis::XmlHelper.escape_xml( item )*}}; _buf << '</p>
  <p>'; {{*_buf << ( item ).to_s*}}; _buf << '</p>
  <p>'; {{*$stderr.puts("*** debug: item=#{(item).inspect}")*}}; _buf << '</p>

'; end 
_buf.to_s
----- result ----------
  <p>{{*&lt;aaa&gt;*}}</p>
  <p><aaa></p>
  <p></p>

  <p>{{*b&amp;b*}}</p>
  <p>b&b</p>
  <p></p>

  <p>{{*&quot;ccc&quot;*}}</p>
  <p>"ccc"</p>
  <p></p>

$ cat stderr.log
.#.<<<: guide.d/stderr.log
*** debug: item="<aaa>"
*** debug: item="b&b"
*** debug: item="\"ccc\""
.====================

The command-line option '-e' will do the same action as Erubis::EscapedEruby.
This option is available for any language.
.#{{(Command-line option '-e' is equivarent to '-E Escape'.)}}

.==================== example3_e.result
$ erubis -l ruby {{*-e*}} example3.eruby
.#.<<<:! (cd guide.d; erubis -e -l ruby example3.eruby)
_buf = ''; for item in list 
 _buf << '  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
  <p>'; _buf << ( item ).to_s; _buf << '</p>
  <p>'; $stderr.puts("*** debug: item=#{(item).inspect}"); _buf << '</p>

'; end 
_buf.to_s
.====================

Escaping function (default 'Erubis::XmlHelper.escape_xml()') can be changed by command-line property '--escapefunc=xxx' or by overriding Erubis::Eruby#escaped_expr() in subclass.

.? example to override Erubis::Eruby#escaped_expr()
.--------------------
class CGIEruby < Erubis::Eruby
  def {{*escaped_expr(code)*}}
    return "CGI.escapeHTML((#{code.strip}).to_s)"
    #return "h(#{code.strip})"
  end
end

class LatexEruby < Erubi::Eruby
  def {{*escaped_expr(code)*}}
    return "(#{code}).gsub(/[%\\]/,'\\\\\&')"
  end
end
.--------------------



.$$ Embedded Pattern	| tut-pattern

You can change embedded pattern '{{,<% %>,}}' to another by command-line option '-p' or option '{{,:pattern=>...,}}' of Erubis::Eruby.new().

.? example4.eruby
.-------------------- example4.eruby
{{*<!--%*}} for item in list {{*%-->*}}
  <p>{{*<!--%=*}} item {{*%-->*}}</p>
{{*<!--%*}} end {{*%-->*}}
.--------------------

.? compiled source code with command-line option '-p'
.==================== example4_x.result
$ erubis -x {{*-p '<!--% %-->'*}} example4.eruby
.#.<<<:! erubis -x -p '<!--% %-->' guide.d/example4.eruby
_buf = ''; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
'; end 
_buf.to_s
.====================

.? example4.rb
.-------------------- example4.rb
require 'erubis'
input = File.read('example4.eruby')
eruby = Erubis::Eruby.new(input{{*, :pattern=>'<!--% %-->'*}})
                                      # or '<(?:!--)?% %(?:--)?>'

puts "---------- script source ---"
puts eruby.src                            # print script source

puts "---------- result ----------"
list = ['aaa', 'bbb', 'ccc']
puts eruby.result(binding())              # get result
.--------------------

.? output
.==================== example4.result
$ ruby example4.rb
.#.<<<:! (cd guide.d; ruby example4.rb)
---------- script source ---
_buf = ''; for item in list 
 _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
'; end 
_buf.to_s
---------- result ----------
  <p>aaa</p>
  <p>bbb</p>
  <p>ccc</p>
.====================

It is able to specify regular expression with :pattern option.
Notice that you must use '{{,(?: ),}}' instead of '{{,( ),}}' for grouping.
For example, '{{,<(!--)?% %(--)?>,}}' will not work while '{{,<(?:!--)?% %(?:--)?>,}}' will work.



.$$ Context Object	| tut-context

Context object is a set of data which are used in eRuby script.
Using context object makes clear which data to be used.
In Erubis, Hash object and Erubis::Context object are available as context object.

Context data can be accessible via instance variables in eRuby script.

.? example5.eruby
.-------------------- example5.eruby
<span><%= {{*@val*}} %></span>
<ul>
 <% for item in {{*@list*}} %>
  <li><%= item %></li>
 <% end %>
</ul>
.--------------------

.? example5.rb
.-------------------- example5.rb
require 'erubis'
input = File.read('example5.eruby')
eruby = Erubis::Eruby.new(input)      # create Eruby object

## create context object
## (key means var name, which may be string or symbol.)
{{*context = {
  :val   => 'Erubis Example',
  'list' => ['aaa', 'bbb', 'ccc'],
}*}}
## or
# context = Erubis::Context.new()
# context['val'] = 'Erubis Example'
# context[:list] = ['aaa', 'bbb', 'ccc'],

puts {{*eruby.evaluate(context)*}}         # get result
.--------------------

.? output
.==================== example5.result
$ ruby example5.rb
.#.<<<:! (cd guide.d; ruby example5.rb)
<span>Erubis Example</span>
<ul>
  <li>aaa</li>
  <li>bbb</li>
  <li>ccc</li>
</ul>
.====================

The difference between Erubis#result(binding) and Erubis#evaluate(context) is that the former invokes 'eval @src, binding' and the latter invokes 'context.instance_eval @src'.
This means that data is passed into eRuby script via local variables when Eruby::binding() is called, or passed via instance variables when Eruby::evaluate() is called.

Here is the definition of Erubis#result() and Erubis#evaluate().

.? definition of result(binding) and evaluate(context)
.--------------------
def result(_binding=TOPLEVEL_BINDING)
  if _binding.is_a?(Hash)
    # load hash data as local variable
    _h = _binding
    _binding = binding()
    eval _h.collect{|k,v| "#{k} = _h[#{k.inspect}];"}.join, _binding
  end
  return {{*eval(@src, _binding)*}}
end

def evaluate(_context=Erubis::Context.new)
  if _context.is_a?(Hash)
    # convert hash object to Context object
    _hash = _context
    _context = Erubis::Context.new
    _hash.each {|k, v| _context[k] = v }
  end
  return {{*_context.instance_eval(@src)*}}
end
.--------------------

instance_eval() is defined at Object class so it is able to use any object as a context object as well as Hash or Erubis::Context.

.? example6.rb
.-------------------- example6.rb
class MyData
  attr_accessor :val, :list
end

## any object can be a context object
{{*mydata = MyData.new*}}
{{*mydata.val = 'Erubis Example'*}}
{{*mydata.list = ['aaa', 'bbb', 'ccc']*}}

require 'erubis'
eruby = Erubis::Eruby.new(File.read('example5.eruby'))
puts eruby.evaluate({{*mydata*}})
.--------------------

.? output
.==================== example6.result
$ ruby example6.rb
.#.<<<:! (cd guide.d; ruby example6.rb)
<span>Erubis Example</span>
<ul>
  <li>aaa</li>
  <li>bbb</li>
  <li>ccc</li>
</ul>
.====================


It is recommended to use 'Erubis::Eruby#evaluate(context)' rather than 'Erubis::Eruby#result(binding())' because the latter has some problems.
See {{<evaluate(context) v.s. result(binding)|#topics-context-vs-binding>}} section for details.



.$$ Context Data File	| tut-datafile

Command-line option '-f' specifies context data file.
Erubis load context data file and use it as context data.
Context data file can be YAML file ('*.yaml' or '*.yml') or Ruby script ('*.rb').
.#It is very useful to import YAML document data into Hash context object.
.#You can specify YAML file as context data file with command-line option '-f'.

.? example7.eruby
.-------------------- example7.eruby
<h1><%= {{*@title*}} %></h1>
<ul>
 <% for user in {{*@users*}} %>
  <li>
    <a href="mailto:<%= user['mail']%>"><%= user['name'] %></a>
  </li>
 <% end %>
</ul>
.--------------------

.? context.yaml
.-------------------- context.yaml
{{*title:*}} Users List
{{*users:*}}
  - name:  foo
    mail:  foo@mail.com
  - name:  bar
    mail:  bar@mail.net
  - name:  baz
    mail:  baz@mail.org
.--------------------

.? context.rb
.-------------------- context.rb
@title = 'Users List'
@users = [
   { 'name'=>'foo', 'mail'=>'foo@mail.com' },
   { 'name'=>'bar', 'mail'=>'bar@mail.net' },
   { 'name'=>'baz', 'mail'=>'baz@mail.org' },
]
.--------------------

.#.? example7.rb
.#.-------------------- example7.rb
.#require 'erubis'
.#input = File.read('example7.eruby')
.#eruby = Erubis::Eruby.new(input)      # create Eruby object
.#
.### load YAML document as context object
.#{{*require 'yaml'*}}
.#{{*context = YAML.load_file('example7.yaml')*}}
.#
.#puts {{*eruby.evaluate(context)*}}        # get result
.#.--------------------
.#
.#.? output
.#.====================
.#$ ruby example7.rb
.#.<<<:! (cd guide.d; ruby example7.rb)
.#.====================
.#
.#It is able to specify YAML data file with the command-line option '-f'.
.#You don't have to write ruby script such as 'example7.rb'.

.? example of command-line option '-f'
.==================== example7.result.split_filter
$ erubis {{*-f context.yaml*}} example7.eruby
.#.<<<:! (cd guide.d; erubis -f context.yaml example7.eruby)
<h1>Users List</h1>
<ul>
  <li>
    <a href="mailto:foo@mail.com">foo</a>
  </li>
  <li>
    <a href="mailto:bar@mail.net">bar</a>
  </li>
  <li>
    <a href="mailto:baz@mail.org">baz</a>
  </li>
</ul>
$ erubis {{*-f context.rb*}} example7.eruby
.#.<<<:! (cd guide.d; erubis -f context.rb example7.eruby)
<h1>Users List</h1>
<ul>
  <li>
    <a href="mailto:foo@mail.com">foo</a>
  </li>
  <li>
    <a href="mailto:bar@mail.net">bar</a>
  </li>
  <li>
    <a href="mailto:baz@mail.org">baz</a>
  </li>
</ul>
.====================

Command-line option '-S' converts keys of mapping in YAML data file from string into symbol.
Command-line option '-B' invokes 'Erubis::Eruby#result(binding())' instead of 'Erubis::Eruby#evaluate(context)'.



.$$ Context Data String		| tut-datastr

Command-line option '-c {{/str/}}' enables you to specify context data in command-line.
{{/str/}} can be YAML flow-style or Ruby code.

.? example8.eruby
.-------------------- example8.eruby
<h1><%= @title %></h1>
<ul>
<% for item in @list %>
 <li><%= item %></li>
<% end %>
</ul>
.--------------------

.? example of YAML flow style
.==================== example8_yaml.result
$ erubis {{*-c '{title: Example, list: [AAA, BBB, CCC]}'*}} example8.eruby
.#.<<<:! (cd guide.d; erubis -c '{title: Example, list: [AAA, BBB, CCC]}' example8.eruby)
<h1>Example</h1>
<ul>
 <li>AAA</li>
 <li>BBB</li>
 <li>CCC</li>
</ul>
.====================

.? example of Ruby code
.==================== example8_ruby.result
$ erubis {{*-c '@title="Example"; @list=%w[AAA BBB CCC]'*}} example8.eruby
.#.<<<:! (cd guide.d; erubis -c '@title="Example"; @list=%w[AAA BBB CCC]' example8.eruby)
<h1>Example</h1>
<ul>
 <li>AAA</li>
 <li>BBB</li>
 <li>CCC</li>
</ul>
.====================


.$$ Preamble and Postamble   | tut-preamble

The first line ('_buf = '';') in the compiled source code is called preamble
and the last line ('_buf.to_s') is called postamble.

Command-line option '-b' skips the output of preamble and postamble.

.? example9.eruby
.-------------------- example9.eruby
<% for item in @list %>
 <b><%= item %></b>
<% end %>
.--------------------

.? compiled source code with and without command-line option '-b'
.==================== example9.result.split_filter
$ erubis -x example9.eruby
.#.<<<:! erubis -x guide.d/example9.eruby | ruby -pe 'sub! /^_buf.*?(;|$)/, "{{*\\&*}}"'
{{*_buf = '';*}} for item in @list 
 _buf << ' <b>'; _buf << ( item ).to_s; _buf << '</b>
'; end 
{{*_buf.to_s*}}
$ erubis -x {{*-b*}} example9.eruby
.#.<<<:! erubis -x -b guide.d/example9.eruby
 for item in @list 
 _buf << ' <b>'; _buf << ( item ).to_s; _buf << '</b>
'; end 
.====================

Erubis::Eruby.new option '{{,:preamble=>false,}}' and '{{,:postamble=>false,}}' also suppress output of preamble or postamle.

.? example9.rb
.-------------------- example9.rb
require 'erubis'
input = File.read('example9.eruby')
eruby1 = Erubis::Eruby.new(input)
eruby2 = Erubis::Eruby.new(input, {{*:preamble=>false, :postamble=>false*}})

puts eruby1.src   # print preamble and postamble
puts "--------------"
puts eruby2.src   # don't print preamble and postamble
.--------------------

.? output
.==================== example9.result
$ ruby example9.rb
.#.<<<:! (cd guide.d; ruby example9.rb)
_buf = ''; for item in @list 
 _buf << ' <b>'; _buf << ( item ).to_s; _buf << '</b>
'; end 
_buf.to_s
--------------
 for item in @list 
 _buf << ' <b>'; _buf << ( item ).to_s; _buf << '</b>
'; end 
.====================

.#The command-line option '-b' specify both :preamble and :postamble to false.



.$$ Processing Instruction (PI) Converter  | tut-pi

Erubis can parse Processing Instructions (PI) as embedded pattern.

.* '{{,<?rb {{/.../}} ?>,}}' represents Ruby statement.
.* '{{,@{{{/.../}}}@,}}' represents escaped expression value.
.* '{{,@!{{{/.../}}}@,}}' represents normal expression value.
.* '{{,@!!{{{/.../}}}@,}}' prints expression value to standard output.
.* (experimental) '{{,<%= {{/.../}} %>,}}' is also available to print expression value.

This is more useful than basic embedded pattern ('{{,<% ... >,}}') because PI doesn't break XML or HTML at all.
For example the following XHTML file is well-formed and HTML validator got no errors on this example.

.? example10.xhtml
.-------------------- example10.xhtml
<?xml version="1.0" ?>
{{*<?rb
  lang = 'en'
  list = ['<aaa>', 'b&b', '"ccc"']
?>*}}
<html lang="{{*@!{lang}@*}}">
 <body>
  <ul>
  {{*<?rb for item in list ?>*}}
   <li>{{*@{item}@*}}</li>
  {{*<?rb end ?>*}}
  </ul>
 </body>
</html>
.--------------------

If the command-line property '--pi={{/name/}}' is specified, erubis command parses input with PI converter.
If {{/name/}} is omitted then the following name is used according to '-l {{/lang/}}'.

.? mapping of '-l' option and PI name
.+--------------------
 '-l' option ., PI name
.--------------------
-l ruby  .,  <?rb ... ?>
-l php   .,  <?php ... ?>
-l perl  .,  <?perl ... ?>
-l java  .,  <?java ... ?>
-l javascript ., <?js ... ?>
-l scheme ., <?scheme ... ?>
.+--------------------

.? output
.==================== example10_x.result
$ erubis -x {{*--pi*}} example10.xhtml
.#.<<<:! (cd guide.d; erubis -x --pi example10.xhtml)
_buf = ''; _buf << '<?xml version="1.0" ?>
';
  lang = 'en'
  list = ['<aaa>', 'b&b', '"ccc"']

 _buf << '<html lang="'; _buf << (lang).to_s; _buf << '">
 <body>
  <ul>
';   for item in list 
 _buf << '   <li>'; _buf << Erubis::XmlHelper.escape_xml(item); _buf << '</li>
';   end 
 _buf << '  </ul>
 </body>
</html>
';
_buf.to_s
.====================

Expression character can be changeable by command-line property '--embchar={{/char/}}. Default is '{{,@,}}'.

Use Erubis::PI::Eruby instead of Erubis::Eruby if you want to use PI as embedded pattern.

.? example10.rb
.-------------------- example10.rb
require 'erubis'
input = File.read('example10.xhtml')
eruby = Erubis::PI::Eruby.new(input)
print eruby.src
.--------------------

.? output
.==================== example10.result
$ ruby example10.rb
.#.<<<:! (cd guide.d; ruby example10.rb)
_buf = ''; _buf << '<?xml version="1.0" ?>
';
  lang = 'en'
  list = ['<aaa>', 'b&b', '"ccc"']

 _buf << '<html lang="'; _buf << (lang).to_s; _buf << '">
 <body>
  <ul>
';   for item in list 
 _buf << '   <li>'; _buf << Erubis::XmlHelper.escape_xml(item); _buf << '</li>
';   end 
 _buf << '  </ul>
 </body>
</html>
';
_buf.to_s
.====================


{{*(experimental)*}} Erubis supports '<%= ... %>' pattern with PI pattern.
.#It is useful if you are Rails user to write helper methods which contains '}' character.

.? example of Rails view template
.--------------------
<table>
  <tr>
<?rb for item in @list ?>
    <td>@{item.id}@</td>
    <td>@{item.name}@</td>
    <td>
       {{*<%=*}} link_to 'Destroy', {:action=>'destroy', :id=>item.id},
                       :confirm=>'Are you OK?' {{*%>*}}
    </td>
<?rb end ?>
  </tr>
</table>
.--------------------



.$$ Retrieve Ruby Code		| tut-notext

Similar to '-x', ommand-line option '-X' shows converted Ruby source code.
The difference between '-x' and 'X' is that the former converts text part but the latter ignores it.
It means that you can retrieve Ruby code from eRuby script by '-X' option.

.#Command 'notext' is a utility to extract only program code from eRuby/PHP/ePerl script.
.#It is an application of NoTextEnhancer.

For example, see the following eRuby script.
This is some complex, so it is difficult to grasp the program code.

.? example11.rhtml
.-------------------- example11.rhtml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <body>
    <h3>List</h3>
    <% if @list.nil? || @list.empty? %>
    <p>not found.</p>
    <% else %>
    <table>
      <tbody>
        <% @list.each_with_index do |item, i| %>
        <tr bgcolor="<%= i % 2 == 0 ? '#FCC' : '#CCF' %>">
          <td><%= item %></td>
        </tr>
        <% end %>
      </tbody>
    </table>
    <% end %>
  </body>
</html>
.--------------------

Command-line option '-X' extracts only the ruby code from eRuby script.

.? result
.==================== example11.result
$ erubis {{*-X*}} example11.rhtml
_buf = '';





     if @list.nil? || @list.empty? 

     else 


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

         end 


     end 


_buf.to_s
.====================

Command-line option '-C' ({{*c*}}mpact) deletes empty lines.

.? result
.==================== example11_C.result
$ erubis {{*-XC*}} example11.rhtml
_buf = '';
     if @list.nil? || @list.empty? 
     else 
         @list.each_with_index do |item, i| 
                      _buf << ( i % 2 == 0 ? '#FCC' : '#CCF' ).to_s;
               _buf << ( item ).to_s;
         end 
     end 
_buf.to_s
.====================

Option '-U' ({{*u*}}nique) converts empty lines into a line.

.? result
.==================== example11_U.result
$ erubis {{*-XU*}} example11.rhtml
_buf = '';

     if @list.nil? || @list.empty? 

     else 

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

         end 

     end 

_buf.to_s
.====================

Option '-N' ({{*n*}}umber) adds line number.
It is available with '-C' or '-U'.

.? result
.==================== example11_N.result
$ erubis {{*-XNU*}} example11.rhtml
    1:  _buf = '';

    7:       if @list.nil? || @list.empty? 

    9:       else 

   12:           @list.each_with_index do |item, i| 
   13:                        _buf << ( i % 2 == 0 ? '#FCC' : '#CCF' ).to_s;
   14:                 _buf << ( item ).to_s;

   16:           end 

   19:       end 

   22:  _buf.to_s
.====================

Command-line option '-X' is available with PHP script.
.#Language is automatically detected by suffix of filename.
.#And you can specify language with option '-l' ({{*l*}}anguage).

.? example11.php
.-------------------- example11.php
<?xml version="1.0"?>
<html>
  <body>
    <h3>List</h3>
    <?php if (!$list) { ?>
    <p>not found.</p>
    <?php } else { ?>
    <table>
      <tbody>
        <?php $i = 0; ?>
        <?php foreach ($list as $item) { ?>
        <tr bgcolor="<?php echo ++$i % 2 == 1 ? '#FCC' : '#CCF'; ?>">
          <td><?php echo $item; ?></td>
        </tr>
        <?php } ?>
      </tbody>
    </table>
    <?php } ?>
  </body>
</html>
.--------------------

.? result
.==================== example11_php.result
$ erubis -XNU {{*-l php*}} {{*--pi=php*}} --trim=false example11.php

    5:      <?php if (!$list) { ?>

    7:      <?php } else { ?>

   10:          <?php $i = 0; ?>
   11:          <?php foreach ($list as $item) { ?>
   12:                       <?php echo ++$i % 2 == 1 ? '#FCC' : '#CCF'; ?>
   13:                <?php echo $item; ?>

   15:          <?php } ?>

   18:      <?php } ?>

.====================

.#
.#.? example11.eperl
.#.-------------------- example11.eperl
.#<?xml version="1.0"?>
.#<html>
.#  <body>
.#    <h3>List</h3>
.#    <? if (!@list) { !>
.#    <p>not found.</p>
.#    <? } else { !>
.#    <table>
.#      <tbody>
.#        <? $i = 0; !>
.#        <? foreach ($item in @list) { !>
.#        <tr bgcolor="<?= ++$i % 2 == 1 ? '#FCC' : '#CCF' !>">
.#          <td><?= $item !></td>
.#        </tr>
.#        <? } !>
.#      </tbody>
.#    </table>
.#    <? } !>
.#  </body>
.#</html>
.#.chomp
.#.--------------------
.#
.#.? result
.#.==================== example11_eperl.result
.#$ erubis -XNU -l perl example11.eperl
.#  1: use HTML::Entities; 
.#
.#  5:      if (!@list) { 
.#
.#  7:      } else { 
.#
.# 10:          $i = 0; 
.# 11:          foreach ($item in @list) { 
.# 12:                      print(++$i % 2 == 1 ? '#FCC' : '#CCF'); 
.# 13:               print($item); 
.#
.# 15:          } 
.#
.# 18:      } 
.#
.#.====================
.#



.$ Enhancer		| 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|#escape-enhancer>}}, {{<PercentLineEnhancer|#percentline-enhancer>}}, and {{<BiPatternEnhancer|#bipattern-enhancer>}}.

.--------------------
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|#escape-enhancer>}} (language-independent)
	Switch '<%= %>' to escaped and '<%== %>' to unescaped.
.: {{<StdoutEnhancer|#stdout-enhancer>}} (only for Eruby)
	Use $stdout instead of array buffer.
.: {{<PrintOutEnhancer|#printout-enhancer>}} (only for Eruby)
	Use "print(...)" statement insead of "_buf << ...".
.: {{<PrintEnabledEnhancer|#printenabled-enhancer>}} (only for Eruby)
	Enable to use print() in '<% ... %>'.
.: {{<ArrayEnhancer|#array-enhancer>}} (only for Eruby)
	Return array of string instead of returning string.
.: {{<ArrayBufferEnhancer|#arraybuffer-enhancer>}} (only for Eruby)
	Use array buffer. It is a little slower than StringBufferEnhancer.
.: {{<StringBufferEnhancer|#stringbuffer-enhancer>}} (only for Eruby)
	Use string buffer. This is included in Erubis::Eruby by default.
.: {{<ErboutEnhancer|#erbout-enhancer>}} (only for Eruby)
	Set '_erbout = _buf = "";' to be compatible with ERB.
.: {{<NoTextEnhancer|#notext-enhancer>}} (language-independent)
	Print embedded code only and ignore normal text.
.: {{<NoCodeEnhancer|#nocode-enhancer>}} (language-independent)
	Print normal text only and ignore code.
.: {{<SimplifyEnhancer|#simplify-enhancer>}} (language-independent)
	Make compile faster but don't trim spaces around '<% %>'.
.: {{<BiPatternEnhancer|#bipattern-enhancer>}} (language-independent)
	[experimental] Enable to use another embedded pattern with '<% %>'.
.: {{<PercentLineEnhancer|#percentline-enhancer>}} (language-independent)
	Regard lines starting with '%' as Ruby code. This is for compatibility with eruby and ERB.
.: {{<HeaderFooterEnhancer|#headerfooter-enhancer>}} (language-independent)
	[experimental] Enable you to add header and footer in eRuby script.
.: {{<InterpolationEnhancer|#interpolation-enhancer>}} (only for Eruby)
	[experimental] convert '<p><%= text %></p>' into '_buf << %Q`<p>#{text}</p>`'.
.: {{<DeleteIndentEnhancer|#deleteindent-enhancer>}} (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.

.#The following eRuby script ('example.rhtml') is used in the sections.
.#
.#.? example.rhtml
.#.-------------------- example.rhtml
.#<% for item in list %>
.#  <b><%= item %></b>
.#  <b><%== item %></b>
.#<% end %>
.#.--------------------



.$$ EscapeEnhancer	| escape-enhancer

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

.? example.eruby
.-------------------- example.eruby
<div>
<% for item in list %>
  <p><%= item %></p>
  <p><%== item %></p>
<% end %>
</div>
.--------------------

.#.? escape-example.rb
.#.-------------------- escape-example.rb
.#require 'erubis'
.#class EscapedEruby < Erubis::Eruby
.#  include Erubis::EscapeEnhancer
.#end
.#eruby = EscapedEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby escape-example.rb
.#.<<<:! (cd guide.d; ruby escape-example.rb)
.#.====================

.? compiled source code
.==================== escape_example.result
$ erubis -xE Escape example.eruby
.#.<<<:! erubis -xE Escape guide.d/example.eruby | ruby -pe 'sub! /_buf << [E(].*?;/, "{{*\\&*}}"'
_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.



.$$ StdoutEnhancer	| stdout-enhancer

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

.#.? stdout-example.rb
.#.-------------------- stdout-example.rb
.#require 'erubis'
.#class StdoutEruby < Erubis::Eruby
.#  include Erubis::StdoutEnhancer
.#end
.#eruby = StdoutEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby stdout-example.rb
.#.<<<:! (cd guide.d; ruby stdout-example.rb)
.#.====================

.? compiled source code
.==================== stdout_exmple.result
$ erubis -xE Stdout example.eruby
.#.<<<:! erubis -xE Stdout guide.d/example.eruby | ruby -pe 'sub! /^_buf = .*;/, "{{*\\&*}}"'
{{*_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.



.$$ PrintOutEnhancer	| printout-enhancer

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

.#.? printstatement-example.rb
.#.-------------------- printstatement-example.rb
.#require 'erubis'
.#class PrintOutEruby < Erubis::Eruby
.#  include Erubis::PrintOutEnhancer
.#end
.#eruby = PrintOutEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby printstatement-example.rb
.#.<<<:! (cd guide.d; ruby printstatement-example.rb)
.#.====================

.? compiled source code
.==================== printstatement_example.result
$ erubis -xE PrintOut example.eruby
.#.<<<:! erubis -xE PrintOut guide.d/example.eruby | ruby -pe 'gsub! /print/, "{{*\\&*}}"'
 {{*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.



.$$ PrintEnabledEnhancer	| printenabled-enhancer

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

.? printenabled-example.eruby
.-------------------- printenabled-example.eruby
<% for item in @list %>
  <b>{{*<% print item %>*}}</b>
<% end %>
.--------------------

.? printenabled-example.rb
.-------------------- printenabled-example.rb
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)
.--------------------

.? output result
.==================== printenable_example.result
$ ruby printenabled-example.rb
.#.<<<:! (cd guide.d; 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.



.$$ ArrayEnhancer	| array-enhancer

ArrayEnhancer makes Eruby to return an array of strings.

.#.? array-example.rb
.#.-------------------- array-example.rb
.#require 'erubis'
.#class ArrayEruby < Erubis::Eruby
.#  include Erubis::ArrayEnhancer
.#end
.#eruby = ArrayEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby array-example.rb
.#.<<<:! (cd guide.d; ruby array-example.rb)
.#.====================

.? compiled source code
.==================== array_example.result
$ erubis -xE Array example.eruby
.#.<<<:! erubis -xE Array guide.d/example.eruby | ruby -pe 'sub! /^_buf( = \[\];)?/, "{{*\\&*}}"'
{{*_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.



.$$ ArrayBufferEnhancer	| arraybuffer-enhancer

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

ArrayBufferEnhancer is only for Eruby.

.? compiled source code
.==================== arraybuffer_example.result
$ erubis -xE ArrayBuffer example.eruby
.#.<<<:! erubis -xE ArrayBuffer guide.d/example.eruby | ruby -pe 'sub!(/^_buf( = .*?;|\.join)?/,"{{*\\&*}}")'
{{*_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*}}
.====================



.$$ StringBufferEnhancer | stringbuffer-enhancer

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


.#.? stringbuffer-example.rb
.#.-------------------- stringbuffer-example.rb
.#require 'erubis'
.#class StringBufferEruby < Erubis::Eruby
.#  include Erubis::StringBufferEnhancer
.#end
.#eruby = StringBufferEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby stringbuffer-example.rb
.#.<<<:! (cd guide.d; ruby stringbuffer-example.rb)
.#.====================

.? compiled source code
.==================== stringbuffer_example.result
$ erubis -xE StringBuffer example.eruby
.#.<<<:! erubis -xE StringBuffer guide.d/example.eruby | ruby -pe 'sub!(/^_buf( = .*?;)?/,"{{*\\&*}}")'
{{*_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.



.$$ ErboutEnhancer | erbout-enhancer

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

.#.? erbout-example.rb
.#.-------------------- erbout-example.rb
.#require 'erubis'
.#class ErboutEruby < Erubis::Eruby
.#  include Erubis::ErboutEnhancer
.#end
.#eruby = ErboutEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby erbout-example.rb
.#.<<<:! (cd guide.d; ruby erbout-example.rb)
.#.====================

.? compiled source code
.====================
$ erubis -xE Erbout example.eruby
.#.<<<:! erubis -xE Erbout guide.d/example.eruby | ruby -pe 'sub! /^_erbout = _buf = .*?;/,"{{*\\&*}}"'
{{*_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.



.$$ NoTextEnhancer	| notext-enhancer

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

.? notext-example.eruby
.-------------------- notext-example.eruby
<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 %>
.--------------------

.? output example of NoTextEnhancer
.==================== notext_example.result
$ erubis -xE NoText notext-example.eruby
.#.<<<:! (cd guide.d; 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|#topics-php>}}.



.$$ NoCodeEnhancer	| nocode-enhancer

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

.? nocode-example.eruby
.-------------------- nocode-example.eruby
<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 %>
.--------------------

.? output example of NoCodeEnhancer
.==================== nocode_example.result
$ erubis -xE NoCode notext-example.eruby
.#.<<<:! (cd guide.d; erubis -xE NoCode nocode-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|#topics-php>}}.



.$$ SimplifyEnhancer	| simplify-enhancer

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

.#.? simplify-example.rb
.#.-------------------- simplify-example.rb
.#require 'erubis'
.#class SimplifiedEruby < Erubis::Eruby
.#  include Erubis::SimplifyEnhancer
.#end
.#eruby = SimplifiedEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby simplify-example.rb
.#.<<<:! (cd guide.d; ruby simplify-example.rb)
.#.====================

.? compiled source code
.==================== simplify_example.result
$ erubis -xE Simplify example.eruby
.#.<<<:! erubis -xE Simplify guide.d/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.



.$$ BiPatternEnhancer	| bipattern-enhancer

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

.? bipattern-example.rhtml
.-------------------- bipattern-example.rhtml
<% for item in list %>
  <b>{{*[= item =]*}}</b>
  <b>{{*[== item =]*}}</b>
<% end %>
.--------------------

.#.? bipattern-example.rb
.#.-------------------- bipattern-example.rb
.#require 'erubis'
.#class BiPatternEruby < Erubis::Eruby
.#  include Erubis::BiPatternEnhancer
.#end
.#
.#input = File.read('bipattern-example.rhtml')
.#eruby = BiPatternEruby.new(input)
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby bipattern-example.rb
.#.<<<:! (cd guide.d; ruby bipattern-example.rb)
.#.====================

.? compiled source code
.==================== bipattern_example.result
$ erubis -xE BiPattern bipattern-example.rhtml
.#.<<<:! erubis -xE BiPattern guide.d/bipattern-example.rhtml | ruby -pe 'sub! /_buf << [E(].*;/, "{{*\\&*}}"'
_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.



.$$ PercentLineEnhancer	| percentline-enhancer

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

.? percentline-example.rhtml
.-------------------- percentline-example.rhtml
<ul>
{{*% for item in list*}}
  <li><%= item %></li>
{{*% end*}}
</ul>
{{*%% lines with '%%'*}}
.--------------------

.#.? percentline-example.rb
.#.-------------------- percentline-example.rb
.#require 'erubis'
.#class PercentLineEruby < Erubis::Eruby
.#  include Erubis::PercentLineEnhancer
.#end
.#
.#input = File.read('percentline-example.rhtml')
.#eruby = PercentLineEruby.new(input)
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby percentline-example.rb
.#.<<<:! (cd guide.d; ruby percentline-example.rb)
.#.====================

.? compiled source code
.==================== percentline_example.result
$ erubis -xE PercentLine percentline-example.rhtml
.#.<<<:! erubis -xE PercentLine guide.d/percentline-example.rhtml | ruby -pe 'sub! /for.*?list|end/, "{{*\\&*}}"'
_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.



.$$ PrefixedLineEnhancer	| prefixedline-enhancer

PrefixedlineEnhancer regards lines starting with '%' as Ruby code.
It is similar to {{<PercentLineEnhancer|#percentline-enhancer>}}, 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.


.? prefixedline-example.rhtml
.-------------------- prefixedline-example.rhtml
<ul>
  {{*! for item in list*}}
  <li><%= item %></li>
  {{*! end*}}
</ul>
  {{*!! lines with '!!'*}}
.--------------------

.? prefixedline-example.rb
.-------------------- prefixedline-example.rb
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
.--------------------

.? compiled source code
.==================== prefixedline_example.result
$ 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.



.$$ HeaderFooterEnhancer | headerfooter-enhancer

[experimental]

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

.? headerfooter-example.eruby
.-------------------- headerfooter-example.eruby
{{*<!--#header:*}}
{{*def list_items(items)*}}
{{*#-->*}}
<% for item in items %>
  <b><%= item %></b>
<% end %>
{{*<!--#footer:*}}
{{*end*}}
{{*#-->*}}
.--------------------

.#.? headerfooter-example.rb
.#.-------------------- headerfooter-example.rb
.#require 'erubis'
.#class HeaderFooterEruby < Erubis::Eruby
.#  include Erubis::HeaderFooterEnhancer
.#end
.#
.#input = File.read('headerfooter-example.eruby')
.#eruby = HeaderFooterEruby.new(input)
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby headerfooter-example.rb
.#.<<<:! (cd guide.d; ruby headerfooter-example.rb)
.#.====================

.? compiled source code
.==================== headerfooter_example.result
$ erubis -xE HeaderFooter headerfooter-example.eruby
.#.<<<:! erubis -xE HeaderFooter guide.d/headerfooter-example.eruby | ruby -pe 'sub! /^(def|end).*$/, "{{*\\&*}}"'

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

.? normal-eruby-test.eruby
.-------------------- normal-eruby-test.eruby
{{*<%*}}
{{*def list_items(items)*}}
{{*%>*}}
<% for item in items %>
<li><%= item %></li>
<% end %>
{{*<%*}}
{{*end*}}
{{*%>*}}
.--------------------

.? compiled source code
.==================== normal_eruby_test.result
$ erubis -x normal-eruby-test.eruby
.#.<<<:! erubis -x guide.d/normal-eruby-test.eruby | ruby -pe 'sub! /^(def|end).*$/, "{{*\\&*}}"'
_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.

.#+++
.-------------------- headerfooter-example2.rb
require 'erubis'
class HeaderFooterEruby < Erubis::Eruby
  include Erubis::HeaderFooterEnhancer
end

input = File.read('headerfooter-example2.rhtml')
eruby = HeaderFooterEruby.new(input)
print eruby.src
.--------------------
.#---

.? headerfooter-example2.rhtml
.-------------------- headerfooter-example2.rhtml
<?xml version="1.0"?>
<html>
{{*<!--#header:*}}
{{*def page(list)*}}
{{*#-->*}}
 :
{{*<!--#footer:*}}
{{*end*}}
{{*#-->*}}
</html>
.--------------------

.#.? compiled source code
.#.====================
.#$ ruby headerfooter-example2.rb
.#.<<<:! (cd guide.d; ruby headerfooter-example2.rb)
.#.====================

.? compiled source code
.==================== headerfooter_example2.result
$ erubis -xE HeaderFooter headerfooter-example2.rhtml
.#.<<<:! erubis -xE HeaderFooter guide.d/headerfooter-example2.rhtml | ruby -pe 'sub! /^(def|end).*$/, "{{*\\&*}}"'

{{*def page(list)*}}

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

{{*end*}}

.====================

HeaderFooterEnhancer is experimental and is language-independent.



.$$ InterpolationEnhancer | interpolation-enhancer

[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.

.? InterpolationEnhancer elmininates method call of String#<<.
.--------------------
## 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>`;
.--------------------

.#.? interpolation-example.rb
.#.-------------------- interpolation-example.rb
.#require 'erubis'
.#class InterpolationEruby < Erubis::Eruby
.#  include Erubis::InterpolationEnhancer
.#end
.#eruby = InterpolationEruby.new(File.read('example.eruby'))
.### or
.##eruby = Erubis::FastEruby.new(File.read('example.eruby'))
.#print eruby.src
.#.--------------------
.#
.#.? compiled source code
.#.====================
.#$ ruby interpolation-example.rb
.#.<<<:! (cd guide.d; ruby interpolation-example.rb)
.#.====================

.? compiled source code
.==================== interpolation_example.result
$ erubis -xE Interpolation example.eruby
.#.<<<:! erubis -xE Interpolation guide.d/example.eruby | ruby -pe 'gsub! /(%Q`|`|\#\{.*?\})/, "{{*\\&*}}"'
_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.


.$$ DeleteIndentEnhancer | deleteindent-enhancer

[experimental]
DeleteIndentEnhancer deletes indentation of HTML file.

.? compiled source code
.==================== interpolation_example.result
$ erubis -xE DeleteIndent example.eruby
.#.<<<:! erubis -xE DeleteIndent guide.d/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.



.$ Multi-Language Support	| lang

Erubis supports the following languages{{(If you need template engine in pure PHP/Perl/JavaScript, try {{<Tenjin|http://www.kuwata-lab.com/tenjin/>}} ({{<http://www.kuwata-lab.com/tenjin/>}}). Tenjin is a very fast and full-featured template engine implemented in pure PHP/Perl/JavaScript.)}}:

.* Ruby
.* {{<PHP|#lang-php>}}
.* {{<C|#lang-c>}}
.* {{<Java|#lang-java>}}
.* {{<Scheme|#lang-scheme>}}
.* {{<Perl|#lang-perl>}}
.* {{<JavaScript|#lang-javascript>}}



.$$ PHP		| lang-php

.? example.ephp
.-------------------- example.ephp
<?xml version="1.0"?>
<html>
 <body>
  <p>Hello {{*<%= $user %>*}}!</p>
  <table>
   <tbody>
    {{*<% $i = 0; %>*}}
    {{*<% foreach ($list as $item) { %>*}}
    {{*<%   $i++; %>*}}
    <tr bgcolor={{*"<%= $i % 2 == 0 ? '#FFCCCC' : '#CCCCFF' %>"*}}>
     <td>{{*<%= $i %>*}}</td>
     <td>{{*<%== $item %>*}}</td>
    </tr>
    {{*<% } %>*}}
   </tbody>
  </table>
 </body>
</html>
.--------------------

.? compiled source code
.==================== example_php.result
$ erubis -l php example.ephp
.#.<<<:! (cd guide.d; erubis -l php example.ephp)
<<?php ?>?xml version="1.0"?>
<html>
 <body>
  <p>Hello <?php echo $user; ?>!</p>
  <table>
   <tbody>
<?php     $i = 0; ?>
<?php     foreach ($list as $item) { ?>
<?php       $i++; ?>
    <tr bgcolor="<?php echo $i % 2 == 0 ? '#FFCCCC' : '#CCCCFF'; ?>">
     <td><?php echo $i; ?></td>
     <td><?php echo htmlspecialchars($item); ?></td>
    </tr>
<?php     } ?>
   </tbody>
  </table>
 </body>
</html>
.====================

.# If you need template engine in pure PHP, try {{<phpTenjin|http://www.kuwata-lab.com/tenjin/>}} ({{<http://www.kuwata-lab.com/tenjin/>}}).
.# phpTenjin is a very fast and full-featured template engine implemented in pure PHP.


.$$ C		| lang-c

.? example.ec
.-------------------- example.ec
{{*<%
#include <stdio.h>

int main(int argc, char *argv[])
{
    int i;

%>*}}
<html>
 <body>
  <p>Hello {{*<%= "%s", argv[0] %>*}}!</p>
  <table>
   <tbody>
    {{*<% for (i = 1; i < argc; i++) { %>*}}
    <tr bgcolor="{{*<%= i % 2 == 0 ? "#FFCCCC" : "#CCCCFF" %>*}}">
      <td>{{*<%= "%d", i %>*}}</td>
      <td>{{*<%= "%s", argv[i] %>*}}</td>
    </tr>
    {{*<% } %>*}}
   </tbody>
  </table>
 </body>
</html>
{{*<%
    return 0; 
}
%>*}}
.--------------------

.? compiled source code
.==================== example_c.result
$ erubis -l c example.ec
.#.<<<:! (cd guide.d; erubis -l c example.ec)
#line 1 "example.ec"

#include <stdio.h>

int main(int argc, char *argv[])
{
    int i;


fputs("<html>\n"
      " <body>\n"
      "  <p>Hello ", stdout); fprintf(stdout, "%s", argv[0]); fputs("!</p>\n"
      "  <table>\n"
      "   <tbody>\n", stdout);
     for (i = 1; i < argc; i++) { 
fputs("    <tr bgcolor=\"", stdout); fprintf(stdout, i % 2 == 0 ? "#FFCCCC" : "#CCCCFF"); fputs("\">\n"
      "      <td>", stdout); fprintf(stdout, "%d", i); fputs("</td>\n"
      "      <td>", stdout); fprintf(stdout, "%s", argv[i]); fputs("</td>\n"
      "    </tr>\n", stdout);
     } 
fputs("   </tbody>\n"
      "  </table>\n"
      " </body>\n"
      "</html>\n", stdout);

    return 0; 
}

.====================



.$$ Java	| lang-java

.? Example.ejava
.-------------------- Example.ejava
{{*<%
import java.util.*;

public class Example {
  private String user;
  private String[] list;
  public example(String user, String[] list) {
    this.user = user;
    this.list = list;
  }

  public String view() {
    StringBuffer _buf = new StringBuffer();
%>*}}
<html>
 <body>
  <p>Hello {{*<%= user %>*}}!</p>
  <table>
   <tbody>
    {{*<% for (int i = 0; i < list.length; i++) { %>*}}
    <tr bgcolor={{*"<%= i % 2 == 0 ? "#FFCCCC" : "#CCCCFF" %>"*}}>
     <td>{{*<%= i + 1 %>*}}</td>
     <td>{{*<%== list[i] %>*}}</td>
    </tr>
    {{*<% } %>*}}
   </tbody>
  </table>
 <body>
</html>
{{*<%
    return _buf.toString();
  }

  public static void main(String[] args) {
    String[] list = { "<aaa>", "b&b", "\"ccc\"" };
    Example ex = Example.new("Erubis", list);
    System.out.print(ex.view());
  }

  public static String escape(String s) {
    StringBuffer sb = new StringBuffer();
    for (int i = 0; i < s.length(); i++) {
      char ch = s.charAt(i);
      switch (ch) {
      case '<':   sb.append("&lt;"); break;
      case '>':   sb.append("&gt;"); break;
      case '&':   sb.append("&amp;"); break;
      case '"':   sb.append("&quot;"); break;
      default:    sb.append(ch);
      }
    }
    return sb.toString();
  }
}
%>*}}
.--------------------

.? compiled source code
.==================== example_java.result
$ erubis -b -l java example.ejava
.#.<<<:! (cd guide.d; erubis -l java example.ejava)

import java.util.*;

public class Example {
  private String user;
  private String[] list;
  public example(String user, String[] list) {
    this.user = user;
    this.list = list;
  }

  public String view() {
    StringBuffer _buf = new StringBuffer();

_buf.append("<html>\n"
          + " <body>\n"
          + "  <p>Hello "); _buf.append(user); _buf.append("!</p>\n"
          + "  <table>\n"
          + "   <tbody>\n");
     for (int i = 0; i < list.length; i++) { 
_buf.append("    <tr bgcolor=\""); _buf.append(i % 2 == 0 ? "#FFCCCC" : "#CCCCFF"); _buf.append("\">\n"
          + "     <td>"); _buf.append(i + 1); _buf.append("</td>\n"
          + "     <td>"); _buf.append(escape(list[i])); _buf.append("</td>\n"
          + "    </tr>\n");
     } 
_buf.append("   </tbody>\n"
          + "  </table>\n"
          + " <body>\n"
          + "</html>\n");

    return _buf.toString();
  }

  public static void main(String[] args) {
    String[] list = { "<aaa>", "b&b", "\"ccc\"" };
    Example ex = Example.new("Erubis", list);
    System.out.print(ex.view());
  }

  public static String escape(String s) {
    StringBuffer sb = new StringBuffer();
    for (int i = 0; i < s.length(); i++) {
      char ch = s.charAt(i);
      switch (ch) {
      case '<':   sb.append("&lt;"); break;
      case '>':   sb.append("&gt;"); break;
      case '&':   sb.append("&amp;"); break;
      case '"':   sb.append("&quot;"); break;
      default:    sb.append(ch);
      }
    }
    return sb.toString();
  }
}

.====================



.$$ Scheme	| lang-scheme

.? example.escheme
.-------------------- example.escheme
<html>
 <body>
{{*<%
(let ((user "Erubis")
      (items '("<aaa>" "b&b" "\"ccc\""))
      (i 0))
 %>*}}
  <p>Hello {{*<%= user %>*}}!</p>
  <table>
{{*<%
  (for-each
   (lambda (item)
     (set! i (+ i 1))
 %>*}}
   <tr bgcolor="{{*<%= (if (= (modulo i 2) 0) "#FFCCCC" "#CCCCFF") %>*}}">
    <td>{{*<%= i %>*}}</td>
    <td>{{*<%= item %>*}}</td>
   </tr>
{{*<%
   ) ; lambda end
   items) ; for-each end
 %>*}}
  </table>
{{*<%
) ; let end
%>*}}
 </body>
</html>
.--------------------

.? compiled source code
.==================== example_scheme.result
$ erubis -l scheme example.escheme
.#.<<<:! (cd guide.d; erubis -l scheme example.escheme)
(let ((_buf '())) (define (_add x) (set! _buf (cons x _buf))) (_add "<html>
 <body>\n")

(let ((user "Erubis")
      (items '("<aaa>" "b&b" "\"ccc\""))
      (i 0))
 
(_add "  <p>Hello ")(_add user)(_add "!</p>
  <table>\n")

  (for-each
   (lambda (item)
     (set! i (+ i 1))
 
(_add "   <tr bgcolor=\"")(_add (if (= (modulo i 2) 0) "#FFCCCC" "#CCCCFF"))(_add "\">
    <td>")(_add i)(_add "</td>
    <td>")(_add item)(_add "</td>
   </tr>\n")

   ) ; lambda end
   items) ; for-each end
 
(_add "  </table>\n")

) ; let end

(_add " </body>
</html>\n")
  (reverse _buf))
.====================

.? compiled source code (with {{,--func=display,}} property)
.==================== example_scheme_display.result
$ erubis -l scheme --func=display example.escheme
.#.<<<:! (cd guide.d; erubis -l scheme --func=display example.escheme)
(display "<html>
 <body>\n")

(let ((user "Erubis")
      (items '("<aaa>" "b&b" "\"ccc\""))
      (i 0))
 
(display "  <p>Hello ")(display user)(display "!</p>
  <table>\n")

  (for-each
   (lambda (item)
     (set! i (+ i 1))
 
(display "   <tr bgcolor=\"")(display (if (= (modulo i 2) 0) "#FFCCCC" "#CCCCFF"))(display "\">
    <td>")(display i)(display "</td>
    <td>")(display item)(display "</td>
   </tr>\n")

   ) ; lambda end
   items) ; for-each end
 
(display "  </table>\n")

) ; let end

(display " </body>
</html>\n")
.====================



.$$ Perl	| lang-perl

.? example.eperl
.-------------------- example.eperl
{{*<%
   my $user = 'Erubis';
   my @list = ('<aaa>', 'b&b', '"ccc"');
%>*}}
<html>
 <body>
  <p>Hello {{*<%= $user %>*}}!</p>
  <table>
   {{*<% $i = 0; %>*}}
   {{*<% for $item (@list) { %>*}}
   <tr bgcolor={{*<%= ++$i % 2 == 0 ? '#FFCCCC' : '#CCCCFF' %>*}}">
    <td>{{*<%= $i %>*}}</td>
    <td>{{*<%= $item %>*}}</td>
   </tr>
   {{*<% } %>*}}
  </table>
 </body>
</html>
.--------------------

.? compiled source code
.==================== example_perl.result
$ erubis -l perl example.eperl
.#.<<<:! (cd guide.d; erubis -l perl example.eperl)
use HTML::Entities; 
   my $user = 'Erubis';
   my @list = ('<aaa>', 'b&b', '"ccc"');

print('<html>
 <body>
  <p>Hello '); print($user); print('!</p>
  <table>
');     $i = 0; 
    for $item (@list) { 
print('   <tr bgcolor='); print(++$i % 2 == 0 ? '#FFCCCC' : '#CCCCFF'); print('">
    <td>'); print($i); print('</td>
    <td>'); print($item); print('</td>
   </tr>
');     } 
print('  </table>
 </body>
</html>
'); 
.====================

.# If you need template engine in pure Perl, try {{<plTenjin|http://www.kuwata-lab.com/tenjin/>}} ({{<http://www.kuwata-lab.com/tenjin/>}}).
.# plTenjin is a very fast and full-featured template engine implemented in pure Perl.



.$$ JavaScript	| lang-javascript

.? example.ejs
.-------------------- example.ejs
{{*<%
   var user = 'Erubis';
   var list = ['<aaa>', 'b&b', '"ccc"'];
 %>*}}
<html>
 <body>
  <p>Hello {{*<%= user %>*}}!</p>
  <table>
   <tbody>
    {{*<% var i; %>*}}
    {{*<% for (i = 0; i < list.length; i++) { %>*}}
    <tr bgcolor="{{*<%= i % 2 == 0 ? '#FFCCCC' : '#CCCCFF' %>*}}">
     <td>{{*<%= i + 1 %>*}}</td>
     <td>{{*<%= list[i] %>*}}</td>
    </tr>
    {{*<% } %>*}}
   </tbody>
  </table>
 </body>
</html>
.--------------------

.? compiled source code
.==================== example_js.result
$ erubis -l js example.ejs
.#.<<<:! (cd guide.d; erubis -l js example.ejs)
var _buf = [];
   var user = 'Erubis';
   var list = ['<aaa>', 'b&b', '"ccc"'];
 
_buf.push("<html>\n\
 <body>\n\
  <p>Hello "); _buf.push(user); _buf.push("!</p>\n\
  <table>\n\
   <tbody>\n");
     var i; 
     for (i = 0; i < list.length; i++) { 
_buf.push("    <tr bgcolor=\""); _buf.push(i % 2 == 0 ? '#FFCCCC' : '#CCCCFF'); _buf.push("\">\n\
     <td>"); _buf.push(i + 1); _buf.push("</td>\n\
     <td>"); _buf.push(list[i]); _buf.push("</td>\n\
    </tr>\n");
     } 
_buf.push("   </tbody>\n\
  </table>\n\
 </body>\n\
</html>\n");
document.write(_buf.join(""));
.====================

If command-line option '{{,--docwrite=false,}}' is specified,
'{{,_buf.join("");,}}' is used instead of '{{,document.write(_buf.join(""));,}}'.
This is useful when passing converted source code to eval() function in JavaScript.

You can pass {{,:docwrite=>false,}} to Erubis::Ejavascript.new() in your Ruby script.

.--------------------
s = File.read('example.jshtml')
engine = Erubis::Ejavascript.new(s, {{,:docwrite=>false,}})
.--------------------

If you want to specify any JavaScript code, use '--postamble=...'.

Notice that default value of 'docwrite' property will be false in the future release.

.# If you need template engine in pure JavaScript, try {{<jsTenjin|http://www.kuwata-lab.com/tenjin/>}} ({{<http://www.kuwata-lab.com/tenjin/>}}).
.# jsTenjin is a very fast and full-featured template engine implemented in pure JavaScript and available with not only web browser but also Spidermonkey and Rhino.



.$ Ruby on Rails Support	| rails

{{!NOTICE: Rails 3 adopts Erubis as default default engine. You don't need to do anything at all when using Rails 3. This section is for Rails 2.!}}

Erubis supports Ruby on Rails. 
This section describes how to use Erubis with Ruby on Rails.


.$$ Settings		| rails-settings


Add the following code to your 'config/environment.rb' and restart web server.
This replaces ERB in Rails by Erubis entirely.
    
.? config/environment.rb
.--------------------
require 'erubis/helpers/rails_helper'
#Erubis::Helpers::RailsHelper.engine_class = Erubis::Eruby # or Erubis::FastEruby
#Erubis::Helpers::RailsHelper.init_properties = {}
#Erubis::Helpers::RailsHelper.show_src = nil
#Erubis::Helpers::RailsHelper.preprocessing = false
.--------------------

Options:

.% Erubis::Helpers::RailsHelper.engine_class (=Erubis::Eruby)
	Erubis engine class (default Erubis::Eruby).
.% Erubis::Helpers::RailsHelper.init_properties (={})
	Optional arguments for Erubis::Eruby#initialize() method (default {}).
.% Erubis::Helpers::RailsHelper.show_src (=nil)
	Whether to print converted Ruby code into log file.
	If true, Erubis prints coverted code into log file.
	If false, Erubis doesn't.
	If nil, Erubis prints when ENV['RAILS_ENV'] == 'development'.
	Default is nil.
.% Erubis::Helpers::RailsHelper.preprocessing (=false)
	Enable preprocessing if true (default false).
    
    
.#.2) (Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'.
.#    
.#    .? action_view_base_rb.patch
.#    .--------------------
.#    --- lib/action_view/base.rb	(original)
.#    +++ lib/action_view/base.rb	(working copy)
.#    @@ -445,6 +445,11 @@
.#             end
.#           end
.#     
.#    +      # convert template into ruby code
.#    +      def convert_template_into_ruby_code(template)
.#    +        ERB.new(template, nil, @@erb_trim_mode).src
.#    +      end
.#    +
.#           # Create source code for given template
.#           def create_template_source(extension, template, render_symbol, locals)
.#             if template_requires_setup?(extension)
.#    @@ -458,7 +463,7 @@
.#                   "update_page do |page|\n#{template}\nend"
.#               end
.#             else
.#    -          body = ERB.new(template, nil, @@erb_trim_mode).src
.#    +          body = convert_template_into_ruby_code(template)
.#             end
.#     
.#             @@template_args[render_symbol] ||= {}
.#    .--------------------
.#    
.#    This patch is included in erubis_2.X.X/contrib directory and the following is an
.#    example to apply this patch.
.#    
.#    .? how to apply patch:
.#    .====================
.#    $ cd /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.13.1/lib/action_view/
.#    $ sudo patch -p1 < /tmp/erubis_2.X.X/contrib/action_view_base_rb.patch
.#    .====================
.#    
.#    Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended.
.#    
.#.2) Restart web server.
.#    .====================
.#    $ ruby script/server
.#    .====================
.#
.#The setting is above all.



.$$ Preprosessing		| rails-preprocessing

Erubis supports preprocessing of template files.
Preprocessing make your Ruby on Rails application about 20-40 percent faster.
To enable preprocessing, set Erubis::Helpers::RailsHelper.preprocessing to true in your 'environment.rb' file.

For example, assume the following template.
This is slow because link_to() method is called every time when template is rendered.

.--------------------
<%= link_to 'Create', :action=>'create' %>
.--------------------

The following is faster than the above, but not flexible because url is fixed.

.--------------------
<a href="/users/create">Create</a>
.--------------------

Preprocessing solves this problem.
If you use '[%= %]' instead of '<%= %>', preprocessor evaluate it only once when template is loaded.

.--------------------
{{*[%= link_to 'Create', :action=>'create'%]*}}
.--------------------

The above is evaluated by preprocessor and replaced to the following code automatically.

.--------------------
<a href="/users/create">Create</a>
.--------------------

Notice that this is done only once when template file is loaded.
It means that link_to() method is not called when template is rendered.

If link_to() method have variable arguments, use {{,_?(),}} helper method.

.--------------------
<% for user in @users %>
[%= link_to {{*_?('user.name')*}}, :action=>'show', :id=>{{*_?('user.id')*}} %]
<% end %>
.--------------------

The above is evaluated by preprocessor when template is loaded and expanded into the following code.
This will be much faster because link_to() method is not called when rendering.

.--------------------
<% for user in @users %>
<a href="/users/show/{{*<%=user.id%>*}}">{{*<%=user.name%>*}}</a>
<% end %>
.--------------------

Preprocessing statement ({{,[% %],}}) is also available as well as preprocessing expression ({{,[%= %],}}).
.--------------------
<select name="state">
  <option value="">-</option>
{{*[% for code in states.keys.sort %]*}}
  <option value="{{*[%= code %]*}}">{{*[%= states[code] %]*}}</option>
{{*[% end %]*}}
</select>
.--------------------

The above will be evaluated by preprocessor and expanded into the following when template is loaded.
In the result, rendering speed will be much faster because for-loop is not executed when rendering.
.--------------------
<select name="state">
  <option value="">-</option>
  <option value="AK">Alaska</option>
  <option value="AL">Alabama</option>
  <option value="AR">Arkansas</option>
  <option value="AS">American Samoa</option>
  <option value="AZ">Arizona</option>
  <option value="CA">California</option>
  <option value="CO">Colorado</option>
   ....
</select>
.--------------------

Notice that it is not recommended to use preprocessing with tag helpers,
because tag helpers generate different html code when form parameter has errors or not.

Helper methods of Ruby on Rails are divided into two groups.
.* link_to() or _() (method of gettext package) are not need to call for every time
   as template is rendered because it returns same value when same arguments are passed.
   These methods can be got faster by preprocessing.
.* Tag helper methods should be called for every time as template is rendered
   because it may return differrent value even if the same arguments are passed.
   Preprocessing is not available with these methods.

In Ruby on Rails 2.0, {{,_?('user_id'),}} is OK but {{,_?('user.id'),}} is NG
because the latter contains period ('.') character.

.--------------------
<!-- NG in Rails 2.0, because _?('') contains period -->
[%= link_to 'Edit', edit_user_path({{*_?('@user.id')*}}) %]
[%= link_to 'Show', {{*@user*}} %]
[%= link_to 'Delete', {{*@user*}}, :confirm=>'OK?', :method=>:delete %]

<!-- OK in Rails 2.0 -->
{{*<%= user_id = @user.id %>*}}
[%= link_to 'Edit', edit_user_path({{*_?('user_id')*}}) %]
[%= link_to 'Show', {{*:action=>'show', :id=>_?('user_id')*}} %]
[%= link_to 'Delete', {{*{:action=>'destroy', :id=>_?('user_id')}*}},
                      {:confirm=>'OK?', :method=>:delete} %]
.--------------------


.$$ Form Helpers for Preprocessing  | rails-formhelpers

{{*(Experimental)*}}

Erubis provides form helper methods for preprocessing.
These are defined in 'erubis/helpers/rails_form_helper.rb'.
If you want to use it, require it and include Erubis::Helpers::RailsFormHelper in 'app/helpers/applition_helper.rb'

.? app/helpers/xxx_helper.rb
.--------------------
require 'erubis/helpers/rails_form_helper'
module ApplicationHelper
  include Erubis::Helpers::RailsFormHelper
end
.--------------------

Form helper methods defined in Erubis::Helpers::RailsFormHelper are named as 'pp_xxxx'
('pp' represents preprocessing).

Assume the following view template:

.? _form.rhtml
.--------------------
 <p>
  Name: <%= text_field :user, :name %>
 </p>
 <p>
  Name: {{*[%= pp_text_field :user, :name %]*}}
 </p>
.--------------------

Erubis preprocessor converts it to the following eRuby string:

.? preprocessed
.--------------------
 <p>
  Name: <%= text_field :user, :name %>
 </p>
 <p>
  Name: {{*<input id="stock_name" name="stock[name]" size="30" type="text" value="<%=h @stock.name%>" />*}}
 </p>
.--------------------

Erubis converts it to the following Ruby code:

.? Ruby code
.--------------------
 _buf << ' <p>
  Name: '; _buf << ( text_field :stock, :name ).to_s; _buf << '
'; _buf << ' </p>
 <p>
  Name: <input id="stock_name" name="stock[name]" size="30" type="text" value="'; _buf << (h @stock.name).to_s; _buf << '" />
 </p>
';
.--------------------

The above Ruby code shows that text_field() is called everytime when rendering,
but pp_text_field() is called only once when template is loaded.
This means that pp_text_field() with preprocessing makes view layer very fast.

Module Erubis::Helpers::RailsFormHelper defines the following form helper methods.

.*  pp_render_partial(basename)
.*  pp_form_tag(url_for_options={}, options={}, *parameters_for_url, &block)
.*  pp_text_field(object_name, method, options={})
.*  pp_password_field(object_name, method, options={})
.*  pp_hidden_field(object_name, method, options={})
.*  pp_file_field(object_name, method, options={})
.*  pp_text_area(object_name, method, options={})
.*  pp_check_box(object_name, method, options={}, checked_value="1", unchecked_value="0")
.*  pp_radio_button(object_name, method, tag_value, options={})
.*  pp_select(object, method, collection, options={}, html_options={})
.*  pp_collection_select(object, method, collection, value_method, text_method, options={}, html_options={})
.*  pp_country_select(object, method, priority_countries=nil, options={}, html_options={})
.*  pp_time_zone_select(object, method, priority_zones=nil, options={}, html_options={})
.*  pp_submit_tag(value="Save changes", options={})
.*  pp_image_submit_tag(source, options={})

Notice that pp_form_for() is not provided.

{{!CAUTION:!}} These are experimental and may not work in Ruby on Rails 2.0.


.$$ Others			| rails-others

.* ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available.

.* Form helper methods are not tested in Ruby on Rails 2.0.

.* ERB::Util.h() is redefined if you require 'erubis/helpers/rails_helper.rb'.
   Original definition of ERB::Util.h() is the following and it is slow
   because it scans string four times.
   
   .--------------------
    def html_escape(s)
      s.to_s.gsub(/&/, "&amp;").gsub(/\"/, "&quot;").gsub(/>/, "&gt;").gsub(/</, "&lt;")
    end
    alias h html_escape
   .--------------------
   
   New definition in 'erubis/helpers/rails_helper.rb' is faster than the above
   because it scans string only once.
   
   .--------------------
    ESCAPE_TABLE = { '&'=>'&amp;', '<'=>'&lt;', '>'=>'&gt;', '"'=>'&quot;', "'"=>'&#039;', }
    def h(value)
      value.to_s.gsub(/[&<>"]/) { |s| ESCAPE_TABLE[s] }
    end
   .--------------------
   
   Notice that the new definition may be slow if string contains
   many '< > & "' characters because block is call many time.
   You should use ERB::Util.html_hscape() if string contains a lot of '< > & "'
   characters.



.$ Other Topics	| topics


.$$ {{,Erubis::FastEruby,}} Class	| topics-fasteruby

{{,Erubis::FastEruby,}} class generates more effective code than {{,Erubis::Eruby,}}.

.? fasteruby-example.rb
.-------------------- fasteruby-example.rb
require 'erubis'
input = File.read('example.eruby')

puts "----- Erubis::Eruby -----"
print Erubis::Eruby.new(input).src

puts "----- Erubis::FastEruby -----"
print {{*Erubis::FastEruby*}}.new(input).src
.--------------------

.? result
.==================== fasteruby-example.result
$ ruby fasteruby-example.rb
----- Erubis::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
----- Erubis::FastEruby -----
_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
.====================

Technically, {{,Erubis::FastEruby,}} is just a subclass of {{,Erubis::Eruby,}} and includes {{,{{<InterpolationEnhancer|#interpolation-enhancer>}},}}. {{,Erubis::FastEruby,}} is faster than {{,Erubis::Eruby,}} but is not extensible compared to {{,Erubis::Eruby,}}. This is the reason why {{,Erubis::FastEruby,}} is not the default class of Erubis.


.$$ {{,:bufvar,}} Option	| topics-bufvar

Since 2.7.0, Erubis supports {{,:bufvar,}} option which allows you to change buffer variable name (default '{{,_buf,}}').

.? bufvar-example.rb
.-------------------- bufvar-example.rb
require 'erubis'
input = File.read('example.eruby')

puts "----- default -----"
eruby = Erubis::FastEruby.new(input)
puts eruby.src

puts "----- with :bufvar option -----"
eruby = Erubis::FastEruby.new(input, {{*:bufvar=>'@_out_buf'*}})
print eruby.src
.--------------------

.? result
.==================== bufvar-example.result
$ ruby bufvar-example.rb
----- default -----
_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
----- with :bufvar option -----
{{*@_out_buf*}} = ''; {{*@_out_buf*}} << %Q`<div>\n`
 for item in list 
 {{*@_out_buf*}} << %Q`  <p>#{ item }</p>
  <p>#{Erubis::XmlHelper.escape_xml( item )}</p>\n`
 end 
 {{*@_out_buf*}} << %Q`</div>\n`
{{*@_out_buf*}}.to_s
.====================


.$$ '<%= =%>' and '<%= -%>'	| topics-trimspaces

Since 2.6.0, '<%= -%>' remove tail spaces and newline.
This is for compatibiliy with ERB when trim mode is '-'.
'<%= =%>' also removes tail spaces and newlines, and this is
Erubis-original enhancement (cooler than '<%= -%>', isn't it?).

.? tailnewline.rhtml
.-------------------- tailnewline.rhtml.comment_filter
<div>
<%= @var -%>          # or <%= @var =%>
</div>
.--------------------

.? result (version 2.5.0):
.====================
$ erubis -c '{var: "AAA\n"}' tailnewline.rhtml
<div>
AAA

</div>
.====================

.? result (version 2.6.0):
.==================== tail_260.result
$ erubis -c '{var: "AAA\n"}' tailnewline.rhtml
<div>
AAA
</div>
.====================


.$$ '<%% %>' and '<%%= %>'	| topics-doublepercent

Since 2.6.0, '<%% %>' and '<%%= %>' are converted into '<% %>' and '<%= %>' respectively.
This is for compatibility with ERB.

.? doublepercent.rhtml:
.--------------------
<ul>
<%% for item in @list %>
  <li><%%= item %></li>
<%% end %>
</ul>
.--------------------

.? result:
.====================
$ erubis doublepercent.rhtml
<ul>
<% for item in @list %>
  <li><%= item %></li>
<% end %>
</ul>
.====================



.$$ evaluate(context) v.s. result(binding)	| topics-context-vs-binding

It is recommended to use 'Erubis::Eruby#evaluate(context)' instead of 'Erubis::Eruby#result(binding)' because Ruby's Binding object has some problems.

.* It is not able to specify variables to use.
   Using binding() method, all of local variables are passed to templates.
.* Changing local variables in templates may affect to varialbes in main program.
   If you assign '10' to local variable 'x' in templates, it may change variable 'x' in main program unintendedly.

The following example shows that assignment of some values into variable 'x' in templates affect to local variable 'x' in main program unintendedly.

.? template1.rhtml (intended to be passed 'items' from main program)
.-------------------- template1.rhtml
<% for {{*x*}} in {{*items*}} %>
item = <%= x %>
<% end %>
** debug: local variables=<%= local_variables().inspect() %>
.--------------------

.? main_program1.rb (intended to pass 'items' to template)
.-------------------- main_program1.rb
require 'erubis'
eruby = Erubis::Eruby.new(File.read('template1.rhtml'))
items = ['foo', 'bar', 'baz']
x = 1
## local variable 'x' and 'eruby' are passed to template as well as 'items'!
print {{*eruby.result(binding())*}}    
## local variable 'x' is changed unintendedly because it is changed in template!
puts "** debug: x=#{x.inspect}"  #=> "baz"
.--------------------

.? Result:
.==================== main_program1.result
$ ruby main_program1.rb
item = foo
item = bar
item = baz
** debug: local variables=["eruby", "items", "x", "_buf"]
** debug: x="baz"
.====================

This problem is caused because Ruby's Binding class is poor to use in template engine.
Binding class should support the following features.

.--------------------
b = Binding.new     # create empty Binding object
b['x'] = 1          # set local variables using binding object
.--------------------

But the above features are not implemented in Ruby.

A pragmatic solution is to use 'Erubis::Eruby#evaluate(context)' instead of 'Erubis::Eruby#result(binding)'.
'evaluate(context)' uses Erubis::Context object and instance variables instead of Binding object and local variables.

.? template2.rhtml (intended to be passed '@items' from main program)
.-------------------- template2.rhtml
<% for {{*x*}} in {{*@items*}} %>
item = <%= x %>
<% end %>
** debug: local variables=<%= local_variables().inspect() %>
.--------------------

.? main_program2.rb (intended to pass '@items' to template)
.-------------------- main_program2.rb
require 'erubis'
eruby = Erubis::Eruby.new(File.read('template2.rhtml'))
items = ['foo', 'bar', 'baz']
x = 1
## only 'items' are passed to template
print {{*eruby.evaluate(:items=>items)*}}    
## local variable 'x' is not changed!
puts "** debug: x=#{x.inspect}"  #=> 1
.--------------------

.? Result:
.==================== main_program2.result
$ ruby main_program2.rb
item = foo
item = bar
item = baz
** debug: local variables=["_context", "x", "_buf"]
** debug: x=1
.====================



.$$ Class Erubis::FastEruby	| topics-fasteruby

[experimental]

Erubis provides Erubis::FastEruby class which includes {{<InterpolationEnhancer|#interpolation-enhancer>}} and {{<works faster than Erubis::Eruby class|#topics-benchmark>}}.
If you desire more speed, try Erubis::FastEruby class.

.? File 'fasteruby.rhtml':
.-------------------- fasteruby.rhtml
<html>
  <body>
    <h1><%== @title %></h1>
    <table>
<% i = 0 %>
<% for item in @list %>
<%   i += 1 %>
      <tr>
        <td><%= i %></td>
        <td><%== item %></td>
      </tr>
<% end %>
    </table>
  </body>
</html>
.--------------------


.? File 'fasteruby.rb':
.-------------------- fasteruby.rb
require 'erubis'
input = File.read('fasteruby.rhtml')
eruby = {{*Erubis::FastEruby.new(input)*}}    # create Eruby object

puts "---------- script source ---"
puts eruby.src

puts "---------- result ----------"
context = { :title=>'Example', :list=>['aaa', 'bbb', 'ccc'] }
output = eruby.evaluate(context)
print output
.--------------------

.? output
.==================== fasteruby.result
$ ruby fasteruby.rb
---------- script source ---
_buf = ''; _buf << {{*%Q`*}}<html>
  <body>
    <h1>{{*#{Erubis::XmlHelper.escape_xml( @title )}*}}</h1>
    <table>\n{{*`*}}
 i = 0 
 for item in @list 
   i += 1 
 _buf << {{*%Q`*}}      <tr>
        <td>{{*#{ i }*}}</td>
        <td>{{*#{Erubis::XmlHelper.escape_xml( item )}*}}</td>
      </tr>\n{{*`*}}
 end 
 _buf << {{*%Q`*}}    </table>
  </body>
</html>\n{{*`*}}
_buf.to_s
---------- result ----------
<html>
  <body>
    <h1>Example</h1>
    <table>
      <tr>
        <td>1</td>
        <td>aaa</td>
      </tr>
      <tr>
        <td>2</td>
        <td>bbb</td>
      </tr>
      <tr>
        <td>3</td>
        <td>ccc</td>
      </tr>
    </table>
  </body>
</html>
.====================



.$$ Syntax Checking		| topics-syntax

Command-line option '-z' checks syntax. It is similar to 'erubis -x file.rhtml | ruby -wc', but it can take several file names.

.? example of command-line option '-z'
.====================
$ erubis {{*-z*}} app/views/*/*.rhtml
Syntax OK
.====================



.$$ File Caching		| topics-caching

Erubis::Eruby.load_file(filename) convert file into Ruby script and return Eruby object.
In addition, it caches converted Ruby script into cache file (filename + '.cache') if cache file is old or not exist.
If cache file exists and is newer than eruby file, Erubis::Eruby.load_file() loads cache file.

.? example of Erubis::Eruby.load_file()
.--------------------
require 'erubis'
filename = 'example.rhtml'
eruby = {{*Erubis::Eruby.load_file(filename)*}}
cachename = filename + '.cache'
if test(?f, cachename)
  puts "*** cache file '#{cachename}' created."
end
.--------------------

Since 2.6.0, it is able to specify cache filename.

.? specify cache filename.
.--------------------
filename = 'example.rhtml'
eruby = Erubis::Eruby.load_file(filename, :cachename=>filename+'.cache')
.--------------------

Caching makes Erubis about 40-50 percent faster than no-caching.
See {{<benchmark|#topics-benchmark>}} for details.



.$$ Erubis::TinyEruby class	| topics-tinyeruby

Erubis::TinyEruby class in 'erubis/tiny.rb' is the smallest implementation of eRuby.
If you don't need any enhancements of Erubis and only require simple eRuby implementation,
try Erubis::TinyEruby class.



.$$ NoTextEnhancer and NoCodeEnhancer in PHP	| topics-php

NoTextEnhancer and NoCodEnahncer are quite useful not only for eRuby but also for PHP.
The former "drops" HTML text and show up embedded Ruby/PHP code
and the latter drops embedded Ruby/PHP code and leave HTML text.

For example, see the following PHP script.

.? notext-example.php
.-------------------- notext-example.php
<html>
  <body>
    <h3>List</h3>
    <?php if (!$list || count($list) == 0) { ?>
    <p>not found.</p>
    <?php } else { ?>
    <table>
      <tbody>
        <?php $i = 0; ?>
        <?php foreach ($list as $item) { ?>
        <tr bgcolor="<?php echo ++$i % 2 == 1 ? '#FFCCCC' : '#CCCCFF'; ?>">
          <td><?php echo $item; ?></td>
        </tr>
        <?php } ?>
      </tbody>
    </table>
    <?php } ?>
  </body>
</html>
.--------------------

This is complex because PHP code and HTML document are mixed.
NoTextEnhancer can separate PHP code from HTML document.

.? example of using NoTextEnhancer with PHP file
.==================== notext-php.result
$ erubis -l php --pi=php -N -E NoText --trim=false notext-example.php
    1:  
    2:  
    3:  
    4:      <?php if (!$list || count($list) == 0) { ?>
    5:  
    6:      <?php } else { ?>
    7:  
    8:  
    9:          <?php $i = 0; ?>
   10:          <?php foreach ($list as $item) { ?>
   11:                       <?php echo ++$i % 2 == 1 ? '#FFCCCC' : '#CCCCFF'; ?>
   12:                <?php echo $item; ?>
   13:  
   14:          <?php } ?>
   15:  
   16:  
   17:      <?php } ?>
   18:  
   19:  
.====================

In the same way, NoCodeEnhancer can extract HTML tags.

.? example of using NoCodeEnhancer with PHP file
.==================== nocode-php.result
$ erubis -l php --pi=php -N -E NoCode --trim=false notext-example.php
    1:  <html>
    2:    <body>
    3:      <h3>List</h3>
    4:      
    5:      <p>not found.</p>
    6:      
    7:      <table>
    8:        <tbody>
    9:          
   10:          
   11:          <tr bgcolor="">
   12:            <td></td>
   13:          </tr>
   14:          
   15:        </tbody>
   16:      </table>
   17:      
   18:    </body>
   19:  </html>
.====================



.$$ Helper Class for mod_ruby		| topcs-modruby

Thanks Andrew R Jackson, he developed 'erubis-run.rb' which enables you to use Erubis with mod_ruby.

.1) Copy 'erubis-$Release$/contrib/erubis-run.rb' to the 'RUBYLIBDIR/apache' directory (for example '/usr/local/lib/ruby/1.8/apache') which contains 'ruby-run.rb', 'eruby-run.rb', and so on.
     .====================
     $ cd erubis-$Release$/
     $ sudo copy contrib/erubis-run.rb /usr/local/lib/ruby/1.8/apache/
     .====================
.2) Add the following example to your 'httpd.conf' (for example '/usr/local/apache2/conf/httpd.conf')
     .--------------------
     LoadModule ruby_module modules/mod_ruby.so
     <IfModule mod_ruby.c>
       RubyRequire apache/ruby-run
       RubyRequire apache/eruby-run
       RubyRequire apache/erubis-run
       <Location /erubis>
         SetHandler ruby-object
         RubyHandler Apache::ErubisRun.instance
       </Location>
       <Files *.rhtml>
         SetHandler ruby-object
         RubyHandler Apache::ErubisRun.instance
       </Files>
     </IfModule>
     .--------------------
.3) Restart Apache web server.
     .====================
     $ sudo /usr/local/apache2/bin/apachectl stop
     $ sudo /usr/local/apache2/bin/apachectl start
     .====================
.4) Create *.rhtml file, for example:
     .--------------------
     <html>
      <body>
       Now is <%= Time.now %>
       Erubis version is <%= Erubis::VERSION %>
      </body>
     </html>
     .--------------------
.5) Change mode of your directory to be writable by web server process.
     .====================
     $ cd /usr/local/apache2/htdocs/erubis
     $ sudo chgrp daemon .
     $ sudo chmod 775 .
     .====================
.6) Access the *.rhtml file and you'll get the web page.

You must set your directories to be writable by web server process, because
Apache::ErubisRun calls Erubis::Eruby.load_file() internally which creates cache files
in the same directory in which '*.rhtml' file exists.


.$$ Helper CGI Script for Apache	| topics-index-cgi

Erubis provides helper CGI script for Apache.
Using this script, it is very easy to publish *.rhtml files as *.html.

.====================
### install Erubis
$ tar xzf erubis-X.X.X.tar.gz
$ cd erubis-X.X.X/
$ ruby setup.py install
### copy files to ~/public_html
$ mkdir -p ~/public_html
$ cp public_html/_htaccess   ~/public_html/.htaccess
$ cp public_html/index.cgi   ~/public_html/
$ cp public_html/index.rhtml ~/public_html/
### add executable permission to index.cgi
$ chmod a+x ~/public_html/index.cgi
### edit .htaccess
$ vi ~/public_html/.htaccess
### (optional) edit index.cgi to configure
$ vi ~/public_html/index.cgi
.====================

Edit ~/public_html/.htaccess and modify user name.

.? ~/public_html/.htaccess
.--------------------
## enable mod_rewrie
RewriteEngine on
## deny access to *.rhtml and *.cache
#RewriteRule \.(rhtml|cache)$ - [R=404,L]
RewriteRule \.(rhtml|cache)$ - [F,L]
## rewrite only if requested file is not found
RewriteCond %{SCRIPT_FILENAME} !-f
## handle request to *.html and directories by index.cgi
RewriteRule (\.html|/|^)$ /~{{*username*}}/index.cgi
#RewriteRule (\.html|/|^)$ index.cgi
.--------------------

After these steps, *.rhtml will be published as *.html.
For example, if you access to {{,http://{{/host/}}.{{/domain/}}/~{{/username/}}/index.html,}} (or {{,http://{{/host/}}.{{/domain/}}/~{{/username/}}/,}}), file {{,~/public_html/index.rhtml,}} will be displayed.


.$$ Define method	| topics-defmethod

Erubis::Eruby#def_method() defines instance method or singleton method.

.-------------------- def_method.rb
require 'erubis'
s = "hello <%= name %>"
eruby = Erubis::Eruby.new(s)
filename = 'hello.rhtml'

## define instance method to Dummy class (or module)
class Dummy; end
{{*eruby.def_method(Dummy, 'render(name)', filename)*}}  # filename is optional
p Dummy.new.render('world')    #=> "hello world"

## define singleton method to dummy object
obj = Object.new
{{*eruby.def_method(obj, 'render(name)', filename)*}}    # filename is optional
p obj.render('world')          #=> "hello world"
.--------------------

.#+++
.==================== def_method.result
$ ruby def_method.rb
"hello world"
"hello world"
.====================
.#---


.$$ Benchmark		| topics-benchmark

A benchmark script is included in Erubis package at 'erubis-$Release$/benchark/' directory.
Here is an example result of benchmark.

.? MacOS X 10.4 Tiger, Intel CoreDuo 1.83GHz, Ruby1.8.6, eruby1.0.5, gcc4.0.1
.====================
$ cd erubis-$Release$/benchmark/
$ ruby bench.rb -n 10000 -m execute
*** ntimes=10000, testmode=execute
                                    user     system      total        real
eruby                          12.720000   0.240000  {{*12.960000*}} ( 12.971888)
ERB                            36.760000   0.350000  {{*37.110000*}} ( 37.112019)
ERB(cached)                    11.990000   0.440000  {{*12.430000*}} ( 12.430375)
Erubis::Eruby                  10.840000   0.300000  {{*11.140000*}} ( 11.144426)
Erubis::Eruby(cached)           7.540000   0.410000   {{*7.950000*}} (  7.969305)
Erubis::FastEruby              10.440000   0.300000  {{*10.740000*}} ( 10.737808)
Erubis::FastEruby(cached)       6.940000   0.410000   {{*7.350000*}} (  7.353666)
Erubis::TinyEruby               9.550000   0.290000   9.840000 (  9.851729)
Erubis::ArrayBufferEruby       11.010000   0.300000  11.310000 ( 11.314339)
Erubis::PrintOutEruby          11.640000   0.290000  11.930000 ( 11.942141)
Erubis::StdoutEruby            11.590000   0.300000  11.890000 ( 11.886512)
.#$ ruby erubybench.rb -n 10000 -m execute
.### execute
.#                                    user     system      total        real
.#eruby                          12.870000   0.290000  {{*13.160000*}} ( 14.020219)
.#ERB                            37.090000   0.460000  {{*37.550000*}} ( 39.639027)
.#Erubis::Eruby                  11.420000   0.330000  {{*11.750000*}} ( 12.385562)
.#Erubis::Eruby(cached)           7.580000   0.440000   {{*8.020000*}} (  8.536019)
.#Erubis::ArrayBufferEruby       11.550000   0.340000  11.890000 ( 12.597665)
.#Erubis::SimplifiedEruby        10.410000   0.320000  10.730000 ( 11.406730)
.#Erubis::StdoutEruby            12.170000   0.340000  12.510000 ( 13.252177)
.#Erubis::PrintOutEruby          12.070000   0.330000  12.400000 ( 13.142734)
.#Erubis::TinyEruby               9.710000   0.320000  10.030000 ( 10.771446)
.#Erubis::PI::Eruby              12.010000   0.340000  12.350000 ( 13.104801)
.====================

This shows that...
.* Erubis::Eruby runs more than 10 percent faster than eruby.
.* Erubis::Eruby runs about 3 times faster than ERB.
.* Caching (by Erubis::Eruby.load_file()) makes Erubis about 40-50 percent faster.
.* Erubis::FastEruby is a litte faster than Erubis::Eruby.
.* Array buffer (ArrayBufferEnhancer) is a little slower than string buffer (StringBufferEnhancer which Erubis::Eruby includes)
.* $stdout and print() make Erubis a little slower.
.* Erubis::TinyEruby (at 'erubis/tiny.rb') is the fastest in all eRuby implementations when no caching.

Escaping HTML characters (such as '< > & "') makes Erubis more faster than eruby and ERB,
because Erubis::XmlHelper#escape_xml() works faster than CGI.escapeHTML() and ERB::Util#h().
The following shows that Erubis runs more than 40 percent (when no-cached) or 90 percent (when cached) faster than eruby if HTML characters are escaped.

.? When escaping HTML characters with option '-e'
.====================
$ ruby bench.rb -n 10000 -m execute -ep
*** ntimes=10000, testmode=execute
                                    user     system      total        real
eruby                          21.700000   0.290000  {{*21.990000*}} ( 22.050687)
ERB                            45.140000   0.390000  {{*45.530000*}} ( 45.536976)
ERB(cached)                    20.340000   0.470000  {{*20.810000*}} ( 20.822653)
Erubis::Eruby                  14.830000   0.310000  {{*15.140000*}} ( 15.147930)
Erubis::Eruby(cached)          11.090000   0.420000  {{*11.510000*}} ( 11.514954)
Erubis::FastEruby              14.850000   0.310000  {{*15.160000*}} ( 15.172499)
Erubis::FastEruby(cached)      10.970000   0.430000  {{*11.400000*}} ( 11.399605)
Erubis::ArrayBufferEruby       14.970000   0.300000  15.270000 ( 15.281061)
Erubis::PrintOutEruby          15.780000   0.300000  16.080000 ( 16.088289)
Erubis::StdoutEruby            15.840000   0.310000  16.150000 ( 16.235338)
.#$ ruby erubybench.rb -n 10000 -m execute -e
.### execute
.#                                    user     system      total        real
.#eruby                          22.730000   0.350000  {{*23.080000*}} ( 24.815081)
.#ERB                            46.590000   0.520000  {{*47.110000*}} ( 50.360891)
.#Erubis::Eruby                  16.750000   0.360000  {{*17.110000*}} ( 18.253436)
.#Erubis::Eruby(cached)          12.540000   0.450000  {{*12.990000*}} ( 13.935044)
.#Erubis::ArrayBufferEruby       16.860000   0.370000  17.230000 ( 18.373771)
.#Erubis::SimplifiedEruby        15.750000   0.350000  16.100000 ( 17.344105)
.#Erubis::StdoutEruby            17.650000   0.360000  18.010000 ( 19.194326)
.#Erubis::PrintOutEruby          17.560000   0.360000  17.920000 ( 19.293728)
.#Erubis::TinyEruby              16.300000   0.350000  16.650000 ( 17.887278)
.#Erubis::PI::Eruby              17.210000   0.360000  17.570000 ( 18.836510)
.====================



.#.? Env: Linux FedoraCore4, Celeron 667MHz, Mem512MB, Ruby1.8.4, eruby1.0.5
.#.____________________
.#                                        user     system      total        real
.#ERuby                             131.990000   1.900000 133.890000 (135.061456)
.#ERB                               385.040000   3.180000 388.220000 (391.570653)
.#Erubis::Eruby                     127.750000   2.520000 130.270000 (131.385922)
.#Erubis::StringBufferEruby         167.610000   2.600000 170.210000 (171.712798)
.#.#Erubis::SimplifiedEruby         121.400000   2.210000 123.610000 (124.663233)
.#Erubis::StdoutEruby                92.790000   2.000000  94.790000 ( 95.532633)
.#.#Erubis::StdoutSimplifiedEruby    89.260000   2.190000  91.450000 ( 92.164058)
.#.#Erubis::PrintOutEruby            92.730000   1.940000  94.670000 ( 95.417965)
.#.#Erubis::PrintOutSimplifiedEruby  82.030000   2.190000  84.220000 ( 84.879534)
.#Erubis::TinyEruby                 118.720000   2.250000 120.970000 (122.022996)
.#Erubis::TinyStdoutEruby            87.130000   2.030000  89.160000 ( 89.879538)
.#.#Erubis::TinyPrintEruby           84.160000   1.940000  86.100000 ( 86.774579)
.#.____________________
.#.#____________________
.#.#                                        user     system      total        real
.#.#ERuby                             138.280000   1.900000 140.180000 (141.470426)
.#.#ERB                               402.220000   3.190000 405.410000 (408.886894)
.#.#Erubis::Eruby                     147.080000   2.400000 149.480000 (150.752255)
.#.#Erubis::StringBufferEruby         186.130000   2.600000 188.730000 (190.374098)
.#.#Erubis::SimplifiedEruby           130.100000   2.210000 132.310000 (133.426010)
.#.#Erubis::StdoutEruby               106.010000   2.130000 108.140000 (108.999193)
.#.#Erubis::StdoutSimplifiedEruby      97.130000   2.180000  99.310000 (100.104433)
.#.#.#Erubis::PrintOutEruby           109.900000   2.090000 111.990000 (112.854442)
.#.#.#Erubis::PrintOutSimplifiedEruby  93.120000   2.140000  95.260000 ( 96.002970)
.#.#Erubis::TinyEruby                 118.740000   2.360000 121.100000 (122.141380)
.#.#Erubis::TinyStdoutEruby            86.140000   1.840000  87.980000 ( 88.679196)
.#.#.#Erubis::TinyPrintEruby           86.540000   1.970000  88.510000 ( 89.208078)
.#.#.____________________
.#
.#.? Env: MacOS X 10.4, PowerPC 1.42GHz, Mem1.5GB, Ruby1.8.4, eruby1.0.5
.#.____________________
.#                                        user     system      total        real
.#ERuby                              55.040000   2.120000  57.160000 ( 89.311397)
.#ERB                               103.960000   3.480000 107.440000 (159.231792)
.#Erubis::Eruby                      36.130000   1.570000  37.700000 ( 52.188574)
.#Erubis::StringBufferEruby          47.270000   1.980000  49.250000 ( 73.867537)
.#.#Erubis::SimplifiedEruby            34.310000   1.600000  35.910000 ( 51.762841)
.#Erubis::StdoutEruby                26.240000   1.490000  27.730000 ( 41.840430)
.#.#Erubis::StdoutSimplifiedEruby      25.380000   1.340000  26.720000 ( 37.231918)
.#.#Erubis::PrintOutEruby              26.850000   1.260000  28.110000 ( 38.378227)
.#.#Erubis::PrintOutSimplifiedEruby    24.160000   1.280000  25.440000 ( 40.048199)
.#Erubis::TinyEruby                  31.690000   1.590000  33.280000 ( 49.862091)
.#Erubis::TinyStdoutEruby            22.550000   1.230000  23.780000 ( 33.316978)
.#.#Erubis::TinyPrintEruby             22.340000   1.150000  23.490000 ( 33.577150)
.#.____________________
.#
.#This shows that:
.#.* Erubis::Eruby is about 3 times faster than ERB.
.#.* Erubis::Eruby is about 3% faster than ERuby in linux or 1.5 times faster in Mac.
.#.#.* Erubis::SimplifiedEruby (which incudes SimplifiedEnhander) is faster than ERuby.
.#.* String buffer (StringBufferEnhancer) is slower than array buffer (ArrayBufferEnhancer which Erubis::Eruby includes)
.#.* Using $stdout is faster than array buffer and string buffer.
.#.* Erubis::TinyEruby (at 'erubis/tiny.rb') and it's subclasses are the fastest in all eRuby implementation.
.#


.$ Command Reference	| command



.$$ Usage		| command-usage

erubis [..options..] [{{/file/}} ...]



.$$ Options		| command-options

  .[ -h, --help    ]	Help.
  .[ -v            ]	Release version.
  .[ -x            ]	Show compiled source.
  .[ -X            ]	Show compiled source but only Ruby code.
			This is equivarent to '-E NoText'.
  .[ -N            ]	Numbering: add line numbers. (for '-x/-X')
  .[ -U            ]	Unique mode: zip empty lines into a line. (for '-x/-X')
  .[ -C            ]	Compact: remove empty lines. (for '-x/-X')
  .[ -b            ]	Body only: no preamble nor postamble. (for '-x/-X')
			This is equivarent to '--preamble=false --postamble=false'.
  .[ -z            ]	Syntax checking.
.#  .[ -T            ]	No trimming spaces around '<% %>'.
.#			This is equivarent to '--trim=false'.
  .[ -e            ]	Escape. This is equivarent to '-E Escape'.
  .[ -p pattern    ]	Embedded pattern (default '<% %>').
			This is equivarent to '--pattern={{/pattern/}}'.
  .[ -l lang       ]	Language name.
			This option makes erubis command to compile script but no execute.
.#  .[ -C class      ]	Class name (Eruby, XmlEruby, ...) to compile. (default Eruby).
  .[ -E enhacers   ]	Enhancer name (Escape, PercentLine, ...).
			It is able to specify several enhancer name separating with ','
			(ex. -f Escape,PercentLine,HeaderFooter).
  .[ -I path       ]	Require library path ($:).
			It is able to specify several paths separating with ','
			(ex. -f path1,path2,path3).
  .[ -K kanji      ]	Kanji code (euc, sjis, utf8, or none) (default none).
  .[ -f datafile   ]	Context data file in YAML format ('*.yaml', '*.yml') or
                        Ruby script ('*.rb').
			It is able to specify several filenames separating with ','
			(ex. -f file1,file2,file3).
  .[ -c context    ]	Context data string in YAML inline style or Ruby code.
.#  .[ -t            ]	Expand tab characters in YAML file.
  .[ -T            ]	Don't expand tab characters in YAML file.
  .[ -S            ]	Convert mapping key from string to symbol in YAML file.
  .[ -B		   ]	invoke Eruby#result() instead of Eruby#evaluate()
  .[ --pi[=name]   ]	parse '<?name ... ?>' instead of '<% ... %>'
  .[ --trim=false  ]	No trimming spaces around '<% %>'.



.$$ Properties	   	| command-props

Some Eruby classes can take optional properties to change it's compile option.
For example, property '--indent="  "' may change indentation of compiled source code.
Try 'erubis -h' for details.