rbs 3.10.0 → 4.0.0.dev.1

data/stdlib/erb/0/erb.rbs

@@ -1,804 +1,451 @@
 # <!-- rdoc-file=lib/erb.rb -->
-# Class **ERB** (the name stands for **Embedded Ruby**)
-# is an easy-to-use, but also very powerful, [template
-# processor](https://en.wikipedia.org/wiki/Template_processor).
-# ## Usage
-# Before you can use ERB, you must first require it
-# (examples on this page assume that this has been done):
+# # 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'
 #
-# ## In Brief
-# Here's how ERB works:
-# *   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:
-# *   [Expression tags](rdoc-ref:ERB@Expression+Tags):
-#      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."
-#
-#     The above call to #result passes argument `binding`,
-#     which contains the binding of variable `magic_word` to its string value
-#     `'xyzzy'`.
-#     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](rdoc-ref:ERB@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."
-#
-# *   [Comment tags](rdoc-ref:ERB@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."
-#
-# ## Some Simple Examples
-# Here's a simple example of ERB in action:
-#     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 `template`.
-#      Its embedded [expression tag](rdoc-ref:ERB@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`.
-# 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:
-#     erb.result
-# # => "The time is 2025-09-09 10:49:33 -0500."
-#
-# Another example:
-#     template = 'The magic word is <%= magic_word %>.'
-# erb = ERB.new(template)
-# magic_word = 'abracadabra'
-# erb.result(binding)
-# # => "The magic word is abracadabra."
-#
-# Details:
-# 1.  As before, a plain-text string is assigned to variable `template`.
-#      Its embedded [expression tag](rdoc-ref:ERB@Expression+Tags) `'<%=
-#     magic_word %>'` has a variable *name*, `magic_word`.
-# 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 `erb.result(binding)` generates a string
-#      that contains the *value* of `magic_word`.
-# As before, the ERB object may be re-used:
-#     magic_word = 'xyzzy'
-# erb.result(binding)
-# # => "The magic word is xyzzy."
-#
-# ## Bindings
-# A call to method #result, which produces the formatted result string,
-# requires a [Binding object](https://docs.ruby-lang.org/en/master/Binding.html)
-# as its argument.
-# The binding object provides the bindings for expressions in [expression
-# tags](rdoc-ref:ERB@Expression+Tags).
-# There are three ways to provide the required binding:
-# *   [Default binding](rdoc-ref:ERB@Default+Binding).
-# *   [Local binding](rdoc-ref:ERB@Local+Binding).
-# *   [Augmented binding](rdoc-ref:ERB@Augmented+Binding)
-# ### Default Binding
-# When you pass no `binding` argument to method #result,
-# the method uses its default binding: the one returned by method #new_toplevel.
-# This binding has the bindings defined by Ruby itself,
-# which are those for Ruby's constants and variables.
-# That binding is sufficient for an expression tag that refers only to Ruby's
-# constants and variables;
-# these expression tags refer only to Ruby's global constant `RUBY_COPYRIGHT`
-# and global variable `$0`:
-#     template = <<TEMPLATE
-# The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>.
-# 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.
-#
-# (The current process is `irb` because that's where we're doing these
-# examples!)
-# ### Local Binding
-# The default binding is *not* sufficient for an expression
-# that refers to a a constant or variable that is not defined there:
-#     Foo = 1 # Defines local constant Foo.
-# foo = 2 # Defines local variable foo.
-# template = <<TEMPLATE
-# The current value of constant Foo is <%= Foo %>.
-# The current value of variable foo is <%= foo %>.
-# The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>.
-# The current process is <%= $0 %>.
-# TEMPLATE
-# erb = ERB.new(template)
-#
-# This call below raises `NameError` because although `Foo` and `foo` are
-# defined locally,
-# they are not defined in the default binding:
-#     erb.result # Raises NameError.
-#
-# To make the locally-defined constants and variables available,
-# you can call #result with the local binding:
-#     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".
-# The current process is irb.
-#
-# ### Augmented Binding
-# Another way to make variable bindings (but not constant bindings) available
-# is to use method #result_with_hash(hash);
-# the passed hash has name/value pairs that are to be used to define and assign
-# variables
-# in a copy of the default binding:
-#     template = <<TEMPLATE
-# The current value of variable bar is <%= bar %>.
-# The current value of variable baz is <%= baz %>.
-# The Ruby copyright is <%= RUBY_COPYRIGHT.inspect %>.
-# The current process is <%= $0 %>.
-# TEMPLATE
-# erb = ERB.new(template)
-#
-# Both of these calls raise `NameError`, because `bar` and `baz`
-# are not defined in either the default binding or the local binding.
-#     puts erb.result          # Raises NameError.
-# puts erb.result(binding) # Raises NameError.
-#
-# This call passes a hash that causes `bar` and `baz` to be defined
-# in a new binding (derived from #new_toplevel):
-#     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".
-# The current process is irb.
-#
-# ## Tags
-# The examples above use expression tags.
-# These are the tags available in ERB:
-# *   [Expression tag](rdoc-ref:ERB@Expression+Tags): the tag contains a Ruby
-#     expression;
-#      in the result, the entire tag is to be replaced with the run-time value
-#     of the expression.
-# *   [Execution tag](rdoc-ref:ERB@Execution+Tags): the tag contains Ruby code;
-#      in the result, the entire tag is to be replaced with the run-time value
-#     of the code.
-# *   [Comment tag](rdoc-ref:ERB@Comment+Tags): the tag contains comment code;
-#      in the result, the entire tag is to be omitted.
-# ### Expression Tags
-# You can embed a Ruby expression in a template using an *expression tag*.
-# Its syntax is `<%= *expression* %>`,
-# where *expression* is any valid Ruby expression.
-# When you call method #result,
-# the method evaluates the expression and replaces the entire expression tag
-# with the expression's value:
-#     ERB.new('Today is <%= Date::DAYNAMES[Date.today.wday] %>.').result
-# # => "Today is Monday."
-# ERB.new('Tomorrow will be <%= Date::DAYNAMES[Date.today.wday + 1] %>.').result
-# # => "Tomorrow will be Tuesday."
-# ERB.new('Yesterday was <%= Date::DAYNAMES[Date.today.wday - 1] %>.').result
-# # => "Yesterday was Sunday."
-#
-# Note that whitespace before and after the expression
-# is allowed but not required,
-# and that such whitespace is stripped from the result.
-#     ERB.new('My appointment is on <%=Date::DAYNAMES[Date.today.wday + 2]%>.').result
-# # => "My appointment is on Wednesday."
-# ERB.new('My appointment is on <%=     Date::DAYNAMES[Date.today.wday + 2]    %>.').result
-# # => "My appointment is on Wednesday."
-#
-# ### Execution Tags
-# You can embed Ruby executable code in template using an *execution tag*.
-# Its syntax is `<% *code* %>`,
-# where *code* is any valid Ruby code.
-# When you call method #result,
-# the method executes the code and removes the entire execution tag
-# (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.
-# Conditional:
-#     template = <<TEMPLATE
-# <% if verbosity %>
-# An error has occurred.
-# <% else %>
-# Oops!
-# <% end %>
-# TEMPLATE
-# erb = ERB.new(template)
-# verbosity = true
-# erb.result(binding)
-# # => "\nAn error has occurred.\n\n"
-# verbosity = false
-# erb.result(binding)
-# # => "\nOops!\n\n"
-#
-# Note that the interleaved text may itself contain expression tags:
-# Loop:
-#     template = <<TEMPLATE
-# <% Date::ABBR_DAYNAMES.each do |dayname| %>
-# <%= dayname %>
-# <% end %>
-# TEMPLATE
-# ERB.new(template).result
-# # => "\nSun\n\nMon\n\nTue\n\nWed\n\nThu\n\nFri\n\nSat\n\n"
-#
-# Other, non-control, lines of Ruby code may be interleaved with the text,
-# and the Ruby code may itself contain regular Ruby comments:
-#     template = <<TEMPLATE
-# <% 3.times do %>
-# <%= Time.now %>
-# <% sleep(1) # Let's make the times different. %>
-# <% end %>
-# TEMPLATE
-# ERB.new(template).result
-# # => "\n2025-09-09 11:36:02 -0500\n\n\n2025-09-09 11:36:03 -0500\n\n\n2025-09-09 11:36:04 -0500\n\n\n"
-#
-# The execution tag may also contain multiple lines of code:
-#     template = <<TEMPLATE
-# <%
-#   (0..2).each do |i|
-#     (0..2).each do |j|
-# %>
-# * <%=i%>,<%=j%>
-# <%
-#     end
-#   end
-# %>
-# TEMPLATE
-# ERB.new(template).result
-# # => "\n* 0,0\n\n* 0,1\n\n* 0,2\n\n* 1,0\n\n* 1,1\n\n* 1,2\n\n* 2,0\n\n* 2,1\n\n* 2,2\n\n"
-#
-# #### 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* %>`:
-#     template = <<TEMPLATE
-# % priorities.each do |priority|
-#   * <%= priority %>
-# % end
-# TEMPLATE
-# erb = ERB.new(template, trim_mode: '%')
-# priorities = [ 'Run Ruby Quiz',
-#                'Document Modules',
-#                'Answer Questions on Ruby Talk' ]
-# puts erb.result(binding)
-#   * Run Ruby Quiz
-#   * Document Modules
-#   * Answer Questions on Ruby Talk
-#
-# 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:
-#     template = <<TEMPLATE
-# <% if true %>
-# <%= RUBY_VERSION %>
-# <% end %>
-# TEMPLATE
-# ERB.new(template).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 `%>`):
-#     template = <<TEMPLATE
-# <% if true -%>
-# <%= RUBY_VERSION %>
-# <% end -%>
-# TEMPLATE
-# ERB.new(template, 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(template).result.lines.each {|line| puts line.inspect } # Raises SyntaxError.
-#
-# #### Suppressing Unwanted Newlines
-# Consider this template:
-#     template = <<TEMPLATE
-# <% RUBY_VERSION %>
-# <%= RUBY_VERSION %>
-# foo <% RUBY_VERSION %>
-# foo <%= RUBY_VERSION %>
-# TEMPLATE
-#
-# With keyword argument `trim_mode` not given, all newlines go into the result:
-#     ERB.new(template).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(template, 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(template, 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*;
-# its syntax is `<%# *text* %>`,
-# where *text* is the text of the comment.
-# When you call method #result,
-# it removes the entire comment tag
-# (generating no text in the result).
-# Example:
-#     template = 'Some stuff;<%# Note to self: figure out what the stuff is. %> more stuff.'
-# ERB.new(template).result # => "Some stuff; more stuff."
-#
-# A comment tag may appear anywhere in the template.
-# Note that the beginning of the tag must be `'<%#'`, not `'<% #'`.
-# In this example, the tag begins with `'<% #'`, and so is an execution tag, not
-# a comment tag;
-# the cited code consists entirely of a Ruby-style comment (which is of course
-# ignored):
-#     ERB.new('Some stuff;<% # Note to self: figure out what the stuff is. %> more stuff.').result
-# # => "Some stuff;"
-#
-# ## Encodings
-# An ERB object has an
-# [encoding](https://docs.ruby-lang.org/en/master/Encoding.html),
-# which is by default the encoding of the template string;
-# the result string will also have that encoding.
-#     template = <<TEMPLATE
-# <%# Comment. %>
-# TEMPLATE
-# erb = ERB.new(template)
-# template.encoding   # => #<Encoding:UTF-8>
-# erb.encoding        # => #<Encoding:UTF-8>
-# erb.result.encoding # => #<Encoding:UTF-8>
-#
-# You can specify a different encoding by adding a [magic
-# comment](https://docs.ruby-lang.org/en/master/syntax/comments_rdoc.html#label-
-# Magic+Comments)
-# at the top of the given template:
-#     template = <<TEMPLATE
-# <%#-*- coding: Big5 -*-%>
-# <%# Comment. %>
-# TEMPLATE
-# erb = ERB.new(template)
-# template.encoding   # => #<Encoding:UTF-8>
-# erb.encoding        # => #<Encoding:Big5>
-# erb.result.encoding # => #<Encoding:Big5>
-#
-# ## Error Reporting
-# Consider this template (containing an error):
-#     template = '<%= nosuch %>'
-# erb = ERB.new(template)
-#
-# When ERB reports an error,
-# it includes a file name (if available) and a line number;
-# the file name comes from method #filename, the line number from method
-# #lineno.
-# Initially, those values are `nil` and `0`, respectively;
-# these initial values are reported as `'(erb)'` and `1`, respectively:
-#     erb.filename # => nil
-# erb.lineno   # => 0
-# erb.result
-# (erb):1:in '<main>': undefined local variable or method 'nosuch' for main (NameError)
-#
-# You can use methods #filename= and #lineno= to assign values
-# that are more meaningful in your context:
-#     erb.filename = 't.txt'
-# erb.lineno = 555
-# erb.result
-# t.txt:556:in '<main>': undefined local variable or method 'nosuch' for main (NameError)
-#
-# You can use method #location= to set both values:
-#     erb.location = ['u.txt', 999]
-# erb.result
-# u.txt:1000:in '<main>': undefined local variable or method 'nosuch' for main (NameError)
-#
-# ## Plain Text with Embedded Ruby
-# Here's a plain-text template;
-# it uses the literal notation `'%q{ ... }'` to define the template
-# (see [%q
-# literals](https://docs.ruby-lang.org/en/master/syntax/literals_rdoc.html#label
-# -25q-3A+Non-Interpolable+String+Literals));
-# this avoids problems with backslashes.
+#     x = 42
+#     template = ERB.new <<-EOF
+#       The value of x is: <%= x %>
+#     EOF
+#     puts template.result(binding)
+#
+# *Prints:* 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 %> (`<% #` doesn't work. Don't use Ruby comments.)
+#     % 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 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
+#
+# *Prints:* _*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 `%q{...}` 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
+#       From:  James Edward Gray II <james@grayproductions.net>
+#       To:  <%= to %>
+#       Subject:  Addressing Needs
+#
+#       <%= to[/\w+/] %>:
 #
