erubis 2.3.1 → 2.4.0

data/doc/users-guide.html

@@ -14,10 +14,10 @@
 
     <div align="left"><h1>Erubis Users' Guide</h1></div>
     <div align="left">
-      last update: $Date: 2007-05-26 13:29:48 +0900 (Sat, 26 May 2007) $<br>
+      last update: $Date: 2007-07-19 13:13:21 +0900 (Thu, 19 Jul 2007) $<br>
     </div>
 
-<p>release: 2.3.1
+<p>release: 2.4.0
 </p>
 <a name="preface"></a>
 <h2 class="section1">Preface</h2>
@@ -25,29 +25,29 @@
 It has the following features.
 </p>
 <ul type="disc">
-<li><a href="#topics-benchmark">Very fast</a>, almost three times faster than ERB and about ten percent faster than eruby (implemented in C)
+<li>Very fast, almost three times faster than ERB and about ten percent faster than eruby (implemented in C)
 </li>
-<li><a href="#topics-caching">File caching of converted Ruby script support</a>
+<li>File caching of converted Ruby script support
 </li>
-<li><a href="#tut-escape">Auto escaping support</a>
+<li>Auto escaping support
 </li>
-<li><a href="#tut-trim">Auto trimming spaces around '&lt;% %&gt;'</a>
+<li>Auto trimming spaces around '&lt;% %&gt;'
 </li>
-<li><a href="#tut-pattern">Embedded pattern changeable</a> (default '&lt;% %&gt;')
+<li>Embedded pattern changeable (default '&lt;% %&gt;')
 </li>
-<li><a href="#tut-pi">Enable to handle Processing Instructions (PI) as embedded pattern</a> (ex. '&lt;?rb ... ?&gt;')
+<li>Enable to handle Processing Instructions (PI) as embedded pattern (ex. '&lt;?rb ... ?&gt;')
 </li>
-<li><a href="#lang">Multi-language support</a> (Ruby/PHP/C/Java/Scheme/Perl/Javascript)
+<li>Multi-language support (Ruby/PHP/C/Java/Scheme/Perl/Javascript)
 </li>
-<li><a href="#tut-context">Context object available</a> and <a href="#tut-datafile">easy to combine eRuby template with YAML datafile</a>
+<li>Context object available and easy to combine eRuby template with YAML datafile
 </li>
-<li><a href="#printenabled-enhancer">Print statement available</a>
+<li>Print statement available
 </li>
-<li><a href="#enhancer">Easy to expand and customize in subclass</a>
+<li>Easy to expand and customize in subclass
 </li>
-<li><a href="#topics-rails">Ruby on Rails support</a>
+<li><a href="#rails">Ruby on Rails support</a>
 </li>
-<li><a href="#topcs-modruby">mod_ruby support</a>
+<li>mod_ruby support|#topcs-modruby
 </li>
 </ul>
 <p>Erubis is implemented in pure Ruby.  It requires Ruby 1.8 or higher.
@@ -139,6 +139,16 @@ It has the following features.
     </li>
   </ul>
   </li>
+  <li><a href="#rails">Ruby on Rails Support</a>
+  <ul>
+    <li><a href="#rails-settings">Settings</a>
+    </li>
+    <li><a href="#rails-preprocessing">Preprosessing</a>
+    </li>
+    <li><a href="#rails-others">Others</a>
+    </li>
+  </ul>
+  </li>
   <li><a href="#topics">Other Topics</a>
   <ul>
     <li><a href="#topics-fasteruby">Class Erubis::FastEruby</a>
@@ -149,12 +159,12 @@ It has the following features.
     </li>
     <li><a href="#topics-tinyeruby">Erubis::TinyEruby class</a>
     </li>
-    <li><a href="#topics-rails">Ruby on Rails Support</a>
-    </li>
     <li><a href="#topics-php">NoTextEnhancer and NoCodeEnhancer in PHP</a>
     </li>
     <li><a href="#topcs-modruby">Helper Class for mod_ruby</a>
     </li>
