rbs 4.0.0.dev.4 → 4.0.0.dev.5

data/core/pathname.rbs

@@ -0,0 +1,1272 @@
+# <!-- rdoc-file=lib/pathname.rb -->
+# # pathname.rb
+#
+# Object-Oriented Pathname Class
+#
+# Author
+# :   Tanaka Akira <akr@m17n.org>
+#
+# Documentation
+# :   Author and Gavin Sinclair
+#
+#
+# For documentation, see class Pathname.
+#
+# <!-- rdoc-file=pathname_builtin.rb -->
+# Pathname represents the name of a file or directory on the filesystem, but not
+# the file itself.
+#
+# The pathname depends on the Operating System: Unix, Windows, etc. This library
+# works with pathnames of local OS, however non-Unix pathnames are supported
+# experimentally.
+#
+# A Pathname can be relative or absolute.  It's not until you try to reference
+# the file that it even matters whether the file exists or not.
+#
+# Pathname is immutable.  It has no method for destructive update.
+#
+# The goal of this class is to manipulate file path information in a neater way
+# than standard Ruby provides.  The examples below demonstrate the difference.
+#
+# **All** functionality from File, FileTest, and some from Dir and FileUtils is
+# included, in an unsurprising way.  It is essentially a facade for all of
+# these, and more.
+#
+# ## Examples
+#
+# ### Example 1: Using Pathname
+#
+#     require 'pathname'
+#     pn = Pathname.new("/usr/bin/ruby")
+#     size = pn.size              # 27662
+#     isdir = pn.directory?       # false
+#     dir  = pn.dirname           # Pathname:/usr/bin
+#     base = pn.basename          # Pathname:ruby
+#     dir, base = pn.split        # [Pathname:/usr/bin, Pathname:ruby]
+#     data = pn.read
+#     pn.open { |f| _ }
+#     pn.each_line { |line| _ }
+#
+# ### Example 2: Using standard Ruby
+#
+#     pn = "/usr/bin/ruby"
+#     size = File.size(pn)        # 27662
+#     isdir = File.directory?(pn) # false
+#     dir  = File.dirname(pn)     # "/usr/bin"
+#     base = File.basename(pn)    # "ruby"
+#     dir, base = File.split(pn)  # ["/usr/bin", "ruby"]
+#     data = File.read(pn)
+#     File.open(pn) { |f| _ }
+#     File.foreach(pn) { |line| _ }
+#
+# ### Example 3: Special features
+#
+#     p1 = Pathname.new("/usr/lib")   # Pathname:/usr/lib
+#     p2 = p1 + "ruby/1.8"            # Pathname:/usr/lib/ruby/1.8
+#     p3 = p1.parent                  # Pathname:/usr
+#     p4 = p2.relative_path_from(p3)  # Pathname:lib/ruby/1.8
+#     pwd = Pathname.pwd              # Pathname:/home/gavin
+#     pwd.absolute?                   # true
+#     p5 = Pathname.new "."           # Pathname:.
+#     p5 = p5 + "music/../articles"   # Pathname:music/../articles
+#     p5.cleanpath                    # Pathname:articles
+#     p5.realpath                     # Pathname:/home/gavin/articles
+#     p5.children                     # [Pathname:/home/gavin/articles/linux, ...]
+#
+# ## Breakdown of functionality
+#
+# ### Core methods
+#
+# These methods are effectively manipulating a String, because that's all a path
+# is.  None of these access the file system except for #mountpoint?, #children,
+# #each_child, #realdirpath and #realpath.
+#
+# *   +
+# *   #join
+# *   #parent
+# *   #root?
+# *   #absolute?
+# *   #relative?
+# *   #relative_path_from
+# *   #each_filename
+# *   #cleanpath
+# *   #realpath
+# *   #realdirpath
+# *   #children
+# *   #each_child
+# *   #mountpoint?
+#
+# ### File status predicate methods
+#
+# These methods are a facade for FileTest:
+# *   #blockdev?
+# *   #chardev?
+# *   #directory?
+# *   #executable?
+# *   #executable_real?
+# *   #exist?
+# *   #file?
+# *   #grpowned?
+# *   #owned?
+# *   #pipe?
+# *   #readable?
+# *   #world_readable?
+# *   #readable_real?
+# *   #setgid?
+# *   #setuid?
+# *   #size
+# *   #size?
+# *   #socket?
+# *   #sticky?
+# *   #symlink?
+# *   #writable?
+# *   #world_writable?
+# *   #writable_real?
+# *   #zero?
+#
+# ### File property and manipulation methods
+#
+# These methods are a facade for File:
+# *   #each_line(*args, &block)
+# *   #read(*args)
+# *   #binread(*args)
+# *   #readlines(*args)
+# *   #sysopen(*args)
+# *   #write(*args)
+# *   #binwrite(*args)
+# *   #atime
+# *   #birthtime
+# *   #ctime
+# *   #mtime
+# *   #chmod(mode)
+# *   #lchmod(mode)
+# *   #chown(owner, group)
+# *   #lchown(owner, group)
+# *   #fnmatch(pattern, *args)
+# *   #fnmatch?(pattern, *args)
+# *   #ftype
+# *   #make_link(old)
+# *   #open(*args, &block)
+# *   #readlink
+# *   #rename(to)
+# *   #stat
+# *   #lstat
+# *   #make_symlink(old)
+# *   #truncate(length)
+# *   #utime(atime, mtime)
+# *   #lutime(atime, mtime)
+# *   #basename(*args)
+# *   #dirname
+# *   #extname
+# *   #expand_path(*args)
+# *   #split
+#
+# ### Directory methods
+#
+# These methods are a facade for Dir:
+# *   Pathname.glob(*args)
+# *   Pathname.getwd / Pathname.pwd
+# *   #rmdir
+# *   #entries
+# *   #each_entry(&block)
+# *   #mkdir(*args)
+# *   #opendir(*args)
+#
+# ### Utilities
+#
+# These methods are a mixture of Find, FileUtils, and others:
+# *   #find(&block)
+# *   #mkpath
+# *   #rmtree
+# *   #unlink / #delete
+#
+# ## Method documentation
+#
+# As the above section shows, most of the methods in Pathname are facades.  The
+# documentation for these methods generally just says, for instance, "See
+# FileTest.writable?", as you should be familiar with the original method
+# anyway, and its documentation (e.g. through `ri`) will contain more
+# information.  In some cases, a brief description will follow.
+#
+class Pathname
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - getwd()
+  # -->
+  # See `Dir.getwd`.  Returns the current working directory as a Pathname.
+  #
+  def self.getwd: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - glob(*args, **kwargs) { |pathname| ... }
+  # -->
+  # See `Dir.glob`.  Returns or yields Pathname objects.
+  #
+  def self.glob: (String | Array[String] pattern, ?Integer flags) -> Array[Pathname]
+               | (String | Array[String] pattern, ?Integer flags) { (Pathname) -> untyped } -> nil
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - pwd()
+  # -->
+  #
+  def self.pwd: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - +(other)
+  # -->
+  # Appends a pathname fragment to `self` to produce a new Pathname object. Since
+  # `other` is considered as a path relative to `self`, if `other` is an absolute
+  # path, the new Pathname object is created from just `other`.
+  #
+  #     p1 = Pathname.new("/usr")      # Pathname:/usr
+  #     p2 = p1 + "bin/ruby"           # Pathname:/usr/bin/ruby
+  #     p3 = p1 + "/etc/passwd"        # Pathname:/etc/passwd
+  #
+  #     # / is aliased to +.
+  #     p4 = p1 / "bin/ruby"           # Pathname:/usr/bin/ruby
+  #     p5 = p1 / "/etc/passwd"        # Pathname:/etc/passwd
+  #
+  # This method doesn't access the file system; it is pure string manipulation.
+  #
+  def +: (Pathname | String | _ToStr other) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - /(other)
+  # -->
+  #
+  alias / +
+
+  # <!--
+  #   rdoc-file=pathname.c
+  #   - <=>(p1)
+  # -->
+  # Provides a case-sensitive comparison operator for pathnames.
+  #
+  #     Pathname.new('/usr') <=> Pathname.new('/usr/bin')
+  #         #=> -1
+  #     Pathname.new('/usr/bin') <=> Pathname.new('/usr/bin')
+  #         #=> 0
+  #     Pathname.new('/usr/bin') <=> Pathname.new('/USR/BIN')
+  #         #=> 1
+  #
+  # It will return `-1`, `0` or `1` depending on the value of the left argument
+  # relative to the right argument. Or it will return `nil` if the arguments are
+  # not comparable.
+  #
+  def <=>: (Pathname other) -> Integer
+         | (untyped other) -> nil
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - ==(other)
+  # -->
+  # Compare this pathname with `other`.  The comparison is string-based. Be aware
+  # that two different paths (`foo.txt` and `./foo.txt`) can refer to the same
+  # file.
+  #
+  def ==: (untyped) -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - ===(other)
+  # -->
+  #
+  def ===: (untyped) -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - absolute?()
+  # -->
+  # Predicate method for testing whether a path is absolute.
+  #
+  # It returns `true` if the pathname begins with a slash.
+  #
+  #     p = Pathname.new('/im/sure')
+  #     p.absolute?
+  #         #=> true
+  #
+  #     p = Pathname.new('not/so/sure')
+  #     p.absolute?
+  #         #=> false
+  #
+  def absolute?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - ascend() { |self| ... }
+  # -->
+  # Iterates over and yields a new Pathname object for each element in the given
+  # path in ascending order.
+  #
+  #     Pathname.new('/path/to/some/file.rb').ascend {|v| p v}
+  #        #<Pathname:/path/to/some/file.rb>
+  #        #<Pathname:/path/to/some>
+  #        #<Pathname:/path/to>
+  #        #<Pathname:/path>
+  #        #<Pathname:/>
+  #
+  #     Pathname.new('path/to/some/file.rb').ascend {|v| p v}
+  #        #<Pathname:path/to/some/file.rb>
+  #        #<Pathname:path/to/some>
+  #        #<Pathname:path/to>
+  #        #<Pathname:path>
+  #
+  # Returns an Enumerator if no block was given.
+  #
+  #     enum = Pathname.new("/usr/bin/ruby").ascend
+  #       # ... do stuff ...
+  #     enum.each { |e| ... }
+  #       # yields Pathnames /usr/bin/ruby, /usr/bin, /usr, and /.
+  #
+  # It doesn't access the filesystem.
+  #
+  def ascend: () { (Pathname) -> untyped } -> nil
+            | () -> Enumerator[Pathname, nil]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - atime()
+  # -->
+  # See `File.atime`.  Returns last access time.
+  #
+  def atime: () -> Time
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - basename(...)
+  # -->
+  # See `File.basename`.  Returns the last component of the path.
+  #
+  def basename: (?String | _ToStr suffix) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - binread(...)
+  # -->
+  # See `File.binread`.  Returns all the bytes from the file, or the first `N` if
+  # specified.
+  #
+  def binread: (?Integer length, ?Integer offset) -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - binwrite(...)
+  # -->
+  # Writes `contents` to the file, opening it in binary mode.
+  #
+  # See File.binwrite.
+  #
+  def binwrite: (String, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?invalid: :replace ?, ?undef: :replace ?, ?replace: String, ?fallback: Hash[String, String] | Proc | Method, ?xml: :text | :attr, ?universal_newline: true, ?cr_newline: true, ?crlf_newline: true) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - birthtime()
+  # -->
+  # Returns the birth time for the file. If the platform doesn't have birthtime,
+  # raises NotImplementedError.
+  #
+  # See File.birthtime.
+  #
+  def birthtime: () -> Time
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - blockdev?()
+  # -->
+  # See `FileTest.blockdev?`.
+  #
+  def blockdev?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - chardev?()
+  # -->
+  # See `FileTest.chardev?`.
+  #
+  def chardev?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - children(with_directory=true)
+  # -->
+  # Returns the children of the directory (files and subdirectories, not
+  # recursive) as an array of Pathname objects.
+  #
+  # By default, the returned pathnames will have enough information to access the
+  # files. If you set `with_directory` to `false`, then the returned pathnames
+  # will contain the filename only.
+  #
+  # For example:
+  #     pn = Pathname("/usr/lib/ruby/1.8")
+  #     pn.children
+  #         # -> [ Pathname:/usr/lib/ruby/1.8/English.rb,
+  #                Pathname:/usr/lib/ruby/1.8/Env.rb,
+  #                Pathname:/usr/lib/ruby/1.8/abbrev.rb, ... ]
+  #     pn.children(false)
+  #         # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]
+  #
+  # Note that the results never contain the entries `.` and `..` in the directory
+  # because they are not children.
+  #
+  def children: (?boolish with_directory) -> Array[Pathname]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - chmod(mode)
+  # -->
+  # See `File.chmod`.  Changes permissions.
+  #
+  def chmod: (Integer mode_int) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - chown(owner, group)
+  # -->
+  # See `File.chown`.  Change owner and group of file.
+  #
+  def chown: (Integer owner, Integer group) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - cleanpath(consider_symlink=false)
+  # -->
+  # Returns clean pathname of `self` with consecutive slashes and useless dots
+  # removed.  The filesystem is not accessed.
+  #
+  # If `consider_symlink` is `true`, then a more conservative algorithm is used to
+  # avoid breaking symbolic linkages.  This may retain more `..` entries than
+  # absolutely necessary, but without accessing the filesystem, this can't be
+  # avoided.
+  #
+  # See Pathname#realpath.
+  #
+  def cleanpath: (?boolish consider_symlink) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - ctime()
+  # -->
+  # See `File.ctime`.  Returns last (directory entry, not file) change time.
+  #
+  def ctime: () -> Time
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - delete()
+  # -->
+  #
+  def delete: () -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - descend() { |v| ... }
+  # -->
+  # Iterates over and yields a new Pathname object for each element in the given
+  # path in descending order.
+  #
+  #     Pathname.new('/path/to/some/file.rb').descend {|v| p v}
+  #        #<Pathname:/>
+  #        #<Pathname:/path>
+  #        #<Pathname:/path/to>
+  #        #<Pathname:/path/to/some>
+  #        #<Pathname:/path/to/some/file.rb>
+  #
+  #     Pathname.new('path/to/some/file.rb').descend {|v| p v}
+  #        #<Pathname:path>
+  #        #<Pathname:path/to>
+  #        #<Pathname:path/to/some>
+  #        #<Pathname:path/to/some/file.rb>
+  #
+  # Returns an Enumerator if no block was given.
+  #
+  #     enum = Pathname.new("/usr/bin/ruby").descend
+  #       # ... do stuff ...
+  #     enum.each { |e| ... }
+  #       # yields Pathnames /, /usr, /usr/bin, and /usr/bin/ruby.
+  #
+  # It doesn't access the filesystem.
+  #
+  def descend: () { (Pathname) -> untyped } -> nil
+             | () -> Enumerator[Pathname, nil]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - directory?()
+  # -->
+  # See `FileTest.directory?`.
+  #
+  def directory?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - dirname()
+  # -->
+  # See `File.dirname`.  Returns all but the last component of the path.
+  #
+  def dirname: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - each_child(with_directory=true, &b)
+  # -->
+  # Iterates over the children of the directory (files and subdirectories, not
+  # recursive).
+  #
+  # It yields Pathname object for each child.
+  #
+  # By default, the yielded pathnames will have enough information to access the
+  # files.
+  #
+  # If you set `with_directory` to `false`, then the returned pathnames will
+  # contain the filename only.
+  #
+  #     Pathname("/usr/local").each_child {|f| p f }
+  #     #=> #<Pathname:/usr/local/share>
+  #     #   #<Pathname:/usr/local/bin>
+  #     #   #<Pathname:/usr/local/games>
+  #     #   #<Pathname:/usr/local/lib>
+  #     #   #<Pathname:/usr/local/include>
+  #     #   #<Pathname:/usr/local/sbin>
+  #     #   #<Pathname:/usr/local/src>
+  #     #   #<Pathname:/usr/local/man>
+  #
+  #     Pathname("/usr/local").each_child(false) {|f| p f }
+  #     #=> #<Pathname:share>
+  #     #   #<Pathname:bin>
+  #     #   #<Pathname:games>
+  #     #   #<Pathname:lib>
+  #     #   #<Pathname:include>
+  #     #   #<Pathname:sbin>
+  #     #   #<Pathname:src>
+  #     #   #<Pathname:man>
+  #
+  # Note that the results never contain the entries `.` and `..` in the directory
+  # because they are not children.
+  #
+  # See Pathname#children
+  #
+  def each_child: (?boolish with_directory) { (Pathname) -> void } -> Array[Pathname]
+                | (?boolish with_directory) -> Enumerator[Pathname, Array[Pathname]]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - each_entry() { |pathname| ... }
+  # -->
+  # Iterates over the entries (files and subdirectories) in the directory.  It
+  # yields a Pathname object for each entry.
+  #
+  # This method has existed since 1.8.1.
+  #
+  def each_entry: () { (Pathname) -> untyped } -> nil
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - each_filename() { |filename| ... }
+  # -->
+  # Iterates over each component of the path.
+  #
+  #     Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
+  #       # yields "usr", "bin", and "ruby".
+  #
+  # Returns an Enumerator if no block was given.
+  #
+  #     enum = Pathname.new("/usr/bin/ruby").each_filename
+  #       # ... do stuff ...
+  #     enum.each { |e| ... }
+  #       # yields "usr", "bin", and "ruby".
+  #
+  def each_filename: () { (String) -> untyped } -> nil
+                   | () -> Enumerator[String, nil]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - each_line(...) { |line| ... }
+  # -->
+  # #each_line iterates over the line in the file.  It yields a String object for
+  # each line.
+  #
+  # This method has existed since 1.8.1.
+  #
+  def each_line: (?String sep, ?Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) { (String) -> untyped } -> nil
+               | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) { (String) -> untyped } -> nil
+               | (?String sep, ?Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Enumerator[String, nil]
+               | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Enumerator[String, nil]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - empty?()
+  # -->
+  # Tests the file is empty.
+  #
+  # See Dir#empty? and FileTest.empty?.
+  #
+  def empty?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - entries()
+  # -->
+  # Return the entries (files and subdirectories) in the directory, each as a
+  # Pathname object.
+  #
+  def entries: () -> Array[Pathname]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - eql?(other)
+  # -->
+  #
+  def eql?: (untyped) -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - executable?()
+  # -->
+  # See `FileTest.executable?`.
+  #
+  def executable?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - executable_real?()
+  # -->
+  # See `FileTest.executable_real?`.
+  #
+  def executable_real?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - exist?()
+  # -->
+  # See `FileTest.exist?`.
+  #
+  def exist?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - expand_path(...)
+  # -->
+  # See `File.expand_path`.
+  #
+  def expand_path: (?String dir) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - extname()
+  # -->
+  # See `File.extname`.  Returns the file's extension.
+  #
+  def extname: () -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - file?()
+  # -->
+  # See `FileTest.file?`.
+  #
+  def file?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - fnmatch(pattern, ...)
+  # -->
+  # See `File.fnmatch`.  Return `true` if the receiver matches the given pattern.
+  #
+  def fnmatch: (String pattern, ?Integer flags) -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - fnmatch?(pattern, ...)
+  # -->
+  # See `File.fnmatch?` (same as #fnmatch).
+  #
+  alias fnmatch? fnmatch
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - freeze()
+  # -->
+  # Freze self.
+  #
+  def freeze: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - ftype()
+  # -->
+  # See `File.ftype`.  Returns "type" of file ("file", "directory", etc).
+  #
+  def ftype: () -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - glob(*args, **kwargs) { |pathname| ... }
+  # -->
+  # Returns or yields Pathname objects.
+  #
+  #     Pathname("ruby-2.4.2").glob("R*.md")
+  #     #=> [#<Pathname:ruby-2.4.2/README.md>, #<Pathname:ruby-2.4.2/README.ja.md>]
+  #
+  # See Dir.glob. This method uses the `base` keyword argument of Dir.glob.
+  #
+  def glob: (String | Array[String] pattern, ?Integer flags) -> Array[Pathname]
+          | (String | Array[String] pattern, ?Integer flags) { (Pathname) -> untyped } -> nil
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - grpowned?()
+  # -->
+  # See `FileTest.grpowned?`.
+  #
+  def grpowned?: () -> bool
+
+  def hash: () -> Integer
+
+  def inspect: () -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - join(*args)
+  # -->
+  # Joins the given pathnames onto `self` to create a new Pathname object. This is
+  # effectively the same as using Pathname#+ to append `self` and all arguments
+  # sequentially.
+  #
+  #     path0 = Pathname.new("/usr")                # Pathname:/usr
+  #     path0 = path0.join("bin/ruby")              # Pathname:/usr/bin/ruby
+  #         # is the same as
+  #     path1 = Pathname.new("/usr") + "bin/ruby"   # Pathname:/usr/bin/ruby
+  #     path0 == path1
+  #         #=> true
+  #
+  def join: (*String | _ToStr | Pathname args) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - lchmod(mode)
+  # -->
+  # See `File.lchmod`.
+  #
+  def lchmod: (Integer mode) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - lchown(owner, group)
+  # -->
+  # See `File.lchown`.
+  #
+  def lchown: (Integer owner, Integer group) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - lstat()
+  # -->
+  # See `File.lstat`.
+  #
+  def lstat: () -> ::File::Stat
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - lutime(atime, mtime)
+  # -->
+  # Update the access and modification times of the file.
+  #
+  # Same as Pathname#utime, but does not follow symbolic links.
+  #
+  # See File.lutime.
+  #
+  def lutime: (Time | Numeric atime, Time | Numeric mtime) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - make_link(old)
+  # -->
+  # See `File.link`.  Creates a hard link.
+  #
+  def make_link: (String | Pathname | _ToStr old) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - make_symlink(old)
+  # -->
+  # See `File.symlink`.  Creates a symbolic link.
+  #
+  def make_symlink: (String | Pathname | _ToStr old) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - mkdir(...)
+  # -->
+  # See `Dir.mkdir`.  Create the referenced directory.
+  #
+  def mkdir: (?Integer perm) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - mkpath(mode: nil)
+  # -->
+  # Creates a full path, including any intermediate directories that don't yet
+  # exist.
+  #
+  # See FileUtils.mkpath and FileUtils.mkdir_p
+  #
+  def mkpath: () -> self
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - mountpoint?()
+  # -->
+  # Returns `true` if `self` points to a mountpoint.
+  #
+  def mountpoint?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - mtime()
+  # -->
+  # See `File.mtime`.  Returns last modification time.
+  #
+  def mtime: () -> Time
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - open(...) { |file| ... }
+  # -->
+  # See `File.open`.  Opens the file for reading or writing.
+  #
+  def open: (?string | int mode, ?int perm) -> File
+          | [T] (?string | int mode, ?int perm) { (File) -> T } -> T
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - opendir() { |dir| ... }
+  # -->
+  # See `Dir.open`.
+  #
+  def opendir: () -> Dir
+             | [U] () { (Dir) -> U } -> U
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - owned?()
+  # -->
+  # See `FileTest.owned?`.
+  #
+  def owned?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - parent()
+  # -->
+  # Returns the parent directory.
+  #
+  # This is same as `self + '..'`.
+  #
+  def parent: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - pipe?()
+  # -->
+  # See `FileTest.pipe?`.
+  #
+  def pipe?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - read(...)
+  # -->
+  # See `File.read`.  Returns all data from the file, or the first `N` bytes if
+  # specified.
+  #
+  def read: (?Integer length, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish) -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - readable?()
+  # -->
+  # See `FileTest.readable?`.
+  #
+  def readable?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - readable_real?()
+  # -->
+  # See `FileTest.readable_real?`.
+  #
+  def readable_real?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - readlines(...)
+  # -->
+  # See `File.readlines`.  Returns all the lines from the file.
+  #
+  def readlines: (?String sep, ?Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Array[String]
+               | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Array[String]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - readlink()
+  # -->
+  # See `File.readlink`.  Read symbolic link.
+  #
+  def readlink: () -> untyped
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - realdirpath(...)
+  # -->
+  # Returns the real (absolute) pathname of `self` in the actual filesystem.
+  #
+  # Does not contain symlinks or useless dots, `..` and `.`.
+  #
+  # The last component of the real pathname can be nonexistent.
+  #
+  def realdirpath: (?string | Pathname base_dir) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - realpath(...)
+  # -->
+  # Returns the real (absolute) pathname for `self` in the actual filesystem.
+  #
+  # Does not contain symlinks or useless dots, `..` and `.`.
+  #
+  # All components of the pathname must exist when this method is called.
+  #
+  def realpath: (?string | Pathname base_dir) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - relative?()
+  # -->
+  # The opposite of Pathname#absolute?
+  #
+  # It returns `false` if the pathname begins with a slash.
+  #
+  #     p = Pathname.new('/im/sure')
+  #     p.relative?
+  #         #=> false
+  #
+  #     p = Pathname.new('not/so/sure')
+  #     p.relative?
+  #         #=> true
+  #
+  def relative?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - relative_path_from(base_directory)
+  # -->
+  # Returns a relative path from the given `base_directory` to the receiver.
+  #
+  # If `self` is absolute, then `base_directory` must be absolute too.
+  #
+  # If `self` is relative, then `base_directory` must be relative too.
+  #
+  # This method doesn't access the filesystem.  It assumes no symlinks.
+  #
+  # ArgumentError is raised when it cannot find a relative path.
+  #
+  # Note that this method does not handle situations where the case sensitivity of
+  # the filesystem in use differs from the operating system default.
+  #
+  def relative_path_from: (Pathname | string base_directory) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - rename(to)
+  # -->
+  # See `File.rename`.  Rename the file.
+  #
+  def rename: (Pathname | string new_name) -> 0
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - rmdir()
+  # -->
+  # See `Dir.rmdir`.  Remove the referenced directory.
+  #
+  def rmdir: () -> 0
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - root?()
+  # -->
+  # Predicate method for root directories.  Returns `true` if the pathname
+  # consists of consecutive slashes.
+  #
+  # It doesn't access the filesystem.  So it may return `false` for some pathnames
+  # which points to roots such as `/usr/..`.
+  #
+  def root?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - setgid?()
+  # -->
+  # See `FileTest.setgid?`.
+  #
+  def setgid?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - setuid?()
+  # -->
+  # See `FileTest.setuid?`.
+  #
+  def setuid?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - size()
+  # -->
+  # See `FileTest.size`.
+  #
+  def size: () -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - size?()
+  # -->
+  # See `FileTest.size?`.
+  #
+  def size?: () -> Integer?
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - socket?()
+  # -->
+  # See `FileTest.socket?`.
+  #
+  def socket?: () -> untyped
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - split()
+  # -->
+  # See `File.split`.  Returns the #dirname and the #basename in an Array.
+  #
+  def split: () -> [ Pathname, Pathname ]
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - stat()
+  # -->
+  # See `File.stat`.  Returns a `File::Stat` object.
+  #
+  def stat: () -> File::Stat
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - sticky?()
+  # -->
+  # See `FileTest.sticky?`.
+  #
+  def sticky?: () -> untyped
+
+  # <!--
+  #   rdoc-file=pathname.c
+  #   - sub(*args)
+  # -->
+  # Return a pathname which is substituted by String#sub.
+  #
+  #     path1 = Pathname.new('/usr/bin/perl')
+  #     path1.sub('perl', 'ruby')
+  #         #=> #<Pathname:/usr/bin/ruby>
+  #
+  def sub: (Regexp | string pattern, string | Hash[String, String] replacement) -> Pathname
+         | (Regexp | string pattern) { (String match) -> string } -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - sub_ext(repl)
+  # -->
+  # Return a pathname with `repl` added as a suffix to the basename.
+  #
+  # If self has no extension part, `repl` is appended.
+  #
+  #     Pathname.new('/usr/bin/shutdown').sub_ext('.rb')
+  #         #=> #<Pathname:/usr/bin/shutdown.rb>
+  #
+  def sub_ext: (string replacement) -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - symlink?()
+  # -->
+  # See `FileTest.symlink?`.
+  #
+  def symlink?: () -> untyped
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - sysopen(...)
+  # -->
+  # See `File.sysopen`.
+  #
+  def sysopen: (?String mode, ?Integer perm) -> Integer
+
+  # <!--
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.taint -> obj
+  # -->
+  # Returns pathname.  This method is deprecated and will be removed in Ruby 3.2.
+  #
+  def taint: () -> Pathname
+
+  # <!-- rdoc-file=pathname_builtin.rb -->
+  # to_path is implemented so Pathname objects are usable with File.open, etc.
+  #
+  def to_path: () -> String
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - to_s()
+  # -->
+  # Return the path as a String.
+  #
+  alias to_s to_path
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - truncate(length)
+  # -->
+  # See `File.truncate`.  Truncate the file to `length` bytes.
+  #
+  def truncate: (Integer length) -> 0
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - unlink()
+  # -->
+  # Removes a file or directory, using `File.unlink` or `Dir.unlink` as necessary.
+  #
+  def unlink: () -> Integer
+
+  # <!--
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.untaint -> obj
+  # -->
+  # Returns pathname.  This method is deprecated and will be removed in Ruby 3.2.
+  #
+  def untaint: () -> Pathname
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - utime(atime, mtime)
+  # -->
+  # See `File.utime`.  Update the access and modification times.
+  #
+  def utime: (Integer | Time atime, Integer | Time mtime) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - world_readable?()
+  # -->
+  # See `FileTest.world_readable?`.
+  #
+  def world_readable?: () -> (Integer | nil)
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - world_writable?()
+  # -->
+  # See `FileTest.world_writable?`.
+  #
+  def world_writable?: () -> (Integer | nil)
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - writable?()
+  # -->
+  # See `FileTest.writable?`.
+  #
+  def writable?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - writable_real?()
+  # -->
+  # See `FileTest.writable_real?`.
+  #
+  def writable_real?: () -> bool
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - write(...)
+  # -->
+  # Writes `contents` to the file. See `File.write`.
+  #
+  def write: (String content, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish) -> Integer
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - zero?()
+  # -->
+  # See `FileTest.zero?`.
+  #
+  def zero?: () -> bool
+
+  private
+
+  def add_trailing_separator: (untyped path) -> untyped
+
+  def chop_basename: (untyped path) -> untyped
+
+  def cleanpath_aggressive: () -> untyped
+
+  def cleanpath_conservative: () -> untyped
+
+  def del_trailing_separator: (untyped path) -> untyped
+
+  def has_trailing_separator?: (untyped path) -> untyped
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - new(path)
+  # -->
+  # Create a Pathname object from the given String (or String-like object). If
+  # `path` contains a NUL character (`\0`), an ArgumentError is raised.
+  #
+  def initialize: (string | Pathname) -> void
+
+  def plus: (untyped path1, untyped path2) -> untyped
+
+  def prepend_prefix: (untyped prefix, untyped relpath) -> untyped
+
+  def split_names: (untyped path) -> untyped
+
+  SAME_PATHS: Proc
+
+  # <!-- rdoc-file=pathname_builtin.rb -->
+  # Separator list string.
+  #
+  SEPARATOR_LIST: String
+
+  # <!-- rdoc-file=pathname_builtin.rb -->
+  # Regexp that matches a separator.
+  #
+  SEPARATOR_PAT: Regexp
+
+  TO_PATH: Symbol
+end
+
+%a{annotate:rdoc:skip}
+module Kernel
+  private
+
+  # <!--
+  #   rdoc-file=pathname_builtin.rb
+  #   - Pathname(path)
+  # -->
+  # Creates a Pathname object.
+  #
+  def self?.Pathname: (string | Pathname) -> Pathname
+end