rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/enumerator.rbs

@@ -37,8 +37,10 @@
 # list's elements to strings containing the index and the element as a string
 # via:
 #
-#     puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
-#     # => ["0:foo", "1:bar", "2:baz"]
+#      puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
+#      # => ["0:foo", "1:bar", "2:baz"]
+#
+#     == External Iteration
 #
 # An Enumerator can also be used as an external iterator. For example,
 # Enumerator#next returns the next value of the iterator or raises StopIteration
@@ -50,14 +52,44 @@
 #     puts e.next   # => 3
 #     puts e.next   # raises StopIteration
 #
-# Note that enumeration sequence by `next`, `next_values`, `peek` and
-# `peek_values` do not affect other non-external enumeration methods, unless the
-# underlying iteration method itself has side-effect, e.g. IO#each_line.
+# `next`, `next_values`, `peek` and `peek_values` are the only methods which use
+# external iteration (and Array#zip(Enumerable-not-Array) which uses `next`).
 #
-# Moreover, implementation typically uses fibers so performance could be slower
-# and exception stacktraces different than expected.
+# These methods do not affect other internal enumeration methods, unless the
+# underlying iteration method itself has side-effect, e.g. IO#each_line.
 #
-# You can use this to implement an internal iterator as follows:
+# External iteration differs **significantly** from internal iteration due to
+# using a Fiber:
+#     - The Fiber adds some overhead compared to internal enumeration.
+#     - The stacktrace will only include the stack from the Enumerator, not above.
+#     - Fiber-local variables are *not* inherited inside the Enumerator Fiber,
+#       which instead starts with no Fiber-local variables.
+#     - Fiber storage variables *are* inherited and are designed
+#       to handle Enumerator Fibers. Assigning to a Fiber storage variable
+#       only affects the current Fiber, so if you want to change state
+#       in the caller Fiber of the Enumerator Fiber, you need to use an
+#       extra indirection (e.g., use some object in the Fiber storage
+#       variable and mutate some ivar of it).
+#
+# Concretely:
+#      Thread.current[:fiber_local] = 1
+#      Fiber[:storage_var] = 1
+#      e = Enumerator.new do |y|
+#        p Thread.current[:fiber_local] # for external iteration: nil, for internal iteration: 1
+#        p Fiber[:storage_var] # => 1, inherited
+#        Fiber[:storage_var] += 1
+#        y << 42
+#      end
+#
+#      p e.next # => 42
+#      p Fiber[:storage_var] # => 1 (it ran in a different Fiber)
+#
+#      e.each { p _1 }
+#      p Fiber[:storage_var] # => 2 (it ran in the same Fiber/"stack" as the current Fiber)
+#
+#     == Convert External Iteration to Internal Iteration
+#
+# You can use an external iterator to implement an internal iterator as follows:
 #
 #     def ext_each(e)
 #       while true
@@ -92,6 +124,23 @@
 class Enumerator[unchecked out Elem, out Return] < Object
   include Enumerable[Elem]
 
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - Enumerator.product(*enums) -> enumerator
+  #   - Enumerator.product(*enums) { |elts| ... } -> enumerator
+  # -->
+  # Generates a new enumerator object that generates a Cartesian product of given
+  # enumerable objects.  This is equivalent to Enumerator::Product.new.
+  #
+  #     e = Enumerator.product(1..3, [4, 5])
+  #     e.to_a #=> [[1, 4], [1, 5], [2, 4], [2, 5], [3, 4], [3, 5]]
+  #     e.size #=> 6
+  #
+  # When a block is given, calls the block with each N-element array generated and
+  # returns `nil`.
+  #
+  def self.product: [Elem] (*_EachEntry[Elem]) -> Product[Elem]
+
   # <!--
   #   rdoc-file=enumerator.c
   #   - enum.each { |elm| block }                    -> obj

data/core/errors.rbs

@@ -39,14 +39,15 @@ end
 # exist in two forms,
 #
 # one that returns `nil` when the end of file is reached, the other raises
-# `EOFError`.
+# EOFError.
 #
-# `EOFError` is a subclass of `IOError`.
+# EOFError is a subclass of IOError.
 #
 #     file = File.open("/etc/hosts")
 #     file.read
 #     file.gets     #=> nil
 #     file.readline #=> EOFError: end of file reached
