# <!-- rdoc-file=lib/erb.rb -->
# # 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'
#
#     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
#
#       <%= to[/\w+/] %>:
#
#       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:
#
#       <%# ignore numerous minor requests -- focus on priorities %>
#       % priorities.each do |priority|
#         * <%= priority %>
#       % end
#
#       Thanks for your patience.
#
#       James Edward Gray II
#     }.gsub(/^  /, '')
#
#     message = ERB.new(template, trim_mode: "%<>")
#
#     # Set up template data.
#     to = "Community Spokesman <spokesman@ruby_community.org>"
#     priorities = [ "Run Ruby Quiz",
#                    "Document Modules",
#                    "Answer Questions on Ruby Talk" ]
#
#     # Produce result.
#     email = message.result
#     puts email
#
# *Generates:*
#
#     From:  James Edward Gray II <james@grayproductions.net>
#     To:  Community Spokesman <spokesman@ruby_community.org>
#     Subject:  Addressing Needs
#
#     Community:
#
#     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:
#
#         * Run Ruby Quiz
#         * Document Modules
#         * Answer Questions on Ruby Talk
#
#     Thanks for your patience.
#
#     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
#
#     # 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
  #   - version()
  # -->
  # Returns revision information for the erb.rb module.
  #
  def self.version: () -> String

  # <!--
  #   rdoc-file=lib/erb.rb
  #   - new(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eoutvar=NOT_GIVEN, trim_mode: nil, eoutvar: '_erbout')
  # -->
  # 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'.gsub(/^\s+/, ""), trim_mode: "", eoutvar: "@product").result b
  #           <%= PRODUCT[:name] %>
  #           <%= PRODUCT[:desc] %>
  #         END_PRODUCT
  #         ERB.new(<<-'END_PRICE'.gsub(/^\s+/, ""), 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 -->
  # The Ruby code generated by ERB
  #
  def src: () -> String

  # <!-- rdoc-file=lib/erb.rb -->
  # The encoding to eval
  #
  def encoding: () -> Encoding

  # <!-- rdoc-file=lib/erb.rb -->
  # The optional *filename* argument passed to Kernel#eval when the ERB code is
  # run
  #
  def filename: () -> (String | NilClass)

  # <!-- rdoc-file=lib/erb.rb -->
  # The optional *filename* argument passed to Kernel#eval when the ERB code is
  # run
  #
  def filename=: (String | NilClass) -> untyped

  # <!-- rdoc-file=lib/erb.rb -->
  # The optional *lineno* argument passed to Kernel#eval when the ERB code is run
  #
  def lineno: () -> Integer

  # <!-- rdoc-file=lib/erb.rb -->
  # 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))
  # -->
  # 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(b=new_toplevel)
  # -->
  # Generate results and print them. (see ERB#result)
  #
  def run: (?Binding) -> untyped

  # <!--
  #   rdoc-file=lib/erb.rb
  #   - result(b=new_toplevel)
  # -->
  # 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)
  # -->
  # 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(mod, methodname, fname='(ERB)')
  # -->
  # 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(methodname='erb')
  # -->
  # 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(superklass=Object, methodname='result')
  # -->
  # 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.rb -->
  # A utility module for conversion routines, often handy in HTML generation.
  #
  module Util
    # <!--
    #   rdoc-file=lib/erb.rb
    #   - html_escape(s)
    # -->
    # A utility method for escaping HTML tag characters in *s*.
    #
    #     require "erb"
    #     include ERB::Util
    #
    #     puts html_escape("is a > 0 & a < 10?")
    #
    # *Generates*
    #
    #     is a &gt; 0 &amp; a &lt; 10?
    #
    def self?.html_escape: (String str) -> String

    # <!--
    #   rdoc-file=lib/erb.rb
    #   - h(s)
    # -->
    #
    alias h html_escape

    # <!--
    #   rdoc-file=lib/erb.rb
    #   - h(s)
    # -->
    #
    alias self.h self.html_escape

    # <!--
    #   rdoc-file=lib/erb.rb
    #   - url_encode(s)
    # -->
    # A utility method for encoding the String *s* as a URL.
    #
    #     require "erb"
    #     include ERB::Util
    #
    #     puts url_encode("Programming Ruby:  The Pragmatic Programmer's Guide")
    #
    # *Generates*
    #
    #     Programming%20Ruby%3A%20%20The%20Pragmatic%20Programmer%27s%20Guide
    #
    def self?.url_encode: (String) -> String

    # <!--
    #   rdoc-file=lib/erb.rb
    #   - u(s)
    # -->
    #
    alias u url_encode

    # <!--
    #   rdoc-file=lib/erb.rb
    #   - u(s)
    # -->
    #
    alias self.u self.url_encode
  end

  # <!-- rdoc-file=lib/erb.rb -->
  # 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.rb
    #   - def_erb_method(methodname, erb_or_fname)
    # -->
    # define *methodname* as instance method of current module, using ERB object or
    # eRuby file
    #
    def self.def_erb_method: (String methodname, (String | ERB) erb_or_fname) -> untyped
  end
end