diff options
Diffstat (limited to 'lib/erb.rb')
-rw-r--r-- | lib/erb.rb | 486 |
1 files changed, 243 insertions, 243 deletions
diff --git a/lib/erb.rb b/lib/erb.rb index 678f082b07..62b59be249 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -10,249 +10,249 @@ # # You can redistribute it and/or modify it under the same terms as Ruby. -# -# = ERB -- Ruby Templating -# -# == Introduction -# -# ERB provides an easy to use but powerful templating system for Ruby. Using -# ERB, actual Ruby code can be added to any plain text document for the -# purposes of generating document information details and/or flow control. -# -# A very simple example is this: -# -# require 'erb' -# -# x = 42 -# template = ERB.new <<-EOF -# The value of x is: <%= x %> -# EOF -# puts template.result(binding) -# -# <em>Prints:</em> The value of x is: 42 -# -# More complex examples are given below. -# -# -# == Recognized Tags -# -# ERB recognizes certain tags in the provided template and converts them based -# on the rules below: -# -# <% Ruby code -- inline with output %> -# <%= Ruby expression -- replace with result %> -# <%# comment -- ignored -- useful in testing %> -# % a line of Ruby code -- treated as <% line %> (optional -- see ERB.new) -# %% replaced with % if first thing on a line and % processing is used -# <%% or %%> -- replace with <% or %> respectively -# -# All other text is passed through ERB filtering unchanged. -# -# -# == Options -# -# There are several settings you can change when you use ERB: -# * the nature of the tags that are recognized; -# * the value of <tt>$SAFE</tt> under which the template is run; -# * the binding used to resolve local variables in the template. -# -# See the ERB.new and ERB#result methods for more detail. -# -# == Character encodings -# -# ERB (or ruby code generated by ERB) returns a string in the same -# character encoding as the input string. When the input string has -# a magic comment, however, it returns a string in the encoding specified -# by the magic comment. -# -# # -*- coding: UTF-8 -*- -# require 'erb' -# -# template = ERB.new <<EOF -# <%#-*- coding: Big5 -*-%> -# \_\_ENCODING\_\_ is <%= \_\_ENCODING\_\_ %>. -# EOF -# puts template.result -# -# <em>Prints:</em> \_\_ENCODING\_\_ is Big5. -# -# -# == Examples -# -# === Plain Text -# -# ERB is useful for any generic templating situation. Note that in this example, we use the -# convenient "% at start of line" tag, and we quote the template literally with -# <tt>%q{...}</tt> to avoid trouble with the backslash. -# -# require "erb" -# -# # Create template. -# template = %q{ -# From: James Edward Gray II <james@grayproductions.net> -# To: <%= to %> -# Subject: Addressing Needs -# -# <%= to[/\w+/] %>: -# -# Just wanted to send a quick note assuring that your needs are being -# addressed. -# -# I want you to know that my team will keep working on the issues, -# especially: -# -# <%# ignore numerous minor requests -- focus on priorities %> -# % priorities.each do |priority| -# * <%= priority %> -# % end -# -# Thanks for your patience. -# -# James Edward Gray II -# }.gsub(/^ /, '') -# -# message = ERB.new(template, 0, "%<>") -# -# # Set up template data. -# to = "Community Spokesman <spokesman@ruby_community.org>" -# priorities = [ "Run Ruby Quiz", -# "Document Modules", -# "Answer Questions on Ruby Talk" ] -# -# # Produce result. -# email = message.result -# puts email -# -# <i>Generates:</i> -# -# From: James Edward Gray II <james@grayproductions.net> -# To: Community Spokesman <spokesman@ruby_community.org> -# Subject: Addressing Needs -# -# Community: -# -# Just wanted to send a quick note assuring that your needs are being addressed. -# -# I want you to know that my team will keep working on the issues, especially: -# -# * Run Ruby Quiz -# * Document Modules -# * Answer Questions on Ruby Talk -# -# Thanks for your patience. -# -# James Edward Gray II -# -# === Ruby in HTML -# -# ERB is often used in <tt>.rhtml</tt> files (HTML with embedded Ruby). Notice the need in -# this example to provide a special binding when the template is run, so that the instance -# variables in the Product object can be resolved. -# -# require "erb" -# -# # Build template data class. -# class Product -# def initialize( code, name, desc, cost ) -# @code = code -# @name = name -# @desc = desc -# @cost = cost -# -# @features = [ ] -# end -# -# def add_feature( feature ) -# @features << feature -# end -# -# # Support templating of member data. -# def get_binding -# binding -# end -# -# # ... -# end -# -# # Create template. -# template = %{ -# <html> -# <head><title>Ruby Toys -- <%= @name %></title></head> -# <body> -# -# <h1><%= @name %> (<%= @code %>)</h1> -# <p><%= @desc %></p> -# -# <ul> -# <% @features.each do |f| %> -# <li><b><%= f %></b></li> -# <% end %> -# </ul> -# -# <p> -# <% if @cost < 10 %> -# <b>Only <%= @cost %>!!!</b> -# <% else %> -# Call for a price, today! -# <% end %> -# </p> -# -# </body> -# </html> -# }.gsub(/^ /, '') -# -# rhtml = ERB.new(template) -# -# # Set up template data. -# toy = Product.new( "TZ-1002", -# "Rubysapien", -# "Geek's Best Friend! Responds to Ruby commands...", -# 999.95 ) -# toy.add_feature("Listens for verbal commands in the Ruby language!") -# toy.add_feature("Ignores Perl, Java, and all C variants.") -# toy.add_feature("Karate-Chop Action!!!") -# toy.add_feature("Matz signature on left leg.") -# toy.add_feature("Gem studded eyes... Rubies, of course!") -# -# # Produce result. -# rhtml.run(toy.get_binding) -# -# <i>Generates (some blank lines removed):</i> -# -# <html> -# <head><title>Ruby Toys -- Rubysapien</title></head> -# <body> -# -# <h1>Rubysapien (TZ-1002)</h1> -# <p>Geek's Best Friend! Responds to Ruby commands...</p> -# -# <ul> -# <li><b>Listens for verbal commands in the Ruby language!</b></li> -# <li><b>Ignores Perl, Java, and all C variants.</b></li> -# <li><b>Karate-Chop Action!!!</b></li> -# <li><b>Matz signature on left leg.</b></li> -# <li><b>Gem studded eyes... Rubies, of course!</b></li> -# </ul> -# -# <p> -# Call for a price, today! -# </p> -# -# </body> -# </html> -# -# -# == Notes -# -# There are a variety of templating solutions available in various Ruby projects: -# * ERB's big brother, eRuby, works the same but is written in C for speed; -# * Amrita (smart at producing HTML/XML); -# * cs/Template (written in C for speed); -# * RDoc, distributed with Ruby, uses its own template engine, which can be reused elsewhere; -# * and others; search the RAA. -# -# Rails, the web application framework, uses ERB to create views. -# +=begin rdoc += ERB -- Ruby Templating + +== Introduction + +ERB provides an easy to use but powerful templating system for Ruby. Using +ERB, actual Ruby code can be added to any plain text document for the +purposes of generating document information details and/or flow control. + +A very simple example is this: + + require 'erb' + + x = 42 + template = ERB.new <<-EOF + The value of x is: <%= x %> + EOF + puts template.result(binding) + +<em>Prints:</em> The value of x is: 42 + +More complex examples are given below. + + +== Recognized Tags + +ERB recognizes certain tags in the provided template and converts them based +on the rules below: + + <% Ruby code -- inline with output %> + <%= Ruby expression -- replace with result %> + <%# comment -- ignored -- useful in testing %> + % a line of Ruby code -- treated as <% line %> (optional -- see ERB.new) + %% replaced with % if first thing on a line and % processing is used + <%% or %%> -- replace with <% or %> respectively + +All other text is passed through ERB filtering unchanged. + + +== Options + +There are several settings you can change when you use ERB: +* the nature of the tags that are recognized; +* the value of <tt>$SAFE</tt> under which the template is run; +* the binding used to resolve local variables in the template. + +See the ERB.new and ERB#result methods for more detail. + +== Character encodings + +ERB (or ruby code generated by ERB) returns a string in the same +character encoding as the input string. When the input string has +a magic comment, however, it returns a string in the encoding specified +by the magic comment. + + # -*- coding: UTF-8 -*- + require 'erb' + + template = ERB.new <<EOF + <%#-*- coding: Big5 -*-%> + \_\_ENCODING\_\_ is <%= \_\_ENCODING\_\_ %>. + EOF + puts template.result + +<em>Prints:</em> \_\_ENCODING\_\_ is Big5. + + +== Examples + +=== Plain Text + +ERB is useful for any generic templating situation. Note that in this example, we use the +convenient "% at start of line" tag, and we quote the template literally with +<tt>%q{...}</tt> to avoid trouble with the backslash. + + require "erb" + + # Create template. + template = %q{ + From: James Edward Gray II <james@grayproductions.net> + To: <%= to %> + Subject: Addressing Needs + + <%= to[/\w+/] %>: + + Just wanted to send a quick note assuring that your needs are being + addressed. + + I want you to know that my team will keep working on the issues, + especially: + + <%# ignore numerous minor requests -- focus on priorities %> + % priorities.each do |priority| + * <%= priority %> + % end + + Thanks for your patience. + + James Edward Gray II + }.gsub(/^ /, '') + + message = ERB.new(template, 0, "%<>") + + # Set up template data. + to = "Community Spokesman <spokesman@ruby_community.org>" + priorities = [ "Run Ruby Quiz", + "Document Modules", + "Answer Questions on Ruby Talk" ] + + # Produce result. + email = message.result + puts email + +<i>Generates:</i> + + From: James Edward Gray II <james@grayproductions.net> + To: Community Spokesman <spokesman@ruby_community.org> + Subject: Addressing Needs + + Community: + + Just wanted to send a quick note assuring that your needs are being addressed. + + I want you to know that my team will keep working on the issues, especially: + + * Run Ruby Quiz + * Document Modules + * Answer Questions on Ruby Talk + + Thanks for your patience. + + James Edward Gray II + +=== Ruby in HTML + +ERB is often used in <tt>.rhtml</tt> files (HTML with embedded Ruby). Notice the need in +this example to provide a special binding when the template is run, so that the instance +variables in the Product object can be resolved. + + require "erb" + + # Build template data class. + class Product + def initialize( code, name, desc, cost ) + @code = code + @name = name + @desc = desc + @cost = cost + + @features = [ ] + end + + def add_feature( feature ) + @features << feature + end + + # Support templating of member data. + def get_binding + binding + end + + # ... + end + + # Create template. + template = %{ + <html> + <head><title>Ruby Toys -- <%= @name %></title></head> + <body> + + <h1><%= @name %> (<%= @code %>)</h1> + <p><%= @desc %></p> + + <ul> + <% @features.each do |f| %> + <li><b><%= f %></b></li> + <% end %> + </ul> + + <p> + <% if @cost < 10 %> + <b>Only <%= @cost %>!!!</b> + <% else %> + Call for a price, today! + <% end %> + </p> + + </body> + </html> + }.gsub(/^ /, '') + + rhtml = ERB.new(template) + + # Set up template data. + toy = Product.new( "TZ-1002", + "Rubysapien", + "Geek's Best Friend! Responds to Ruby commands...", + 999.95 ) + toy.add_feature("Listens for verbal commands in the Ruby language!") + toy.add_feature("Ignores Perl, Java, and all C variants.") + toy.add_feature("Karate-Chop Action!!!") + toy.add_feature("Matz signature on left leg.") + toy.add_feature("Gem studded eyes... Rubies, of course!") + + # Produce result. + rhtml.run(toy.get_binding) + +<i>Generates (some blank lines removed):</i> + + <html> + <head><title>Ruby Toys -- Rubysapien</title></head> + <body> + + <h1>Rubysapien (TZ-1002)</h1> + <p>Geek's Best Friend! Responds to Ruby commands...</p> + + <ul> + <li><b>Listens for verbal commands in the Ruby language!</b></li> + <li><b>Ignores Perl, Java, and all C variants.</b></li> + <li><b>Karate-Chop Action!!!</b></li> + <li><b>Matz signature on left leg.</b></li> + <li><b>Gem studded eyes... Rubies, of course!</b></li> + </ul> + + <p> + Call for a price, today! + </p> + + </body> + </html> + + +== Notes + +There are a variety of templating solutions available in various Ruby projects: +* ERB's big brother, eRuby, works the same but is written in C for speed; +* Amrita (smart at producing HTML/XML); +* cs/Template (written in C for speed); +* RDoc, distributed with Ruby, uses its own template engine, which can be reused elsewhere; +* and others; search the RAA. + +Rails, the web application framework, uses ERB to create views. +=end class ERB Revision = '$Date:: $' #' |