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

data/core/regexp.rbs

@@ -1,13 +1,4 @@
 # <!-- rdoc-file=re.c -->
-# A Regexp holds a regular expression, used to match a pattern against strings.
-# Regexps are created using the `/.../` and `%r{...}` literals, and by the
-# Regexp::new constructor.
-#
-# You can create a Regexp object explicitly with:
-#
-# *   A [regexp literal](doc/syntax/literals_rdoc.html#label-Regexp+Literals).
-#
-#
 # Regular expressions (*regexp*s) are patterns which describe the contents of a
 # string. They're used for testing whether a string contains a given pattern, or
 # extracting the portions that match. They are created with the `/`*pat*`/` and
@@ -32,12 +23,22 @@
 # Specifically, `/st/` requires that the string contains the letter *s* followed
 # by the letter *t*, so it matches *haystack*, also.
 #
+# Note that any Regexp matching will raise a RuntimeError if timeout is set and
+# exceeded. See ["Timeout"](#label-Timeout) section in detail.
+#
+# ## Regexp Interpolation
+#
+# A regexp may contain interpolated strings; trivially:
+#
+#     foo = 'bar'
+#     /#{foo}/ # => /bar/
+#
 # ## `=~` and Regexp#match
 #
 # Pattern matching may be achieved by using `=~` operator or Regexp#match
 # method.
 #
-# ### `=~` operator
+# ### `=~` Operator
 #
 # `=~` is Ruby's basic pattern-matching operator.  When one operand is a regular
 # expression and the other is a string then the regular expression is used as a
@@ -55,7 +56,7 @@
 # after a successful match.  `$~` holds a MatchData object. Regexp.last_match is
 # equivalent to `$~`.
 #
-# ### Regexp#match method
+# ### Regexp#match Method
 #
 # The #match method returns a MatchData object:
 #
@@ -190,7 +191,7 @@
 #
 #     "Hello".match(/[[:upper:]]+[[:lower:]]+l{2}o/) #=> #<MatchData "Hello">
 #
-# ### Greedy match
+# ### Greedy Match
 #
 # Repetition is *greedy* by default: as many occurrences as possible are matched
 # while still allowing the overall match to succeed. By contrast, *lazy*
@@ -207,7 +208,7 @@
 #     /<.+>/.match("<a><b>")  #=> #<MatchData "<a><b>">
 #     /<.+?>/.match("<a><b>") #=> #<MatchData "<a>">
 #
-# ### Possessive match
+# ### Possessive Match
 #
 # A quantifier followed by `+` matches *possessively*: once it has matched it
 # does not backtrack. They behave like greedy quantifiers, but having matched
@@ -249,7 +250,7 @@
 #     "The cat sat in the hat".gsub(/[csh]at/, '\0s')
 #       # => "The cats sats in the hats"
 #
-# ### Named captures
+# ### Named Captures
 #
 # Capture groups can be referred to by name when defined with the
 # `(?<`*name*`>)` or `(?'`*name*`')` constructs.
@@ -395,6 +396,7 @@
 # *   `/\p{Blank}/` - Space or tab
 # *   `/\p{Cntrl}/` - Control character
 # *   `/\p{Digit}/` - Digit
+# *   `/\p{Emoji}/` - Unicode emoji
 # *   `/\p{Graph}/` - Non-blank character (excludes spaces, control characters,
 #     and similar)
 # *   `/\p{Lower}/` - Lowercase alphabetical character
@@ -523,11 +525,16 @@
 # *   `(?<!`*pat*`)` - *Negative lookbehind* assertion: ensures that the
 #     preceding characters do not match *pat*, but doesn't include those
 #     characters in the matched text
-# *   `\K` - Uses an positive lookbehind of the content preceding `\K` in the
-#     regexp.  For example, the following two regexps are almost equivalent:
 #
-#         /ab\Kc/
-#         /(?<=ab)c/
+# *   `\K` - *Match reset*: the matched content preceding `\K` in the regexp is
+#     excluded from the result.  For example, the following two regexps are
+#     almost equivalent:
+#
+#         /ab\Kc/ =~ "abc"     #=> 0
+#         /(?<=ab)c/ =~ "abc"  #=> 2
+#
+#     These match same string and *$&* equals `"c"`, while the matched position
+#     is different.
 #
 #     As are the following two regexps:
 #
@@ -592,6 +599,11 @@
 #     Regexp.new("abc # Comment", Regexp::EXTENDED)             #=> /abc # Comment/x
 #     Regexp.new("abc", Regexp::IGNORECASE | Regexp::MULTILINE) #=> /abc/mi
 #
+#     Regexp.new("abc", "i")           #=> /abc/i
+#     Regexp.new("abc", "m")           #=> /abc/m
+#     Regexp.new("abc # Comment", "x") #=> /abc # Comment/x
+#     Regexp.new("abc", "im")          #=> /abc/mi
+#
 # ## Free-Spacing Mode and Comments
 #
 # As mentioned above, the `x` option enables *free-spacing* mode. Literal white
@@ -649,9 +661,10 @@
 #        # raises Encoding::CompatibilityError: incompatible encoding regexp match
 #        #         (ISO-8859-1 regexp with UTF-8 string)
 #
-# ## Special global variables
+# ## Regexp Global Variables
 #
 # Pattern matching sets some global variables :
+#
 # *   `$~` is equivalent to Regexp.last_match;
 # *   `$&` contains the complete matched text;
 # *   `$`` contains string before match;