-# <%= to[/\w+/] %>:
+#       Just wanted to send a quick note assuring that your needs are being
+#       addressed.
 #
-# 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:
 #
-# 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
 #
-# <%# ignore numerous minor requests -- focus on priorities %>
-# % priorities.each do |priority|
-#   * <%= priority %>
-# % end
+#       Thanks for your patience.
 #
-# Thanks for your patience.
+#       James Edward Gray II
+#     }.gsub(/^  /, '')
 #
-# James Edward Gray II
-# }
+#     message = ERB.new(template, trim_mode: "%<>")
 #
-# The template will need these:
-#     to = 'Community Spokesman <spokesman@ruby_community.org>'
-# priorities = [ 'Run Ruby Quiz',
-#                'Document Modules',
-#                'Answer Questions on Ruby Talk' ]
+#     # Set up template data.
+#     to = "Community Spokesman <spokesman@ruby_community.org>"
+#     priorities = [ "Run Ruby Quiz",
+#                    "Document Modules",
+#                    "Answer Questions on Ruby Talk" ]
 #
-# Finally, create the ERB object and get the result
-#     erb = ERB.new(template, trim_mode: '%<>')
-# puts erb.result(binding)
+#     # Produce result.
+#     email = message.result
+#     puts email
 #
-# From:  James Edward Gray II <james@grayproductions.net>
-# To:  Community Spokesman <spokesman@ruby_community.org>
-# Subject:  Addressing Needs
+# *Generates:*
 #
