erubis 2.4.1 → 2.5.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-09-24 23:04:21 +0900 (Mon, 24 Sep 2007) $<br>
+      last update: $Date: 2008-01-30 23:27:58 +0900 (Wed, 30 Jan 2008) $<br>
     </div>
 
-<p>release: 2.4.1
+<p>release: 2.5.0
 </p>
 <a name="preface"></a>
 <h2 class="section1">Preface</h2>
@@ -145,6 +145,8 @@ It has the following features.
     </li>
     <li><a href="#rails-preprocessing">Preprosessing</a>
     </li>
+    <li><a href="#rails-formhelpers">Form Helpers for Preprocessing</a>
+    </li>
     <li><a href="#rails-others">Others</a>
     </li>
   </ul>
@@ -2322,71 +2324,55 @@ 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'.
+<p>Add the following code to your 'config/environment.rb' and restart web server.
+This replaces ERB in Rails by Erubis entirely.
+</p>
 <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
+#Erubis::Helpers::RailsHelper.show_src = nil
+#Erubis::Helpers::RailsHelper.preprocessing = false
 </pre>
-<p>    This will replace ERB in Rails by Erubis entirely.
+<p>Options:
 </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.
+<dl class="dl2">
+<dt class="dt2">
+Erubis::Helpers::RailsHelper.engine_class (=Erubis::Eruby)</dt>
+<dd class="dd2">
+<p>	Erubis engine class (default Erubis::Eruby).
 </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.
+</dd>
+<dt class="dt2">
+Erubis::Helpers::RailsHelper.init_properties (={})</dt>
+<dd class="dd2">
+<p>	Optional arguments for Erubis::Eruby#initialize() method (default {}).
 </p>
-</li>
-<li>Restart web server.
-<pre class="terminal">$ ruby script/server
-</pre>
-</li>
-</ol>
-<p>The setting is above all.
+</dd>
+<dt class="dt2">
+Erubis::Helpers::RailsHelper.show_src (=nil)</dt>
+<dd class="dd2">
+<p>	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.
+</p>
+</dd>
+<dt class="dt2">
+Erubis::Helpers::RailsHelper.preprocessing (=false)</dt>
+<dd class="dd2">
+<p>	Enable preprocessing if true (default false).
 </p>
+</dd>
+</dl>
 <br>
 
 
 <a name="rails-preprocessing"></a>
 <h3 class="section2">Preprosessing</h3>
-<p><strong>(Experimental)</strong>
-Erubis supports preprocessing of template files.
+<p>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>
@@ -2463,6 +2449,118 @@ because tag helpers generate different html code when form parameter has errors
    Preprocessing is not available with these methods.
 </li>
 </ul>