@@ -738,30 +751,79 @@
 #
 #     Regexp.new('a{0,29}' + 'a' * 29) =~ 'a' * 29
 #
+# ## Timeout
+#
+# There are two APIs to set timeout. One is Regexp.timeout=, which is
+# process-global configuration of timeout for Regexp matching.
+#
+#     Regexp.timeout = 3
+#     s = 'a' * 25 + 'd' + 'a' * 4 + 'c'
+#     /(b|a+)*c/ =~ s  #=> This raises an exception in three seconds
+#
+# The other is timeout keyword of Regexp.new.
+#
+#     re = Regexp.new("(b|a+)*c", timeout: 3)
+#     s = 'a' * 25 + 'd' + 'a' * 4 + 'c'
+#     /(b|a+)*c/ =~ s  #=> This raises an exception in three seconds
+#
+# When using Regexps to process untrusted input, you should use the timeout
+# feature to avoid excessive backtracking. Otherwise, a malicious user can
+# provide input to Regexp causing Denial-of-Service attack. Note that the
+# timeout is not set by default because an appropriate limit highly depends on
+# an application requirement and context.
+#
 class Regexp
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.new(string, [options])       -> regexp
-  #   - Regexp.new(regexp)                  -> regexp
-  #   - Regexp.compile(string, [options])   -> regexp
-  #   - Regexp.compile(regexp)              -> regexp
+  #   - Regexp.new(string, options = 0, timeout: nil) -> regexp
+  #   - Regexp.new(regexp, timeout: nil) -> regexp
   # -->
-  # Constructs a new regular expression from `pattern`, which can be either a
-  # String or a Regexp (in which case that regexp's options are propagated), and
-  # new options may not be specified (a change as of Ruby 1.8).
-  #
-  # If `options` is an Integer, it should be one or more of the constants
-  # Regexp::EXTENDED, Regexp::IGNORECASE, and Regexp::MULTILINE, *or*-ed together.
-  #  Otherwise, if `options` is not `nil` or `false`, the regexp will be case
-  # insensitive.
-  #
-  #     r1 = Regexp.new('^a-z+:\\s+\w+') #=> /^a-z+:\s+\w+/
-  #     r2 = Regexp.new('cat', true)     #=> /cat/i
-  #     r3 = Regexp.new(r2)              #=> /cat/i
-  #     r4 = Regexp.new('dog', Regexp::EXTENDED | Regexp::IGNORECASE) #=> /dog/ix
-  #
-  def initialize: (String string, ?Integer | nil | false | top options, ?String kcode) -> Object
-                | (Regexp regexp) -> void
+  # With argument `string` given, returns a new regexp with the given string and
+  # options:
+  #
+  #     r = Regexp.new('foo') # => /foo/
+  #     r.source              # => "foo"
+  #     r.options             # => 0
+  #
+  # Optional argument `options` is one of the following:
+  #
+  # *   A String of options:
+  #
+  #         Regexp.new('foo', 'i')  # => /foo/i
+  #         Regexp.new('foo', 'im') # => /foo/im
+  #
+  # *   The logical OR of one or more of the constants Regexp::EXTENDED,
+  #     Regexp::IGNORECASE, Regexp::MULTILINE, and Regexp::NOENCODING:
+  #
+  #         Regexp.new('foo', Regexp::IGNORECASE) # => /foo/i
+  #         Regexp.new('foo', Regexp::EXTENDED)   # => /foo/x
+  #         Regexp.new('foo', Regexp::MULTILINE)  # => /foo/m
+  #         Regexp.new('foo', Regexp::NOENCODING)  # => /foo/n
+  #         flags = Regexp::IGNORECASE | Regexp::EXTENDED |  Regexp::MULTILINE
+  #         Regexp.new('foo', flags)              # => /foo/mix
+  #
+  # *   `nil` or `false`, which is ignored.
+  #
+  #
+  # If optional keyword argument `timeout` is given, its float value overrides the
+  # timeout interval for the class, Regexp.timeout. If `nil` is passed as
+  # +timeout, it uses the timeout interval for the class, Regexp.timeout.
+  #
+  # With argument `regexp` given, returns a new regexp. The source, options,
+  # timeout are the same as `regexp`. `options` and `n_flag` arguments are
+  # ineffective.  The timeout can be overridden by `timeout` keyword.
+  #
+  #     options = Regexp::MULTILINE
+  #     r = Regexp.new('foo', options, timeout: 1.1) # => /foo/m
+  #     r2 = Regexp.new(r)                           # => /foo/m
+  #     r2.timeout                                   # => 1.1
+  #     r3 = Regexp.new(r, timeout: 3.14)            # => /foo/m
+  #     r3.timeout                                   # => 3.14
+  #
+  # Regexp.compile is an alias for Regexp.new.
+  #
+  def initialize: (String string, ?String | Integer | nil | false options, ?timeout: Float?) -> Object
+                | (Regexp regexp, ?timeout: Float?) -> void
 
   # <!--
   #   rdoc-file=re.c
@@ -773,42 +835,57 @@ class Regexp
 
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.escape(str)   -> string
-  #   - Regexp.quote(str)    -> string
+  #   - Regexp.escape(string) -> new_string
   # -->
