From a383bfd0df0007acb79b0928f33bcf7a91df79c9 Mon Sep 17 00:00:00 2001 From: makoto kuwata Date: Mon, 21 Mar 2011 11:26:35 +0900 Subject: [update] 'doc/users-guide.{txt,html}' --- doc/users-guide.html | 220 +++++++++++++++++++++++++++++++++++++++++++++++---- doc/users-guide.txt | 200 +++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 393 insertions(+), 27 deletions(-) diff --git a/doc/users-guide.html b/doc/users-guide.html index 56213d2..82aaf31 100644 --- a/doc/users-guide.html +++ b/doc/users-guide.html @@ -13,11 +13,6 @@

Erubis Users' Guide

-
- release: $Release$
- last update: $Date$
-
-

release: $Release$

@@ -117,6 +112,8 @@ Erubis now supports Ruby 1.9.
  • PercentLineEnhancer
    • +
  • PrefixedLineEnhancer +
  • HeaderFooterEnhancer
  • InterpolationEnhancer @@ -155,9 +152,13 @@ Erubis now supports Ruby 1.9.
  • Other Topics
      -
    • '<%= =%>' and '<%= -%>' +
    • Erubis::FastEruby Class +
      • +
    • :bufname Option
      • -
    • '<%% %>' and '<%%= %>' +
    • '<%= =%>' and '<%= -%>' +
      • +
    • '<%% %>' and '<%%= %>'
    • evaluate(context) v.s. result(binding)
      • @@ -173,6 +174,8 @@ Erubis now supports Ruby 1.9.
    • Helper Class for mod_ruby
      • +
    • Helper CGI Script for Apache +
    • Define method
    • Benchmark @@ -1638,19 +1641,23 @@ This is for compatibility with eruby and ERB.
      percentline-example.rhtml
      -
      % for item in list
-  <b><%= item %></b>
+
      <ul>
+% for item in list
+  <li><%= item %></li>
 % end
-%% lines with '%%'
+</ul>
+%% lines with '%%'
 
      
 
 
      
 compiled source code
      
 
      $ erubis -xE PercentLine percentline-example.rhtml
-_buf = ''; for item in list
- _buf << '  <b>'; _buf << ( item ).to_s; _buf << '</b>
+_buf = ''; _buf << '<ul>
+'; for item in list
+ _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
 '; end
- _buf << '% lines with \'%%\'
+ _buf << '</ul>
+% lines with \'%%\'
 ';
 _buf.to_s
 
      
@@ -1659,6 +1666,58 @@ _buf.to_s
 
      
 
 
+
+
      PrefixedLineEnhancer
      
+
      PrefixedlineEnhancer regards lines starting with '%' as Ruby code.
+It is similar to PercentLineEnhancer, but there are some differences.
+
      
+
        
+
      • PrefixedlineEnhancer allows to indent lines starting with '%', but PercentLineEnhancer doesn't.
+
        • 
+
      • PrefixedlineEnhancer allows to change prefixed character (default '%'), but PercentLineEnhancer doesn't.
+
        • 
+
      
+
+
      
+prefixedline-example.rhtml
      
+
      <ul>
+  ! for item in list
+  <li><%= item %></li>
+  ! end
+</ul>
+  !! lines with '!!'
+
      
+
+
      
+prefixedline-example.rb
      
+
      require 'erubis'
+
+class PrefixedLineEruby < Erubis::Eruby
+  include Erubis::PrefixedLineEnhancer
+end
+
+input = File.read('prefixedline-example.rhtml')
+eruby = PrefixedLineEruby.new(input, :prefixchar=>'!')  # default '%'
+print eruby.src
+
      
+
+
      
+compiled source code
      
+
      $ ruby prefixedline-example.rb
+_buf = ''; _buf << '<ul>
+';   for item in list
+ _buf << '  <li>'; _buf << ( item ).to_s; _buf << '</li>
+';   end
+ _buf << '</ul>
+  ! lines with \'!!\'
+';
+_buf.to_s
+
      
+
      PrefixedLineEnhancer is language-independent.
+
      
+
      
+
+
 
 
      HeaderFooterEnhancer
      
 
      [experimental]
@@ -2206,7 +2265,7 @@ compiled source code (with --func=display property)

    • Perl

    -example.eprl
    +example.eperl 
    <%
    my $user = 'Erubis';
    my @list = ('<aaa>', 'b&b', '"ccc"');
@@ -2326,6 +2385,8 @@ engine = Erubis::Ejavascript.new(s, :docwrite=>false)
 
 
 
    Ruby on Rails Support
    
+
    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.
+
    
 
    Erubis supports Ruby on Rails. 
 This section describes how to use Erubis with Ruby on Rails.
 
    
