core/file.rbs in rbs-3.0.0.dev.2 vs core/file.rbs in rbs-3.0.0.dev.3
- old
+ new
@@ -1,331 +1,883 @@
# <!-- rdoc-file=file.c -->
-# A File is an abstraction of any file object accessible by the program and is
-# closely associated with class IO. File includes the methods of module
-# FileTest as class methods, allowing you to write (for example)
-# `File.exist?("foo")`.
+# A File object is a representation of a file in the underlying platform.
#
-# In the description of File methods, *permission bits* are a platform-specific
-# set of bits that indicate permissions of a file. On Unix-based systems,
-# permissions are viewed as a set of three octets, for the owner, the group, and
-# the rest of the world. For each of these entities, permissions may be set to
-# read, write, or execute the file:
+# Class File extends module FileTest, supporting such singleton methods as
+# `File.exist?`.
#
-# The permission bits `0644` (in octal) would thus be interpreted as read/write
-# for owner, and read-only for group and other. Higher-order bits may also be
-# used to indicate the type of file (plain, directory, pipe, socket, and so on)
-# and various other special features. If the permissions are for a directory,
-# the meaning of the execute bit changes; when set the directory can be
-# searched.
+# ### About the Examples
#
-# On non-Posix operating systems, there may be only the ability to make a file
-# read-only or read-write. In this case, the remaining permission bits will be
-# synthesized to resemble typical values. For instance, on Windows NT the
-# default permission bits are `0644`, which means read/write for owner,
-# read-only for all others. The only change that can be made is to make the file
-# read-only, which is reported as `0444`.
+# Many examples here use these variables:
#
-# Various constants for the methods in File can be found in File::Constants.
+# # English text with newlines.
+# text = <<~EOT
+# First line
+# Second line
#
-# ## What's Here
+# Fourth line
+# Fifth line
+# EOT
#
-# First, what's elsewhere. Class File:
+# # Russian text.
+# russian = "\u{442 435 441 442}" # => "ัะตัั"
#
-# * Inherits from [class IO](IO.html#class-IO-label-What-27s+Here), in
-# particular, methods for creating, reading, and writing files
-# * Includes [module
-# FileTest](FileTest.html#module-FileTest-label-What-27s+Here). which
-# provides dozens of additional methods.
+# # Binary data.
+# data = "\u9990\u9991\u9992\u9993\u9994"
#
+# # Text file.
+# File.write('t.txt', text)
#
-# Here, class File provides methods that are useful for:
+# # File with Russian text.
+# File.write('t.rus', russian)
#
-# * [Creating](#class-File-label-Creating)
-# * [Querying](#class-File-label-Querying)
-# * [Settings](#class-File-label-Settings)
-# * [Other](#class-File-label-Other)
+# # File with binary data.
+# f = File.new('t.dat', 'wb:UTF-16')
+# f.write(data)
+# f.close
#
+# ## Access Modes
#
-# ### Creating
+# Methods File.new and File.open each create a File object for a given file
+# path.
#
-# ::new
-# : Opens the file at the given path; returns the file.
+# ### String Access Modes
#
-# ::open
-# : Same as ::new, but when given a block will yield the file to the
-# block, and close the file upon exiting the block.
+# Methods File.new and File.open each may take string argument `mode`, which:
#
-# ::link
-# : Creates a new name for an existing file using a hard link.
+# * Begins with a 1- or 2-character [read/write
+# mode](rdoc-ref:File@Read-2FWrite+Mode).
+# * May also contain a 1-character [data mode](rdoc-ref:File@Data+Mode).
+# * May also contain a 1-character [file-create
+# mode](rdoc-ref:File@File-Create+Mode).
#
-# ::mkfifo
-# : Returns the FIFO file created at the given path.
#
-# ::symlink
-# : Creates a symbolic link for the given file path.
+# #### Read/Write Mode
#
+# The read/write `mode` determines:
#
+# * Whether the file is to be initially truncated.
#
-# ### Querying
+# * Whether reading is allowed, and if so:
#
-# *Paths*
+# * The initial read position in the file.
+# * Where in the file reading can occur.
#
-# ::absolute_path
-# : Returns the absolute file path for the given path.
#
-# ::absolute_path?
-# : Returns whether the given path is the absolute file path.
+# * Whether writing is allowed, and if so:
#
-# ::basename
-# : Returns the last component of the given file path.
+# * The initial write position in the file.
+# * Where in the file writing can occur.
#
-# ::dirname
-# : Returns all but the last component of the given file path.
#
-# ::expand_path
-# : Returns the absolute file path for the given path, expanding `~` for a
-# home directory.
#
-# ::extname
-# : Returns the file extension for the given file path.
+# These tables summarize:
#
-# ::fnmatch? (aliased as ::fnmatch)
-# : Returns whether the given file path matches the given pattern.
+# Read/Write Modes for Existing File
#
-# ::join
-# : Joins path components into a single path string.
+# |------|-----------|----------|----------|----------|-----------|
+# | R/W | Initial | | Initial | | Initial |
+# | Mode | Truncate? | Read | Read Pos | Write | Write Pos |
+# |------|-----------|----------|----------|----------|-----------|
+# | 'r' | No | Anywhere | 0 | Error | - |
+# | 'w' | Yes | Error | - | Anywhere | 0 |
+# | 'a' | No | Error | - | End only | End |
+# | 'r+' | No | Anywhere | 0 | Anywhere | 0 |
+# | 'w+' | Yes | Anywhere | 0 | Anywhere | 0 |
+# | 'a+' | No | Anywhere | End | End only | End |
+# |------|-----------|----------|----------|----------|-----------|
#
-# ::path
-# : Returns the string representation of the given path.
+# Read/Write Modes for \File To Be Created
#
-# ::readlink
-# : Returns the path to the file at the given symbolic link.
+# |------|----------|----------|----------|-----------|
+# | R/W | | Initial | | Initial |
+# | Mode | Read | Read Pos | Write | Write Pos |
+# |------|----------|----------|----------|-----------|
+# | 'w' | Error | - | Anywhere | 0 |
+# | 'a' | Error | - | End only | 0 |
+# | 'w+' | Anywhere | 0 | Anywhere | 0 |
+# | 'a+' | Anywhere | 0 | End only | End |
+# |------|----------|----------|----------|-----------|
#
-# ::realdirpath
-# : Returns the real path for the given file path, where the last
-# component need not exist.
+# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
+# (exception raised).
#
-# ::realpath
-# : Returns the real path for the given file path, where all components
-# must exist.
+# In the tables:
#
-# ::split
-# : Returns an array of two strings: the directory name and basename of
-# the file at the given path.
+# * `Anywhere` means that methods IO#rewind, IO#pos=, and IO#seek may be used
+# to change the file's position, so that allowed reading or writing may
+# occur anywhere in the file.
+# * `End only` means that writing can occur only at end-of-file, and that
+# methods IO#rewind, IO#pos=, and IO#seek do not affect writing.
+# * `Error` means that an exception is raised if disallowed reading or writing
+# is attempted.
#
-# #path (aliased as #to_path)
-# : Returns the string representation of the given path.
#
+# ##### Read/Write Modes for Existing File
#
+# * `'r'`:
#
-# *Times*
+# * File is not initially truncated:
#
-# ::atime
-# : Returns a Time for the most recent access to the given file.
+# f = File.new('t.txt') # => #<File:t.txt>
+# f.size == 0 # => false
#
-# ::birthtime
-# : Returns a Time for the creation of the given file.
+# * File's initial read position is 0:
#
-# ::ctime
-# : Returns a Time for the metadata change of the given file.
+# f.pos # => 0
#
-# ::mtime
-# : Returns a Time for the most recent data modification to the content of
-# the given file.
+# * File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
#
-# #atime
-# : Returns a Time for the most recent access to `self`.
+# f.readline # => "First line\n"
+# f.readline # => "Second line\n"
#
-# #birthtime
-# : Returns a Time the creation for `self`.
+# f.rewind
+# f.readline # => "First line\n"
#
-# #ctime
-# : Returns a Time for the metadata change of `self`.
+# f.pos = 1
+# f.readline # => "irst line\n"
#
-# #mtime
-# : Returns a Time for the most recent data modification to the content of
-# `self`.
+# f.seek(1, :CUR)
+# f.readline # => "econd line\n"
#
+# * Writing is not allowed:
#
+# f.write('foo') # Raises IOError.
#
-# *Types*
#
-# ::blockdev?
-# : Returns whether the file at the given path is a block device.
+# * `'w'`:
#
-# ::chardev?
-# : Returns whether the file at the given path is a character device.
+# * File is initially truncated:
#
-# ::directory?
-# : Returns whether the file at the given path is a diretory.
+# path = 't.tmp'
+# File.write(path, text)
+# f = File.new(path, 'w')
+# f.size == 0 # => true
#
-# ::executable?
-# : Returns whether the file at the given path is executable by the
-# effective user and group of the current process.
+# * File's initial write position is 0:
#
-# ::executable_real?
-# : Returns whether the file at the given path is executable by the real
-# user and group of the current process.
+# f.pos # => 0
#
-# ::exist?
-# : Returns whether the file at the given path exists.
+# * File may be written anywhere (even past end-of-file); see IO#rewind,
+# IO#pos=, IO#seek:
#
-# ::file?
-# : Returns whether the file at the given path is a regular file.
+# f.write('foo')
+# f.flush
+# File.read(path) # => "foo"
+# f.pos # => 3
#
-# ::ftype
-# : Returns a string giving the type of the file at the given path.
+# f.write('bar')
+# f.flush
+# File.read(path) # => "foobar"
+# f.pos # => 6
#
-# ::grpowned?
-# : Returns whether the effective group of the current process owns the
-# file at the given path.
+# f.rewind
+# f.write('baz')
+# f.flush
+# File.read(path) # => "bazbar"
+# f.pos # => 3
#
-# ::identical?
-# : Returns whether the files at two given paths are identical.
+# f.pos = 3
+# f.write('foo')
+# f.flush
+# File.read(path) # => "bazfoo"
+# f.pos # => 6
#
-# ::lstat
-# : Returns the File::Stat object for the last symbolic link in the given
-# path.
+# f.seek(-3, :END)
+# f.write('bam')
+# f.flush
+# File.read(path) # => "bazbam"
+# f.pos # => 6
#
-# ::owned?
-# : Returns whether the effective user of the current process owns the
-# file at the given path.
+# f.pos = 8
+# f.write('bah') # Zero padding as needed.
+# f.flush
+# File.read(path) # => "bazbam\u0000\u0000bah"
+# f.pos # => 11
#
-# ::pipe?
-# : Returns whether the file at the given path is a pipe.
+# * Reading is not allowed:
#
-# ::readable?
-# : Returns whether the file at the given path is readable by the
-# effective user and group of the current process.
+# f.read # Raises IOError.
#
-# ::readable_real?
-# : Returns whether the file at the given path is readable by the real
-# user and group of the current process.
#
-# ::setgid?
-# : Returns whether the setgid bit is set for the file at the given path.
+# * `'a'`:
#
-# ::setuid?
-# : Returns whether the setuid bit is set for the file at the given path.
+# * File is not initially truncated:
#
-# ::socket?
-# : Returns whether the file at the given path is a socket.
+# path = 't.tmp'
+# File.write(path, 'foo')
+# f = File.new(path, 'a')
+# f.size == 0 # => false
#
-# ::stat
-# : Returns the File::Stat object for the file at the given path.
+# * File's initial position is 0 (but is ignored):
#
-# ::sticky?
-# : Returns whether the file at the given path has its sticky bit set.
+# f.pos # => 0
#
-# ::symlink?
-# : Returns whether the file at the given path is a symbolic link.
+# * File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek
+# do not affect writing:
#
-# ::umask
-# : Returns the umask value for the current process.
+# f.write('bar')
+# f.flush
+# File.read(path) # => "foobar"
+# f.write('baz')
+# f.flush
+# File.read(path) # => "foobarbaz"
#
-# ::world_readable?
-# : Returns whether the file at the given path is readable by others.
+# f.rewind
+# f.write('bat')
+# f.flush
+# File.read(path) # => "foobarbazbat"
#
-# ::world_writable?
-# : Returns whether the file at the given path is writable by others.
+# * Reading is not allowed:
#
-# ::writable?
-# : Returns whether the file at the given path is writable by the
-# effective user and group of the current process.
+# f.read # Raises IOError.
#
-# ::writable_real?
-# : Returns whether the file at the given path is writable by the real
-# user and group of the current process.
#
-# #lstat
-# : Returns the File::Stat object for the last symbolic link in the path
-# for `self`.
+# * `'r+'`:
#
+# * File is not initially truncated:
#
+# path = 't.tmp'
+# File.write(path, text)
+# f = File.new(path, 'r+')
+# f.size == 0 # => false
#
-# *Contents*
+# * File's initial read position is 0:
#
-# ::empty? (aliased as ::zero?)
-# : Returns whether the file at the given path exists and is empty.
+# f.pos # => 0
#
-# ::size
-# : Returns the size (bytes) of the file at the given path.
+# * File may be read or written anywhere (even past end-of-file); see
+# IO#rewind, IO#pos=, IO#seek:
#
-# ::size?
-# : Returns `nil` if there is no file at the given path, or if that file
-# is empty; otherwise returns the file size (bytes).
+# f.readline # => "First line\n"
+# f.readline # => "Second line\n"
#
-# #size
-# : Returns the size (bytes) of `self`.
+# f.rewind
+# f.readline # => "First line\n"
#
+# f.pos = 1
+# f.readline # => "irst line\n"
#
+# f.seek(1, :CUR)
+# f.readline # => "econd line\n"
#
-# ### Settings
+# f.rewind
+# f.write('WWW')
+# f.flush
+# File.read(path)
+# # => "WWWst line\nSecond line\nFourth line\nFifth line\n"
#
-# ::chmod
-# : Changes permissions of the file at the given path.
+# f.pos = 10
+# f.write('XXX')
+# f.flush
+# File.read(path)
+# # => "WWWst lineXXXecond line\nFourth line\nFifth line\n"
#
-# ::chown
-# : Change ownership of the file at the given path.
+# f.seek(-6, :END)
+# # => 0
+# f.write('YYY')
+# # => 3
+# f.flush
+# # => #<File:t.tmp>
+# File.read(path)
+# # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n"
#
-# ::lchmod
-# : Changes permissions of the last symbolic link in the given path.
+# f.seek(2, :END)
+# f.write('ZZZ') # Zero padding as needed.
+# f.flush
+# File.read(path)
+# # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
#
-# ::lchown
-# : Change ownership of the last symbolic in the given path.
#
-# ::lutime
-# : For each given file path, sets the access time and modification time
-# of the last symbolic link in the path.
+# * `'a+'`:
#
-# ::rename
-# : Moves the file at one given path to another given path.
+# * File is not initially truncated:
#
-# ::utime
-# : Sets the access time and modification time of each file at the given
-# paths.
+# path = 't.tmp'
+# File.write(path, 'foo')
+# f = File.new(path, 'a+')
+# f.size == 0 # => false
#
-# #flock
-# : Locks or unlocks `self`.
+# * File's initial read position is 0:
#
+# f.pos # => 0
#
+# * File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek
+# do not affect writing:
#
-# ### Other
+# f.write('bar')
+# f.flush
+# File.read(path) # => "foobar"
+# f.write('baz')
+# f.flush
+# File.read(path) # => "foobarbaz"
#
-# ::truncate
-# : Truncates the file at the given file path to the given size.
+# f.rewind
+# f.write('bat')
+# f.flush
+# File.read(path) # => "foobarbazbat"
#
-# ::unlink (aliased as ::delete)
-# : Deletes the file for each given file path.
+# * File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:
#
-# #truncate
-# : Truncates `self` to the given size.
+# f.rewind
+# f.read # => "foobarbazbat"
#
+# f.pos = 3
+# f.read # => "barbazbat"
+#
+# f.seek(-3, :END)
+# f.read # => "bat"
+#
+#
+#
+# ##### Read/Write Modes for File To Be Created
+#
+# Note that modes `'r'` and `'r+'` are not allowed for a non-existent file
+# (exception raised).
+#
+# * `'w'`:
+#
+# * File's initial write position is 0:
+#
+# path = 't.tmp'
+# FileUtils.rm_f(path)
+# f = File.new(path, 'w')
+# f.pos # => 0
+#
+# * File may be written anywhere (even past end-of-file); see IO#rewind,
+# IO#pos=, IO#seek:
+#
+# f.write('foo')
+# f.flush
+# File.read(path) # => "foo"
+# f.pos # => 3
+#
+# f.write('bar')
+# f.flush
+# File.read(path) # => "foobar"
+# f.pos # => 6
+#
+# f.rewind
+# f.write('baz')
+# f.flush
+# File.read(path) # => "bazbar"
+# f.pos # => 3
+#
+# f.pos = 3
+# f.write('foo')
+# f.flush
+# File.read(path) # => "bazfoo"
+# f.pos # => 6
+#
+# f.seek(-3, :END)
+# f.write('bam')
+# f.flush
+# File.read(path) # => "bazbam"
+# f.pos # => 6
+#
+# f.pos = 8
+# f.write('bah') # Zero padding as needed.
+# f.flush
+# File.read(path) # => "bazbam\u0000\u0000bah"
+# f.pos # => 11
+#
+# * Reading is not allowed:
+#
+# f.read # Raises IOError.
+#
+#
+# * `'a'`:
+#
+# * File's initial write position is 0:
+#
+# path = 't.tmp'
+# FileUtils.rm_f(path)
+# f = File.new(path, 'a')
+# f.pos # => 0
+#
+# * Writing occurs only at end-of-file:
+#
+# f.write('foo')
+# f.pos # => 3
+# f.write('bar')
+# f.pos # => 6
+# f.flush
+# File.read(path) # => "foobar"
+#
+# f.rewind
+# f.write('baz')
+# f.flush
+# File.read(path) # => "foobarbaz"
+#
+# * Reading is not allowed:
+#
+# f.read # Raises IOError.
+#
+#
+# * `'w+'`:
+#
+# * File's initial position is 0:
+#
+# path = 't.tmp'
+# FileUtils.rm_f(path)
+# f = File.new(path, 'w+')
+# f.pos # => 0
+#
+# * File may be written anywhere (even past end-of-file); see IO#rewind,
+# IO#pos=, IO#seek:
+#
+# f.write('foo')
+# f.flush
+# File.read(path) # => "foo"
+# f.pos # => 3
+#
+# f.write('bar')
+# f.flush
+# File.read(path) # => "foobar"
+# f.pos # => 6
+#
+# f.rewind
+# f.write('baz')
+# f.flush
+# File.read(path) # => "bazbar"
+# f.pos # => 3
+#
+# f.pos = 3
+# f.write('foo')
+# f.flush
+# File.read(path) # => "bazfoo"
+# f.pos # => 6
+#
+# f.seek(-3, :END)
+# f.write('bam')
+# f.flush
+# File.read(path) # => "bazbam"
+# f.pos # => 6
+#
+# f.pos = 8
+# f.write('bah') # Zero padding as needed.
+# f.flush
+# File.read(path) # => "bazbam\u0000\u0000bah"
+# f.pos # => 11
+#
+# * File may be read anywhere (even past end-of-file); see IO#rewind,
+# IO#pos=, IO#seek:
+#
+# f.rewind
+# # => 0
+# f.read
+# # => "bazbam\u0000\u0000bah"
+#
+# f.pos = 3
+# # => 3
+# f.read
+# # => "bam\u0000\u0000bah"
+#
+# f.seek(-3, :END)
+# # => 0
+# f.read
+# # => "bah"
+#
+#
+# * `'a+'`:
+#
+# * File's initial write position is 0:
+#
+# path = 't.tmp'
+# FileUtils.rm_f(path)
+# f = File.new(path, 'a+')
+# f.pos # => 0
+#
+# * Writing occurs only at end-of-file:
+#
+# f.write('foo')
+# f.pos # => 3
+# f.write('bar')
+# f.pos # => 6
+# f.flush
+# File.read(path) # => "foobar"
+#
+# f.rewind
+# f.write('baz')
+# f.flush
+# File.read(path) # => "foobarbaz"
+#
+# * File may be read anywhere (even past end-of-file); see IO#rewind,
+# IO#pos=, IO#seek:
+#
+# f.rewind
+# f.read # => "foobarbaz"
+#
+# f.pos = 3
+# f.read # => "barbaz"
+#
+# f.seek(-3, :END)
+# f.read # => "baz"
+#
+# f.pos = 800
+# f.read # => ""
+#
+#
+#
+# #### Data Mode
+#
+# To specify whether data is to be treated as text or as binary data, either of
+# the following may be suffixed to any of the string read/write modes above:
+#
+# * `'t'`: Text data; sets the default external encoding to `Encoding::UTF_8`;
+# on Windows, enables conversion between EOL and CRLF and enables
+# interpreting `0x1A` as an end-of-file marker.
+# * `'b'`: Binary data; sets the default external encoding to
+# `Encoding::ASCII_8BIT`; on Windows, suppresses conversion between EOL and
+# CRLF and disables interpreting `0x1A` as an end-of-file marker.
+#
+#
+# If neither is given, the stream defaults to text data.
+#
+# Examples:
+#
+# File.new('t.txt', 'rt')
+# File.new('t.dat', 'rb')
+#
+# When the data mode is specified, the read/write mode may not be omitted, and
+# the data mode must precede the file-create mode, if given:
+#
+# File.new('t.dat', 'b') # Raises an exception.
+# File.new('t.dat', 'rxb') # Raises an exception.
+#
+# #### File-Create Mode
+#
+# The following may be suffixed to any writable string mode above:
+#
+# * `'x'`: Creates the file if it does not exist; raises an exception if the
+# file exists.
+#
+#
+# Example:
+#
+# File.new('t.tmp', 'wx')
+#
+# When the file-create mode is specified, the read/write mode may not be
+# omitted, and the file-create mode must follow the data mode:
+#
+# File.new('t.dat', 'x') # Raises an exception.
+# File.new('t.dat', 'rxb') # Raises an exception.
+#
+# ### Integer Access Modes
+#
+# When mode is an integer it must be one or more of the following constants,
+# which may be combined by the bitwise OR operator `|`:
+#
+# * `File::RDONLY`: Open for reading only.
+# * `File::WRONLY`: Open for writing only.
+# * `File::RDWR`: Open for reading and writing.
+# * `File::APPEND`: Open for appending only.
+#
+#
+# Examples:
+#
+# File.new('t.txt', File::RDONLY)
+# File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)
+#
+# Note: Method IO#set_encoding does not allow the mode to be specified as an
+# integer.
+#
+# ### File-Create Mode Specified as an Integer
+#
+# These constants may also be ORed into the integer mode:
+#
+# * `File::CREAT`: Create file if it does not exist.
+# * `File::EXCL`: Raise an exception if `File::CREAT` is given and the file
+# exists.
+#
+#
+# ### Data Mode Specified as an Integer
+#
+# Data mode cannot be specified as an integer. When the stream access mode is
+# given as an integer, the data mode is always text, never binary.
+#
+# Note that although there is a constant `File::BINARY`, setting its value in an
+# integer stream mode has no effect; this is because, as documented in
+# File::Constants, the `File::BINARY` value disables line code conversion, but
+# does not change the external encoding.
+#
+# ### Encodings
+#
+# Any of the string modes above may specify encodings - either external encoding
+# only or both external and internal encodings - by appending one or both
+# encoding names, separated by colons:
+#
+# f = File.new('t.dat', 'rb')
+# f.external_encoding # => #<Encoding:ASCII-8BIT>
+# f.internal_encoding # => nil
+# f = File.new('t.dat', 'rb:UTF-16')
+# f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+# f.internal_encoding # => nil
+# f = File.new('t.dat', 'rb:UTF-16:UTF-16')
+# f.external_encoding # => #<Encoding:UTF-16 (dummy)>
+# f.internal_encoding # => #<Encoding:UTF-16>
+# f.close
+#
+# The numerous encoding names are available in array Encoding.name_list:
+#
+# Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]
+#
+# When the external encoding is set, strings read are tagged by that encoding
+# when reading, and strings written are converted to that encoding when writing.
+#
+# When both external and internal encodings are set, strings read are converted
+# from external to internal encoding, and strings written are converted from
+# internal to external encoding. For further details about transcoding input and
+# output, see [Encodings](rdoc-ref:encodings.rdoc@Encodings).
+#
+# If the external encoding is `'BOM|UTF-8'`, `'BOM|UTF-16LE'` or
+# `'BOM|UTF16-BE'`, Ruby checks for a Unicode BOM in the input document to help
+# determine the encoding. For UTF-16 encodings the file open mode must be
+# binary. If the BOM is found, it is stripped and the external encoding from the
+# BOM is used.
+#
+# Note that the BOM-style encoding option is case insensitive, so `'bom|utf-8'`
+# is also valid.
+#
+# ## File Permissions
+#
+# A File object has *permissions*, an octal integer representing the permissions
+# of an actual file in the underlying platform.
+#
+# Note that file permissions are quite different from the *mode* of a file
+# stream (File object). See IO@Modes.
+#
+# In a File object, the permissions are available thus, where method `mode`,
+# despite its name, returns permissions:
+#
+# f = File.new('t.txt')
+# f.lstat.mode.to_s(8) # => "100644"
+#
+# On a Unix-based operating system, the three low-order octal digits represent
+# the permissions for owner (6), group (4), and world (4). The triplet of bits
+# in each octal digit represent, respectively, read, write, and execute
+# permissions.
+#
+# Permissions `0644` thus represent read-write access for owner and read-only
+# access for group and world. See man pages
+# [open(2)](https://www.unix.com/man-page/bsd/2/open) and
+# [chmod(2)](https://www.unix.com/man-page/bsd/2/chmod).
+#
+# For a directory, the meaning of the execute bit changes: when set, the
+# directory can be searched.
+#
+# Higher-order bits in permissions may indicate the type of file (plain,
+# directory, pipe, socket, etc.) and various other special features.
+#
+# On non-Posix operating systems, permissions may include only read-only or
+# read-write, in which case, the remaining permission will resemble typical
+# values. On Windows, for instance, the default permissions are `0644`; The only
+# change that can be made is to make the file read-only, which is reported as
+# `0444`.
+#
+# For a method that actually creates a file in the underlying platform (as
+# opposed to merely creating a File object), permissions may be specified:
+#
+# File.new('t.tmp', File::CREAT, 0644)
+# File.new('t.tmp', File::CREAT, 0444)
+#
+# Permissions may also be changed:
+#
+# f = File.new('t.tmp', File::CREAT, 0444)
+# f.chmod(0644)
+# f.chmod(0444)
+#
+# ## File Constants
+#
+# Various constants for use in File and IO methods may be found in module
+# File::Constants; an array of their names is returned by
+# `File::Constants.constants`.
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class File:
+#
+# * Inherits from [class IO](rdoc-ref:IO@What-27s+Here), in particular,
+# methods for creating, reading, and writing files
+# * Includes [module FileTest](rdoc-ref:FileTest@What-27s+Here). which
+# provides dozens of additional methods.
+#
+#
+# Here, class File provides methods that are useful for:
+#
+# * [Creating](rdoc-ref:File@Creating)
+# * [Querying](rdoc-ref:File@Querying)
+# * [Settings](rdoc-ref:File@Settings)
+# * [Other](rdoc-ref:File@Other)
+#
+#
+# ### Creating
+#
+# * ::new: Opens the file at the given path; returns the file.
+# * ::open: Same as ::new, but when given a block will yield the file to the
+# block, and close the file upon exiting the block.
+# * ::link: Creates a new name for an existing file using a hard link.
+# * ::mkfifo: Returns the FIFO file created at the given path.
+# * ::symlink: Creates a symbolic link for the given file path.
+#
+#
+# ### Querying
+#
+# *Paths*
+#
+# * ::absolute_path: Returns the absolute file path for the given path.
+# * ::absolute_path?: Returns whether the given path is the absolute file
+# path.
+# * ::basename: Returns the last component of the given file path.
+# * ::dirname: Returns all but the last component of the given file path.
+# * ::expand_path: Returns the absolute file path for the given path,
+# expanding `~` for a home directory.
+# * ::extname: Returns the file extension for the given file path.
+# * ::fnmatch? (aliased as ::fnmatch): Returns whether the given file path
+# matches the given pattern.
+# * ::join: Joins path components into a single path string.
+# * ::path: Returns the string representation of the given path.
+# * ::readlink: Returns the path to the file at the given symbolic link.
+# * ::realdirpath: Returns the real path for the given file path, where the
+# last component need not exist.
+# * ::realpath: Returns the real path for the given file path, where all
+# components must exist.
+# * ::split: Returns an array of two strings: the directory name and basename
+# of the file at the given path.
+# * #path (aliased as #to_path): Returns the string representation of the
+# given path.
+#
+#
+# *Times*
+#
+# * ::atime: Returns a Time for the most recent access to the given file.
+# * ::birthtime: Returns a Time for the creation of the given file.
+# * ::ctime: Returns a Time for the metadata change of the given file.
+# * ::mtime: Returns a Time for the most recent data modification to the
+# content of the given file.
+# * #atime: Returns a Time for the most recent access to `self`.
+# * #birthtime: Returns a Time the creation for `self`.
+# * #ctime: Returns a Time for the metadata change of `self`.
+# * #mtime: Returns a Time for the most recent data modification to the
+# content of `self`.
+#
+#
+# *Types*
+#
+# * ::blockdev?: Returns whether the file at the given path is a block device.
+# * ::chardev?: Returns whether the file at the given path is a character
+# device.
+# * ::directory?: Returns whether the file at the given path is a directory.
+# * ::executable?: Returns whether the file at the given path is executable by
+# the effective user and group of the current process.
+# * ::executable_real?: Returns whether the file at the given path is
+# executable by the real user and group of the current process.
+# * ::exist?: Returns whether the file at the given path exists.
+# * ::file?: Returns whether the file at the given path is a regular file.
+# * ::ftype: Returns a string giving the type of the file at the given path.
+# * ::grpowned?: Returns whether the effective group of the current process
+# owns the file at the given path.
+# * ::identical?: Returns whether the files at two given paths are identical.
+# * ::lstat: Returns the File::Stat object for the last symbolic link in the
+# given path.
+# * ::owned?: Returns whether the effective user of the current process owns
+# the file at the given path.
+# * ::pipe?: Returns whether the file at the given path is a pipe.
+# * ::readable?: Returns whether the file at the given path is readable by the
+# effective user and group of the current process.
+# * ::readable_real?: Returns whether the file at the given path is readable
+# by the real user and group of the current process.
+# * ::setgid?: Returns whether the setgid bit is set for the file at the given
+# path.
+# * ::setuid?: Returns whether the setuid bit is set for the file at the given
+# path.
+# * ::socket?: Returns whether the file at the given path is a socket.
+# * ::stat: Returns the File::Stat object for the file at the given path.
+# * ::sticky?: Returns whether the file at the given path has its sticky bit
+# set.
+# * ::symlink?: Returns whether the file at the given path is a symbolic link.
+# * ::umask: Returns the umask value for the current process.
+# * ::world_readable?: Returns whether the file at the given path is readable
+# by others.
+# * ::world_writable?: Returns whether the file at the given path is writable
+# by others.
+# * ::writable?: Returns whether the file at the given path is writable by the
+# effective user and group of the current process.
+# * ::writable_real?: Returns whether the file at the given path is writable
+# by the real user and group of the current process.
+# * #lstat: Returns the File::Stat object for the last symbolic link in the
+# path for `self`.
+#
+#
+# *Contents*
+#
+# * ::empty? (aliased as ::zero?): Returns whether the file at the given path
+# exists and is empty.
+# * ::size: Returns the size (bytes) of the file at the given path.
+# * ::size?: Returns `nil` if there is no file at the given path, or if that
+# file is empty; otherwise returns the file size (bytes).
+# * #size: Returns the size (bytes) of `self`.
+#
+#
+# ### Settings
+#
+# * ::chmod: Changes permissions of the file at the given path.
+# * ::chown: Change ownership of the file at the given path.
+# * ::lchmod: Changes permissions of the last symbolic link in the given path.
+# * ::lchown: Change ownership of the last symbolic in the given path.
+# * ::lutime: For each given file path, sets the access time and modification
+# time of the last symbolic link in the path.
+# * ::rename: Moves the file at one given path to another given path.
+# * ::utime: Sets the access time and modification time of each file at the
+# given paths.
+# * #flock: Locks or unlocks `self`.
+#
+#
+# ### Other
+#
+# * ::truncate: Truncates the file at the given file path to the given size.
+# * ::unlink (aliased as ::delete): Deletes the file for each given file path.
+# * #truncate: Truncates `self` to the given size.
+#
class File < IO
# <!--
# rdoc-file=io.c
- # - File.new(filename, mode="r" [, opt]) -> file
- # - File.new(filename [, mode [, perm]] [, opt]) -> file
+ # - File.new(path, mode = 'r', perm = 0666, **opts) -> file
# -->
- # Opens the file named by `filename` according to the given `mode` and returns a
- # new File object.
+ # Opens the file at the given `path` according to the given `mode`; creates and
+ # returns a new File object for that file.
#
- # See IO.new for a description of `mode` and `opt`.
+ # The new File object is buffered mode (or non-sync mode), unless `filename` is
+ # a tty. See IO#flush, IO#fsync, IO#fdatasync, and IO#sync=.
#
- # If a file is being created, permission bits may be given in `perm`. These
- # mode and permission bits are platform dependent; on Unix systems, see open(2)
- # and chmod(2) man pages for details.
+ # Argument `path` must be a valid file path:
#
- # The new File object is buffered mode (or non-sync mode), unless `filename` is
- # a tty. See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode.
+ # f = File.new('/etc/fstab')
+ # f.close
+ # f = File.new('t.txt')
+ # f.close
#
- # ### Examples
+ # Optional argument `mode` (defaults to 'r') must specify a valid mode; see
+ # [Access Modes](rdoc-ref:File@Access+Modes):
#
- # f = File.new("testfile", "r")
- # f = File.new("newfile", "w+")
- # f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
+ # f = File.new('t.tmp', 'w')
+ # f.close
+ # f = File.new('t.tmp', File::RDONLY)
+ # f.close
#
+ # Optional argument `perm` (defaults to 0666) must specify valid permissions see
+ # [File Permissions](rdoc-ref:File@File+Permissions):
+ #
+ # f = File.new('t.tmp', File::CREAT, 0644)
+ # f.close
+ # f = File.new('t.tmp', File::CREAT, 0444)
+ # f.close
+ #
+ # Optional keyword arguments `opts` specify:
+ #
+ # * [Open Options](rdoc-ref:IO@Open+Options).
+ # * [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
+ #
def initialize: (string | _ToPath | int file_name, ?string | int mode, ?int perm) -> File
# <!--
# rdoc-file=file.c
# - File.absolute_path(file_name [, dir_string] ) -> abs_file_name
@@ -385,25 +937,27 @@
#
def self.birthtime: (string | _ToPath | IO file_name) -> Time
# <!--
# rdoc-file=file.c
- # - File.blockdev?(file_name) -> true or false
+ # - File.blockdev?(filepath) -> true or false
# -->
- # Returns `true` if the named file is a block device.
+ # Returns `true` if `filepath` points to a block device, `false` otherwise:
#
- # *file_name* can be an IO object.
+ # File.blockdev?('/dev/sda1') # => true
+ # File.blockdev?(File.new('t.tmp')) # => false
#
def self.blockdev?: (string | _ToPath | IO file_name) -> bool
# <!--
# rdoc-file=file.c
- # - File.chardev?(file_name) -> true or false
+ # - File.chardev?(filepath) -> true or false
# -->
- # Returns `true` if the named file is a character device.
+ # Returns `true` if `filepath` points to a character device, `false` otherwise.
#
- # *file_name* can be an IO object.
+ # File.chardev?($stdin) # => true
+ # File.chardev?('t.txt') # => false
#
def self.chardev?: (string | _ToPath | IO file_name) -> bool
# <!--
# rdoc-file=file.c
@@ -462,18 +1016,23 @@
#
alias self.delete self.unlink
# <!--
# rdoc-file=file.c
- # - File.directory?(file_name) -> true or false
+ # - File.directory?(path) -> true or false
# -->
- # Returns `true` if the named file is a directory, or a symlink that points at a
- # directory, and `false` otherwise.
+ # With string `object` given, returns `true` if `path` is a string path leading
+ # to a directory, or to a symbolic link to a directory; `false` otherwise:
#
- # *file_name* can be an IO object.
+ # File.directory?('.') # => true
+ # File.directory?('foo') # => false
+ # File.symlink('.', 'dirlink') # => 0
+ # File.directory?('dirlink') # => true
+ # File.symlink('t,txt', 'filelink') # => 0
+ # File.directory?('filelink') # => false
#
- # File.directory?(".")
+ # Argument `path` can be an IO object.
#
def self.directory?: (string | _ToPath | IO path) -> bool
# <!--
# rdoc-file=file.c
@@ -804,19 +1363,18 @@
#
def self.link: (string | _ToPath old_name, string | _ToPath new_name) -> 0
# <!--
# rdoc-file=file.c
- # - File.lstat(file_name) -> stat
+ # - File.lstat(filepath) -> stat
# -->
- # Same as File::stat, but does not follow the last symbolic link. Instead,
- # reports on the link itself.
+ # Like File::stat, but does not follow the last symbolic link; instead, returns
+ # a File::Stat object for the link itself.
#
- # File.symlink("testfile", "link2test") #=> 0
- # File.stat("testfile").size #=> 66
- # File.lstat("link2test").size #=> 8
- # File.stat("link2test").size #=> 66
+ # File.symlink('t.txt', 'symlink')
+ # File.stat('symlink').size # => 47
+ # File.lstat('symlink').size # => 5
#
def self.lstat: (string | _ToPath file_name) -> File::Stat
# <!--
# rdoc-file=file.c
@@ -851,24 +1409,19 @@
#
def self.mtime: (string | _ToPath | IO file_name) -> Time
# <!--
# rdoc-file=io.c
- # - File.open(filename, mode="r" [, opt]) -> file
- # - File.open(filename [, mode [, perm]] [, opt]) -> file
- # - File.open(filename, mode="r" [, opt]) {|file| block } -> obj
- # - File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj
+ # - File.open(path, mode = 'r', perm = 0666, **opts) -> file
+ # - File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object
# -->
- # With no associated block, File.open is a synonym for File.new. If the optional
- # code block is given, it will be passed the opened `file` as an argument and
- # the File object will automatically be closed when the block terminates. The
- # value of the block will be returned from File.open.
+ # Creates a new File object, via File.new with the given arguments.
#
- # If a file is being created, its initial permissions may be set using the
- # `perm` parameter. See File.new for further discussion.
+ # With no block given, returns the File object.
#
- # See IO.new for a description of the `mode` and `opt` parameters.
+ # With a block given, calls the block with the File object and returns the
+ # block's value.
#
def self.open: (string | _ToPath | int file_name, ?string | int mode, ?int perm) -> instance
| [T] (string | _ToPath | int file_name, ?string | int mode, ?int perm) { (File) -> T } -> T
# <!--
@@ -893,15 +1446,17 @@
#
def self.path: (string | _ToPath path) -> String
# <!--
# rdoc-file=file.c
- # - File.pipe?(file_name) -> true or false
+ # - File.pipe?(filepath) -> true or false
# -->
- # Returns `true` if the named file is a pipe.
+ # Returns `true` if `filepath` points to a pipe, `false` otherwise:
#
- # *file_name* can be an IO object.
+ # File.mkfifo('tmp/fifo')
+ # File.pipe?('tmp/fifo') # => true
+ # File.pipe?('t.txt') # => false
#
def self.pipe?: (string | _ToPath | IO file_name) -> bool
# <!--
# rdoc-file=file.c
@@ -1019,15 +1574,17 @@
#
def self.size?: (string | _ToPath | IO file_name) -> Integer?
# <!--
# rdoc-file=file.c
- # - File.socket?(file_name) -> true or false
+ # - File.socket?(filepath) -> true or false
# -->
- # Returns `true` if the named file is a socket.
+ # Returns `true` if `filepath` points to a socket, `false` otherwise:
#
- # *file_name* can be an IO object.
+ # require 'socket'
+ # File.socket?(Socket.new(:INET, :STREAM)) # => true
+ # File.socket?(File.new('t.txt')) # => false
#
def self.socket?: (string | _ToPath | IO file_name) -> bool
# <!--
# rdoc-file=file.c
@@ -1040,15 +1597,15 @@
#
def self.split: (string | _ToPath file_name) -> [ String, String ]
# <!--
# rdoc-file=file.c
- # - File.stat(file_name) -> stat
+ # - File.stat(filepath) -> stat
# -->
- # Returns a File::Stat object for the named file (see File::Stat).
+ # Returns a File::Stat object for the file at `filepath` (see File::Stat):
#
- # File.stat("testfile").mtime #=> Tue Apr 08 12:58:04 CDT 2003
+ # File.stat('t.txt').class # => File::Stat
#
def self.stat: (string | _ToPath file_name) -> File::Stat
# <!--
# rdoc-file=file.c
@@ -1072,14 +1629,18 @@
#
def self.symlink: (string | _ToPath old_name, string | _ToPath new_name) -> 0
# <!--
# rdoc-file=file.c
- # - File.symlink?(file_name) -> true or false
+ # - File.symlink?(filepath) -> true or false
# -->
- # Returns `true` if the named file is a symbolic link.
+ # Returns `true` if `filepath` points to a symbolic link, `false` otherwise:
#
+ # symlink = File.symlink('t.txt', 'symlink')
+ # File.symlink?('symlink') # => true
+ # File.symlink?('t.txt') # => false
+ #
def self.symlink?: (string | _ToPath file_name) -> bool
# <!--
# rdoc-file=file.c
# - File.truncate(file_name, integer) -> 0
@@ -1309,20 +1870,19 @@
#
def flock: (int locking_constant) -> (0 | false)
# <!--
# rdoc-file=file.c
- # - file.lstat -> stat
+ # - lstat -> stat
# -->
- # Same as IO#stat, but does not follow the last symbolic link. Instead, reports
- # on the link itself.
+ # Like File#stat, but does not follow the last symbolic link; instead, returns a
+ # File::Stat object for the link itself:
#
- # File.symlink("testfile", "link2test") #=> 0
- # File.stat("testfile").size #=> 66
- # f = File.new("link2test")
- # f.lstat.size #=> 8
- # f.stat.size #=> 66
+ # File.symlink('t.txt', 'symlink')
+ # f = File.new('symlink')
+ # f.stat.size # => 47
+ # f.lstat.size # => 11
#
def lstat: () -> (File::Stat | nil)
# <!--
# rdoc-file=file.c
@@ -1520,11 +2080,11 @@
#
def atime: () -> Time
# <!--
# rdoc-file=file.c
- # - stat.birthtime -> aTime
+ # - stat.birthtime -> time
# -->
# Returns the birth time for *stat*.
#
# If the platform doesn't have birthtime, raises NotImplementedError.
#
@@ -1587,11 +2147,11 @@
#
def chardev?: () -> bool
# <!--
# rdoc-file=file.c
- # - stat.ctime -> aTime
+ # - stat.ctime -> time
# -->
# Returns the change time for *stat* (that is, the time directory information
# about the file was changed, not the file itself).
#
# Note that on Windows (NTFS), returns creation time (birth time).
@@ -1632,18 +2192,23 @@
#
def dev_minor: () -> Integer
# <!--
# rdoc-file=file.c
- # - File.directory?(file_name) -> true or false
+ # - File.directory?(path) -> true or false
# -->
- # Returns `true` if the named file is a directory, or a symlink that points at a
- # directory, and `false` otherwise.
+ # With string `object` given, returns `true` if `path` is a string path leading
+ # to a directory, or to a symbolic link to a directory; `false` otherwise:
#
- # *file_name* can be an IO object.
+ # File.directory?('.') # => true
+ # File.directory?('foo') # => false
+ # File.symlink('.', 'dirlink') # => 0
+ # File.directory?('dirlink') # => true
+ # File.symlink('t,txt', 'filelink') # => 0
+ # File.directory?('filelink') # => false
#
- # File.directory?(".")
+ # Argument `path` can be an IO object.
#
def directory?: () -> bool
# <!--
# rdoc-file=file.c
@@ -1701,11 +2266,11 @@
# <!--
# rdoc-file=file.c
# - stat.grpowned? -> true or false
# -->
# Returns true if the effective group id of the process is the same as the group
- # id of *stat*. On Windows NT, returns `false`.
+ # id of *stat*. On Windows, returns `false`.
#
# File.stat("testfile").grpowned? #=> true
# File.stat("/etc/passwd").grpowned? #=> false
#
def grpowned?: () -> bool
@@ -1749,10 +2314,10 @@
#
def mode: () -> Integer
# <!--
# rdoc-file=file.c
- # - stat.mtime -> aTime
+ # - stat.mtime -> time
# -->
# Returns the modification time of *stat*.
#
# File.stat("testfile").mtime #=> Wed Apr 09 08:53:14 CDT 2003
#