-  # Escapes any characters that would have special meaning in a regular
-  # expression. Returns a new escaped string with the same or compatible encoding.
-  # For any string, `Regexp.new(Regexp.escape(*str*))=~*str`* will be true.
+  # Returns a new string that escapes any characters that have special meaning in
+  # a regular expression:
+  #
+  #     s = Regexp.escape('\*?{}.')      # => "\\\\\\*\\?\\{\\}\\."
   #
-  #     Regexp.escape('\*?{}.')   #=> \\\*\?\{\}\.
+  # For any string `s`, this call returns a MatchData object:
+  #
+  #     r = Regexp.new(Regexp.escape(s)) # => /\\\\\\\*\\\?\\\{\\\}\\\./
+  #     r.match(s)                       # => #<MatchData "\\\\\\*\\?\\{\\}\\.">
+  #
+  # Regexp.quote is an alias for Regexp.escape.
   #
   def self.escape: (String | Symbol str) -> String
 
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.last_match           -> matchdata
-  #   - Regexp.last_match(n)        -> str
+  #   - Regexp.last_match -> matchdata or nil
+  #   - Regexp.last_match(n) -> string or nil
+  #   - Regexp.last_match(name) -> string or nil
   # -->
-  # The first form returns the MatchData object generated by the last successful
-  # pattern match.  Equivalent to reading the special global variable `$~` (see
-  # Special global variables in Regexp for details).
+  # With no argument, returns the value of `$!`, which is the result of the most
+  # recent pattern match (see [Regexp Global
+  # Variables](rdoc-ref:Regexp@Regexp+Global+Variables)):
+  #
+  #     /c(.)t/ =~ 'cat'  # => 0
+  #     Regexp.last_match # => #<MatchData "cat" 1:"a">
+  #     /a/ =~ 'foo'      # => nil
+  #     Regexp.last_match # => nil
+  #
+  # With non-negative integer argument `n`, returns the _n_th field in the
+  # matchdata, if any, or nil if none:
   #
-  # The second form returns the *n*th field in this MatchData object. *n* can be a
-  # string or symbol to reference a named capture.
+  #     /c(.)t/ =~ 'cat'     # => 0
+  #     Regexp.last_match(0) # => "cat"
+  #     Regexp.last_match(1) # => "a"
+  #     Regexp.last_match(2) # => nil
   #
-  # Note that the last_match is local to the thread and method scope of the method
-  # that did the pattern match.
+  # With negative integer argument `n`, counts backwards from the last field:
   #
-  #     /c(.)t/ =~ 'cat'        #=> 0
-  #     Regexp.last_match       #=> #<MatchData "cat" 1:"a">
-  #     Regexp.last_match(0)    #=> "cat"
-  #     Regexp.last_match(1)    #=> "a"
-  #     Regexp.last_match(2)    #=> nil
+  #     Regexp.last_match(-1)       # => "a"
   #
-  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "var = val"
-  #     Regexp.last_match       #=> #<MatchData "var = val" lhs:"var" rhs:"val">
-  #     Regexp.last_match(:lhs) #=> "var"
-  #     Regexp.last_match(:rhs) #=> "val"
+  # With string or symbol argument `name`, returns the string value for the named
+  # capture, if any:
+  #
+  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ 'var = val'
+  #     Regexp.last_match        # => #<MatchData "var = val" lhs:"var"rhs:"val">
+  #     Regexp.last_match(:lhs)  # => "var"
+  #     Regexp.last_match('rhs') # => "val"
+  #     Regexp.last_match('foo') # Raises IndexError.
   #
   def self.last_match: () -> MatchData?
                      | (Integer n) -> String?
@@ -816,54 +893,116 @@ class Regexp
 
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.escape(str)   -> string
-  #   - Regexp.quote(str)    -> string
+  #   - Regexp.linear_time?(re)
+  #   - Regexp.linear_time?(string, options = 0)
   # -->
-  # Escapes any characters that would have special meaning in a regular
-  # expression. Returns a new escaped string with the same or compatible encoding.
-  # For any string, `Regexp.new(Regexp.escape(*str*))=~*str`* will be true.
+  # Returns `true` if matching against `re` can be done in linear time to the
+  # input string.
+  #
+  #     Regexp.linear_time?(/re/) # => true
+  #
+  # Note that this is a property of the ruby interpreter, not of the argument
+  # regular expression.  Identical regexp can or cannot run in linear time
+  # depending on your ruby binary.  Neither forward nor backward compatibility is
+  # guaranteed about the return value of this method.  Our current algorithm is
+  # (*1) but this is subject to change in the future.  Alternative implementations
+  # can also behave differently.  They might always return false for everything.
   #
-  #     Regexp.escape('\*?{}.')   #=> \\\*\?\{\}\.
+  # (*1): https://doi.org/10.1109/SP40001.2021.00032
+  #
+  def self.linear_time?: () -> bool
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - Regexp.escape(string) -> new_string
+  # -->
+  # Returns a new string that escapes any characters that have special meaning in
+  # a regular expression:
+  #
+  #     s = Regexp.escape('\*?{}.')      # => "\\\\\\*\\?\\{\\}\\."
+  #
+  # For any string `s`, this call returns a MatchData object:
+  #
+  #     r = Regexp.new(Regexp.escape(s)) # => /\\\\\\\*\\\?\\\{\\\}\\\./
+  #     r.match(s)                       # => #<MatchData "\\\\\\*\\?\\{\\}\\.">
+  #
+  # Regexp.quote is an alias for Regexp.escape.
   #
   def self.quote: (String | Symbol str) -> String
 
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.try_convert(obj) -> re or nil
+  #   - Regexp.try_convert(object) -> regexp or nil
   # -->
