From 061f9b8bfdde47371df97a1d3d6a4c4eec06b723 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 15 Sep 2025 17:48:56 -0500 Subject: [ruby/erb] [DOC] More on class ERB (https://github.com/ruby/erb/pull/69) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [DOC] More on class …ERB * [DOC] More on class …ERB * More * More * More https://github.com/ruby/erb/commit/d9d73ed58e --- lib/erb.rb | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 109 insertions(+), 12 deletions(-) diff --git a/lib/erb.rb b/lib/erb.rb index d4f43e0772..f3f2ae3f47 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -189,7 +189,17 @@ require 'erb/util' # # When you call method #result, # the method executes the code and removes the entire execution tag -# (generating no text in the result). +# (generating no text in the result): +# +# ``` +# ERB.new('foo <% Dir.chdir("C:/") %> bar').result # => "foo bar" +# ``` +# +# Whitespace before and after the embedded code is optional: +# +# ``` +# ERB.new('foo <%Dir.chdir("C:/")%> 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. @@ -261,7 +271,7 @@ require 'erb/util' # # #### Shorthand Format for Execution Tags # -# You can give `trim_mode: '%'` to enable a 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_ %>`: # # ``` @@ -283,6 +293,90 @@ require 'erb/util' # Note that in the shorthand format, the character `'%'` must be the first character in the code line # (no leading whitespace). # +# #### Suppressing Unwanted Blank Lines +# +# With keyword argument `trim_mode` not given, +# all blank lines go into the result: +# +# ``` +# s = < +# <%= RUBY_VERSION %> +# <% end %> +# EOT +# ERB.new(s).result.lines.each {|line| puts line.inspect } +# "\n" +# "3.4.5\n" +# "\n" +# ``` +# +# You can give `trim_mode: '-'`, you can suppress each blank line +# whose source line ends with `-%>` (instead of `%>`): +# +# ``` +# s = < +# <%= RUBY_VERSION %> +# <% end -%> +# EOT +# ERB.new(s, trim_mode: '-').result.lines.each {|line| puts line.inspect } +# "3.4.5\n" +# ``` +# +# It is an error to use the trailing `'-%>'` notation without `trim_mode: '-'`: +# +# ``` +# ERB.new(s).result.lines.each {|line| puts line.inspect } # Raises SyntaxError. +# ``` +# +# #### Suppressing Unwanted Newlines +# +# Consider this input string: +# +# ``` +# s = < +# <%= RUBY_VERSION %> +# foo <% RUBY_VERSION %> +# foo <%= RUBY_VERSION %> +# EOT +# ``` +# +# With keyword argument `trim_mode` not given, all newlines go into the result: +# +# ``` +# ERB.new(s).result.lines.each {|line| puts line.inspect } +# "\n" +# "3.4.5\n" +# "foo \n" +# "foo 3.4.5\n" +# ``` +# +# You can give `trim_mode: '>'` to suppress the trailing newline +# for each line that ends with `'%<'` (regardless of its beginning): +# +# ``` +# ERB.new(s, trim_mode: '>').result.lines.each {|line| puts line.inspect } +# "3.4.5foo foo 3.4.5" +# ``` +# +# You can give `trim_mode: '<>'` to suppress the trailing newline +# for each line that both begins with `'<%'` and ends with `'%<'`: +# +# ``` +# ERB.new(s, trim_mode: '<>').result.lines.each {|line| puts line.inspect } +# "3.4.5foo \n" +# "foo 3.4.5\n" +# ``` +# +# #### Combining Trim Modes +# +# You can combine certain trim modes: +# +# - `'%-'`: Enable shorthand and omit each blank line ending with `'%>'`. +# - `'%>'`: Enable shorthand and omit newline for each line ending with `'%>'`. +# - `'%<>'`: Enable shorthand and omit newline for each line starting with `'<%'` and ending with `'%>'`. +# # ### Comment Tags # # You can embed a comment in a template using a *comment tag*; @@ -537,19 +631,19 @@ class ERB # # **Keyword Argument `trim_mode`** # - # When keyword argument `trim_mode` has a string value, - # that value may be one of: + # You can use keyword argument `trim_mode: '%'` + # to enable the [shorthand format][shorthand format] for execution tags. + # + # This value allows [blank line control][blank line control]: # - # - `'%'`: Enable [shorthand format][shorthand format] for execution tags. # - `'-'`: Omit each blank line ending with `'%>'`. + # + # Other values allow [newline control][newline control]: + # # - `'>'`: Omit newline for each line ending with `'%>'`. # - `'<>'`: Omit newline for each line starting with `'<%'` and ending with `'%>'`. # - # The value may also be certain combinations of the above. - # - # - `'%-'`: Enable shorthand and omit each blank line ending with `'%>'`. - # - `'%>'`: Enable shorthand and omit newline for each line ending with `'%>'`. - # - `'%<>'`: Enable shorthand and omit newline for each line starting with `'<%'` and ending with `'%>'`. + # You can also [combine trim modes][combine trim modes]. # # **Keyword Argument `eoutvar`** # @@ -578,9 +672,12 @@ class ERB # However, their values, if given, are handled thus: # # - `safe_level`: ignored. - # - `legacy_trim_mode: overrides keyword argument `trim_mode`. - # - `legacy_eoutvar: overrides keyword argument `eoutvar`. + # - `legacy_trim_mode`: overrides keyword argument `trim_mode`. + # - `legacy_eoutvar`: overrides keyword argument `eoutvar`. # + # [blank line control]: rdoc-ref:ERB@Suppressing+Unwanted+Blank+Lines + # [combine trim modes]: rdoc-ref:ERB@Combining+Trim+Modes + # [newline control]: rdoc-ref:ERB@Suppressing+Unwanted+Newlines # [shorthand format]: rdoc-ref:ERB@Shorthand+Format+for+Execution+Tags # def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: '_erbout') -- cgit v1.2.3