+<p>In Ruby on Rails 2.0, <code>_?('user_id')</code> is OK but <code>_?('user.id')</code> is NG
+because the latter contains period ('.') character.
+</p>
+<pre class="program">&lt;!-- NG in Rails 2.0, because _?('') contains period --&gt;
+[%= link_to 'Edit', edit_user_path(<strong>_?('@user.id')</strong>) %]
+[%= link_to 'Show', <strong>@user</strong> %]
+[%= link_to 'Delete', <strong>@user</strong>, :confirm=&gt;'OK?', :method=&gt;:delete %]
+
+&lt;!-- OK in Rails 2.0 --&gt;
+<strong>&lt;%= user_id = @user.id %&gt;</strong>
+[%= link_to 'Edit', edit_user_path(<strong>_?('user_id')</strong>) %]
+[%= link_to 'Show', <strong>:action=&gt;'show', :id=&gt;_?('user_id')</strong> %]
+[%= link_to 'Delete', <strong>{:action=&gt;'destroy', :id=&gt;_?('user_id')}</strong>,
+                      {:confirm=&gt;'OK?', :method=&gt;:delete} %]
+</pre>
+<br>
+
+
+<a name="rails-formhelpers"></a>
+<h3 class="section2">Form Helpers for Preprocessing</h3>
+<p><strong>(Experimental)</strong>
+</p>
+<p>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'
+</p>
+<div class="program_caption">
+app/helpers/xxx_helper.rb</div>
+<pre class="program">require 'erubis/helpers/rails_form_helper'
+module ApplicationHelper
+  include Erubis::Helpers::RailsFormHelper
+end
+</pre>
+<p>Form helper methods defined in Erubis::Helpers::RailsFormHelper are named as 'pp_xxxx'
+('pp' represents preprocessing).
+</p>
+<p>Assume the following view template:
+</p>
+<div class="program_caption">
+_form.rhtml</div>
+<pre class="program"> &lt;p&gt;
+  Name: &lt;%= text_field :user, :name %&gt;
+ &lt;/p&gt;
+ &lt;p&gt;
+  Name: <strong>[%= pp_text_field :user, :name %]</strong>
+ &lt;/p&gt;
+</pre>
+<p>Erubis preprocessor converts it to the following eRuby string:
+</p>
+<div class="program_caption">
+preprocessed</div>
+<pre class="program"> &lt;p&gt;
+  Name: &lt;%= text_field :user, :name %&gt;
+ &lt;/p&gt;
+ &lt;p&gt;
+  Name: <strong>&lt;input id="stock_name" name="stock[name]" size="30" type="text" value="&lt;%=h @stock.name%&gt;" /&gt;</strong>
+ &lt;/p&gt;
+</pre>
+<p>Erubis converts it to the following Ruby code:
+</p>
+<div class="program_caption">
+Ruby code</div>
+<pre class="program"> _buf &lt;&lt; ' &lt;p&gt;
+  Name: '; _buf &lt;&lt; ( text_field :stock, :name ).to_s; _buf &lt;&lt; '
+'; _buf &lt;&lt; ' &lt;/p&gt;
+ &lt;p&gt;
+  Name: &lt;input id="stock_name" name="stock[name]" size="30" type="text" value="'; _buf &lt;&lt; (h @stock.name).to_s; _buf &lt;&lt; '" /&gt;
+ &lt;/p&gt;
+';
+</pre>
+<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.
+</p>
+<p>Module Erubis::Helpers::RailsFormHelper defines the following form helper methods.
+</p>
+<ul type="disc">
+<li>pp_render_partial(basename)
+</li>
+<li>pp_form_tag(url_for_options={}, options={}, *parameters_for_url, &amp;block)
+</li>
+<li>pp_text_field(object_name, method, options={})
+</li>
+<li>pp_password_field(object_name, method, options={})
+</li>
+<li>pp_hidden_field(object_name, method, options={})
+</li>
+<li>pp_file_field(object_name, method, options={})
+</li>
+<li>pp_text_area(object_name, method, options={})
+</li>
+<li>pp_check_box(object_name, method, options={}, checked_value="1", unchecked_value="0")
+</li>
+<li>pp_radio_button(object_name, method, tag_value, options={})
+</li>
+<li>pp_select(object, method, collection, options={}, html_options={})
+</li>
+<li>pp_collection_select(object, method, collection, value_method, text_method, options={}, html_options={})
+</li>
+<li>pp_country_select(object, method, priority_countries=nil, options={}, html_options={})
+</li>
+<li>pp_time_zone_select(object, method, priority_zones=nil, options={}, html_options={})
+</li>
+<li>pp_submit_tag(value="Save changes", options={})
+</li>
+<li>pp_image_submit_tag(source, options={})
+</li>
+</ul>
+<p>Notice that pp_form_for() is not provided.
+</p>
+<p><span style="color:#FF0000">CAUTION:</span> These are experimental and may not work in Ruby on Rails 2.0.
+</p>
 <br>
 
 
@@ -2473,12 +2571,9 @@ because tag helpers generate different html code when form parameter has errors
 </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>Form helper methods are not tested in Ruby on Rails 2.0.
 </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
@@ -2488,8 +2583,6 @@ because tag helpers generate different html code when form parameter has errors
  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>
@@ -2503,6 +2596,8 @@ because tag helpers generate different html code when form parameter has errors
    You should use ERB::Util.html_hscape() if string contains a lot of '&lt; &gt; &amp; "'
    characters.
 </p>
+</li>
+</ul>
 <br>
 
 
@@ -2820,8 +2915,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.4.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.4.1/
+<li>Copy 'erubis-2.5.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.5.0/
 $ sudo copy contrib/erubis-run.rb /usr/local/lib/ruby/1.8/apache/
 </pre>
 </li>
@@ -2897,12 +2992,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.4.1/benchark/' directory.
+<p>A benchmark script is included in Erubis package at 'erubis-2.5.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.4.1/benchmark/
+<pre class="terminal">$ cd erubis-2.5.0/benchmark/
 $ ruby bench.rb -n 10000 -m execute
 *** ntimes=10000, testmode=execute
                                     user     system      total        real

data/lib/erubis.rb

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

data/lib/erubis/context.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 

data/lib/erubis/converter.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 89 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'abstract'

data/lib/erubis/engine.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 

data/lib/erubis/engine/ec.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/ejava.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/ejavascript.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 95 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/enhanced.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/enhancer'

data/lib/erubis/engine/eperl.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/ephp.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/eruby.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/escheme.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##
 
 require 'erubis/engine'

data/lib/erubis/engine/optimized.rb

@@ -1,7 +1,7 @@
 ##
 ## $Rev: 77 $
-## $Release: 2.4.1 $
-## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+## $Release: 2.5.0 $
+## copyright(c) 2006-2008 kuwata-lab.com all rights reserved.
 ##