@@ -2613,7 +2674,92 @@ This means that pp_text_field() with preprocessing makes view layer very fast.
 
 
 
    Other Topics
    
-
+
+
    Erubis::FastEruby Class
    
+
    Erubis::FastEruby class generates more effective code than Erubis::Eruby.
+
    
+
+
    
+fasteruby-example.rb
    
+
    require 'erubis'
+input = File.read('example.eruby')
+
+puts "----- Erubis::Eruby -----"
+print Erubis::Eruby.new(input).src
+
+puts "----- Erubis::FastEruby -----"
+print Erubis::FastEruby.new(input).src
+
    
+
+
    
+result
    
+
    $ ruby fasteruby-example.rb
+----- Erubis::Eruby -----
+_buf = ''; _buf << '<div>
+'; for item in list 
+ _buf << '  <p>'; _buf << ( item ).to_s; _buf << '</p>
+  <p>'; _buf << Erubis::XmlHelper.escape_xml( item ); _buf << '</p>
+'; end 
+ _buf << '</div>
+';
+_buf.to_s
+----- Erubis::FastEruby -----
+_buf = ''; _buf << %Q`<div>\n`
+ for item in list 
+ _buf << %Q`  <p>#{ item }</p>
+  <p>#{Erubis::XmlHelper.escape_xml( item )}</p>\n`
+ end 
+ _buf << %Q`</div>\n`
+_buf.to_s
+
    
+
    Technically, Erubis::FastEruby is just a subclass of Erubis::Eruby and includes InterpolationEnhancer. Erubis::FastEruby is faster than Erubis::Eruby but is not extensible compared to Erubis::Eruby. This is the reason why Erubis::FastEruby is not the default class of Erubis.
+
    
+
    
+
+
+
+
    :bufname Option
    
+
    Since 2.7.0, Erubis supports :bufname option which allows you to change buffer variable name (default '_buf').
+
    
+
+
    
+bufname-example.rb
    
+
    require 'erubis'
+input = File.read('example.eruby')
+
+puts "----- default -----"
+eruby = Erubis::FastEruby.new(input)
+puts eruby.src
+
+puts "----- with :bufname option -----"
+eruby = Erubis::FastEruby.new(input, :bufname=>'@_out_buf')
+print eruby.src
+
    
+
+
    
+result
    
+
    $ ruby bufname-example.rb
+----- default -----
+_buf = ''; _buf << %Q`<div>\n`
+ for item in list 
+ _buf << %Q`  <p>#{ item }</p>
+  <p>#{Erubis::XmlHelper.escape_xml( item )}</p>\n`
+ end 
+ _buf << %Q`</div>\n`
+_buf.to_s
+----- with :bufname option -----
+@_out_buf = ''; @_out_buf << %Q`<div>\n`
+ for item in list 
+ @_out_buf << %Q`  <p>#{ item }</p>
+  <p>#{Erubis::XmlHelper.escape_xml( item )}</p>\n`
+ end 
+ @_out_buf << %Q`</div>\n`
+@_out_buf.to_s
+
    
+
    
+
+
+
 
    '<%= =%>' and '<%= -%>'
    
 
    Since 2.6.0, '<%= -%>' remove tail spaces and newline.
 This is for compatibiliy with ERB when trim mode is '-'.
@@ -2646,7 +2792,7 @@ AAA
 
    
 
 
-
+
 
    '<%% %>' and '<%%= %>'
    
 
    Since 2.6.0, '<%% %>' and '<%%= %>' are converted into '<% %>' and '<%= %>' respectively.
 This is for compatibility with ERB.
@@ -3039,6 +3185,48 @@ in the same directory in which '*.rhtml' file exists.
 
    
 
 
+
+
    Helper CGI Script for Apache
    
+
    Erubis provides helper CGI script for Apache.
+Using this script, it is very easy to publish *.rhtml files as *.html.
+
    
+
    ### 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
+
    
+
    Edit ~/public_html/.htaccess and modify user name.
+
    
+
    
+~/public_html/.htaccess
    
+
    ## 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|/|^)$ /~username/index.cgi
+#RewriteRule (\.html|/|^)$ index.cgi
+
    
+
    After these steps, *.rhtml will be published as *.html.
+For example, if you access to http://host.domain/~username/index.html (or http://host.domain/~username/), file ~/public_html/index.rhtml will be displayed.
+
    
+
    
+
+
 
 
    Define method
    
 
    Erubis::Eruby#def_method() defines instance method or singleton method.
