rbs 2.0.0 → 2.1.0

data/stdlib/erb/0/erb.rbs

@@ -1,256 +1,20 @@
-# # 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 %>
-#     % 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 value of `$SAFE` under which the template is run;
-# *   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:
-# *   ERB's big brother, eRuby, works the same but is written in C for speed;
-# *   Amrita (smart at producing HTML/XML);
-# *   cs/Template (written in C for speed);
-# *   RDoc, distributed with Ruby, uses its own template engine, which can be
-#     reused elsewhere;
-# *   and others; search [RubyGems.org](https://rubygems.org/) or [The Ruby
-#     Toolbox](https://www.ruby-toolbox.com/).
-#
-#
-# Rails, the web application framework, uses ERB to create views.
-#
 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 *safe_level* is set to a non-nil value, ERB
-  # code will be run in a separate thread with **$SAFE** set to the provided
-  # level.
+  # 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:
@@ -312,30 +76,70 @@ class ERB
   #
   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*.)
@@ -345,11 +149,19 @@ class ERB
   #
   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:
@@ -360,6 +172,10 @@ class ERB
   #
   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.
   #
@@ -374,6 +190,10 @@ class ERB
   #
   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:

data/stdlib/fiber/0/fiber.rbs

@@ -1,117 +1,99 @@
-# Fibers are primitives for implementing light weight cooperative concurrency in
-# Ruby. Basically they are a means of creating code blocks that can be paused
-# and resumed, much like threads. The main difference is that they are never
-# preempted and that the scheduling must be done by the programmer and not the
-# VM.
-#
-# As opposed to other stackless light weight concurrency models, each fiber
-# comes with a stack.  This enables the fiber to be paused from deeply nested
-# function calls within the fiber block.  See the ruby(1) manpage to configure
-# the size of the fiber stack(s).
-#
-# When a fiber is created it will not run automatically. Rather it must be
-# explicitly asked to run using the Fiber#resume method. The code running inside
-# the fiber can give up control by calling Fiber.yield in which case it yields
-# control back to caller (the caller of the Fiber#resume).
-#
-# Upon yielding or termination the Fiber returns the value of the last executed
-# expression
-#
-# For instance:
-#
-#     fiber = Fiber.new do
-#       Fiber.yield 1
-#       2
-#     end
-#
-#     puts fiber.resume
-#     puts fiber.resume
-#     puts fiber.resume
-#
-# *produces*
-#
-#     1
-#     2
-#     FiberError: dead fiber called
-#
-# The Fiber#resume method accepts an arbitrary number of parameters, if it is
-# the first call to #resume then they will be passed as block arguments.
-# Otherwise they will be the return value of the call to Fiber.yield
-#
-# Example:
-#
-#     fiber = Fiber.new do |first|
-#       second = Fiber.yield first + 2
-#     end
-#
-#     puts fiber.resume 10
-#     puts fiber.resume 1_000_000
-#     puts fiber.resume "The fiber will be dead before I can cause trouble"
-#
-# *produces*
-#
-#     12
-#     1000000
-#     FiberError: dead fiber called
-#
+%a{annotate:rdoc:skip}
 class Fiber
-  # Returns the current fiber. You need to `require 'fiber'` before using this
-  # method. If you are not running in the context of a fiber this method will
-  # return the root fiber.
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber.current -> fiber
+  # -->
+  # Returns the current fiber. If you are not running in the context of a fiber
+  # this method will return the root fiber.
   #
   def self.current: () -> Fiber
 
   public
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.alive? -> true or false
+  # -->
   # Returns true if the fiber can still be resumed (or transferred to). After
-  # finishing execution of the fiber block this method will always return false.
-  # You need to `require 'fiber'` before using this method.
+  # finishing execution of the fiber block this method will always return `false`.
   #
   def alive?: () -> bool
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.transfer(args, ...) -> obj
+  # -->
   # Transfer control to another fiber, resuming it from where it last stopped or
   # starting it if it was not resumed before. The calling fiber will be suspended
-  # much like in a call to Fiber.yield. You need to `require 'fiber'` before using
-  # this method.
+  # much like in a call to Fiber.yield.
   #