+#     file.close
 #
 class EOFError < IOError
 end
@@ -567,6 +568,11 @@ class SyntaxError < ScriptError
   # Construct a SyntaxError exception.
   #
   def initialize: (?string msg) -> void
+
+  # <!-- rdoc-file=error.c -->
+  # the path failed to parse
+  #
+  def path: () -> String?
 end
 
 # <!-- rdoc-file=error.c -->

data/core/exception.rbs

@@ -191,6 +191,47 @@ class Exception < Object
   #
   def cause: () -> Exception?
 
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception.detailed_message(highlight: bool, **opt)   ->  string
+  # -->
+  # Processes a string returned by #message.
+  #
+  # It may add the class name of the exception to the end of the first line. Also,
+  # when `highlight` keyword is true, it adds ANSI escape sequences to make the
+  # message bold.
+  #
+  # If you override this method, it must be tolerant for unknown keyword
+  # arguments. All keyword arguments passed to #full_message are delegated to this
+  # method.
+  #
+  # This method is overridden by did_you_mean and error_highlight to add their
+  # information.
+  #
+  # A user-defined exception class can also define their own `detailed_message`
+  # method to add supplemental information. When `highlight` is true, it can
+  # return a string containing escape sequences, but use widely-supported ones. It
+  # is recommended to limit the following codes:
+  #
+  # *   Reset (`\e[0m`)
+  # *   Bold (`\e[1m`)
+  # *   Underline (`\e[4m`)
+  # *   Foreground color except white and black
+  #     *   Red (`\e[31m`)
+  #     *   Green (`\e[32m`)
+  #     *   Yellow (`\e[33m`)
+  #     *   Blue (`\e[34m`)
+  #     *   Magenta (`\e[35m`)
+  #     *   Cyan (`\e[36m`)
+  #
+  #
+  #
+  # Use escape sequences carefully even if `highlight` is true. Do not use escape
+  # sequences to express essential information; the message should be readable
+  # even if all escape sequences are ignored.
+  #
+  def detailed_message: () -> String
+
   # <!--
   #   rdoc-file=error.c
   #   - exc.exception([string])  ->  an_exception or exc

data/core/fiber.rbs

@@ -69,13 +69,38 @@
 # blocking and non-blocking fibers' behavior is identical.
 #
 # Ruby doesn't provide a scheduler class: it is expected to be implemented by
-# the user and correspond to Fiber::SchedulerInterface.
+# the user and correspond to Fiber::Scheduler.
 #
 # There is also Fiber.schedule method, which is expected to immediately perform
 # the given block in a non-blocking manner. Its actual implementation is up to
 # the scheduler.
 #
 class Fiber < Object
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber[key] -> value
+  # -->
+  # Returns the value of the fiber storage variable identified by `key`.
+  #
+  # The `key` must be a symbol, and the value is set by Fiber#[]= or Fiber#store.
+  #
+  # See also Fiber::[]=.
+  #
+  def self.[]: (Symbol | String) -> untyped
+
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber[key] = value
+  # -->
+  # Assign `value` to the fiber storage variable identified by `key`. The variable
+  # is created if it doesn't exist.
+  #
+  # `key` must be a Symbol, otherwise a TypeError is raised.
+  #
+  # See also Fiber::[].
+  #
+  def self.[]=: [A] (Symbol | String, A) -> A
+
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.blocking? -> false or 1
@@ -146,8 +171,8 @@ class Fiber < Object
   #
   # Note that the behavior described above is how the method is *expected* to
   # behave, actual behavior is up to the current scheduler's implementation of
-  # Fiber::SchedulerInterface#fiber method. Ruby doesn't enforce this method to
-  # behave in any particular way.
+  # Fiber::Scheduler#fiber method. Ruby doesn't enforce this method to behave in
+  # any particular way.
   #
   # If the scheduler is not set, the method raises `RuntimeError (No scheduler is
   # available!)`.
@@ -158,11 +183,11 @@ class Fiber < Object
   #   rdoc-file=cont.c
   #   - Fiber.scheduler -> obj or nil
   # -->