diff --git a/doc/users-guide.txt b/doc/users-guide.txt
index da64462..2e48d2f 100644
--- a/doc/users-guide.txt
+++ b/doc/users-guide.txt
@@ -1,7 +1,7 @@
 .=title:	Erubis Users' Guide
-.?version:	$Release$
-.?release:	$Release$
-.?lastupdate:	$Date$
+.#.?version:	$Release$
+.#.?release:	$Release$
+.#.?lastupdate:	$Date$
 .?stylesheet:	docstyle.css
 
 release: $Release$
@@ -1661,10 +1661,12 @@ This is for compatibility with eruby and ERB.
 
 .? percentline-example.rhtml
 .-------------------- percentline-example.rhtml
+
      
 {{*% for item in list*}}
-  <%= item %>
+  
    • <%= item %>
      • 
 {{*% end*}}
-%% lines with '%%'
+
    
+{{*%% lines with '%%'*}}
 .--------------------
 
 .#.? percentline-example.rb
@@ -1689,10 +1691,12 @@ This is for compatibility with eruby and ERB.
 .==================== percentline_example.result
 $ erubis -xE PercentLine percentline-example.rhtml
 .#.<<<:! erubis -xE PercentLine guide.d/percentline-example.rhtml | ruby -pe 'sub! /for.*?list|end/, "{{*\\&*}}"'
-_buf = ''; {{*for item in list*}}
- _buf << '  '; _buf << ( item ).to_s; _buf << '
+_buf = ''; _buf << '
      
+'; {{*for item in list*}}
+ _buf << '  
    • '; _buf << ( item ).to_s; _buf << '
      • 
 '; {{*end*}}
- _buf << '% lines with \'%%\'
+ _buf << '
    