-  # The fiber which receives the transfer call is treats it much like a resume
-  # call. Arguments passed to transfer are treated like those passed to resume.
+  # The fiber which receives the transfer call treats it much like a resume call.
+  # Arguments passed to transfer are treated like those passed to resume.
   #
-  # You cannot call `resume` on a fiber that has been transferred to. If you call
-  # `transfer` on a fiber, and later call `resume` on the the fiber, a
-  # `FiberError` will be raised. Once you call `transfer` on a fiber, the only way
-  # to resume processing the fiber is to call `transfer` on it again.
+  # The two style of control passing to and from fiber (one is #resume and
+  # Fiber::yield, another is #transfer to and from fiber) can't be freely mixed.
+  #
+  # *   If the Fiber's lifecycle had started with transfer, it will never be able
+  #     to yield or be resumed control passing, only finish or transfer back. (It
+  #     still can resume other fibers that are allowed to be resumed.)
+  # *   If the Fiber's lifecycle had started with resume, it can yield or transfer
+  #     to another Fiber, but can receive control back only the way compatible
+  #     with the way it was given away: if it had transferred, it only can be
+  #     transferred back, and if it had yielded, it only can be resumed back.
+  #     After that, it again can transfer or yield.
+  #
+  #
+  # If those rules are broken FiberError is raised.
+  #
+  # For an individual Fiber design, yield/resume is easier to use (the Fiber just
+  # gives away control, it doesn't need to think about who the control is given
+  # to), while transfer is more flexible for complex cases, allowing to build
+  # arbitrary graphs of Fibers dependent on each other.
   #
   # Example:
   #
-  #     fiber1 = Fiber.new do
-  #       puts "In Fiber 1"
-  #       Fiber.yield
-  #       puts "In Fiber 1 again"
-  #     end
+  #     manager = nil # For local var to be visible inside worker block
   #
-  #     fiber2 = Fiber.new do
-  #       puts "In Fiber 2"
-  #       fiber1.transfer
-  #       puts "Never see this message"
-  #     end
+  #     # This fiber would be started with transfer
+  #     # It can't yield, and can't be resumed
+  #     worker = Fiber.new { |work|
+  #       puts "Worker: starts"
+  #       puts "Worker: Performed #{work.inspect}, transferring back"
+  #       # Fiber.yield     # this would raise FiberError: attempt to yield on a not resumed fiber
+  #       # manager.resume  # this would raise FiberError: attempt to resume a resumed fiber (double resume)
+  #       manager.transfer(work.capitalize)
+  #     }
   #
-  #     fiber3 = Fiber.new do
-  #       puts "In Fiber 3"
-  #     end
+  #     # This fiber would be started with resume
+  #     # It can yield or transfer, and can be transferred
+  #     # back or resumed
+  #     manager = Fiber.new {
+  #       puts "Manager: starts"
+  #       puts "Manager: transferring 'something' to worker"
+  #       result = worker.transfer('something')
+  #       puts "Manager: worker returned #{result.inspect}"
+  #       # worker.resume    # this would raise FiberError: attempt to resume a transferring fiber
+  #       Fiber.yield        # this is OK, the fiber transferred from and to, now it can yield
+  #       puts "Manager: finished"
+  #     }
   #
-  #     fiber2.resume
-  #     fiber3.resume
-  #     fiber1.resume rescue (p $!)
-  #     fiber1.transfer
+  #     puts "Starting the manager"
+  #     manager.resume
+  #     puts "Resuming the manager"
+  #     # manager.transfer  # this would raise FiberError: attempt to transfer to a yielding fiber
+  #     manager.resume
   #
   # *produces*
   #
-  #     In Fiber 2
-  #     In Fiber 1
-  #     In Fiber 3
-  #     #<FiberError: cannot resume transferred Fiber>
-  #     In Fiber 1 again
+  #     Starting the manager
+  #     Manager: starts
+  #     Manager: transferring 'something' to worker
+  #     Worker: starts
+  #     Worker: Performed "something", transferring back
+  #     Manager: worker returned "Something"
+  #     Resuming the manager
+  #     Manager: finished
   #
   def transfer: (*untyped) -> untyped
 end