erubis 2.4.0 → 2.4.1

data/doc-api/files/erubis/helper_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 89 $ $Release: 2.4.0 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 89 $ $Release: 2.4.1 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

data/doc-api/files/erubis/helpers/rails_helper_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 90 $ $Release: 2.4.0 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 90 $ $Release: 2.4.1 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

data/doc-api/files/erubis/local-setting_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 77 $ $Release: 2.4.0 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 77 $ $Release: 2.4.1 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

data/doc-api/files/erubis/main_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 91 $ $Release: 2.4.0 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 91 $ $Release: 2.4.1 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

data/doc-api/files/erubis/tiny_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 77 $ $Release: 2.4.0 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 77 $ $Release: 2.4.1 $ copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

data/doc-api/files/erubis_rb.html

@@ -70,7 +70,7 @@
 
     <div id="description">
       <p>
-$Rev: 59 $ 2.4.0 copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
+$Rev: 59 $ 2.4.1 copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 </p>
 
     </div>

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-07-19 13:13:21 +0900 (Thu, 19 Jul 2007) $<br>
+      last update: $Date: 2007-09-24 23:04:21 +0900 (Mon, 24 Sep 2007) $<br>
     </div>
 
-<p>release: 2.4.0
+<p>release: 2.4.1
 </p>
 <a name="preface"></a>
 <h2 class="section1">Preface</h2>
@@ -151,6 +151,8 @@ It has the following features.
   </li>
   <li><a href="#topics">Other Topics</a>
   <ul>
+    <li><a href="#topics-context-vs-binding">evaluate(context) v.s. result(binding)</a>
+    </li>
     <li><a href="#topics-fasteruby">Class Erubis::FastEruby</a>
     </li>
     <li><a href="#topics-syntax">Syntax Checking</a>
@@ -661,6 +663,9 @@ output</div>
   &lt;li&gt;ccc&lt;/li&gt;
 &lt;/ul&gt;
 </pre>
+<p>It is recommended to use 'Erubis::Eruby#evaluate(context)' rather than 'Erubis::Eruby#result(binding())' because the latter has some problems.
+See <a href="#topics-context-vs-binding">evaluate(context) v.s. result(binding)</a> section for details.
+</p>
 <br>
 
 
@@ -1817,24 +1822,30 @@ It deletes indentations even if they are in &lt;PRE&gt;&lt;/PRE&gt;.
 
 <a name="lang"></a>
 <h2 class="section1">Multi-Language Support</h2>
-<p>Erubis supports the following language currently:
+<p>Erubis supports the following languages<sup>(<a href="#fnref:2" name="fnlink:2">*2</a>)</sup>:
 </p>
 <ul type="disc">
 <li>Ruby
 </li>
-<li>PHP
+<li><a href="#lang-php">PHP</a>
 </li>
-<li>C
+<li><a href="#lang-c">C</a>
 </li>
-<li>Java
+<li><a href="#lang-java">Java</a>
 </li>
-<li>Scheme
+<li><a href="#lang-scheme">Scheme</a>
 </li>
-<li>Perl
+<li><a href="#lang-perl">Perl</a>
 </li>
-<li>JavaScript
+<li><a href="#lang-javascript">JavaScript</a>
 </li>
 </ul>