-  # Try to convert *obj* into a Regexp, using to_regexp method. Returns converted
-  # regexp or nil if *obj* cannot be converted for any reason.
+  # Returns `object` if it is a regexp:
+  #
+  #     Regexp.try_convert(/re/) # => /re/
   #
-  #     Regexp.try_convert(/re/)         #=> /re/
-  #     Regexp.try_convert("re")         #=> nil
+  # Otherwise if `object` responds to `:to_regexp`, calls `object.to_regexp` and
+  # returns the result.
   #
-  #     o = Object.new
-  #     Regexp.try_convert(o)            #=> nil
-  #     def o.to_regexp() /foo/ end
-  #     Regexp.try_convert(o)            #=> /foo/
+  # Returns `nil` if `object` does not respond to `:to_regexp`.
+  #
+  #     Regexp.try_convert('re') # => nil
+  #
+  # Raises an exception unless `object.to_regexp` returns a regexp.
   #
   def self.try_convert: (untyped obj) -> Regexp?
 
   # <!--
   #   rdoc-file=re.c
-  #   - Regexp.union(pat1, pat2, ...)            -> new_regexp
-  #   - Regexp.union(pats_ary)                   -> new_regexp
+  #   - Regexp.timeout  -> float or nil
+  # -->
+  # It returns the current default timeout interval for Regexp matching in second.
+  # `nil` means no default timeout configuration.
+  #
+  def self.timeout: () -> Float?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - Regexp.timeout = float or nil
+  # -->
+  # It sets the default timeout interval for Regexp matching in second. `nil`
+  # means no default timeout configuration. This configuration is process-global.
+  # If you want to set timeout for each Regexp, use `timeout` keyword for
+  # `Regexp.new`.
+  #
+  #     Regexp.timeout = 1
+  #     /^a*b?a*$/ =~ "a" * 100000 + "x" #=> regexp match timeout (RuntimeError)
+  #
+  def self.timeout=: (Float?) -> Float?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - Regexp.union(*patterns) -> regexp
+  #   - Regexp.union(array_of_patterns) -> regexp
   # -->
-  # Return a Regexp object that is the union of the given *pattern*s, i.e., will
-  # match any of its parts. The *pattern*s can be Regexp objects, in which case
-  # their options will be preserved, or Strings. If no patterns are given, returns
-  # `/(?!)/`.  The behavior is unspecified if any given *pattern* contains
-  # capture.
-  #
-  #     Regexp.union                         #=> /(?!)/
-  #     Regexp.union("penzance")             #=> /penzance/
-  #     Regexp.union("a+b*c")                #=> /a\+b\*c/
-  #     Regexp.union("skiing", "sledding")   #=> /skiing|sledding/
-  #     Regexp.union(["skiing", "sledding"]) #=> /skiing|sledding/
-  #     Regexp.union(/dogs/, /cats/i)        #=> /(?-mix:dogs)|(?i-mx:cats)/
-  #
-  # Note: the arguments for ::union will try to be converted into a regular
-  # expression literal via #to_regexp.
+  # Returns a new regexp that is the union of the given patterns:
+  #
+  #     r = Regexp.union(%w[cat dog])      # => /cat|dog/
+  #     r.match('cat')      # => #<MatchData "cat">
+  #     r.match('dog')      # => #<MatchData "dog">
+  #     r.match('cog')      # => nil
+  #
+  # For each pattern that is a string, `Regexp.new(pattern)` is used:
+  #
+  #     Regexp.union('penzance')             # => /penzance/
+  #     Regexp.union('a+b*c')                # => /a\+b\*c/
+  #     Regexp.union('skiing', 'sledding')   # => /skiing|sledding/
+  #     Regexp.union(['skiing', 'sledding']) # => /skiing|sledding/
+  #
+  # For each pattern that is a regexp, it is used as is, including its flags:
+  #
+  #     Regexp.union(/foo/i, /bar/m, /baz/x)
+  #     # => /(?i-mx:foo)|(?m-ix:bar)|(?x-mi:baz)/
+  #     Regexp.union([/foo/i, /bar/m, /baz/x])
+  #     # => /(?i-mx:foo)|(?m-ix:bar)|(?x-mi:baz)/
+  #
+  # With no arguments, returns `/(?!)/`:
+  #
+  #     Regexp.union # => /(?!)/
+  #
+  # If any regexp pattern contains captures, the behavior is unspecified.
   #
   def self.union: () -> Regexp
                 | (String | Regexp pat1, *String | Regexp pat2) -> Regexp
@@ -872,93 +1011,103 @@ class Regexp
   public
 
   # <!-- rdoc-file=re.c -->
-  # Equality---Two regexps are equal if their patterns are identical, they have
-  # the same character set code, and their `casefold?` values are the same.
+  # Returns `true` if `object` is another Regexp whose pattern, flags, and
+  # encoding are the same as `self`, `false` otherwise:
   #
-  #     /abc/  == /abc/x   #=> false
-  #     /abc/  == /abc/i   #=> false
-  #     /abc/  == /abc/u   #=> false
-  #     /abc/u == /abc/n   #=> false
+  #     /foo/ == Regexp.new('foo')                          # => true
+  #     /foo/ == /foo/i                                     # => false
+  #     /foo/ == Regexp.new('food')                         # => false
+  #     /foo/ == Regexp.new("abc".force_encoding("euc-jp")) # => false
+  #
+  # Regexp#eql? is an alias for Regexp#==.
   #
   def ==: (untyped other) -> bool
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp === str   -> true or false
+  #   - regexp === string -> true or false
   # -->
