<%= @desc %>
- -- <% if @cost < 10 %> - Only <%= @cost %>!!! - <% else %> - Call for a price, today! - <% end %> -
- - - -}.gsub(/^ /, '') - -rhtml = ERB.new(template) +There are a variety of template engines available in various Ruby projects. +For example, [RDoc][rdoc], distributed with Ruby, uses its own template engine, which +can be reused elsewhere. -# 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!") +Other popular template engines may be found in the [Ruby Toolbox][ruby toolbox]. -# Produce result. -rhtml.run(toy.get_binding) -``` +## Code -Generates (some blank lines removed): +The \ERB source code is in GitHub project [ruby/erb][ruby/erb]/ -```html - -Geek's Best Friend! Responds to Ruby commands...
- -- Call for a price, today! -
- - - -``` - -## Notes - -There are a variety of templating solutions available in various Ruby projects. -For example, RDoc, distributed with Ruby, uses its own template engine, which -can be reused elsewhere. +## Bugs -Other popular engines could be found in the corresponding -[Category](https://www.ruby-toolbox.com/categories/template_engines) of -The Ruby Toolbox. +Bugs may be reported at [ERB Issues][erb issues]. ## License -The gem is available as open source under the terms of the [2-Clause BSD License](https://opensource.org/licenses/BSD-2-Clause). +This software is available as open source under the terms +of the [2-Clause BSD License][2-clause bsd license]. + +[2-clause bsd license]: https://opensource.org/licenses/BSD-2-Clause +[erb executable]: rdoc-ref:erb_executable.md +[erb issues]: https://github.com/ruby/erb/issues +[rdoc]: https://ruby.github.io/rdoc/ +[ruby/erb]: https://github.com/ruby/erb +[ruby toolbox]: https://www.ruby-toolbox.com/categories/template_engines +[sprintf]: https://docs.ruby-lang.org/en/master/Kernel.html#method-i-sprintf +[template processor]: https://en.wikipedia.org/wiki/Template_processor_ diff --git a/_doc/erb_executable.md b/_doc/erb_executable.md new file mode 100644 index 0000000..87a7883 --- /dev/null +++ b/_doc/erb_executable.md @@ -0,0 +1,240 @@ +# \ERB Executable + +The `erb` executable gives command-line access to ERB template processing. + +The executable is installed with \ERB, which is part of the Ruby installation. + +For a quick summary, type: + +```bash +$ erb --help +``` + +The format of the command is +`erb [_options_] [_filepaths_]`, +where: + +- _options_ are zero or more [options][options]. +- _filepaths_ are zero or more paths to files, each containing an plain text + that can include \ERB tags. + +## Filepaths + +With one or more _filepaths_ given, `erb` reads all the given files as a single template; +that is, `erb` processes multiple files into a single result: + +```bash +$ cat t.erb +<%= RUBY_VERSION %> +<%= Time.now %> +$ cat u.erb +% Encoding.list.take(4).each do |encoding| +* <%= encoding %> +% end +$ erb t.erb u.erb +3.4.5 +2025-09-24 00:23:00 +0100 +* ASCII-8BIT +* UTF-8 +* US-ASCII +* UTF-16BE +``` + +There is a special "filepath", `'-'`, that specifies the standard input: + +```bash +$ echo "<%= RUBY_VERSION %>" | erb u.erb - +* ASCII-8BIT +* UTF-8 +* US-ASCII +* UTF-16BE +3.4.5 +``` + +Any filepath, including `'-'`, may be repeated. + +With no _filepaths_ given, `erb` reads and processes the standard input: + +```bash +$ echo "<%= RUBY_VERSION %>" | erb # Prints the ERB version string. +``` + +## Options + +### `-d`, `--debug`: Set $DEBUG + +Use option `-d` or `--debug` to turn on debugging output: + +```bash +$ echo "<%= $DEBUG %>" | erb +"false" +$echo "<%= $DEBUG %>" | erb --debug +"true" +``` + +### `-E`, `--encoding`: Set Encodings + +Use option `-E` or `--encoding` to set the default external encoding to `_ex_` +and, if `_in_` is given, to set the default internal encoding to `_in_`. + +Each encoding, `ex` and `in`, must be the name of an Encoding: + +``` +erb -E ASCII-8BIT:ASCII-8BIT t.erb +``` + +### `-h`, `--help`: Print Help + +Use option `-h` or `--help` to print `erb` help text: + +```bash +$ erb --help +``` + +### `-n`: Print Source with Line Numbers + +Use option `-n` with option `-x` to print the output of ERB#src, +with numbered lines: + +```bash +$ cat t.erb +<%= RUBY_VERSION %> +<%= Time.now %> +$ erb -n -x t.erb + 1 #coding:UTF-8 + 2 _erbout = +''; _erbout.<<(( RUBY_VERSION ).to_s); _erbout.<< "\n".freeze + 3 ; _erbout.<<(( Time.now ).to_s); _erbout.<< "\n".freeze + 4 ; _erbout +``` + +Using option `-n` without option `-x` has no effect: + +```bash +$ erb -n t.erb +3.4.5 +2025-09-23 02:44:57 +0100 +``` + +### `-P`: Disable Execution Tag Shorthand + +By default, `erb` enables [execution tag shorthand][execution tag shorthand]: + +``` +$ cat u.erb +% Encoding.list.take(4).each do |encoding| +* <%= encoding %> +% end +$ erb u.erb +* ASCII-8BIT +* UTF-8 +* US-ASCII +* UTF-16BE +``` + +You can use option `-P` to disable the shorthand: + +``` +$ erb -P u.erb # Raises NameError: "undefined local variable or method 'encoding'" +``` + +### `-r`: Load Library + +You can use option `-r` to load a library; +the option may be given multiple times, to load multiple libraries: + +``` +$ erb -r csv -r bigdecimal t.erb +``` + +### `-T`: Set Trim Mode + +You can use option `-T` to set the trim mode. + +The values for the option are: + +- `'0'`, meaning `'%'`; enable execution tag shorthand; + see [execution tag shorthand][execution tag shorthand]. +- `'1'`, meaning `'%>'`: enable execution tag shorthand and omit newline for each line ending with `'%>'`; + see [suppressing unwanted newlines][suppressing unwanted newlines]. +- `'2'`, meaning `'<>'`: to suppress the trailing newline for each line + that both begins with `'<%'` and ends with `'%>'`; + see [suppressing unwanted newlines][suppressing unwanted newlines]. +- `'-'`, meaning `'%-'`: enable execution tag shorthand and omit each blank line ending with `'-%>'`. + see [execution tag shorthand][execution tag shorthand] + and [suppressing unwanted blank lines][suppressing unwanted blank lines]. + +Example: + +```bash +$ erb -T 0 t.erb +``` + +### `-U`: Set Default Encodings to UTF-8 + +You can use option `-U` to set both external and internal encodings to UTF-8: + +```bash +$ erb -U t.erb +``` + +### `-v`: Set $VERBOSE + +Use option `-v` to turn on verbose output: + +```bash +$ $ "<%= $VERBOSE %>" | erb +"false" +$ echo "<%= $VERBOSE %>" | erb -v +"true" +``` + +### `-v`: Print \ERB Version + +Use option `--version` to print the \ERB version string: + +```bash +$ erb --version +``` + +### `-x`: Print Source + +Use option `-x` to print the output of ERB#src, +which is the Ruby code that is to be run when ERB#result is called: + +```bash +$ cat t.erb +<%= RUBY_VERSION %> +<%= Time.now %> +$ erb -x t.erb +#coding:UTF-8 +_erbout = +''; _erbout.<<(( RUBY_VERSION ).to_s); _erbout.<< "\n".freeze +; _erbout.<<(( Time.now ).to_s); _erbout.<< "\n".freeze +; _erbout +``` + +### `--`: End of Options + +You can use option `'--'` to declare the end of options in the `erb` command; +`erb` treats each word following as a filepath (even if it looks like an option): + +``` +erb -- --help # Raises Errno::ENOENT: "No such file or directory @ rb_sysopen - --help" +``` + +### `name=value`: Set the Value of a Variable + +You can use option `name=value` to set the value of the variable named `name` +to the given `value`. + +The option may be given multiple times to set multiple variables: + +```bash +$ echo "<%= foo %> <%= bar %>" | erb foo=1 bar=2 +"1 2" +``` + +[erb.new]: https://docs.ruby-lang.org/en/master/ERB.html#method-c-new. +[execution tag shorthand]: rdoc-ref:ERB@Shorthand+Format+for+Execution+Tags +[options]: rdoc-ref:erb_executable.md@Options +[suppressing unwanted blank lines]: rdoc-ref:ERB@Suppressing+Unwanted+Blank+Lines +[suppressing unwanted newlines]: rdoc-ref:ERB@Suppressing+Unwanted+Newlines \ No newline at end of file diff --git a/lib/erb.rb b/lib/erb.rb index b9b4ef7..884a630 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -12,6 +12,24 @@ # # You can redistribute it and/or modify it under the same terms as Ruby. +# A NOTE ABOUT TERMS: +# +# Formerly: The documentation in this file used the term _template_ to refer to an ERB object. +# +# Now: The documentation in this file uses the term _template_ +# to refer to the string input to ERB.new. +# +# The reason for the change: When documenting the ERB executable erb, +# we need a term that refers to its string input; +# _source_ is not a good idea, because ERB#src means something entirely different; +# the two different sorts of sources would bring confusion. +# +# Therefore we use the term _template_ to refer to: +# +# - The string input to ERB.new +# - The string input to executable erb. +# + require 'erb/version' require 'erb/compiler' require 'erb/def_method' @@ -22,15 +40,6 @@ # Class **ERB** (the name stands for **Embedded Ruby**) # is an easy-to-use, but also very powerful, [template processor][template processor]. # -# Like method [sprintf][sprintf], \ERB can format run-time data into a string. -# \ERB, however,s is *much more powerful*. -# -# \ERB is commonly used to produce: -# -# - Customized or personalized email messages. -# - Customized or personalized web pages. -# - Software code (in code-generating applications). -# # ## Usage # # Before you can use \ERB, you must first require it @@ -44,7 +53,8 @@ # # Here's how \ERB works: # -# - You can create an \ERB object (a *template*) to store text that includes specially formatted *tags*. +# - You can create a *template*: a plain-text string that includes specially formatted *tags*.. +# - You can create an \ERB object to store the template. # - You can call instance method ERB#result to get the *result*. # # \ERB supports tags of three kinds: @@ -53,83 +63,85 @@ # each begins with `'<%'`, ends with `'%>'`; contains a Ruby expression; # in the result, the value of the expression replaces the entire tag: # +# template = 'The magic word is <%= magic_word %>.' +# erb = ERB.new(template) # magic_word = 'xyzzy' -# template.result(binding) # => "The magic word is xyzzy." -# -# ERB.new('Today is <%= Date::DAYNAMES[Date.today.wday] %>.').result # => "Today is Monday." +# erb.result(binding) # => "The magic word is xyzzy." # -# The first call to #result passes argument `binding`, +# The above call to #result passes argument `binding`, # which contains the binding of variable `magic_word` to its string value `'xyzzy'`. # -# The second call need not pass a binding, +# The below call to #result need not pass a binding, # because its expression `Date::DAYNAMES` is globally defined. # +# ERB.new('Today is <%= Date::DAYNAMES[Date.today.wday] %>.').result # => "Today is Monday." +# # - [Execution tags][execution tags]: # each begins with `'<%='`, ends with `'%>'`; contains Ruby code to be executed: # -# s = '<% File.write("t.txt", "Some stuff.") %>' -# ERB.new(s).result +# template = '<% File.write("t.txt", "Some stuff.") %>' +# ERB.new(template).result # File.read('t.txt') # => "Some stuff." # # - [Comment tags][comment tags]: # each begins with `'<%#'`, ends with `'%>'`; contains comment text; # in the result, the entire tag is omitted. # -# s = 'Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.' -# ERB.new(s).result # => "Some stuff; more stuff." +# template = 'Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.' +# ERB.new(template).result # => "Some stuff; more stuff." # # ## Some Simple Examples # # Here's a simple example of \ERB in action: # # ``` -# s = 'The time is <%= Time.now %>.' -# template = ERB.new(s) -# template.result +# template = 'The time is <%= Time.now %>.' +# erb = ERB.new(template) +# erb.result # # => "The time is 2025-09-09 10:49:26 -0500." # ``` # # Details: # -# 1. A plain-text string is assigned to variable `s`. +# 1. A plain-text string is assigned to variable `template`. # Its embedded [expression tag][expression tags] `'<%= Time.now %>'` includes a Ruby expression, `Time.now`. -# 2. The string is put into a new \ERB object, and stored in variable `template`. -# 4. Method call `template.result` generates a string that contains the run-time value of `Time.now`, +# 2. The string is put into a new \ERB object, and stored in variable `erb`. +# 4. Method call `erb.result` generates a string that contains the run-time value of `Time.now`, # as computed at the time of the call. # -# The template may be re-used: +# The +# \ERB object may be re-used: # # ``` -# template.result +# erb.result # # => "The time is 2025-09-09 10:49:33 -0500." # ``` # # Another example: # # ``` -# s = 'The magic word is <%= magic_word %>.' -# template = ERB.new(s) +# template = 'The magic word is <%= magic_word %>.' +# erb = ERB.new(template) # magic_word = 'abracadabra' -# # => "abracadabra" -# template.result(binding) +# erb.result(binding) # # => "The magic word is abracadabra." # ``` # # Details: # -# 1. As before, a plain-text string is assigned to variable `s`. +# 1. As before, a plain-text string is assigned to variable `template`. # Its embedded [expression tag][expression tags] `'<%= magic_word %>'` has a variable *name*, `magic_word`. -# 2. The string is put into a new \ERB object, and stored in variable `template`; +# 2. The string is put into a new \ERB object, and stored in variable `erb`; # note that `magic_word` need not be defined before the \ERB object is created. # 3. `magic_word = 'abracadabra'` assigns a value to variable `magic_word`. -# 4. Method call `template.result(binding)` generates a string +# 4. Method call `erb.result(binding)` generates a string # that contains the *value* of `magic_word`. # -# As before, the template may be re-used: +# As before, the \ERB object may be re-used: # # ``` # magic_word = 'xyzzy' -# template.result(binding) +# erb.result(binding) # # => "The magic word is xyzzy." # ``` # @@ -157,18 +169,17 @@ # these expression tags refer only to Ruby's global constant `RUBY_COPYRIGHT` and global variable `$0`: # # ``` -# s = <