path: root/doc/users-guide.txt

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



.$ Preface		| preface*

Erubis is an implementation of eRuby.
It has the following features.
.* Very fast, almost three times faster than ERB and even faster than eruby (implemented in C)
.* 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

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



.$$ 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
## eruby = Erubis::Eruby.new
## input = File.read('example1.eruby')
## src = eruby.convert(input)
## eval src
.--------------------

.? output
.====================
$ ruby example1.rb
.<<<:! (cd guide.d; ruby example1.rb)
.====================

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

.? example of command-line option '-x'
.====================
$ erubis {{*-x*}} example1.eruby
.<<<:! (cd guide.d; erubis -x example1.eruby)
.====================



.$$ Trimming Spaces	| tut-trim

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

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

.? compiled source code
.====================
$ erubis -x example2.eruby
.<<<:! (ruby -pi.bak -e 'sub! /\s*\#.*$/, ""' guide.d/example2.eruby; erubis -x guide.d/example2.eruby)
.====================

If you want leave spaces around '<% %>', add command-line option '-T'.

.? compiled source code with command-line option '-T'
.====================
$ erubis -x {{*-T*}} example2.eruby
.<<<:! erubis -x -T guide.d/example2.eruby
.====================

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
.====================
$ ruby example2.rb
.<<<:! (cd guide.d; ruby example2.rb)
.#--- script source ---
.#_buf = ''; _buf << "<ul>\n"
.#{{*_buf << "  ";*}}  for item in list {{*; _buf << "\n"*}}
.#_buf << "  <li>\n"
.#_buf << "    "; _buf << ( item ).to_s; _buf << "\n"
.#_buf << "  </li>\n"
.#{{*_buf << "  ";*}}  end {{*; _buf << "\n"*}}
.#_buf << "</ul>\n"
.#_buf
.#--- result ---
.#<ul>
.#  
.#  <li>
.#    aaa
.#  </li>
.#  
.#  <li>
.#    bbb
.#  </li>
.#  
.#  <li>
.#    ccc
.#  </li>
.#  
.#</ul>
.====================



.$$ Escape		| tut-escape

Erubis have 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
.====================
$ ruby example3.rb 2> stderr.log
.<<<:! (cd guide.d; ruby example3.rb  2> stderr.log)  | ruby -pe 'sub! /_buf << [E(].*?;|\$stderr.*?;/, "{{*\\&*}}"'
.#--- script source ---
.#_buf = ''; _buf << "<ul>\n"
.#   for item in list 
.#_buf << "  <li>"; {{*_buf << Erubis::XmlEruby.escape( item )*}}; _buf << "</li>\n"
.#_buf << "  <li>"; _buf << ( item ).to_s; _buf << "</li>\n"
.#_buf << "  <li>"; {{*$stderr.puts("** erubis: item = #{(item).inspect}")*}}; _buf << "</li>\n"
.#_buf << "\n"
.#   end 
.#_buf << "</ul>\n"
.#_buf
.#--- result ---
.#<ul>
.#  <li>{{*&lt;aaa&gt;*}}</li>
.#  <li><aaa></li>
.#  <li></li>
.#
.#  <li>{{*b&amp;b*}}</li>
.#  <li>b&b</li>
.#  <li></li>
.#
.#  <li>{{*&quot;ccc&quot;*}}</li>
.#  <li>"ccc"</li>
.#  <li></li>
.#
.#</ul>
$ cat stderr.log
.<<<: guide.d/stderr.log
.#** erubis: item = "<aaa>"
.#** erubis: item = "b&b"
.#** erubis: 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'.)}}

.====================
$ erubis -l ruby {{*-e*}} example3.eruby
.<<<:! (cd guide.d; erubis -e -l ruby example3.eruby)
.====================

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'
.====================
$ erubis -x {{*-p '<!--% %-->'*}} example4.eruby
.<<<:! erubis -x -p '<!--% %-->' guide.d/example4.eruby
.====================

.? 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
.====================
$ ruby example4.rb
.<<<:! (cd guide.d; ruby example4.rb)
.====================

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 isntance 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
.====================
$ ruby example5.rb
.<<<:! (cd guide.d; ruby example5.rb)
.====================

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 variable when Eruby::binding() is called, or instance variable 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)
  if _binding.is_a?(Hash)
    # load hash data as local variable
    _h = _binding
    eval _h.keys.inject("") {|s,k| s << "#{k} = _h[#{k.inspect}];"}
    _binding = binding()
  end
  return {{*eval(@src, _binding)*}}
end

def evaluate(context)
  if context.is_a?(Hash)
    # convert hash object to Context object
    hash = context
    context = Erubis::Context.new
    hash.each { |key, val| context[key] = val }
  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
.====================
$ ruby example6.rb
.<<<:! (cd guide.d; ruby example6.rb)
.====================



.$$ Context Data File	| tut-datafile

It is very useful to import YAML document data into Hash context object.

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

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

.? 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'
.====================
$ erubis {{*-f example7.yaml*}} example7.eruby
.<<<:! (cd guide.d; erubis -f example7.yaml example7.eruby)
.====================

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)'.