-# Community:
+#     From:  James Edward Gray II <james@grayproductions.net>
+#     To:  Community Spokesman <spokesman@ruby_community.org>
+#     Subject:  Addressing Needs
 #
-# Just wanted to send a quick note assuring that your needs are being
-# addressed.
+#     Community:
 #
-# I want you to know that my team will keep working on the issues,
-# especially:
+#     Just wanted to send a quick note assuring that your needs are being addressed.
 #
-# * Run Ruby Quiz
-# * Document Modules
-# * Answer Questions on Ruby Talk
+#     I want you to know that my team will keep working on the issues, especially:
 #
-# Thanks for your patience.
+#         * Run Ruby Quiz
+#         * Document Modules
+#         * Answer Questions on Ruby Talk
 #
-# James Edward Gray II
+#     Thanks for your patience.
 #
-# ## HTML with Embedded Ruby
-# This example shows an HTML template.
-# First, here's a custom class, `Product`:
+#     James Edward Gray II
+#
+# ### Ruby in HTML
+#
+# ERB is often used in `.rhtml` 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
-#
-# The template below will need these values:
-#     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!')
-#
-# Here's the HTML:
-#     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>
-# TEMPLATE
-#
-# Finally, create the ERB object and get the result (omitting some blank lines):
-#     erb = ERB.new(template)
-# puts erb.result(toy.get_binding)
-# <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>
-#
-# ## Other Template Processors
-# Various Ruby projects have their own template processors.
-# The Ruby Processing System [RDoc](https://ruby.github.io/rdoc), for example,
-# has one that can be used elsewhere.
-# Other popular template processors may found in the [Template
-# Engines](https://www.ruby-toolbox.com/categories/template_engines) page
-# of the Ruby Toolbox.
+#       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)
+#
+# *Generates (some blank lines removed):*
+#
+#     <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. For example, RDoc, distributed with Ruby, uses its own template
+# engine, which can be reused elsewhere.
+#
+# Other popular engines could be found in the corresponding
+# [Category](https://www.ruby-toolbox.com/categories/template_engines) of The
+# Ruby Toolbox.
 #
 class ERB
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - self.version -> string
+  #   - version()
   # -->