+    <li><a href="#topics-defmethod">Define method</a>
+    </li>
     <li><a href="#topics-benchmark">Benchmark</a>
     </li>
   </ul>
@@ -2281,6 +2291,200 @@ document.write(_buf.join(""));
 <br>
 
 
+<a name="rails"></a>
+<h2 class="section1">Ruby on Rails Support</h2>
+<p>Erubis supports Ruby on Rails. 
+This section describes how to use Erubis with Ruby on Rails.
+</p>
+<a name="rails-settings"></a>
+<h3 class="section2">Settings</h3>
+<ol type="1">
+<li>Add the following code to your 'config/environment.rb'.
+<div class="program_caption">
+config/environment.rb</div>
+<pre class="program">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 = false
+#Erubis::Helpers::RailsHelper.preprocessing = true
+</pre>
+<p>    This will replace ERB in Rails by Erubis entirely.
+</p>
+</li>
+<li>(Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'.
+<div class="program_caption">
+action_view_base_rb.patch</div>
+<pre class="program">--- 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] ||= {}
+</pre>
+<p>    This patch is included in erubis_2.X.X/contrib directory and the following is an
+    example to apply this patch.
+</p>
+<div class="terminal_caption">
+how to apply patch:</div>
+<pre class="terminal">$ cd /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.13.1/lib/action_view/
+$ sudo patch -p1 &lt; /tmp/erubis_2.X.X/contrib/action_view_base_rb.patch
+</pre>
+<p>    Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended.
+</p>
+</li>
+<li>Restart web server.
+<pre class="terminal">$ ruby script/server
+</pre>
+</li>
+</ol>
+<p>The setting is above all.
+</p>
+<br>
+
+
+<a name="rails-preprocessing"></a>
+<h3 class="section2">Preprosessing</h3>
+<p><strong>(Experimental)</strong>
+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.
+</p>
+<p>For example, assume the following template.
+This is slow because link_to() method is called every time when template is rendered.
+</p>
+<pre class="program">&lt;%= link_to 'Create', :action=&gt;'create' %&gt;
+</pre>
+<p>The following is faster than the above, but not flexible because url is fixed.
+</p>
+<pre class="program">&lt;a href="/users/create"&gt;Create&lt;/a&gt;
+</pre>
+<p>Preprocessing solves this problem.
+If you use '[%= %]' instead of '&lt;%= %&gt;', preprocessor evaluate it only once when template is loaded.
+</p>
+<pre class="program"><strong>[%= link_to 'Create', :action=&gt;'create'%]</strong>
+</pre>
+<p>The above is evaluated by preprocessor and replaced to the following code automatically.
+</p>
+<pre class="program">&lt;a href="/users/create"&gt;Create&lt;/a&gt;
+</pre>
+<p>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.
+</p>
+<p>If link_to() method have variable arguments, use <code>_?()</code> helper method.
+</p>
+<pre class="program">&lt;% for user in @users %&gt;
+[%= link_to <strong>_?('user.name')</strong>, :action=&gt;'show', :id=&gt;<strong>_?('user.id')</strong> %]
+&lt;% end %&gt;
+</pre>
+<p>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.
+</p>
+<pre class="program">&lt;% for user in @users %&gt;
+&lt;a href="/users/show/<strong>&lt;%=user.id%&gt;</strong>"&gt;<strong>&lt;%=user.name%&gt;</strong>&lt;/a&gt;
+&lt;% end %&gt;
+</pre>
+<p>Preprocessing statement (<code>[% %]</code>) is also available as well as preprocessing expression (<code>[%= %]</code>).
+</p>
+<pre class="program">&lt;select name="state"&gt;
+  &lt;option value=""&gt;-&lt;/option&gt;
+<strong>[% for code in states.keys.sort %]</strong>
+  &lt;option value="<strong>[%= code %]</strong>"&gt;<strong>[%= states[code] %]</strong>&lt;/option&gt;
+<strong>[% end %]</strong>
+&lt;/select&gt;
+</pre>
+<p>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.
+</p>
+<pre class="program">&lt;select name="state"&gt;
+  &lt;option value=""&gt;-&lt;/option&gt;
+  &lt;option value="AK"&gt;Alaska&lt;/option&gt;
+  &lt;option value="AL"&gt;Alabama&lt;/option&gt;
+  &lt;option value="AR"&gt;Arkansas&lt;/option&gt;
+  &lt;option value="AS"&gt;American Samoa&lt;/option&gt;
+  &lt;option value="AZ"&gt;Arizona&lt;/option&gt;
+  &lt;option value="CA"&gt;California&lt;/option&gt;
+  &lt;option value="CO"&gt;Colorado&lt;/option&gt;
+   ....
+&lt;/select&gt;
+</pre>
+<p>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.
+</p>
+<p>Helper methods of Ruby on Rails are divided into two groups.
+</p>
+<ul type="disc">
+<li>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.
+</li>
+<li>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.
+</li>
+</ul>
+<br>
+
+
+<a name="rails-others"></a>
+<h3 class="section2">Others</h3>
+<ul type="disc">
+<li>ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available.
+</li>
+</ul>
+<ul type="disc">
+<li>If Erubis::Helper::Rails.show_src is ture, Erubis prints converted Ruby code into log file (ex. 'log/development.log').
+</li>
+</ul>
+<p>If it is nil (default), Erubis prints converted Ruby code into log file only when development mode.
+   It is useful for debugging.
+</p>
+<ul type="disc">
+<li>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.
+<pre class="program"> def html_escape(s)
+   s.to_s.gsub(/&amp;/, "&amp;amp;").gsub(/\"/, "&amp;quot;").gsub(/&gt;/, "&amp;gt;").gsub(/&lt;/, "&amp;lt;")
+ end
+ alias h html_escape
+</pre>
+</li>
+</ul>
+<p>   New definition in 'erubis/helpers/rails_helper.rb' is faster than the above
+   because it scans string only once.
+</p>
+<pre class="program"> ESCAPE_TABLE = { '&amp;'=&gt;'&amp;amp;', '&lt;'=&gt;'&amp;lt;', '&gt;'=&gt;'&amp;gt;', '"'=&gt;'&amp;quot;', "'"=&gt;'&amp;#039;', }
+ def h(value)
+   value.to_s.gsub(/[&amp;&lt;&gt;"]/) { |s| ESCAPE_TABLE[s] }
+ end
+</pre>
+<p>   Notice that the new definition may be slow if string contains
+   many '&lt; &gt; &amp; "' characters because block is call many time.
+   You should use ERB::Util.html_hscape() if string contains a lot of '&lt; &gt; &amp; "'
+   characters.
+</p>
+<br>
+
+
+<br>
+
+
 <a name="topics"></a>
 <h2 class="section1">Other Topics</h2>
 <a name="topics-fasteruby"></a>
@@ -2412,73 +2616,6 @@ try Erubis::TinyEruby class.
 <br>
 
 
-<a name="topics-rails"></a>
-<h3 class="section2">Ruby on Rails Support</h3>
-<p>Erubis supports Ruby on Rails. 
-</p>
-<ol type="1">
-<li>Add the following code to your 'config/environment.rb'.
-<div class="program_caption">
-config/environment.rb</div>
-<pre class="program">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 = false
-</pre>
-<p>    This will replace ERB in Rails by Erubis entirely.
-</p>
-</li>
-<li>(Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'.
-<div class="program_caption">
-action_view_base_rb.patch</div>
-<pre class="program">--- 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] ||= {}
-</pre>
-<p>    This patch is included in erubis_2.X.X/contrib directory and the following is an
-    example to apply this patch.
-</p>
-<div class="terminal_caption">
-how to apply patch:</div>
-<pre class="terminal">$ cd /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.13.1/lib/action_view/
-$ sudo patch -p1 &lt; /tmp/erubis_2.X.X/contrib/action_view_base_rb.patch
-</pre>
-<p>    Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended.
-</p>
-</li>
-<li>Restart web server.
-<pre class="terminal">$ ruby script/server
-</pre>
-</li>
-</ol>
-<p>ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available.
-</p>
-<p>If Erubis::Helper::Rails.show_src is ture, Erubis prints converted Ruby code into log file (ex. 'log/development.log').
-It is useful for debugging.
-</p>
-<br>
-
-
 <a name="topics-php"></a>
 <h3 class="section2">NoTextEnhancer and NoCodeEnhancer in PHP</h3>
 <p>NoTextEnhancer and NoCodEnahncer are quite useful not only for eRuby but also for PHP.
@@ -2571,8 +2708,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.3.1/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.3.1/
+<li>Copy 'erubis-2.4.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.4.0/
 $ sudo copy contrib/erubis-run.rb /usr/local/lib/ruby/1.8/apache/
 </pre>
 </li>
@@ -2618,19 +2755,42 @@ $ sudo chmod 775 .
 </ol>
 <p>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 as '*.rhtml' file.
+in the same directory in which '*.rhtml' file exists.
 </p>
 <br>
 
 
+<a name="topics-defmethod"></a>
+<h3 class="section2">Define method</h3>
+<p>Erubis::Eruby#def_method() defines instance method or singleton method.
+</p>
+<a name="def_method.rb"></a>
+<pre class="program">require 'erubis'
+s = "hello &lt;%= name %&gt;"
+eruby = Erubis::Eruby.new(s)
+filename = 'hello.rhtml'
+
+## define instance method to Dummy class (or module)
+class Dummy; end
+<strong>eruby.def_method(Dummy, 'render(name)', filename)</strong>  # filename is optional
+p Dummy.new.render('world')    #=&gt; "hello world"
+
+## define singleton method to dummy object
+obj = Object.new
+<strong>eruby.def_method(obj, 'render(name)', filename)</strong>    # filename is optional
+p obj.render('world')          #=&gt; "hello world"
+</pre>
+<br>
+
+
 <a name="topics-benchmark"></a>
 <h3 class="section2">Benchmark</h3>
-<p>A benchmark script is included in Erubis package at 'erubis-2.3.1/benchark/' directory.
+<p>A benchmark script is included in Erubis package at 'erubis-2.4.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.3.1/benchmark/
+<pre class="terminal">$ cd erubis-2.4.0/benchmark/
 $ ruby bench.rb -n 10000 -m execute
 *** ntimes=10000, testmode=execute
                                     user     system      total        real

data/lib/erubis.rb

@@ -1,6 +1,6 @@
 ##
 ## $Rev: 59 $
-## 2.3.1
+## 2.4.0
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 
@@ -48,7 +48,7 @@
 
 
 module Erubis
-  VERSION = ('$Release: 2.3.1 $' =~ /([.\d]+)/) && $1
+  VERSION = ('$Release: 2.4.0 $' =~ /([.\d]+)/) && $1
 end
 
 require 'erubis/engine'

data/lib/erubis/context.rb

@@ -1,6 +1,6 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.3.1 $
+## $Release: 2.4.0 $
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 

data/lib/erubis/converter.rb

@@ -1,6 +1,6 @@
 ##
-## $Rev: 77 $
-## $Release: 2.3.1 $
+## $Rev: 89 $
+## $Release: 2.4.0 $
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 
@@ -36,6 +36,7 @@ module Erubis
       @preamble.nil? ? add_preamble(codebuf) : (@preamble && (codebuf << @preamble))
       convert_input(codebuf, input)
       @postamble.nil? ? add_postamble(codebuf) : (@postamble && (codebuf << @postamble))
+      @_proc = nil    # clear cached proc object
       return codebuf  # or codebuf.join()
     end