From 9ebee947a4d1379806158d9b1ef74c0a9c01ce4e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 22:28:56 +0100 Subject: [PATCH 1/9] [DOC] Doc for attribute src --- lib/erb.rb | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/lib/erb.rb b/lib/erb.rb index e72fe95..1b0ec2e 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -878,7 +878,48 @@ def make_compiler(trim_mode) ERB::Compiler.new(trim_mode) end - # The Ruby code generated by ERB + # :markup: markdown + # + # Returns a string containing the Ruby code that, when executed, generates the result; + # the code is executed by method #result, + # and by its wrapper methods #result_with_hash and #run: + # + # ``` + # s = 'The time is <%= Time.now %>.' + # template = ERB.new(s) + # template.src + # # => "#coding:UTF-8\n_erbout = +''; _erbout.<< \"The time is \".freeze; _erbout.<<(( Time.now ).to_s); _erbout.<< \".\".freeze; _erbout" + # template.result + # # => "The time is 2025-09-18 15:58:08 -0500." + # ``` + # + # In a more readable format: + # + # ``` + # # puts template.src.split('; ') + # # #coding:UTF-8 + # # _erbout = +'' + # # _erbout.<< "The time is ".freeze + # # _erbout.<<(( Time.now ).to_s) + # # _erbout.<< ".".freeze + # # _erbout + # ``` + # + # Variable `_erbout` is used to store the intermediate results in the code; + # the name `_erbout` is the default in ERB.new, + # and can be changed via keyword argument `eoutvar`: + # + # ``` + # template = ERB.new(s, eoutvar: '_foo') + # puts template.src.split('; ') + # #coding:UTF-8 + # _foo = +'' + # _foo.<< "The time is ".freeze + # _foo.<<(( Time.now ).to_s) + # _foo.<< ".".freeze + # _foo + # ``` + # attr_reader :src # :markup: markdown From 119259437078d1b32f93116e07110de28c71ba7a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 22:36:57 +0100 Subject: [PATCH 2/9] [DOC] Doc for constant NOT_GIVEN --- lib/erb.rb | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/erb.rb b/lib/erb.rb index 1b0ec2e..9557f66 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -868,6 +868,10 @@ def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eou @lineno = 0 @_init = self.class.singleton_class end + + # :markup: markdown + # + # Placeholder constant; used as default value for certain method arguments. NOT_GIVEN = defined?(Ractor) ? Ractor.make_shareable(Object.new) : Object.new private_constant :NOT_GIVEN From 3bfe90231ff8ff360194cc7f9092a9930117e5ff Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 22:42:28 +0100 Subject: [PATCH 3/9] [DOC] Doc for constant VERSION --- lib/erb/version.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/erb/version.rb b/lib/erb/version.rb index 1c2c6fe..7d0b384 100644 --- a/lib/erb/version.rb +++ b/lib/erb/version.rb @@ -1,5 +1,5 @@ # frozen_string_literal: true class ERB - # The version string + # The string \ERB version. VERSION = '5.0.2' end From c1e45b46e2a961e3aaac42aadf97fcbffc8941f2 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 22:48:33 +0100 Subject: [PATCH 4/9] [DOC] Correct link in doc for attribute #encoding --- lib/erb.rb | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/erb.rb b/lib/erb.rb index 9557f66..053d161 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -929,9 +929,10 @@ def make_compiler(trim_mode) # :markup: markdown # # Returns the encoding of `self`; - # see [encoding][encoding]. + # see [Encodings][encodings]: + # + # [encodings]: rdoc-ref:ERB@Encodings # - # [encoding]: https://docs.ruby-lang.org/en/master/Encoding.html attr_reader :encoding # :markup: markdown From e84c72c9061789e23e3034797244c277b52c5e1d Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 22:52:28 +0100 Subject: [PATCH 5/9] [DOC] Tweak for ERB.new (argument eoutvar) --- lib/erb.rb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/erb.rb b/lib/erb.rb index 053d161..5986109 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -815,7 +815,9 @@ def self.version # **Keyword Argument `eoutvar`** # # The string value of keyword argument `eoutvar` specifies the name of the variable - # that method #result uses to construct its result string. + # that method #result uses to construct its result string; + # see #src. + # # This is useful when you need to run multiple \ERB templates through the same binding # and/or when you want to control where output ends up. # From 36e68399a2b482f0fa63e1c8d50e6bb224cdd918 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 23:00:53 +0100 Subject: [PATCH 6/9] [DOC] Remove example from ERB.version (will get out-of-date) --- lib/erb.rb | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/lib/erb.rb b/lib/erb.rb index 5986109..2aa985a 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -777,12 +777,7 @@ class ERB # :call-seq: # self.version -> string # - # Returns the string revision for \ERB: - # - # ``` - # ERB.version # => "4.0.4" - # ``` - # + # Returns the string \ERB version. def self.version VERSION end @@ -817,7 +812,7 @@ def self.version # The string value of keyword argument `eoutvar` specifies the name of the variable # that method #result uses to construct its result string; # see #src. - # + # # This is useful when you need to run multiple \ERB templates through the same binding # and/or when you want to control where output ends up. # From 0f7897ce09ed762a5256602556704af1cf445a05 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 23:12:56 +0100 Subject: [PATCH 7/9] [DOC] Doc for ERB#make_compiler --- lib/erb.rb | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/lib/erb.rb b/lib/erb.rb index 2aa985a..e34f57f 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -872,8 +872,19 @@ def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eou NOT_GIVEN = defined?(Ractor) ? Ractor.make_shareable(Object.new) : Object.new private_constant :NOT_GIVEN - ## - # Creates a new compiler for ERB. See ERB::Compiler.new for details + # :markup: markdown + # + # :call-seq: + # make_compiler -> erb_compiler + # + # Returns a new ERB::Compiler with the given `trim_mode`; + # for `trim_mode` values, see ERB.new: + # + # ``` + # template = ERB.new('').make_compiler(nil) + # # => # + # ``` + # def make_compiler(trim_mode) ERB::Compiler.new(trim_mode) From 2ef65ee88135492998824ca0255190e006095362 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 23:18:58 +0100 Subject: [PATCH 8/9] [DOC] Correct error in #make_compiler example --- lib/erb.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/erb.rb b/lib/erb.rb index e34f57f..8483431 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -881,7 +881,7 @@ def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eou # for `trim_mode` values, see ERB.new: # # ``` - # template = ERB.new('').make_compiler(nil) + # ERB.new('').make_compiler(nil) # # => # # ``` # From bfbb07181da119b70660d411253daed2ca43cae7 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 18 Sep 2025 23:38:06 +0100 Subject: [PATCH 9/9] [DOC] Doc for ERB#set_eoutvar --- lib/erb.rb | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/lib/erb.rb b/lib/erb.rb index 8483431..71ee886 100644 --- a/lib/erb.rb +++ b/lib/erb.rb @@ -974,10 +974,35 @@ def location=((filename, lineno)) @lineno = lineno if lineno end + # :markup: markdown + # + # :call-seq: + # set_eoutvar(compiler, eoutvar = '_erbout') -> [eoutvar] # - # Can be used to set _eoutvar_ as described in ERB::new. It's probably - # easier to just use the constructor though, since calling this method - # requires the setup of an ERB _compiler_ object. + # Sets the `eoutvar` value in the ERB::Compiler object `compiler`; + # returns a 1-element array containing the value of `eoutvar`: + # + # ``` + # template = ERB.new('') + # compiler = template.make_compiler(nil) + # pp compiler + # # + # template.set_eoutvar(compiler, '_foo') # => ["_foo"] + # pp compiler + # # + # ``` # def set_eoutvar(compiler, eoutvar = '_erbout') compiler.put_cmd = "#{eoutvar}.<<"