-  # Returns the string ERB version.
+  # Returns revision information for the erb.rb module.
   #
   def self.version: () -> String
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - ERB.new(template, trim_mode: nil, eoutvar: '_erbout')
+  #   - new(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: '_erbout')
   # -->
-  # Returns a new ERB object containing the given string `template`.
-  # For details about `template`, its embedded tags, and generated results, see
-  # ERB.
-  # **Keyword Argument `trim_mode`**
-  # You can use keyword argument `trim_mode: '%'`
-  # to enable the [shorthand
-  # format](rdoc-ref:ERB@Shorthand+Format+for+Execution+Tags) for execution tags.
-  # This value allows [blank line
-  # control](rdoc-ref:ERB@Suppressing+Unwanted+Blank+Lines):
-  # *   `'-'`: Omit each blank line ending with `'%>'`.
-  # Other values allow [newline
-  # control](rdoc-ref:ERB@Suppressing+Unwanted+Newlines):
-  # *   `'>'`: Omit newline for each line ending with `'%>'`.
-  # *   `'<>'`: Omit newline for each line starting with `'<%'` and ending with
-  #     `'%>'`.
-  # You can also [combine trim modes](rdoc-ref:ERB@Combining+Trim+Modes).
-  # **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;
-  # 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.
-  # It's good practice to choose a variable name that begins with an underscore:
-  # `'_'`.
+  # Constructs a new ERB object with the template specified in *str*.
+  #
+  # An ERB object works by building a chunk of Ruby code that will output the
+  # completed template when run.
+  #
+  # If *trim_mode* is passed a String containing one or more of the following
+  # modifiers, ERB will adjust its code generation as listed:
+  #
+  #     %  enables Ruby code processing for lines beginning with %
+  #     <> omit newline for lines starting with <% and ending in %>
+  #     >  omit newline for lines ending in %>
+  #     -  omit blank lines ending in -%>
+  #
+  # *eoutvar* can be used to set the name of the variable ERB will build up its
+  # output in.  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.  Pass
+  # the name of the variable to be used inside a String.
+  #
+  # ### Example
+  #
+  #     require "erb"
+  #
+  #     # build data class
+  #     class Listings
+  #       PRODUCT = { :name => "Chicken Fried Steak",
+  #                   :desc => "A well messages pattie, breaded and fried.",
+  #                   :cost => 9.95 }
+  #
+  #       attr_reader :product, :price
+  #
+  #       def initialize( product = "", price = "" )
+  #         @product = product
+  #         @price = price
+  #       end
+  #
+  #       def build
+  #         b = binding
+  #         # create and run templates, filling member data variables
+  #         ERB.new(<<~'END_PRODUCT', trim_mode: "", eoutvar: "@product").result b
+  #           <%= PRODUCT[:name] %>
+  #           <%= PRODUCT[:desc] %>
+  #         END_PRODUCT
+  #         ERB.new(<<~'END_PRICE', trim_mode: "", eoutvar: "@price").result b
+  #           <%= PRODUCT[:name] %> -- <%= PRODUCT[:cost] %>
+  #           <%= PRODUCT[:desc] %>
+  #         END_PRICE
+  #       end
+  #     end
+  #
+  #     # setup template data
+  #     listings = Listings.new
+  #     listings.build
+  #
+  #     puts listings.product + "\n" + listings.price
+  #
+  # *Generates*
+  #
+  #     Chicken Fried Steak
+  #     A well messages pattie, breaded and fried.
+  #
+  #     Chicken Fried Steak -- 9.95
+  #     A well messages pattie, breaded and fried.
   #
   def initialize: (String, ?eoutvar: String, ?trim_mode: Integer | String | NilClass) -> untyped
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Returns 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:
-  #     template = 'The time is <%= Time.now %>.'
-  # erb = ERB.new(template)
-  # erb.src
-  # # => "#coding:UTF-8\n_erbout = +''; _erbout.<< \"The time is \".freeze; _erbout.<<(( Time.now ).to_s); _erbout.<< \".\".freeze; _erbout"
-  # erb.result
-  # # => "The time is 2025-09-18 15:58:08 -0500."
-  #
-  # In a more readable format:
-  #     # puts erb.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`:
-  #     erb = ERB.new(template, eoutvar: '_foo')
-  # puts template.src.split('; ')
-  # #coding:UTF-8
-  # _foo = +''
-  # _foo.<< "The time is ".freeze
-  # _foo.<<(( Time.now ).to_s)
-  # _foo.<< ".".freeze
-  # _foo
+  # The Ruby code generated by ERB
   #
   def src: () -> String
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Returns the encoding of `self`;
-  # see [Encodings](rdoc-ref:ERB@Encodings):
+  # The encoding to eval
   #
   def encoding: () -> Encoding
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Sets or returns the file name to be used in reporting errors;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
+  # The optional *filename* argument passed to Kernel#eval when the ERB code is
+  # run
   #
   def filename: () -> (String | NilClass)
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Sets or returns the file name to be used in reporting errors;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
+  # The optional *filename* argument passed to Kernel#eval when the ERB code is
+  # run
   #
   def filename=: (String | NilClass) -> untyped
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Sets or returns the line number to be used in reporting errors;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
+  # The optional *lineno* argument passed to Kernel#eval when the ERB code is run
   #
   def lineno: () -> Integer
 
   # <!-- rdoc-file=lib/erb.rb -->
