rbs 4.0.0.dev.4 → 4.0.0

data/core/enumerator.rbs

@@ -137,7 +137,7 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
 
   # <!--
   #   rdoc-file=enumerator.c
-  #   - Enumerator.produce(initial = nil) { |prev| block } -> enumerator
+  #   - Enumerator.produce(initial = nil, size: nil) { |prev| block } -> enumerator
   # -->
   # Creates an infinite enumerator from any block, just called over and over.  The
   # result of the previous iteration is passed to the next one. If `initial` is
@@ -169,6 +169,30 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
   #     Enumerator.produce { scanner.scan(PATTERN) }.slice_after { scanner.eos? }.first
   #     # => ["7", "+", "38", "/", "6"]
   #
+  # The optional `size` keyword argument specifies the size of the enumerator,
+  # which can be retrieved by Enumerator#size.  It can be an integer,
+  # <code>Float::INFINITY</code>, a callable object (such as a lambda), or `nil`
+  # to indicate unknown size.  When not specified, the size defaults to
+  # <code>Float::INFINITY</code>.
+  #
+  #     # Infinite enumerator
+  #     enum = Enumerator.produce(1, size: Float::INFINITY, &:succ)
+  #     enum.size  # => Float::INFINITY
+  #
+  #     # Finite enumerator with known/computable size
+  #     abs_dir = File.expand_path("./baz") # => "/foo/bar/baz"
+  #     traverser = Enumerator.produce(abs_dir, size: -> { abs_dir.count("/") + 1 }) {
+  #       raise StopIteration if it == "/"
+  #       File.dirname(it)
+  #     }
+  #     traverser.size  # => 4
+  #
+  #     # Finite enumerator with unknown size
+  #     calendar = Enumerator.produce(Date.today, size: nil) {
+  #       it.monday? ? raise(StopIteration) : it + 1
+  #     }
+  #     calendar.size  # => nil
+  #
   def self.produce: [T] () { (T? prev) -> T } -> Enumerator[T, bot]
                   | [T] (T initial) { (T prev) -> T } -> Enumerator[T, bot]
 
@@ -282,7 +306,7 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
   #
   # Iteration is defined by the given block, in which a "yielder" object, given as
   # block parameter, can be used to yield a value by calling the `yield` method
-  # (aliased as `<<`):
+  # (aliased as <code><<</code>):
   #
   #     fib = Enumerator.new do |y|
   #       a = b = 1
@@ -446,8 +470,39 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
   #     loop.size # => Float::INFINITY
   #     (1..100).drop_while.size # => nil
   #
+  # Note that enumerator size might be inaccurate, and should be rather treated as
+  # a hint. For example, there is no check that the size provided to ::new is
+  # accurate:
+  #
+  #     e = Enumerator.new(5) { |y| 2.times { y << it} }
+  #     e.size # => 5
+  #     e.to_a.size # => 2
+  #
+  # Another example is an enumerator created by ::produce without a `size`
+  # argument. Such enumerators return `Infinity` for size, but this is inaccurate
+  # if the passed block raises StopIteration:
+  #
+  #     e = Enumerator.produce(1) { it + 1 }
+  #     e.size # => Infinity
+  #
+  #     e = Enumerator.produce(1) { it > 3 ? raise(StopIteration) : it + 1 }
+  #     e.size # => Infinity
+  #     e.to_a.size # => 4
+  #
   def size: () -> (Integer | Float)?
 
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - e + enum -> enumerator
+  # -->
+  # Returns an enumerator object generated from this enumerator and a given
+  # enumerable.
+  #
+  #     e = (1..3).each + [4, 5]
+  #     e.to_a #=> [1, 2, 3, 4, 5]
+  #
+  def +: [Elem2] (::_Each[Elem2]) -> ::Enumerator::Chain[Elem | Elem2]
+
   # <!--
   #   rdoc-file=enumerator.c
   #   - e.with_index(offset = 0) {|(*args), idx| ... }