-  # Case Equality---Used in case statements.
+  # Returns `true` if `self` finds a match in `string`:
   #
-  #     a = "HELLO"
-  #     case a
-  #     when /\A[a-z]*\z/; print "Lower case\n"
-  #     when /\A[A-Z]*\z/; print "Upper case\n"
-  #     else;              print "Mixed case\n"
-  #     end
-  #     #=> "Upper case"
+  #     /^[a-z]*$/ === 'HELLO' # => false
+  #     /^[A-Z]*$/ === 'HELLO' # => true
   #
-  # Following a regular expression literal with the #=== operator allows you to
-  # compare against a String.
+  # This method is called in case statements:
   #
-  #     /^[a-z]*$/ === "HELLO" #=> false
-  #     /^[A-Z]*$/ === "HELLO" #=> true
+  #     s = 'HELLO'
+  #     case s
+  #     when /\A[a-z]*\z/; print "Lower case\n"
+  #     when /\A[A-Z]*\z/; print "Upper case\n"
+  #     else               print "Mixed case\n"
+  #     end # => "Upper case"
   #
   def ===: (untyped other) -> bool
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp =~ str    -> integer or nil
+  #   - regexp =~ string -> integer or nil
   # -->
-  # Match---Matches *rxp* against *str*.
+  # Returns the integer index (in characters) of the first match for `self` and
+  # `string`, or `nil` if none; also sets the [rdoc-ref:Regexp Global
+  # Variables](rdoc-ref:Regexp@Regexp+Global+Variables):
+  #
+  #     /at/ =~ 'input data' # => 7
+  #     $~                   # => #<MatchData "at">
+  #     /ax/ =~ 'input data' # => nil
+  #     $~                   # => nil
   #
-  #     /at/ =~ "input data"   #=> 7
-  #     /ax/ =~ "input data"   #=> nil
+  # Assigns named captures to local variables of the same names if and only if
+  # `self`:
   #
-  # If `=~` is used with a regexp literal with named captures, captured strings
-  # (or nil) is assigned to local variables named by the capture names.
+  # *   Is a regexp literal; see [Regexp
+  #     Literals](rdoc-ref:literals.rdoc@Regexp+Literals).
+  # *   Does not contain interpolations; see [Regexp
+  #     Interpolation](rdoc-ref:Regexp@Regexp+Interpolation).
+  # *   Is at the left of the expression.
   #
-  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "  x = y  "
-  #     p lhs    #=> "x"
-  #     p rhs    #=> "y"
   #
-  # If it is not matched, nil is assigned for the variables.
+  # Example:
   #
-  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "  x = "
-  #     p lhs    #=> nil
-  #     p rhs    #=> nil
+  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ '  x = y  '
+  #     p lhs # => "x"
+  #     p rhs # => "y"
   #
-  # This assignment is implemented in the Ruby parser. The parser detects
-  # 'regexp-literal =~ expression' for the assignment. The regexp must be a
-  # literal without interpolation and placed at left hand side.
+  # Assigns `nil` if not matched:
   #
-  # The assignment does not occur if the regexp is not a literal.
+  #     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ '  x = '
+  #     p lhs # => nil
+  #     p rhs # => nil
   #
-  #     re = /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/
-  #     re =~ "  x = y  "
-  #     p lhs    # undefined local variable
-  #     p rhs    # undefined local variable
+  # Does not make local variable assignments if `self` is not a regexp literal:
   #
-  # A regexp interpolation, `#{}`, also disables the assignment.
+  #     r = /(?<foo>\w+)\s*=\s*(?<foo>\w+)/
+  #     r =~ '  x = y  '
+  #     p foo # Undefined local variable
+  #     p bar # Undefined local variable
   #
-  #     rhs_pat = /(?<rhs>\w+)/
-  #     /(?<lhs>\w+)\s*=\s*#{rhs_pat}/ =~ "x = y"
-  #     p lhs    # undefined local variable
+  # The assignment does not occur if the regexp is not at the left:
   #
-  # The assignment does not occur if the regexp is placed at the right hand side.
+  #     '  x = y  ' =~ /(?<foo>\w+)\s*=\s*(?<foo>\w+)/
+  #     p foo, foo # Undefined local variables
   #
-  #     "  x = y  " =~ /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/
-  #     p lhs, rhs # undefined local variable
+  # A regexp interpolation, `#{}`, also disables the assignment:
   #
-  def =~: (String? str) -> Integer?
+  #     r = /(?<foo>\w+)/
+  #     /(?<foo>\w+)\s*=\s*#{r}/ =~ 'x = y'
+  #     p foo # Undefined local variable
+  #
+  def =~: (String? | Symbol | _ToStr str) -> Integer?
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.casefold?   -> true or false
+  #   - casefold?-> true or false
   # -->
-  # Returns the value of the case-insensitive flag.
+  # Returns `true` if the case-insensitivity flag in `self` is set, `false`
+  # otherwise:
   #
-  #     /a/.casefold?           #=> false
-  #     /a/i.casefold?          #=> true
-  #     /(?i:a)/.casefold?      #=> false
+  #     /a/.casefold?           # => false
+  #     /a/i.casefold?          # => true
+  #     /(?i:a)/.casefold?      # => false
   #
   def casefold?: () -> bool
 