-  # Sets or returns the line number to be used in reporting errors;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
+  # The optional *lineno* argument passed to Kernel#eval when the ERB code is run
   #
   def lineno=: (Integer) -> untyped
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - location = [filename, lineno] => [filename, lineno]
-  #   - location = filename -> filename
+  #   - location=((filename, lineno))
   # -->
-  # Sets the values of #filename and, if given, #lineno;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
+  # Sets optional filename and line number that will be used in ERB code
+  # evaluation and error reporting. See also #filename= and #lineno=
+  #
+  #     erb = ERB.new('<%= some_x %>')
+  #     erb.render
+  #     # undefined local variable or method `some_x'
+  #     #   from (erb):1
+  #
+  #     erb.location = ['file.erb', 3]
+  #     # All subsequent error reporting would use new location
+  #     erb.render
+  #     # undefined local variable or method `some_x'
+  #     #   from file.erb:4
   #
   def location=: (Array[String | Integer]) -> untyped
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - run(binding = new_toplevel) -> nil
+  #   - run(b=new_toplevel)
   # -->
-  # Like #result, but prints the result string (instead of returning it);
-  # returns `nil`.
+  # Generate results and print them. (see ERB#result)
   #
   def run: (?Binding) -> untyped
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - result(binding = new_toplevel) -> new_string
+  #   - result(b=new_toplevel)
   # -->