+{{*% lines with \'%%\'*}}
 ';
 _buf.to_s
 .====================
@@ -1701,6 +1705,55 @@ PercentLineEnhancer is language-independent.
 
 
 
+.$$ PrefixedLineEnhancer	| prefixedline-enhancer
+
+PrefixedlineEnhancer regards lines starting with '%' as Ruby code.
+It is similar to {{}}, but there are some differences.
+
+.* PrefixedlineEnhancer allows to indent lines starting with '%', but PercentLineEnhancer doesn't.
+.* PrefixedlineEnhancer allows to change prefixed character (default '%'), but PercentLineEnhancer doesn't.
+
+
+.? prefixedline-example.rhtml
+.-------------------- prefixedline-example.rhtml
+
      
+  {{*! for item in list*}}
+  
    • <%= item %>
      • 
+  {{*! end*}}
+
    
+  {{*!! lines with '!!'*}}
+.--------------------
+
+.? prefixedline-example.rb
+.-------------------- prefixedline-example.rb
+require 'erubis'
+
+class PrefixedLineEruby < Erubis::Eruby
+  include Erubis::PrefixedLineEnhancer
+end
+
+input = File.read('prefixedline-example.rhtml')
+eruby = PrefixedLineEruby.new(input, :prefixchar=>'!')  # default '%'
+print eruby.src
+.--------------------
+
+.? compiled source code
+.==================== prefixedline_example.result
+$ ruby prefixedline-example.rb
+_buf = ''; _buf << '
      
+';   {{*for item in list*}}
+ _buf << '  
    • '; _buf << ( item ).to_s; _buf << '
      • 
+';   {{*end*}}
+ _buf << '
    
+  {{*! lines with \'!!\'*}}
+';
+_buf.to_s
+.====================
+
+PrefixedLineEnhancer is language-independent.
+
+
+
 .$$ HeaderFooterEnhancer | headerfooter-enhancer
 
 [experimental]
@@ -2291,7 +2344,7 @@ $ erubis -l scheme --func=display example.escheme
 
 .$$ Perl	| lang-perl
 
-.? example.eprl
+.? example.eperl
 .-------------------- example.eperl
 {{*<%
    my $user = 'Erubis';
@@ -2418,6 +2471,8 @@ Notice that default value of 'docwrite' property will be false in the future rel
 
 .$ Ruby on Rails Support	| rails
 
+{{!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.!}}
+
 Erubis supports Ruby on Rails. 
 This section describes how to use Erubis with Ruby on Rails.
 
@@ -2729,7 +2784,88 @@ Notice that pp_form_for() is not provided.
 .$ Other Topics	| topics
 
 
-.$$ '<%= =%>' and '<%= -%>'
+.$$ {{,Erubis::FastEruby,}} Class	| topics-fasteruby
+
+{{,Erubis::FastEruby,}} class generates more effective code than {{,Erubis::Eruby,}}.
+
+.? fasteruby-example.rb
+.-------------------- fasteruby-example.rb
+require 'erubis'
+input = File.read('example.eruby')
+
+puts "----- Erubis::Eruby -----"
+print Erubis::Eruby.new(input).src
+
+puts "----- Erubis::FastEruby -----"
+print {{*Erubis::FastEruby*}}.new(input).src
+.--------------------
+
+.? result
+.==================== fasteruby-example.result
+$ ruby fasteruby-example.rb
+----- Erubis::Eruby -----
+_buf = ''; _buf << '
    
+'; for item in list 
+ _buf << '  
    '; {{*_buf << ( item ).to_s;*}} _buf << '
    
+  
    '; {{*_buf << Erubis::XmlHelper.escape_xml( item );*}} _buf << '
    
+'; end 
+ _buf << '
    
+';
+_buf.to_s
+----- Erubis::FastEruby -----
+_buf = ''; _buf << %Q`
    \n`
+ for item in list 
+ _buf << %Q`  
    {{*#{ item }*}}
    
+  
    {{*#{Erubis::XmlHelper.escape_xml( item )}*}}
    \n`
+ end 
+ _buf << %Q`
    \n`
+_buf.to_s
+.====================
+
+Technically, {{,Erubis::FastEruby,}} is just a subclass of {{,Erubis::Eruby,}} and includes {{,{{}},}}. {{,Erubis::FastEruby,}} is faster than {{,Erubis::Eruby,}} but is not extensible compared to {{,Erubis::Eruby,}}. This is the reason why {{,Erubis::FastEruby,}} is not the default class of Erubis.
+
+
+.$$ {{,:bufname,}} Option	| topics-bufname
+
+Since 2.7.0, Erubis supports {{,:bufname,}} option which allows you to change buffer variable name (default '{{,_buf,}}').
+
+.? bufname-example.rb
+.-------------------- bufname-example.rb
+require 'erubis'
+input = File.read('example.eruby')
+
+puts "----- default -----"
+eruby = Erubis::FastEruby.new(input)
+puts eruby.src
+
+puts "----- with :bufname option -----"
+eruby = Erubis::FastEruby.new(input, {{*:bufname=>'@_out_buf'*}})
+print eruby.src
+.--------------------
+
+.? result
+.==================== bufname-example.result
+$ ruby bufname-example.rb
+----- default -----
+_buf = ''; _buf << %Q`
    \n`
+ for item in list 
+ _buf << %Q`  
    #{ item }
    
+  
    #{Erubis::XmlHelper.escape_xml( item )}
    \n`
+ end 
+ _buf << %Q`
    \n`
+_buf.to_s
+----- with :bufname option -----
+{{*@_out_buf*}} = ''; {{*@_out_buf*}} << %Q`
    \n`
+ for item in list 
+ {{*@_out_buf*}} << %Q`  
    #{ item }
    
+  
    #{Erubis::XmlHelper.escape_xml( item )}
    \n`
+ end 
+ {{*@_out_buf*}} << %Q`
    \n`
+{{*@_out_buf*}}.to_s
+.====================
+
+
+.$$ '<%= =%>' and '<%= -%>'	| topics-trimspaces
 
 Since 2.6.0, '<%= -%>' remove tail spaces and newline.
 This is for compatibiliy with ERB when trim mode is '-'.
@@ -2761,7 +2897,7 @@ AAA
 .====================
 
 
-.$$ '<%% %>' and '<%%= %>'
+.$$ '<%% %>' and '<%%= %>'	| topics-doublepercent
 
 Since 2.6.0, '<%% %>' and '<%%= %>' are converted into '<% %>' and '<%= %>' respectively.
 This is for compatibility with ERB.
@@ -3148,6 +3284,48 @@ Apache::ErubisRun calls Erubis::Eruby.load_file() internally which creates cache
 in the same directory in which '*.rhtml' file exists.
 
 
+.$$ Helper CGI Script for Apache	| topics-index-cgi
+
+Erubis provides helper CGI script for Apache.
+Using this script, it is very easy to publish *.rhtml files as *.html.
+
+.====================
+### 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
+.====================
+
+Edit ~/public_html/.htaccess and modify user name.
+
+.? ~/public_html/.htaccess
+.--------------------
+## 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|/|^)$ /~{{*username*}}/index.cgi
+#RewriteRule (\.html|/|^)$ index.cgi
+.--------------------
+
+After these steps, *.rhtml will be published as *.html.
+For example, if you access to {{,http://{{/host/}}.{{/domain/}}/~{{/username/}}/index.html,}} (or {{,http://{{/host/}}.{{/domain/}}/~{{/username/}}/,}}), file {{,~/public_html/index.rhtml,}} will be displayed.
+
 
 .$$ Define method	| topics-defmethod
 
-- 
cgit v1.2.1