.$$ Preamble and Postamble   | tut-preamble

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

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

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

compiled source code with and without command-line option '-b'
.====================
## without '-b'
$ erubis -x example8.eruby
.<<<:! erubis -x guide.d/example8.eruby | ruby -pe 'sub! /^_buf.*?(;|$)/, "{{*\\&*}}"'

## with '-b'
$ erubis -x {{*-b*}} example8.eruby
.<<<:! erubis -x -b guide.d/example8.eruby
.====================

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

.? example8.rb
.-------------------- example8.rb
require 'erubis'
input = File.read('example8.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
.====================
$ ruby example8.rb
.<<<:! (cd guide.d; ruby example8.rb)
.====================

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

.? example9.xhtml
.-------------------- example9.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 ... ?>
.+--------------------
	mapping of '-l' option and PI name

.? output
.====================
$ erubis {{*--pi*}} example9.xhtml
.<<<:! (cd guide.d; erubis --pi example9.xhtml)
.====================

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

{{*(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>
.--------------------



.$ 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. This is included in Erubis::Eruby by default.
.: {{<StringBufferEnhancer|#stringbuffer-enhancer>}} (only for Eruby)
	Use string buffer. It is a little slower than ArrayBufferEnhancer.
.: {{<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.


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

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

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

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
.====================
$ ruby printenabled-example.rb
.<<<:! (cd guide.d; ruby printenabled-example.rb)
.====================

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

ArrayEnhancer is only for Eruby.



.$$ ArrayBufferEnhancer	| arraybuffer-enhancer

Arraybufferenhancer makes Eruby to use array buffer.
Array buffer is a litte faster than String buffer.
Erubis::Eruby includes this enhancer by default.

ArrayBufferEnhancer is only for Eruby.



.$$ StringBufferEnhancer | stringbuffer-enhancer

StringBufferEnhancer makes Eruby to use string buffer.

.#.? 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)
.#.====================

.====================
$ erubis -xE StringBuffer example.eruby
.<<<:! erubis -xE StringBuffer guide.d/example.eruby | ruby -pe 'sub!(/^_buf( = ..;)?/,"{{*\\&*}}")'
.====================



StringBufferEnhancer 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
.====================
$ erubis -TxE NoText notext-example.eruby
.<<<:! (cd guide.d; erubis -TxE NoText notext-example.eruby)
.====================

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 NoTextEnhancer
.====================
$ erubis -TxE NoCode notext-example.eruby
.<<<:! (cd guide.d; erubis -TxE NoCode nocode-example.eruby)
.====================

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
.====================
$ erubis -xE Simplify example.euby
.<<<:! erubis -xE Simplify guide.d/example.eruby
.====================

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

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
{{*% for item in list*}}
  <b><%= item %></b>
{{*% end*}}
%% 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
.====================
$ erubis -xE PercentLine percentline-example.rhtml
.<<<:! erubis -xE PercentLine guide.d/percentline-example.rhtml | ruby -pe 'sub! /for.*?list|end/, "{{*\\&*}}"'
.====================

PercentLineEnhancer 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
.====================
$ erubis -xE HeaderFooter headerfooter-example.eruby
.<<<:! erubis -xE HeaderFooter guide.d/headerfooter-example.eruby | ruby -pe 'sub! /^(def|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
.====================
$ erubis -x normal-eruby-test.eruby
.<<<:! erubis -x guide.d/normal-eruby-test.eruby | ruby -pe 'sub! /^(def|end).*$/, "{{*\\&*}}"'
.====================

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
.====================
$ erubis -xE HeaderFooter headerfooter-example2.rhtml
.<<<:! erubis -xE HeaderFooter guide.d/headerfooter-example2.rhtml | ruby -pe 'sub! /^(def|end).*$/, "{{*\\&*}}"'
.====================

HeaderFooterEnhancer is experimental and is language-independent.



.$ Multi-Language	| lang

Erubis supports the following language currently:

.* Ruby
.* PHP
.* C
.* Java
.* Scheme
.* Perl
.* 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
.====================
$ erubis -l php example.ephp
.<<<:! (cd guide.d; erubis -l php example.ephp)
.====================



.$$ 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
.====================
$ erubis -l c example.ec
.<<<:! (cd guide.d; erubis -l c example.ec)
.====================



.$$ 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
.====================
$ erubis -b -l java example.ejava
.<<<:! (cd guide.d; erubis -l java example.ejava)
.====================



.$$ 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
.====================
$ erubis -l scheme example.escheme
.<<<:! (cd guide.d; erubis -l scheme example.escheme)
.====================

.? compiled source code (with --func=display property)
.====================
$ erubis -l scheme --func=display example.escheme
.<<<:! (cd guide.d; erubis -l scheme --func=display example.escheme)
.====================



.$$ Perl	| lang-perl

.? example.eprl
.-------------------- 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
.====================
$ erubis -l perl example.eperl
.<<<:! (cd guide.d; erubis -l perl example.eperl)
.====================



.$$ 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
.====================
$ erubis -l js example.ejs
.<<<:! (cd guide.d; erubis -l js example.ejs)
.====================



.$ Other Topics	| topics



.$$ TinyEruby class	| topics-tinyeruby

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 TinyEruby class.


.$$ Ruby on Rails Support	| topics-rails

Erubis supports Ruby on Rails.
Add the following code to your 'app/controllers/application.rb'.

.? app/controllers/application.rb
.--------------------
require 'erubis/helper/rails'
suffix = 'erubis' 
ActionView::Base.register_template_handler(suffix, Erubis::Helper::RailsTemplate)
#Erubis::Helper::RailsTemplate.engine_class = Erubis::EscapedEruby ## or Erubis::PI::Eruby
#Erubis::Helper::RailsTemplate.default_properties = { :escape=>true, :escapefunc=>'h' }
.--------------------

If you specify Erubis::Helper::CachedRailsTemplate class instead of Erubis::Helper::RailsTemplate class, template string is cached in memory (but template is not reloaded when it is modified).

You may got the followign error:
.--------------------
(eval):10:in `render': no block given
.--------------------

It is because layout file scaffold created contains 'yield' method.
Use '@content_for_layout' instead 'yield'.

.? app/views/layouts/xxx.erubis
.--------------------
  ...
  <%{{*#*}}= yield %>
  {{*<%= @content_for_layout %>*}}
  ...
.--------------------



.$$ 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
.====================
$ erubis -T -l php -E NoText -p '<\?php \?>' notext-example.php | cat -n
.<<<:! erubis -T -l php -E NoText -p '<\?php \?>' guide.d/notext-example.php | cat -n
.====================

In the same way, NoCodeEnhancer can extract HTML tags.

.? example of using NoCodeEnhancer with PHP file
.====================
$ erubis -T -l php -E NoCode -p '<\?php \?>' notext-example.php | cat -n
.<<<:! erubis -T -l php -E NoCode -p '<\?php \?>' guide.d/notext-example.php | cat -n
.====================



.$$ Command {{,notext,}}  | topics-notext

Command 'notext' removes text part from eRuby script and leaves only embedded Ruby code.
This is very useful when debugging eRuby script.
 

.? notext-ex.rhtml
--------------------
<html>
 <body>
  <table>
<% @list.each_with_index do |item, i| %>
<%   klass = i % 2 == 0 ? 'odd' : 'even' %>
   <tr class="<%= klass %>">
    <td><%== item %></td>
   </tr>
<% end %>
  </table>
 </body>
</html>
--------------------
 
.? command line example
====================
$ notext notext-ex.rhtml
_buf = [];


 @list.each_with_index do |item, i| ;
   klass = i % 2 == 0 ? 'odd' : 'even' ;
               _buf << ( klass ).to_s;
         _buf << Erubis::XmlHelper.escape_xml( item );

 end ;


_buf.join
.====================

Command-line option '-u' deletes continuous empty lines to one empty line.

.? command-line example
.====================
$ notext {{*-u*}} notext-ex.rhtml
_buf = [];

 @list.each_with_index do |item, i| ;
   klass = i % 2 == 0 ? 'odd' : 'even' ;
               _buf << ( klass ).to_s;
         _buf << Erubis::XmlHelper.escape_xml( item );

 end ;

_buf.join
.====================

Command-line option '-c' deletes all empty lines.

.? command-line example
.====================
$ notext {{*-c*}} notext-ex.rhtml
_buf = [];
 @list.each_with_index do |item, i| ;
   klass = i % 2 == 0 ? 'odd' : 'even' ;
               _buf << ( klass ).to_s;
         _buf << Erubis::XmlHelper.escape_xml( item );
 end ;
_buf.join
.====================

Command-line option '-n' shows line numbers. It can work with '-c' or '-u'.

.====================
$ notext {{*-nu*}} example2.rhtml
  1: _buf = [];

  4:  @list.each_with_index do |item, i| ;
  5:    klass = i % 2 == 0 ? 'odd' : 'even' ;
  6:                _buf << ( klass ).to_s;
  7:          _buf << Erubis::XmlHelper.escape_xml( item );

  9:  end ;

 13: _buf.join
$ notext {{*-nc*}} example2.rhtml
  1: _buf = [];
  4:  @list.each_with_index do |item, i| ;
  5:    klass = i % 2 == 0 ? 'odd' : 'even' ;
  6:                _buf << ( klass ).to_s;
  7:          _buf << Erubis::XmlHelper.escape_xml( item );
  9:  end ;
 13: _buf.join
====================

Command 'notext' supports '-l {{/lang/}}' options. For example, command-line option '-l php' retrieves embedded PHP code from PHP file.



.$$ Benchmark		| topics-benchmark

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

.? 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.
  .[ -T            ]	No trimming spaces around '<% %>'.
			This is equivarent to '--trim=false'.
  .[ -b            ]	Body only (no preamble nor postamble).
			This is equivarent to '--preamble=false --postamble=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 file.yaml  ]	YAML file for context values (read stdin if filename is '-').
			It is able to specify several filenames separating with ','
			(ex. -f file1,file2,file3).
  .[ -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()



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