From aa624a679d3e302a7e82b56d91df535eb4c8fcfa Mon Sep 17 00:00:00 2001 From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com> Date: Sun, 19 Jul 2026 02:39:10 +0900 Subject: [PATCH] Fix documentation typos and code examples Makes documentation-only changes. Summary: - Fix typos and grammar - Fix invalid code examples - Fix syntax highlighting in code examples - Fix invalid Markdown tags --- README.md | 40 ++++++------ _doc/erb_executable.md | 49 +++++++------- lib/erb.rb | 144 ++++++++++++++++++++++++++++------------- 3 files changed, 148 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 3ad6e57..b126bb7 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,14 @@ ERB is commonly used to produce: - Customized or personalized web pages. - Software code (in code-generating applications). -Like method [sprintf][sprintf], ERB can format run-time data into a string. -ERB, however, is *much more powerful* +Like method [`sprintf`][sprintf], ERB can format run-time data into a string. +ERB, however, is *much more powerful*. ## How ERB Works Using ERB, you can create a *template*: a plain-text string that has specially-formatted *tags*, then store it into an ERB object; -when ERB produces _result_ string, it: +when ERB produces the _result_ string, it: - Inserts run-time-evaluated expressions into the result. - Executes snippets of Ruby code. @@ -31,30 +31,32 @@ There are three types of tags: | Tag | Form | Action | Text in Result | |----------------|:------------------------------------:|:-------------------------------------:|:--------------------:| -| Expression tag | '<%= _ruby_expression_ %>' | Evaluates _ruby_expression_. | Value of expression. | -| Execution tag | '<% _ruby_code_ %>' | Execute _ruby_code_. | None. | -| Comment tag | '<%# _comment_text_ %>' | None. | None. | +| Expression tag | `<%= ruby_expression %>` | Evaluates `ruby_expression`. | Value of expression. | +| Execution tag | `<% ruby_code %>` | Executes `ruby_code`. | None. | +| Comment tag | `<%# comment_text %>` | None. | None. | These examples use `erb`, the ERB command-line interface; each "echoes" a string template and pipes it to `erb` as input: - Expression tag: + ```bash + $ echo "<%= \$VERBOSE %>" | erb + false - $ echo "<%= $VERBOSE %>" | erb - "false" - $ echo "<%= 2 + 2 %>" | erb - "4" - + $ echo "<%= 2 + 2 %>" | erb + 4 + ``` - Execution tag: - - echo "<% if $VERBOSE %> Long message. <% else %> Short message. <% end %>" | erb - " Short message. " - + ```bash + $ echo "<% if \$VERBOSE %> Long message. <% else %> Short message. <% end %>" | erb + Short message. + ``` - Comment tag: - - echo "<%# TODO: Fix this nonsense. %> Nonsense." | erb - " Nonsense." + ```bash + $ echo "<%# TODO: Fix this nonsense. %> Nonsense." | erb + Nonsense. + ``` ## How to Use ERB @@ -95,4 +97,4 @@ of the [2-Clause BSD License][2-clause bsd license]. [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_ +[template processor]: https://en.wikipedia.org/wiki/Template_processor diff --git a/_doc/erb_executable.md b/_doc/erb_executable.md index 87a7883..28fead9 100644 --- a/_doc/erb_executable.md +++ b/_doc/erb_executable.md @@ -10,12 +10,10 @@ For a quick summary, type: $ erb --help ``` -The format of the command is -`erb [_options_] [_filepaths_]`, -where: +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 +- _filepaths_ are zero or more paths to files, each containing plain text that can include \ERB tags. ## Filepaths @@ -27,10 +25,12 @@ that is, `erb` processes multiple files into a single result: $ 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 @@ -66,21 +66,22 @@ $ echo "<%= RUBY_VERSION %>" | erb # Prints the ERB version string. Use option `-d` or `--debug` to turn on debugging output: ```bash -$ echo "<%= $DEBUG %>" | erb -"false" -$echo "<%= $DEBUG %>" | erb --debug -"true" +$ 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_`. +Use option `-E ex[:in]` or `--encoding ex[:in]` 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 +```bash +$ erb -E ASCII-8BIT:ASCII-8BIT t.erb ``` ### `-h`, `--help`: Print Help @@ -100,6 +101,7 @@ with numbered lines: $ 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 @@ -119,11 +121,12 @@ $ erb -n t.erb By default, `erb` enables [execution tag shorthand][execution tag shorthand]: -``` +```bash $ cat u.erb % Encoding.list.take(4).each do |encoding| * <%= encoding %> % end + $ erb u.erb * ASCII-8BIT * UTF-8 @@ -133,7 +136,7 @@ $ erb u.erb You can use option `-P` to disable the shorthand: -``` +```bash $ erb -P u.erb # Raises NameError: "undefined local variable or method 'encoding'" ``` @@ -142,7 +145,7 @@ $ erb -P u.erb # Raises NameError: "undefined local variable or method 'encoding You can use option `-r` to load a library; the option may be given multiple times, to load multiple libraries: -``` +```bash $ erb -r csv -r bigdecimal t.erb ``` @@ -182,13 +185,14 @@ $ erb -U t.erb Use option `-v` to turn on verbose output: ```bash -$ $ "<%= $VERBOSE %>" | erb -"false" -$ echo "<%= $VERBOSE %>" | erb -v -"true" +$ echo "<%= \$VERBOSE %>" | erb +false + +$ echo "<%= \$VERBOSE %>" | erb -v +true ``` -### `-v`: Print \ERB Version +### `--version`: Print \ERB Version Use option `--version` to print the \ERB version string: @@ -205,6 +209,7 @@ which is the Ruby code that is to be run when ERB#result is called: $ cat t.erb <%= RUBY_VERSION %> <%= Time.now %> + $ erb -x t.erb #coding:UTF-8 _erbout = +''; _erbout.<<(( RUBY_VERSION ).to_s); _erbout.<< "\n".freeze @@ -230,11 +235,11 @@ The option may be given multiple times to set multiple variables: ```bash $ echo "<%= foo %> <%= bar %>" | erb foo=1 bar=2 -"1 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 +[suppressing unwanted newlines]: rdoc-ref:ERB@Suppressing+Unwanted+Newlines diff --git a/lib/erb.rb b/lib/erb.rb index a4b481a..0c4653d 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -53,7 +53,7 @@ # # Here's how \ERB works: # -# - You can create a *template*: a plain-text string 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*. # @@ -63,10 +63,12 @@ # 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' -# erb.result(binding) # => "The magic word is xyzzy." +# ``` +# template = 'The magic word is <%= magic_word %>.' +# erb = ERB.new(template) +# magic_word = 'xyzzy' +# erb.result(binding) # => "The magic word is xyzzy." +# ``` # # The above call to #result passes argument `binding`, # which contains the binding of variable `magic_word` to its string value `'xyzzy'`. @@ -74,21 +76,27 @@ # 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." +# ``` +# 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: # -# template = '<% File.write("t.txt", "Some stuff.") %>' -# ERB.new(template).result -# File.read('t.txt') # => "Some stuff." +# ``` +# 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. # -# template = 'Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.' -# ERB.new(template).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 # @@ -106,11 +114,10 @@ # 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 `erb`. -# 4. Method call `erb.result` generates a string that contains the run-time value of `Time.now`, +# 3. 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 -# \ERB object may be re-used: +# The \ERB object may be re-used: # # ``` # erb.result @@ -148,14 +155,14 @@ # ## Bindings # # A call to method #result, which produces the formatted result string, -# requires a [Binding object][binding object] as its argument. +# requires a [`Binding` object][binding object] as its argument. # # The binding object provides the bindings for expressions in [expression tags][expression tags]. # # There are three ways to provide the required binding: # -# - [Default binding][default binding]. -# - [Local binding][local binding]. +# - [Default binding][default binding] +# - [Local binding][local binding] # - [Augmented binding][augmented binding] # # ### Default Binding @@ -174,6 +181,9 @@ # The current process is <%= $0 %>. # TEMPLATE # puts ERB.new(template).result +# ``` +# +# ``` # The Ruby copyright is "ruby - Copyright (C) 1993-2025 Yukihiro Matsumoto". # The current process is irb. # ``` @@ -183,7 +193,7 @@ # ### Local Binding # # The default binding is *not* sufficient for an expression -# that refers to a a constant or variable that is not defined there: +# that refers to a constant or variable that is not defined there: # # ``` # Foo = 1 # Defines local constant Foo. @@ -209,6 +219,9 @@ # # ``` # puts erb.result(binding) +# ``` +# +# ``` # The current value of constant Foo is 1. # The current value of variable foo is 2. # The Ruby copyright is "ruby - Copyright (C) 1993-2025 Yukihiro Matsumoto". @@ -246,6 +259,9 @@ # ``` # hash = {bar: 3, baz: 4} # puts erb.result_with_hash(hash) +# ``` +# +# ``` # The current value of variable bar is 3. # The current value of variable baz is 4. # The Ruby copyright is "ruby - Copyright (C) 1993-2025 Yukihiro Matsumoto". @@ -268,7 +284,7 @@ # # You can embed a Ruby expression in a template using an *expression tag*. # -# Its syntax is `<%= _expression_ %>`, +# Its syntax is `<%= expression %>`, # where *expression* is any valid Ruby expression. # # When you call method #result, @@ -298,7 +314,7 @@ # # You can embed Ruby executable code in template using an *execution tag*. # -# Its syntax is `<% _code_ %>`, +# Its syntax is `<% code %>`, # where *code* is any valid Ruby code. # # When you call method #result, @@ -306,17 +322,17 @@ # (generating no text in the result): # # ``` -# ERB.new('foo <% Dir.chdir("C:/") %> bar').result # => "foo bar" +# ERB.new('foo <% Dir.chdir(Dir.pwd) %> bar').result # => "foo bar" # ``` # # Whitespace before and after the embedded code is optional: # # ``` -# ERB.new('foo <%Dir.chdir("C:/")%> bar').result # => "foo bar" +# ERB.new('foo <%Dir.chdir(Dir.pwd)%> bar').result # => "foo bar" # ``` # # You can interleave text with execution tags to form a control structure -# such as a conditional, a loop, or a `case` statements. +# such as a conditional, a loop, or a `case` statement. # # Conditional: # @@ -386,7 +402,7 @@ # #### Shorthand Format for Execution Tags # # You can use keyword argument `trim_mode: '%'` to enable a shorthand format for execution tags; -# this example uses the shorthand format `% _code_` instead of `<% _code_ %>`: +# this example uses the shorthand format `% code` instead of `<% code %>`: # # ``` # template = <