+<div class="footnote">
+ <dl compact>
+  <dt>(<a name="fnref:2" href="#fnlink:2">*2</a>)</dt>
+  <dd>If you need template engine in pure PHP/Perl/JavaScript, try <a href="http://www.kuwata-lab.com/tenjin/">Tenjin</a> (<a href="http://www.kuwata-lab.com/tenjin/">http://www.kuwata-lab.com/tenjin/</a>). Tenjin is a very fast and full-featured template engine implemented in pure PHP/Perl/JavaScript.</dd>
+ </dl>
+</div>
 <a name="lang-php"></a>
 <h3 class="section2">PHP</h3>
 <a name="example.ephp"></a>
@@ -2148,7 +2159,7 @@ compiled source code</div>
 </pre>
 <a name="example_scheme_display.result"></a>
 <div class="terminal_caption">
-compiled source code (with --func=display property)</div>
+compiled source code (with <code>--func=display</code> property)</div>
 <pre class="terminal">$ erubis -l scheme --func=display example.escheme
 (display "&lt;html&gt;
  &lt;body&gt;\n")
@@ -2285,6 +2296,19 @@ _buf.push("   &lt;/tbody&gt;\n\
 &lt;/html&gt;\n");
 document.write(_buf.join(""));
 </pre>
+<p>If command-line option '<code>--docwrite=false</code>' is specified,
+'<code>_buf.join("");</code>' is used instead of '<code>document.write(_buf.join(""));</code>'.
+This is useful when passing converted source code to eval() function in JavaScript.
+</p>
+<p>You can pass <code>:docwrite=&gt;false</code> to Erubis::Ejavascript.new() in your Ruby script.
+</p>
+<pre class="program">s = File.read('example.jshtml')
+engine = Erubis::Ejavascript.new(s, <code>:docwrite=&gt;false</code>)
+</pre>
+<p>If you want to specify any JavaScript code, use '--postamble=...'.
+</p>
+<p>Notice that default value of 'docwrite' property will be false in the future release.
+</p>
 <br>
 
 
@@ -2487,6 +2511,94 @@ because tag helpers generate different html code when form parameter has errors
 
 <a name="topics"></a>
 <h2 class="section1">Other Topics</h2>
+<a name="topics-context-vs-binding"></a>
+<h3 class="section2">evaluate(context) v.s. result(binding)</h3>
+<p>It is recommended to use 'Erubis::Eruby#evaluate(context)' instead of 'Erubis::Eruby#result(binding)' because Ruby's Binding object has some problems.
+</p>
+<ul type="disc">
+<li>It is not able to specify variables to use.
+   Using binding() method, all of local variables are passed to templates.
+</li>
+<li>Changing local variables in templates may affect to varialbes in main program.
+   If you assign '10' to local variable 'x' in templates, it may change variable 'x' in main program unintendedly.
+</li>
+</ul>
+<p>The following example shows that assignment of some values into variable 'x' in templates affect to local variable 'x' in main program unintendedly.
+</p>
+<a name="template1.rhtml"></a>
+<div class="program_caption">
+template1.rhtml (intended to be passed 'items' from main program)</div>
+<pre class="program">&lt;% for <strong>x</strong> in <strong>items</strong> %&gt;
+item = &lt;%= x %&gt;
+&lt;% end %&gt;
+** debug: local variables=&lt;%= local_variables().inspect() %&gt;
+</pre>
+<a name="main_program1.rb"></a>
+<div class="program_caption">
+main_program1.rb (intended to pass 'items' to template)</div>
+<pre class="program">require 'erubis'
+eruby = Erubis::Eruby.new(File.read('template1.rhtml'))
+items = ['foo', 'bar', 'baz']
+x = 1
+## local variable 'x' and 'eruby' are passed to template as well as 'items'!
+print <strong>eruby.result(binding())</strong>    
+## local variable 'x' is changed unintendedly because it is changed in template!
+puts "** debug: x=#{x.inspect}"  #=&gt; "baz"
+</pre>
+<a name="main_program1.result"></a>
+<div class="terminal_caption">
+Result:</div>
+<pre class="terminal">$ ruby main_program1.rb
+item = foo
+item = bar
+item = baz
+** debug: local variables=["eruby", "items", "x", "_buf"]
+** debug: x="baz"
+</pre>
+<p>This problem is caused because Ruby's Binding class is poor to use in template engine.
+Binding class should support the following features.
+</p>
+<pre class="program">b = Binding.new     # create empty Binding object
+b['x'] = 1          # set local variables using binding object
+</pre>
+<p>But the above features are not implemented in Ruby.
+</p>
+<p>A pragmatic solution is to use 'Erubis::Eruby#evaluate(context)' instead of 'Erubis::Eruby#result(binding)'.
+'evaluate(context)' uses Erubis::Context object and instance variables instead of Binding object and local variables.
+</p>
+<a name="template2.rhtml"></a>
+<div class="program_caption">
+template2.rhtml (intended to be passed '@items' from main program)</div>
+<pre class="program">&lt;% for <strong>x</strong> in <strong>@items</strong> %&gt;
+item = &lt;%= x %&gt;
+&lt;% end %&gt;
+** debug: local variables=&lt;%= local_variables().inspect() %&gt;
+</pre>
+<a name="main_program2.rb"></a>
+<div class="program_caption">
+main_program2.rb (intended to pass '@items' to template)</div>
+<pre class="program">require 'erubis'
+eruby = Erubis::Eruby.new(File.read('template2.rhtml'))
+items = ['foo', 'bar', 'baz']
+x = 1
+## only 'items' are passed to template
+print <strong>eruby.evaluate(:items=&gt;items)</strong>    
+## local variable 'x' is not changed!
+puts "** debug: x=#{x.inspect}"  #=&gt; 1
+</pre>
+<a name="main_program2.result"></a>
+<div class="terminal_caption">
+Result:</div>
+<pre class="terminal">$ ruby main_program2.rb
+item = foo
+item = bar
+item = baz
+** debug: local variables=["x", "_buf"]
+** debug: x=1
+</pre>
+<br>
+
+
 <a name="topics-fasteruby"></a>
 <h3 class="section2">Class Erubis::FastEruby</h3>
 <p>[experimental]
@@ -2708,8 +2820,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.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/
+<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/
 $ sudo copy contrib/erubis-run.rb /usr/local/lib/ruby/1.8/apache/
 </pre>
 </li>
@@ -2785,12 +2897,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.0/benchark/' directory.
+<p>A benchmark script is included in Erubis package at 'erubis-2.4.1/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.0/benchmark/
+<pre class="terminal">$ cd erubis-2.4.1/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.4.0
+## 2.4.1
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 
@@ -48,7 +48,7 @@
 
 
 module Erubis
-  VERSION = ('$Release: 2.4.0 $' =~ /([.\d]+)/) && $1
+  VERSION = ('$Release: 2.4.1 $' =~ /([.\d]+)/) && $1
 end
 
 require 'erubis/engine'

data/lib/erubis/context.rb

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

data/lib/erubis/converter.rb

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

data/lib/erubis/engine.rb

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

data/lib/erubis/engine/ec.rb

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

data/lib/erubis/engine/ejava.rb

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

data/lib/erubis/engine/ejavascript.rb

@@ -1,6 +1,6 @@
 ##
-## $Rev: 77 $
-## $Release: 2.4.0 $
+## $Rev: 95 $
+## $Release: 2.4.1 $
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 
@@ -18,6 +18,7 @@ module Erubis
       list = []
       #list << [:indent,   '',       "indent spaces (ex. '  ')"]
       #list << [:buf,      '_buf',   "output buffer name"]
+      list << [:docwrite, true,     "use 'document.write()' when true"]
       return list
     end
 
@@ -26,6 +27,7 @@ module Erubis
       @escapefunc ||= 'escape'
       @indent = properties[:indent] || ''
       @buf = properties[:out] || '_buf'
+      @docwrite = properties[:docwrite] != false  # '!= false' will be removed in the next release
     end
 
     def add_preamble(src)
@@ -76,7 +78,11 @@ module Erubis
 
     def add_postamble(src)
       src << "\n" if src[-1] == ?;
-      src << @indent << 'document.write(' << @buf << ".join(\"\"));\n"
+      if @docwrite
+        src << @indent << 'document.write(' << @buf << ".join(\"\"));\n"
+      else
+        src << @indent << @buf << ".join(\"\");\n"
+      end
     end
 
   end

data/lib/erubis/engine/enhanced.rb

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

data/lib/erubis/engine/eperl.rb

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

data/lib/erubis/engine/ephp.rb

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

data/lib/erubis/engine/eruby.rb

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

data/lib/erubis/engine/escheme.rb

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

data/lib/erubis/engine/optimized.rb

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

data/lib/erubis/enhancer.rb

@@ -1,6 +1,6 @@
 ##
-## $Rev: 77 $
-## $Release: 2.4.0 $
+## $Rev: 93 $
+## $Release: 2.4.1 $
 ## copyright(c) 2006-2007 kuwata-lab.com all rights reserved.
 ##
 
@@ -443,18 +443,33 @@ module Erubis
       "regard lines starting with '%' as program code"
     end
 
-    PERCENT_LINE_PATTERN = /(.*?)^\%(.*?\r?\n)/m
-
     def add_text(src, text)
-      text.scan(PERCENT_LINE_PATTERN) do |txt, line|
-        super(src, txt)
+      pos = 0
+      text2 = ''
+      text.scan(/^\%(.*?\r?\n)/) do
+        line  = $1
+        match = Regexp.last_match
+        len   = match.begin(0) - pos
+        str   = text[pos, len]
+        pos   = match.end(0)
+        if text2.empty?
+          text2 = str
+        else
+          text2 << str
+        end
         if line[0] == ?%
-          super(src, line)
+          text2 << line
         else
+          super(src, text2)
+          text2 = ''
           add_stmt(src, line)
         end
       end
-      rest = $' || text
+      rest = pos == 0 ? text : $'  # or $' || text
+      unless text2.empty?
+        text2 << rest if rest
+        rest = text2
+      end
       super(src, rest)
     end