@@ -578,6 +633,14 @@ class Enumerator::Lazy[out Elem, out Return = void] < Enumerator[Elem, Return]
   # Like Enumerable#compact, but chains operation to be lazy-evaluated.
   #
   def compact: () -> Enumerator::Lazy[Elem, Return]
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - lzy.eager -> enum
+  # -->
+  # Returns a non-lazy Enumerator converted from the lazy enumerator.
+  #
+  def eager: () -> ::Enumerator[Elem, Return]
 end
 
 # <!-- rdoc-file=enumerator.c -->

data/core/errno.rbs

@@ -9,7 +9,7 @@
 #
 # When the Ruby interpreter interacts with the operating system and receives
 # such an error code (e.g., `2`), it maps the code to a particular Ruby
-# exception class (e.g., `Errno::ENOENT`):
+# exception class (e.g., <code>Errno::ENOENT</code>):
 #
 #     File.open('nosuch.txt')
 #     # => No such file or directory @ rb_sysopen - nosuch.txt (Errno::ENOENT)
@@ -25,7 +25,8 @@
 #     Errno::ENOENT.superclass # => SystemCallError
 #     Errno::ENOENT::Errno     # => 2
 #
-# The names of nested classes are returned by method `Errno.constants`:
+# The names of nested classes are returned by method
+# <code>Errno.constants</code>:
 #
 #     Errno.constants.size         # => 158
 #     Errno.constants.sort.take(5) # => [:E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, :EADV]
@@ -38,6 +39,14 @@
 #     Errno::ENOENT::Errno      # => 2
 #     Errno::ENOTCAPABLE::Errno # => 0
 #
+# Each class in Errno can be created with optional messages:
+#
+#     Errno::EPIPE.new                  # => #<Errno::EPIPE: Broken pipe>
+#     Errno::EPIPE.new("foo")           # => #<Errno::EPIPE: Broken pipe - foo>
+#     Errno::EPIPE.new("foo", "here")   # => #<Errno::EPIPE: Broken pipe @ here - foo>
+#
+# See SystemCallError.new.
+#
 module Errno
   class NOERROR < SystemCallError
     Errno: 0

data/core/errors.rbs

@@ -6,7 +6,7 @@
 #
 #     [1, 2, 3].first(4, 5)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     ArgumentError: wrong number of arguments (given 2, expected 1)
 #
@@ -14,7 +14,7 @@
 #
 #     [1, 2, 3].first(-4)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     ArgumentError: negative array size
 #
@@ -66,7 +66,7 @@ end
 #
 #     [1, 2, 3].freeze << 4
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     FrozenError: can't modify frozen Array
 #
@@ -115,11 +115,11 @@ end
 #       puts "Note: You will typically use Signal.trap instead."
 #     end
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     Press ctrl-C when you get bored
 #
-# *then waits until it is interrupted with Control-C and then prints:*
+# <em>then waits until it is interrupted with Control-C and then prints:</em>
 #
 #     Note: You will typically use Signal.trap instead.
 #
@@ -184,7 +184,7 @@ end
 #
 #     require 'this/file/does/not/exist'
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LoadError: no such file to load -- this/file/does/not/exist
 #
@@ -209,7 +209,7 @@ end
 #     end
 #     call_block
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LocalJumpError: no block given (yield)
 #
@@ -220,7 +220,7 @@ end
 #     end
 #     get_me_a_return.call
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LocalJumpError: unexpected return
 #
@@ -248,7 +248,7 @@ end
 #
 #     puts foo
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NameError: undefined local variable or method `foo' for main:Object
 #
@@ -256,7 +256,7 @@ end
 #
 #     Integer.const_set :answer, 42
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NameError: wrong constant name answer
 #
@@ -302,9 +302,15 @@ class NameError[T] < StandardError
   def receiver: () -> T?
 end
 
+# <!-- rdoc-file=error.c -->
+# Raised when matching pattern not found.
+#
 class NoMatchingPatternError < StandardError
 end
 
+# <!-- rdoc-file=error.c -->
+# Raised when matching key not found.
+#
 class NoMatchingPatternKeyError[M, K] < NoMatchingPatternError
   # <!--
   #   rdoc-file=error.c
@@ -344,7 +350,7 @@ end
 #
 #     "hello".to_ary
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     NoMethodError: undefined method `to_ary' for an instance of String
 #