-  # Returns the string result formed by processing ERB tags found in the stored
-  # template in `self`.
-  # With no argument given, uses the default binding;
-  # see [Default Binding](rdoc-ref:ERB@Default+Binding).
-  # With argument `binding` given, uses the local binding;
-  # see [Local Binding](rdoc-ref:ERB@Local+Binding).
-  # See also #result_with_hash.
+  # Executes the generated ERB code to produce a completed template, returning the
+  # results of that code.  (See ERB::new for details on how this process can be
+  # affected by *safe_level*.)
+  #
+  # *b* accepts a Binding object which is used to set the context of code
+  # evaluation.
   #
   def result: (?Binding) -> String
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - result_with_hash(hash) -> new_string
+  #   - result_with_hash(hash)
   # -->
-  # Returns the string result formed by processing ERB tags found in the stored
-  # string in `self`;
-  # see [Augmented Binding](rdoc-ref:ERB@Augmented+Binding).
-  # See also #result.
+  # Render a template on a new toplevel binding with local variables specified by
+  # a Hash object.
   #
   def result_with_hash: (Hash[untyped, untyped]) -> String
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - def_method(module, method_signature, filename = '(ERB)') -> method_name
+  #   - def_method(mod, methodname, fname='(ERB)')
   # -->
-  # Creates and returns a new instance method in the given module `module`;
-  # returns the method name as a symbol.
-  # The method is created from the given `method_signature`,
-  # which consists of the method name and its argument names (if any).
-  # The `filename` sets the value of #filename;
-  # see [Error Reporting](rdoc-ref:ERB@Error+Reporting).
-  #     template = '<%= arg1 %> <%= arg2 %>'
-  # erb = ERB.new(template)
-  # MyModule = Module.new
-  # erb.def_method(MyModule, 'render(arg1, arg2)') # => :render
-  # class MyClass; include MyModule; end
-  # MyClass.new.render('foo', 123)                      # => "foo 123"
+  # Define *methodname* as instance method of *mod* from compiled Ruby source.
+  #
+  # example:
+  #     filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
+  #     erb = ERB.new(File.read(filename))
+  #     erb.def_method(MyClass, 'render(arg1, arg2)', filename)
+  #     print MyClass.new.render('foo', 123)
   #
   def def_method: (Module, String, ?String) -> untyped
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - def_module(method_name = 'erb') -> new_module
+  #   - def_module(methodname='erb')
   # -->
