erubis 2.6.6 → 2.7.0

data/doc/docstyle.css

@@ -27,7 +27,7 @@ pre {
 	white-space:pre;
 }
 
-.program {
+pre.program {
 	border-style:solid;
 	border-width:1px;
 	border-color:#6699FF;
@@ -38,7 +38,7 @@ pre {
 	word-break:break-all;
 }
 
-.terminal {
+pre.terminal {
 	border-style:solid;
 	border-width:1;
 	border-color:#999999;
@@ -49,7 +49,7 @@ pre {
 	word-break:break-all;
 }
 
-.output {
+pre.output {
 	border-style:solid;
 	border-width:1px;
 	border-color:#CCCCCC;
@@ -61,6 +61,12 @@ pre {
 }
 
 
+pre strong {
+	color: #990000;
+	font-weight: bold;
+}
+
+
 .program_caption {
         margin-top: 20px;
 }
@@ -168,7 +174,7 @@ h3, .subsection {
 	font-size:small;
 }
 
-.note {
+div.note, div.tips {
 	background-color:#FFFFDD;
 	border-style:solid;
 	border-width:0px 1px 0px 1px;
@@ -176,9 +182,14 @@ h3, .subsection {
 	color:#333300;
 	/* font-size:small; */
 	line-height:120%;
+	margin-top: 10px;
 	padding: 5px 20px 5px 20px;
 }
 
+div.note span.caption, div.tips span.caption {
+	color: #C60;
+}
+
 .figure {
 	/*
 	border-width:1px;
@@ -186,3 +197,13 @@ h3, .subsection {
 	white-space:pre;
 	*/
 }
+
+strong {
+	color: #630;
+	font-weight; bold;
+}
+
+
+em {
+	font-style: italic;
+}

data/doc/users-guide.html

@@ -13,12 +13,7 @@
    <div class="mainbody">
 
     <div align="left"><h1>Erubis Users' Guide</h1></div>
-    <div align="left">
-      release:     2.6.6<br>
-      last update: $Date$<br>
-    </div>
-
-<p>release: 2.6.6
+<p>release: 2.7.0
 </p>
 <a name="preface"></a>
 <h2 class="section1">Preface</h2>
@@ -117,6 +112,8 @@ Erubis now supports Ruby 1.9.
     </li>
     <li><a href="#percentline-enhancer">PercentLineEnhancer</a>
     </li>
+    <li><a href="#prefixedline-enhancer">PrefixedLineEnhancer</a>
+    </li>
     <li><a href="#headerfooter-enhancer">HeaderFooterEnhancer</a>
     </li>
     <li><a href="#interpolation-enhancer">InterpolationEnhancer</a>
@@ -131,6 +128,8 @@ Erubis now supports Ruby 1.9.
     </li>
     <li><a href="#lang-c">C</a>
     </li>
+    <li><a href="#lang-cpp">C++</a>
+    </li>
     <li><a href="#lang-java">Java</a>
     </li>
     <li><a href="#lang-scheme">Scheme</a>
@@ -155,9 +154,13 @@ Erubis now supports Ruby 1.9.
   </li>
   <li><a href="#topics">Other Topics</a>
   <ul>
-    <li><a href="#'&lt;%= =%&gt;' and '&lt;%= -%&gt;'">'&lt;%= =%&gt;' and '&lt;%= -%&gt;'</a>
+    <li><a href="#topics-fasteruby"><code>Erubis::FastEruby</code> Class</a>
+    </li>
+    <li><a href="#topics-bufvar"><code>:bufvar</code> Option</a>
+    </li>
+    <li><a href="#topics-trimspaces">'&lt;%= =%&gt;' and '&lt;%= -%&gt;'</a>
     </li>
-    <li><a href="#'&lt;%% %&gt;' and '&lt;%%= %&gt;'">'&lt;%% %&gt;' and '&lt;%%= %&gt;'</a>
+    <li><a href="#topics-doublepercent">'&lt;%% %&gt;' and '&lt;%%= %&gt;'</a>
     </li>
     <li><a href="#topics-context-vs-binding">evaluate(context) v.s. result(binding)</a>
     </li>
@@ -173,6 +176,8 @@ Erubis now supports Ruby 1.9.
     </li>
     <li><a href="#topcs-modruby">Helper Class for mod_ruby</a>
     </li>
+    <li><a href="#topics-index-cgi">Helper CGI Script for Apache</a>
+    </li>
     <li><a href="#topics-defmethod">Define method</a>
     </li>
     <li><a href="#topics-benchmark">Benchmark</a>
@@ -1638,19 +1643,23 @@ This is for compatibility with eruby and ERB.
 <a name="percentline-example.rhtml"></a>
 <div class="program_caption">
 percentline-example.rhtml</div>
-<pre class="program"><strong>% for item in list</strong>
-  &lt;b&gt;&lt;%= item %&gt;&lt;/b&gt;
+<pre class="program">&lt;ul&gt;
+<strong>% for item in list</strong>
+  &lt;li&gt;&lt;%= item %&gt;&lt;/li&gt;
 <strong>% end</strong>
-%% lines with '%%'
+&lt;/ul&gt;
+<strong>%% lines with '%%'</strong>
 </pre>
 <a name="percentline_example.result"></a>
 <div class="terminal_caption">
 compiled source code</div>
 <pre class="terminal">$ erubis -xE PercentLine percentline-example.rhtml
-_buf = ''; <strong>for item in list</strong>
- _buf &lt;&lt; '  &lt;b&gt;'; _buf &lt;&lt; ( item ).to_s; _buf &lt;&lt; '&lt;/b&gt;
+_buf = ''; _buf &lt;&lt; '&lt;ul&gt;
+'; <strong>for item in list</strong>
+ _buf &lt;&lt; '  &lt;li&gt;'; _buf &lt;&lt; ( item ).to_s; _buf &lt;&lt; '&lt;/li&gt;
 '; <strong>end</strong>
- _buf &lt;&lt; '% lines with \'%%\'
+ _buf &lt;&lt; '&lt;/ul&gt;
+<strong>% lines with \'%%\'</strong>
 ';
 _buf.to_s
 </pre>
@@ -1659,6 +1668,58 @@ _buf.to_s
 <br>
 
 
+<a name="prefixedline-enhancer"></a>
+<h3 class="section2">PrefixedLineEnhancer</h3>
+<p>PrefixedlineEnhancer regards lines starting with '%' as Ruby code.
+It is similar to <a href="#percentline-enhancer">PercentLineEnhancer</a>, but there are some differences.
+</p>
+<ul type="disc">
+<li>PrefixedlineEnhancer allows to indent lines starting with '%', but PercentLineEnhancer doesn't.
+</li>
+<li>PrefixedlineEnhancer allows to change prefixed character (default '%'), but PercentLineEnhancer doesn't.
+</li>
+</ul>
+<a name="prefixedline-example.rhtml"></a>
+<div class="program_caption">
+prefixedline-example.rhtml</div>
+<pre class="program">&lt;ul&gt;
+  <strong>! for item in list</strong>
+  &lt;li&gt;&lt;%= item %&gt;&lt;/li&gt;
+  <strong>! end</strong>
+&lt;/ul&gt;
+  <strong>!! lines with '!!'</strong>
+</pre>
+<a name="prefixedline-example.rb"></a>
+<div class="program_caption">
+prefixedline-example.rb</div>
+<pre class="program">require 'erubis'
+
+class PrefixedLineEruby &lt; Erubis::Eruby
+  include Erubis::PrefixedLineEnhancer
+end
+
+input = File.read('prefixedline-example.rhtml')
+eruby = PrefixedLineEruby.new(input, :prefixchar=&gt;'!')  # default '%'
+print eruby.src
+</pre>
+<a name="prefixedline_example.result"></a>
+<div class="terminal_caption">
+compiled source code</div>
+<pre class="terminal">$ ruby prefixedline-example.rb
+_buf = ''; _buf &lt;&lt; '&lt;ul&gt;
+';   <strong>for item in list</strong>
+ _buf &lt;&lt; '  &lt;li&gt;'; _buf &lt;&lt; ( item ).to_s; _buf &lt;&lt; '&lt;/li&gt;
+';   <strong>end</strong>
+ _buf &lt;&lt; '&lt;/ul&gt;
+  <strong>! lines with \'!!\'</strong>
+';
+_buf.to_s
+</pre>
+<p>PrefixedLineEnhancer is language-independent.
+</p>
+<br>
+
+
 <a name="headerfooter-enhancer"></a>
 <h3 class="section2">HeaderFooterEnhancer</h3>
 <p>[experimental]
@@ -1974,6 +2035,81 @@ fputs("   &lt;/tbody&gt;\n"
 <br>
 
 
+<a name="lang-cpp"></a>
+<h3 class="section2">C++</h3>
+<a name="example.ecpp"></a>
+<div class="program_caption">
+example.ecpp</div>
+<pre class="program"><strong>&lt;%
+#include &lt;string&gt;
+#include &lt;iostream&gt;
+#include &lt;sstream&gt;
+
+int main(int argc, char *argv[])
+{
+    std::stringstream _buf;
+%&gt;</strong>
+&lt;html&gt;
+ &lt;body&gt;
+  &lt;p&gt;Hello <strong>&lt;%= argv[0] %&gt;</strong>!&lt;/p&gt;
+  &lt;table&gt;
+   &lt;tbody&gt;
+    <strong>&lt;% for (int i = 1; i &lt; argc; i++) { %&gt;</strong>
+    &lt;tr bgcolor="<strong>&lt;%= i % 2 == 0 ? "#FFCCCC" : "#CCCCFF" %&gt;</strong>"&gt;
+      &lt;td&gt;<strong>&lt;%= i %&gt;</strong>&lt;/td&gt;
+      &lt;td&gt;<strong>&lt;%= argv[i] %&gt;</strong>&lt;/td&gt;
+    &lt;/tr&gt;
+    <strong>&lt;% } %&gt;</strong>
+   &lt;/tbody&gt;
+  &lt;/table&gt;
+ &lt;/body&gt;
+&lt;/html&gt;
+<strong>&lt;%
+    std::string output = _buf.str();
+    std::cout &lt;&lt; output;
+    return 0; 
+}
+%&gt;</strong>
+</pre>
+<a name="example_c.result"></a>
+<div class="terminal_caption">
+compiled source code</div>
+<pre class="terminal">$ erubis -l cpp example.ecpp
+#line 1 "example.ecpp"
+
+#include &lt;string&gt;
+#include &lt;iostream&gt;
+#include &lt;sstream&gt;
+
+int main(int argc, char *argv[])
+{
+    std::stringstream _buf;
+
+_buf &lt;&lt; "&lt;html&gt;\n"
+        " &lt;body&gt;\n"
+        "  &lt;p&gt;Hello "; _buf &lt;&lt; (argv[0]); _buf &lt;&lt; "!&lt;/p&gt;\n"
+        "  &lt;table&gt;\n"
+        "   &lt;tbody&gt;\n";
+     for (int i = 1; i &lt; argc; i++) { 
+_buf &lt;&lt; "    &lt;tr bgcolor=\""; _buf &lt;&lt; (i % 2 == 0 ? "#FFCCCC" : "#CCCCFF"); _buf &lt;&lt; "\"&gt;\n"
+        "      &lt;td&gt;"; _buf &lt;&lt; (i); _buf &lt;&lt; "&lt;/td&gt;\n"
+        "      &lt;td&gt;"; _buf &lt;&lt; (argv[i]); _buf &lt;&lt; "&lt;/td&gt;\n"
+        "    &lt;/tr&gt;\n";
+     } 
+_buf &lt;&lt; "   &lt;/tbody&gt;\n"
+        "  &lt;/table&gt;\n"
+        " &lt;/body&gt;\n"
+        "&lt;/html&gt;\n";
+
+    std::string output = _buf.str();
+    std::cout &lt;&lt; output;
+    return 0; 
+}
+
+</pre>
+<br>
+
+
 <a name="lang-java"></a>
 <h3 class="section2">Java</h3>
 <a name="Example.ejava"></a>
@@ -2206,7 +2342,7 @@ compiled source code (with <code>--func=display</code> property)</div>
 <h3 class="section2">Perl</h3>
 <a name="example.eperl"></a>
 <div class="program_caption">
-example.eprl</div>
+example.eperl</div>
 <pre class="program"><strong>&lt;%
    my $user = 'Erubis';
    my @list = ('&lt;aaa&gt;', 'b&amp;b', '"ccc"');
@@ -2326,6 +2462,8 @@ engine = Erubis::Ejavascript.new(s, <code>:docwrite=&gt;false</code>)
 
 <a name="rails"></a>
 <h2 class="section1">Ruby on Rails Support</h2>
+<p><span style="color:#FF0000">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.</span>
+</p>
 <p>Erubis supports Ruby on Rails. 
 This section describes how to use Erubis with Ruby on Rails.
 </p>
@@ -2613,7 +2751,92 @@ This means that pp_text_field() with preprocessing makes view layer very fast.
 
 <a name="topics"></a>
 <h2 class="section1">Other Topics</h2>
-<a name="'&lt;%= =%&gt;' and '&lt;%= -%&gt;'"></a>
+<a name="topics-fasteruby"></a>
+<h3 class="section2"><code>Erubis::FastEruby</code> Class</h3>
+<p><code>Erubis::FastEruby</code> class generates more effective code than <code>Erubis::Eruby</code>.
+</p>
+<a name="fasteruby-example.rb"></a>
+<div class="program_caption">
+fasteruby-example.rb</div>
+<pre class="program">require 'erubis'
+input = File.read('example.eruby')
+
+puts "----- Erubis::Eruby -----"
+print Erubis::Eruby.new(input).src
+
+puts "----- Erubis::FastEruby -----"
+print <strong>Erubis::FastEruby</strong>.new(input).src
+</pre>
+<a name="fasteruby-example.result"></a>
+<div class="terminal_caption">
+result</div>
+<pre class="terminal">$ ruby fasteruby-example.rb
+----- Erubis::Eruby -----
+_buf = ''; _buf &lt;&lt; '&lt;div&gt;
+'; for item in list 
+ _buf &lt;&lt; '  &lt;p&gt;'; <strong>_buf &lt;&lt; ( item ).to_s;</strong> _buf &lt;&lt; '&lt;/p&gt;
+  &lt;p&gt;'; <strong>_buf &lt;&lt; Erubis::XmlHelper.escape_xml( item );</strong> _buf &lt;&lt; '&lt;/p&gt;
+'; end 
+ _buf &lt;&lt; '&lt;/div&gt;
+';
+_buf.to_s
+----- Erubis::FastEruby -----
+_buf = ''; _buf &lt;&lt; %Q`&lt;div&gt;\n`
+ for item in list 
+ _buf &lt;&lt; %Q`  &lt;p&gt;<strong>#{ item }</strong>&lt;/p&gt;
+  &lt;p&gt;<strong>#{Erubis::XmlHelper.escape_xml( item )}</strong>&lt;/p&gt;\n`
+ end 
+ _buf &lt;&lt; %Q`&lt;/div&gt;\n`
+_buf.to_s
+</pre>
+<p>Technically, <code>Erubis::FastEruby</code> is just a subclass of <code>Erubis::Eruby</code> and includes <code><a href="#interpolation-enhancer">InterpolationEnhancer</a></code>. <code>Erubis::FastEruby</code> is faster than <code>Erubis::Eruby</code> but is not extensible compared to <code>Erubis::Eruby</code>. This is the reason why <code>Erubis::FastEruby</code> is not the default class of Erubis.
+</p>
+<br>
+
+
+<a name="topics-bufvar"></a>
+<h3 class="section2"><code>:bufvar</code> Option</h3>
+<p>Since 2.7.0, Erubis supports <code>:bufvar</code> option which allows you to change buffer variable name (default '<code>_buf</code>').
+</p>
+<a name="bufvar-example.rb"></a>
+<div class="program_caption">
+bufvar-example.rb</div>
+<pre class="program">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, <strong>:bufvar=&gt;'@_out_buf'</strong>)
+print eruby.src
+</pre>
+<a name="bufvar-example.result"></a>
+<div class="terminal_caption">
+result</div>
+<pre class="terminal">$ ruby bufvar-example.rb
+----- default -----
+_buf = ''; _buf &lt;&lt; %Q`&lt;div&gt;\n`
+ for item in list 
+ _buf &lt;&lt; %Q`  &lt;p&gt;#{ item }&lt;/p&gt;
+  &lt;p&gt;#{Erubis::XmlHelper.escape_xml( item )}&lt;/p&gt;\n`
+ end 
+ _buf &lt;&lt; %Q`&lt;/div&gt;\n`
+_buf.to_s
+----- with :bufvar option -----
+<strong>@_out_buf</strong> = ''; <strong>@_out_buf</strong> &lt;&lt; %Q`&lt;div&gt;\n`
+ for item in list 
+ <strong>@_out_buf</strong> &lt;&lt; %Q`  &lt;p&gt;#{ item }&lt;/p&gt;
+  &lt;p&gt;#{Erubis::XmlHelper.escape_xml( item )}&lt;/p&gt;\n`
+ end 
+ <strong>@_out_buf</strong> &lt;&lt; %Q`&lt;/div&gt;\n`
+<strong>@_out_buf</strong>.to_s
+</pre>
+<br>
+
+
+<a name="topics-trimspaces"></a>
 <h3 class="section2">'&lt;%= =%&gt;' and '&lt;%= -%&gt;'</h3>
 <p>Since 2.6.0, '&lt;%= -%&gt;' remove tail spaces and newline.
 This is for compatibiliy with ERB when trim mode is '-'.
@@ -2646,7 +2869,7 @@ AAA
 <br>
 
 
-<a name="'&lt;%% %&gt;' and '&lt;%%= %&gt;'"></a>
+<a name="topics-doublepercent"></a>
 <h3 class="section2">'&lt;%% %&gt;' and '&lt;%%= %&gt;'</h3>
 <p>Since 2.6.0, '&lt;%% %&gt;' and '&lt;%%= %&gt;' are converted into '&lt;% %&gt;' and '&lt;%= %&gt;' respectively.
 This is for compatibility with ERB.
@@ -2987,8 +3210,8 @@ example of using NoCodeEnhancer with PHP file</div>
 <p>Thanks Andrew R Jackson, he developed 'erubis-run.rb' which enables you to use Erubis with mod_ruby.
 </p>
 <ol type="1">
-<li>Copy 'erubis-2.6.6/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.
-<pre class="terminal">$ cd erubis-2.6.6/
+<li>Copy 'erubis-2.7.0/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.
+<pre class="terminal">$ cd erubis-2.7.0/
 $ sudo copy contrib/erubis-run.rb /usr/local/lib/ruby/1.8/apache/
 </pre>
 </li>
@@ -3039,6 +3262,48 @@ in the same directory in which '*.rhtml' file exists.
 <br>
 
 
+<a name="topics-index-cgi"></a>
+<h3 class="section2">Helper CGI Script for Apache</h3>
+<p>Erubis provides helper CGI script for Apache.
+Using this script, it is very easy to publish *.rhtml files as *.html.
+</p>
+<pre class="terminal">### 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
+</pre>
+<p>Edit ~/public_html/.htaccess and modify user name.
+</p>
+<div class="program_caption">
+~/public_html/.htaccess</div>
+<pre class="program">## 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|/|^)$ /~<strong>username</strong>/index.cgi
+#RewriteRule (\.html|/|^)$ index.cgi
+</pre>
+<p>After these steps, *.rhtml will be published as *.html.
+For example, if you access to <code>http://<em>host</em>.<em>domain</em>/~<em>username</em>/index.html</code> (or <code>http://<em>host</em>.<em>domain</em>/~<em>username</em>/</code>), file <code>~/public_html/index.rhtml</code> will be displayed.
+</p>
+<br>
+
+
 <a name="topics-defmethod"></a>
 <h3 class="section2">Define method</h3>
 <p>Erubis::Eruby#def_method() defines instance method or singleton method.
@@ -3064,12 +3329,12 @@ p obj.render('world')          #=&gt; "hello world"
 
 <a name="topics-benchmark"></a>
 <h3 class="section2">Benchmark</h3>
-<p>A benchmark script is included in Erubis package at 'erubis-2.6.6/benchark/' directory.
+<p>A benchmark script is included in Erubis package at 'erubis-2.7.0/benchark/' directory.
 Here is an example result of benchmark.
 </p>
 <div class="terminal_caption">
 MacOS X 10.4 Tiger, Intel CoreDuo 1.83GHz, Ruby1.8.6, eruby1.0.5, gcc4.0.1</div>
-<pre class="terminal">$ cd erubis-2.6.6/benchmark/
+<pre class="terminal">$ cd erubis-2.7.0/benchmark/
 $ ruby bench.rb -n 10000 -m execute
 *** ntimes=10000, testmode=execute
                                     user     system      total        real