@@ -972,224 +1121,265 @@ class Regexp
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp == other_rxp      -> true or false
-  #   - rxp.eql?(other_rxp)   -> true or false
+  #   - regexp == object -> true or false
   # -->
-  # Equality---Two regexps are equal if their patterns are identical, they have
-  # the same character set code, and their `casefold?` values are the same.
+  # Returns `true` if `object` is another Regexp whose pattern, flags, and
+  # encoding are the same as `self`, `false` otherwise:
+  #
+  #     /foo/ == Regexp.new('foo')                          # => true
+  #     /foo/ == /foo/i                                     # => false
+  #     /foo/ == Regexp.new('food')                         # => false
+  #     /foo/ == Regexp.new("abc".force_encoding("euc-jp")) # => false
   #
-  #     /abc/  == /abc/x   #=> false
-  #     /abc/  == /abc/i   #=> false
-  #     /abc/  == /abc/u   #=> false
-  #     /abc/u == /abc/n   #=> false
+  # Regexp#eql? is an alias for Regexp#==.
   #
   def eql?: (untyped other) -> bool
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.fixed_encoding?   -> true or false
+  #   - fixed_encoding?   -> true or false
   # -->
-  # Returns false if rxp is applicable to a string with any ASCII compatible
-  # encoding. Returns true otherwise.
-  #
-  #     r = /a/
-  #     r.fixed_encoding?                               #=> false
-  #     r =~ "\u{6666} a"                               #=> 2
-  #     r =~ "\xa1\xa2 a".force_encoding("euc-jp")      #=> 2
-  #     r =~ "abc".force_encoding("euc-jp")             #=> 0
-  #
-  #     r = /a/u
-  #     r.fixed_encoding?                               #=> true
-  #     r.encoding                                      #=> #<Encoding:UTF-8>
-  #     r =~ "\u{6666} a"                               #=> 2
-  #     r =~ "\xa1\xa2".force_encoding("euc-jp")        #=> Encoding::CompatibilityError
-  #     r =~ "abc".force_encoding("euc-jp")             #=> 0
-  #
-  #     r = /\u{6666}/
-  #     r.fixed_encoding?                               #=> true
-  #     r.encoding                                      #=> #<Encoding:UTF-8>
-  #     r =~ "\u{6666} a"                               #=> 0
-  #     r =~ "\xa1\xa2".force_encoding("euc-jp")        #=> Encoding::CompatibilityError
-  #     r =~ "abc".force_encoding("euc-jp")             #=> nil
+  # Returns `false` if `self` is applicable to a string with any ASCII-compatible
+  # encoding; otherwise returns `true`:
+  #
+  #     r = /a/                                          # => /a/
+  #     r.fixed_encoding?                               # => false
+  #     r.match?("\u{6666} a")                          # => true
+  #     r.match?("\xa1\xa2 a".force_encoding("euc-jp")) # => true
+  #     r.match?("abc".force_encoding("euc-jp"))        # => true
+  #
+  #     r = /a/u                                        # => /a/
+  #     r.fixed_encoding?                               # => true
+  #     r.match?("\u{6666} a")                          # => true
+  #     r.match?("\xa1\xa2".force_encoding("euc-jp"))   # Raises exception.
+  #     r.match?("abc".force_encoding("euc-jp"))        # => true
+  #
+  #     r = /\u{6666}/                                  # => /\u{6666}/
+  #     r.fixed_encoding?                               # => true
+  #     r.encoding                                      # => #<Encoding:UTF-8>
+  #     r.match?("\u{6666} a")                          # => true
+  #     r.match?("\xa1\xa2".force_encoding("euc-jp"))   # Raises exception.
+  #     r.match?("abc".force_encoding("euc-jp"))        # => false
   #
   def fixed_encoding?: () -> bool
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.hash   -> integer
+  #   - hash -> integer
   # -->
-  # Produce a hash based on the text and options of this regular expression.
+  # Returns the integer hash value for `self`.
   #
-  # See also Object#hash.
+  # Related: Object#hash.
   #
   def hash: () -> Integer
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.inspect   -> string
+  #   - inspect -> string
   # -->
-  # Produce a nicely formatted string-version of *rxp*. Perhaps surprisingly,
-  # `#inspect` actually produces the more natural version of the string than
-  # `#to_s`.
+  # Returns a nicely-formatted string representation of `self`:
+  #
+  #     /ab+c/ix.inspect # => "/ab+c/ix"
   #
-  #     /ab+c/ix.inspect        #=> "/ab+c/ix"
+  # Related: Regexp#to_s.
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.match(str, pos=0)                   -> matchdata or nil
-  #   - rxp.match(str, pos=0) {|match| block }  -> obj
+  #   - match(string, offset = 0) -> matchdata or nil
+  #   - match(string, offset = 0) {|matchdata| ... } -> object
   # -->
-  # Returns a MatchData object describing the match, or `nil` if there was no
-  # match. This is equivalent to retrieving the value of the special variable `$~`
-  # following a normal match.  If the second parameter is present, it specifies
-  # the position in the string to begin the search.
+  # With no block given, returns the MatchData object that describes the match, if
+  # any, or `nil` if none; the search begins at the given character `offset` in
+  # `string`:
   #