-  # Returns a new nameless module that has instance method `method_name`.
-  #     template = '<%= arg1 %> <%= arg2 %>'
-  # erb = ERB.new(template)
-  # MyModule = template.def_module('render(arg1, arg2)')
-  # class MyClass
-  #   include MyModule
-  # end
-  # MyClass.new.render('foo', 123)
-  # # => "foo 123"
+  # Create unnamed module, define *methodname* as instance method of it, and
+  # return it.
+  #
+  # example:
+  #     filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
+  #     erb = ERB.new(File.read(filename))
+  #     erb.filename = filename
+  #     MyModule = erb.def_module('render(arg1, arg2)')
+  #     class MyClass
+  #       include MyModule
+  #     end
   #
   def def_module: (?String) -> Module
 
   # <!--
   #   rdoc-file=lib/erb.rb
-  #   - def_class(super_class = Object, method_name = 'result') -> new_class
+  #   - def_class(superklass=Object, methodname='result')
   # -->
-  # Returns a new nameless class whose superclass is `super_class`,
-  # and which has instance method `method_name`.
-  # Create a template from HTML that has embedded expression tags that use `@arg1`
-  # and `@arg2`:
-  #     html = <<TEMPLATE
-  # <html>
-  # <body>
-  #   <p><%= @arg1 %></p>
-  #   <p><%= @arg2 %></p>
-  # </body>
-  # </html>
-  # TEMPLATE
-  # template = ERB.new(html)
-  #
-  # Create a base class that has `@arg1` and `@arg2`:
-  #     class MyBaseClass
-  #   def initialize(arg1, arg2)
-  #     @arg1 = arg1
-  #     @arg2 = arg2
-  #   end
-  # end
-  #
-  # Use method #def_class to create a subclass that has method `:render`:
-  #     MySubClass = template.def_class(MyBaseClass, :render)
-  #
-  # Generate the result:
-  #     puts MySubClass.new('foo', 123).render
-  # <html>
-  # <body>
-  #   <p>foo</p>
-  #   <p>123</p>
-  # </body>
-  # </html>
+  # Define unnamed class which has *methodname* as instance method, and return it.
+  #
+  # example:
+  #     class MyClass_
+  #       def initialize(arg1, arg2)
+  #         @arg1 = arg1;  @arg2 = arg2
+  #       end
+  #     end
+  #     filename = 'example.rhtml'  # @arg1 and @arg2 are used in example.rhtml
+  #     erb = ERB.new(File.read(filename))
+  #     erb.filename = filename
+  #     MyClass = erb.def_class(MyClass_, 'render()')
+  #     print MyClass.new('foo', 123).render()
   #
   def def_class: (?Class, ?String) -> Class
 