@@ -354,11 +360,13 @@ class NoMethodError[T] < NameError[T]
   #   - NoMethodError.new(msg=nil, name=nil, args=nil, private=false, receiver: nil)  -> no_method_error
   # -->
   # Construct a NoMethodError exception for a method of the given name called with
-  # the given arguments. The name may be accessed using the `#name` method on the
-  # resulting object, and the arguments using the `#args` method.
+  # the given arguments. The name may be accessed using the <code>#name</code>
+  # method on the resulting object, and the arguments using the <code>#args</code>
+  # method.
   #
   # If *private* argument were passed, it designates method was attempted to call
-  # in private context, and can be accessed with `#private_call?` method.
+  # in private context, and can be accessed with <code>#private_call?</code>
+  # method.
   #
   # *receiver* argument stores an object whose method was called.
   #
@@ -387,8 +395,8 @@ end
 # exception if the underlying operating system or Ruby runtime does not support
 # them.
 #
-# Note that if `fork` raises a `NotImplementedError`, then `respond_to?(:fork)`
-# returns `false`.
+# Note that if `fork` raises a `NotImplementedError`, then
+# <code>respond_to?(:fork)</code> returns `false`.
 #
 class NotImplementedError < ScriptError
 end
@@ -398,7 +406,7 @@ end
 #
 #     [1, 2, 3].drop(1 << 100)
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RangeError: bignum too big to convert into `long'
 #
@@ -410,7 +418,7 @@ end
 #
 #     Regexp.new("?")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RegexpError: target of repeat operator is not specified: /?/
 #
@@ -423,7 +431,7 @@ end
 #
 #     raise "ouch"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     RuntimeError: ouch
 #
@@ -455,7 +463,7 @@ end
 #       puts "received Exception #{e}"
 #     end
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     received Exception SIGHUP
 #
@@ -496,7 +504,7 @@ end
 #
 #     require 'does/not/exist' rescue "Hi"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     LoadError: no such file to load -- does/not/exist
 #
@@ -514,7 +522,7 @@ end
 #     end
 #     puts "Done!"
 #
-# *produces:*
+# <em>produces:</em>
 #
 #     Hello
 #     Done!
@@ -554,7 +562,7 @@ end
 #
 #     eval("1+1=2")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
 #
@@ -581,20 +589,41 @@ end
 #
 #     File.open("does/not/exist")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     Errno::ENOENT: No such file or directory - does/not/exist
 #
 class SystemCallError < StandardError
   # <!--
   #   rdoc-file=error.c
-  #   - SystemCallError.new(msg, errno)  -> system_call_error_subclass
+  #   - SystemCallError.new(msg, errno = nil, func = nil)  -> system_call_error_subclass
   # -->
   # If *errno* corresponds to a known system error code, constructs the
   # appropriate Errno class for that error, otherwise constructs a generic
   # SystemCallError object. The error number is subsequently available via the
   # #errno method.
   #
+  # If only numeric object is given, it is treated as an Integer *errno*, and
+  # *msg* is omitted, otherwise the first argument *msg* is used as the additional
+  # error message.
+  #
+  #     SystemCallError.new(Errno::EPIPE::Errno)
+  #     #=> #<Errno::EPIPE: Broken pipe>
+  #
+  #     SystemCallError.new("foo")
+  #     #=> #<SystemCallError: unknown error - foo>
+  #
+  #     SystemCallError.new("foo", Errno::EPIPE::Errno)
+  #     #=> #<Errno::EPIPE: Broken pipe - foo>
+  #
+  # If *func* is not `nil`, it is appended to the message with "<code> @ </code>".
+  #
+  #     SystemCallError.new("foo", Errno::EPIPE::Errno, "here")
+  #     #=> #<Errno::EPIPE: Broken pipe @ here - foo>
+  #
+  # A subclass of SystemCallError can also be instantiated via the `new` method of
+  # the subclass.  See Errno.
+  #
   def initialize: (string msg, Integer errno) -> void
 
   # <!--
@@ -658,7 +687,7 @@ end
 #     end
 #     me_myself_and_i
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     SystemStackError: stack level too deep
 #
@@ -685,7 +714,7 @@ end
 #
 #     [1, 2, 3].first("two")
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     TypeError: no implicit conversion of String into Integer
 #
@@ -698,7 +727,7 @@ end
 #
 #     throw "foo", "bar"
 #
-# *raises the exception:*
+# <em>raises the exception:</em>
 #
 #     UncaughtThrowError: uncaught throw "foo"
 #
@@ -714,7 +743,7 @@ class UncaughtThrowError < ArgumentError
   #
   #     throw "foo", "bar"
   #
-  # *raises the exception:*
+  # <em>raises the exception:</em>
   #
   #     UncaughtThrowError: uncaught throw "foo"
   #

data/core/exception.rbs

@@ -102,7 +102,7 @@ class Exception
   # Returns the backtrace (the list of code locations that led to the exception),
   # as an array of strings.
   #
-  # Example (assuming the code is stored in the file named `t.rb`):
+  # Example (assuming the code is stored in the file named <code>t.rb</code>):
   #
   #     def division(numerator, denominator)
   #       numerator / denominator
@@ -118,7 +118,7 @@ class Exception
   #       # String
   #     end
   #
-  # The value returned by this method migth be adjusted when raising (see
+  # The value returned by this method might be adjusted when raising (see
   # Kernel#raise), or during intermediate handling by #set_backtrace.
   #
   # See also #backtrace_locations that provide the same value, as structured
@@ -136,7 +136,7 @@ class Exception
   # Returns the backtrace (the list of code locations that led to the exception),
   # as an array of Thread::Backtrace::Location instances.
   #
-  # Example (assuming the code is stored in the file named `t.rb`):
+  # Example (assuming the code is stored in the file named <code>t.rb</code>):
   #
   #     def division(numerator, denominator)
   #       numerator / denominator
@@ -173,8 +173,8 @@ class Exception
   #   rdoc-file=error.c
   #   - cause -> exception or nil
   # -->
-  # Returns the previous value of global variable `$!`, which may be `nil` (see
-  # [Global Variables](rdoc-ref:exceptions.md@Global+Variables)):
+  # Returns the previous value of global variable <code>$!</code>, which may be
+  # `nil` (see [Global Variables](rdoc-ref:exceptions.md@Global+Variables)):
   #
   #     begin
   #       raise('Boom 0')
@@ -237,10 +237,10 @@ class Exception
   # An overriding method must be tolerant of passed keyword arguments, which may
   # include (but may not be limited to):
   #
-  # *   `:highlight`.
-  # *   `:did_you_mean`.
-  # *   `:error_highlight`.
-  # *   `:syntax_suggest`.
+  # *   <code>:highlight</code>.
+  # *   <code>:did_you_mean</code>.
+  # *   <code>:error_highlight</code>.
+  # *   <code>:syntax_suggest</code>.
   #
   # An overriding method should also be careful with ANSI code enhancements; see
   # [Messages](rdoc-ref:exceptions.md@Messages).
@@ -444,10 +444,10 @@ class Exception
   #     message.
   # *   Includes the [backtrace](rdoc-ref:exceptions.md@Backtraces):
   #
-  #     *   If the value of keyword `order` is `:top` (the default), lists the
-  #         error message and the innermost backtrace entry first.
-  #     *   If the value of keyword `order` is `:bottom`, lists the error message
-  #         the the innermost entry last.
+  #     *   If the value of keyword `order` is <code>:top</code> (the default),
+  #         lists the error message and the innermost backtrace entry first.
+  #     *   If the value of keyword `order` is <code>:bottom</code>, lists the
+  #         error message the innermost entry last.
   #
   # Example:
   #