-  #     /(.)(.)(.)/.match("abc")[2]   #=> "b"
-  #     /(.)(.)/.match("abc", 1)[2]   #=> "c"
+  #     /abra/.match('abracadabra')      # => #<MatchData "abra">
+  #     /abra/.match('abracadabra', 4)   # => #<MatchData "abra">
+  #     /abra/.match('abracadabra', 8)   # => nil
+  #     /abra/.match('abracadabra', 800) # => nil
   #
-  # If a block is given, invoke the block with MatchData if match succeed, so that
-  # you can write
+  #     string = "\u{5d0 5d1 5e8 5d0}cadabra"
+  #     /abra/.match(string, 7)          #=> #<MatchData "abra">
+  #     /abra/.match(string, 8)          #=> nil
+  #     /abra/.match(string.b, 8)        #=> #<MatchData "abra">
   #
-  #     /M(.*)/.match("Matz") do |m|
-  #       puts m[0]
-  #       puts m[1]
-  #     end
+  # With a block given, calls the block if and only if a match is found; returns
+  # the block's value:
   #
-  # instead of
+  #     /abra/.match('abracadabra') {|matchdata| p matchdata }
+  #     # => #<MatchData "abra">
+  #     /abra/.match('abracadabra', 4) {|matchdata| p matchdata }
+  #     # => #<MatchData "abra">
+  #     /abra/.match('abracadabra', 8) {|matchdata| p matchdata }
+  #     # => nil
+  #     /abra/.match('abracadabra', 8) {|marchdata| fail 'Cannot happen' }
+  #     # => nil
   #
-  #     if m = /M(.*)/.match("Matz")
-  #       puts m[0]
-  #       puts m[1]
-  #     end
+  # Output (from the first two blocks above):
   #
-  # The return value is a value from block execution in this case.
+  #     #<MatchData "abra">
+  #     #<MatchData "abra">
+  #
+  #      /(.)(.)(.)/.match("abc")[2] # => "b"
+  #      /(.)(.)/.match("abc", 1)[2] # => "c"
   #
   def match: (String? | Symbol | _ToStr str, ?Integer pos) -> MatchData?
            | [T] (String? | Symbol | _ToStr str, ?Integer pos) { (MatchData) -> T } -> T?
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.match?(str)          -> true or false
-  #   - rxp.match?(str, pos=0)   -> true or false
+  #   - match?(string) -> true or false
+  #   - match?(string, offset = 0) -> true or false
   # -->
   # Returns `true` or `false` to indicate whether the regexp is matched or not
   # without updating $~ and other related variables. If the second parameter is
   # present, it specifies the position in the string to begin the search.
   #
-  #     /R.../.match?("Ruby")    #=> true
-  #     /R.../.match?("Ruby", 1) #=> false
-  #     /P.../.match?("Ruby")    #=> false
-  #     $&                       #=> nil
+  #     /R.../.match?("Ruby")    # => true
+  #     /R.../.match?("Ruby", 1) # => false
+  #     /P.../.match?("Ruby")    # => false
+  #     $&                       # => nil
   #
   def match?: (String? | Symbol | _ToStr str, ?Integer pos) -> bool
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.named_captures  -> hash
+  #   - named_captures  -> hash
   # -->
-  # Returns a hash representing information about named captures of *rxp*.
-  #
-  # A key of the hash is a name of the named captures. A value of the hash is an
-  # array which is list of indexes of corresponding named captures.
+  # Returns a hash representing named captures of `self` (see [Named
+  # Captures](rdoc-ref:Regexp@Named+Captures)):
   #
-  #     /(?<foo>.)(?<bar>.)/.named_captures
-  #     #=> {"foo"=>[1], "bar"=>[2]}
+  # *   Each key is the name of a named capture.
+  # *   Each value is an array of integer indexes for that named capture.
   #
-  #     /(?<foo>.)(?<foo>.)/.named_captures
-  #     #=> {"foo"=>[1, 2]}
   #
-  # If there are no named captures, an empty hash is returned.
+  # Examples:
   #
-  #     /(.)(.)/.named_captures
-  #     #=> {}
+  #     /(?<foo>.)(?<bar>.)/.named_captures # => {"foo"=>[1], "bar"=>[2]}
+  #     /(?<foo>.)(?<foo>.)/.named_captures # => {"foo"=>[1, 2]}
+  #     /(.)(.)/.named_captures             # => {}
   #
   def named_captures: () -> ::Hash[String, ::Array[Integer]]
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.names   -> [name1, name2, ...]
+  #   - names -> array_of_names
   # -->
-  # Returns a list of names of captures as an array of strings.
-  #
-  #     /(?<foo>.)(?<bar>.)(?<baz>.)/.names
-  #     #=> ["foo", "bar", "baz"]
-  #
-  #     /(?<foo>.)(?<foo>.)/.names
-  #     #=> ["foo"]
+  # Returns an array of names of captures (see [Named
+  # Captures](rdoc-ref:Regexp@Named+Captures)):
   #
-  #     /(.)(.)/.names
-  #     #=> []
+  #     /(?<foo>.)(?<bar>.)(?<baz>.)/.names # => ["foo", "bar", "baz"]
+  #     /(?<foo>.)(?<foo>.)/.names          # => ["foo"]
+  #     /(.)(.)/.names                      # => []
   #
   def names: () -> ::Array[String]
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.options   -> integer
+  #   - options -> integer
   # -->