-  # <!-- rdoc-file=lib/erb/util.rb -->
-  # ERB::Util
-  #
-  # A utility module for conversion routines, often handy in HTML generation.
-  #
   module Util
     # <!--
     #   rdoc-file=lib/erb.rb
@@ -863,37 +510,6 @@ class ERB
     alias self.u self.url_encode
   end
 
-  # <!-- rdoc-file=lib/erb/def_method.rb -->
-  # ERB::DefMethod
-  #
-  # Utility module to define eRuby script as instance method.
-  #
-  # ### Example
-  #
-  # example.rhtml:
-  #     <% for item in @items %>
-  #     <b><%= item %></b>
-  #     <% end %>
-  #
-  # example.rb:
-  #     require 'erb'
-  #     class MyClass
-  #       extend ERB::DefMethod
-  #       def_erb_method('render()', 'example.rhtml')
-  #       def initialize(items)
-  #         @items = items
-  #       end
-  #     end
-  #     print MyClass.new([10,20,30]).render()
-  #
-  # result:
-  #
-  #     <b>10</b>
-  #
-  #     <b>20</b>
-  #
-  #     <b>30</b>
-  #
   module DefMethod
     # <!--
     #   rdoc-file=lib/erb/def_method.rb
@@ -905,12 +521,6 @@ class ERB
     def self.def_erb_method: (String methodname, (String | ERB) erb_or_fname) -> untyped
   end
 
-  # <!-- rdoc-file=lib/erb/util.rb -->
-  # ERB::Escape
-  #
-  # A subset of ERB::Util. Unlike ERB::Util#html_escape, we expect/hope Rails will
-  # not monkey-patch ERB::Escape#html_escape.
-  #
   module Escape
     # <!--
     #   rdoc-file=lib/erb/util.rb