-  # Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler.
-  #     Returns +nil+ if no scheduler is set (which is the default), and non-blocking fibers'
-  #
-  # #  behavior is the same as blocking.
-  #     (see "Non-blocking fibers" section in class docs for details about the scheduler concept).
+  # Returns the Fiber scheduler, that was last set for the current thread with
+  # Fiber.set_scheduler. Returns `nil` if no scheduler is set (which is the
+  # default), and non-blocking fibers' behavior is the same as blocking. (see
+  # "Non-blocking fibers" section in class docs for details about the scheduler
+  # concept).
   #
   def self.scheduler: () -> untyped?
 
@@ -177,8 +202,8 @@ class Fiber < Object
   # finalization (allowing the scheduler to properly manage all non-finished
   # fibers).
   #
-  # `scheduler` can be an object of any class corresponding to
-  # Fiber::SchedulerInterface. Its implementation is up to the user.
+  # `scheduler` can be an object of any class corresponding to Fiber::Scheduler.
+  # Its implementation is up to the user.
   #
   # See also the "Non-blocking fibers" section in class docs.
   #
@@ -197,7 +222,7 @@ class Fiber < Object
 
   # <!--
   #   rdoc-file=cont.c
-  #   - Fiber.new(blocking: false) { |*args| ... } -> fiber
+  #   - Fiber.new(blocking: false, storage: true) { |*args| ... } -> fiber
   # -->
   # Creates new Fiber. Initially, the fiber is not running and can be resumed with
   # #resume. Arguments to the first #resume call will be passed to the block:
@@ -218,7 +243,32 @@ class Fiber < Object
   # Fiber.scheduler defined, the Fiber becomes non-blocking (see "Non-blocking
   # Fibers" section in class docs).
   #
-  def initialize: (?blocking: boolish) { (*untyped) -> void } -> void
+  # If the `storage` is unspecified, the default is to inherit a copy of the
+  # storage from the current fiber. This is the same as specifying `storage:
+  # true`.
+  #
+  #     Fiber[:x] = 1
+  #     Fiber.new do
+  #       Fiber[:x] # => 1
+  #       Fiber[:x] = 2
+  #     end.resume
+  #     Fiber[:x] # => 1
+  #
+  # If the given `storage` is `nil`, this function will lazy initialize the
+  # internal storage, which starts as an empty hash.
+  #
+  #     Fiber[:x] = "Hello World"
+  #     Fiber.new(storage: nil) do
+  #       Fiber[:x] # nil
+  #     end
+  #
+  # Otherwise, the given `storage` is used as the new fiber's storage, and it must
+  # be an instance of Hash.
+  #
+  # Explicitly using `storage: true` is currently experimental and may change in
+  # the future.
+  #
+  def initialize: (?blocking: boolish, ?storage: true | Hash[Symbol | String, untyped] | nil) { (*untyped) -> void } -> void
 
   # <!--
   #   rdoc-file=cont.c
@@ -357,6 +407,39 @@ class Fiber < Object
   #
   def resume: (*untyped) -> untyped
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.storage -> hash (dup)
+  # -->
+  # Returns a copy of the storage hash for the fiber. The method can only be
+  # called on the Fiber.current.
+  #
+  def storage: () -> Hash[Symbol | String, untyped]
+
+  # <!--
+  #   rdoc-file=cont.c
+  #   - fiber.storage = hash
+  # -->
+  # Sets the storage hash for the fiber. This feature is experimental and may
+  # change in the future. The method can only be called on the Fiber.current.
+  #
+  # You should be careful about using this method as you may inadvertently clear
+  # important fiber-storage state. You should mostly prefer to assign specific
+  # keys in the storage using Fiber::[]=.
+  #
+  # You can also use `Fiber.new(storage: nil)` to create a fiber with an empty
+  # storage.
+  #
+  # Example:
+  #
+  #     while request = request_queue.pop
+  #       # Reset the per-request state:
+  #       Fiber.current.storage = nil
+  #       handle_request(request)
+  #     end
+  #
+  def storage=: (Hash[Symbol | String, untyped]) -> Hash[Symbol | String, untyped]
+
   # <!--
   #   rdoc-file=cont.c
   #   - to_s()