-  # Returns the set of bits corresponding to the options used when creating this
-  # Regexp (see Regexp::new for details. Note that additional bits may be set in
-  # the returned options: these are used internally by the regular expression
-  # code. These extra bits are ignored if the options are passed to Regexp::new.
+  # Returns an integer whose bits show the options set in `self`.
+  #
+  # The option bits are:
   #
-  #     Regexp::IGNORECASE                  #=> 1
-  #     Regexp::EXTENDED                    #=> 2
-  #     Regexp::MULTILINE                   #=> 4
+  #     Regexp::IGNORECASE # => 1
+  #     Regexp::EXTENDED   # => 2
+  #     Regexp::MULTILINE  # => 4
   #
-  #     /cat/.options                       #=> 0
-  #     /cat/ix.options                     #=> 3
-  #     Regexp.new('cat', true).options     #=> 1
-  #     /\xa1\xa2/e.options                 #=> 16
+  # Examples:
   #
-  #     r = /cat/ix
-  #     Regexp.new(r.source, r.options)     #=> /cat/ix
+  #     /foo/.options    # => 0
+  #     /foo/i.options   # => 1
+  #     /foo/x.options   # => 2
+  #     /foo/m.options   # => 4
+  #     /foo/mix.options # => 7
+  #
+  # Note that additional bits may be set in the returned integer; these are
+  # maintained internally internally in `self`, are ignored if passed to
+  # Regexp.new, and may be ignored by the caller:
+  #
+  # Returns the set of bits corresponding to the options used when creating this
+  # regexp (see Regexp::new for details). Note that additional bits may be set in
+  # the returned options: these are used internally by the regular expression
+  # code. These extra bits are ignored if the options are passed to Regexp::new:
+  #
+  #     r = /\xa1\xa2/e                 # => /\xa1\xa2/
+  #     r.source                        # => "\\xa1\\xa2"
+  #     r.options                       # => 16
+  #     Regexp.new(r.source, r.options) # => /\xa1\xa2/
   #
   def options: () -> Integer
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.source   -> str
+  #   - source -> string
   # -->
-  # Returns the original string of the pattern.
+  # Returns the original string of `self`:
+  #
+  #     /ab+c/ix.source # => "ab+c"
+  #
+  # Regexp escape sequences are retained:
   #
-  #     /ab+c/ix.source #=> "ab+c"
+  #     /\x20\+/.source  # => "\\x20\\+"
   #
-  # Note that escape sequences are retained as is.
+  # Lexer escape characters are not retained:
   #
-  #     /\x20\+/.source  #=> "\\x20\\+"
+  #     /\//.source  # => "/"
   #
   def source: () -> String
 
   # <!--
   #   rdoc-file=re.c
-  #   - rxp.to_s   -> str
+  #   - to_s -> string
   # -->
-  # Returns a string containing the regular expression and its options (using the
-  # `(?opts:source)` notation. This string can be fed back in to Regexp::new to a
-  # regular expression with the same semantics as the original. (However,
-  # `Regexp#==` may not return true when comparing the two, as the source of the
-  # regular expression itself may differ, as the example shows).  Regexp#inspect
-  # produces a generally more readable version of *rxp*.
-  #
-  #     r1 = /ab+c/ix           #=> /ab+c/ix
-  #     s1 = r1.to_s            #=> "(?ix-m:ab+c)"
-  #     r2 = Regexp.new(s1)     #=> /(?ix-m:ab+c)/
-  #     r1 == r2                #=> false
-  #     r1.source               #=> "ab+c"
-  #     r2.source               #=> "(?ix-m:ab+c)"
+  # Returns a string showing the options and string of `self`:
+  #
+  #     r0 = /ab+c/ix
+  #     s0 = r0.to_s # => "(?ix-m:ab+c)"
+  #
+  # The returned string may be used as an argument to Regexp.new, or as
+  # interpolated text for a [Regexp literal](rdoc-ref:regexp.rdoc@Regexp+Literal):
+  #
+  #     r1 = Regexp.new(s0) # => /(?ix-m:ab+c)/
+  #     r2 = /#{s0}/        # => /(?ix-m:ab+c)/
+  #
+  # Note that `r1` and `r2` are not equal to `r0` because their original strings
+  # are different:
+  #
+  #     r0 == r1  # => false
+  #     r0.source # => "ab+c"
+  #     r1.source # => "(?ix-m:ab+c)"
+  #
+  # Related: Regexp#inspect.
   #
   def to_s: () -> String
 
   # <!--
   #   rdoc-file=re.c
-  #   - ~ rxp   -> integer or nil
+  #   - rxp.timeout  -> float or nil
+  # -->
+  # It returns the timeout interval for Regexp matching in second. `nil` means no
+  # default timeout configuration.
+  #
+  # This configuration is per-object. The global configuration set by
+  # Regexp.timeout= is ignored if per-object configuration is set.
+  #
+  #     re = Regexp.new("^a*b?a*$", timeout: 1)
+  #     re.timeout               #=> 1.0
+  #     re =~ "a" * 100000 + "x" #=> regexp match timeout (RuntimeError)
+  #
+  %a{pure}
+  def timeout: () -> Float?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - ~ rxp -> integer or nil
   # -->
-  # Match---Matches *rxp* against the contents of `$_`. Equivalent to *`rxp* =~
-  # $_`.
+  # Equivalent to *`rxp* =~ $_`:
   #
   #     $_ = "input data"
-  #     ~ /at/   #=> 7
+  #     ~ /at/ # => 7
   #
   def ~: () -> Integer?