rbs 3.7.0 → 3.8.0.pre.1

data/core/file.rbs

@@ -49,7 +49,6 @@
 # *   May also contain a 1-character [file-create
 #     mode](rdoc-ref:File@File-Create+Mode).
 #
-#
 # #### Read/Write Mode
 #
 # The read/write `mode` determines:
@@ -61,14 +60,11 @@
 #     *   The initial read position in the file.
 #     *   Where in the file reading can occur.
 #
-#
 # *   Whether writing is allowed, and if so:
 #
 #     *   The initial write position in the file.
 #     *   Where in the file writing can occur.
 #
-#
-#
 # These tables summarize:
 #
 #     Read/Write Modes for Existing File
@@ -110,7 +106,6 @@
 # *   `Error` means that an exception is raised if disallowed reading or writing
 #     is attempted.
 #
-#
 # ##### Read/Write Modes for Existing File
 #
 # *   `'r'`:
@@ -142,7 +137,6 @@
 #
 #             f.write('foo') # Raises IOError.
 #
-#
 # *   `'w'`:
 #
 #     *   File is initially truncated:
@@ -197,7 +191,6 @@
 #
 #             f.read # Raises IOError.
 #
-#
 # *   `'a'`:
 #
 #     *   File is not initially truncated:
@@ -230,7 +223,6 @@
 #
 #             f.read # Raises IOError.
 #
-#
 # *   `'r+'`:
 #
 #     *   File is not initially truncated:
@@ -286,7 +278,6 @@
 #             File.read(path)
 #             # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
 #
-#
 # *   `'a+'`:
 #
 #     *   File is not initially truncated:
@@ -326,8 +317,6 @@
 #             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
@@ -383,7 +372,6 @@
 #
 #             f.read # Raises IOError.
 #
-#
 # *   `'a'`:
 #
 #     *   File's initial write position is 0:
@@ -411,7 +399,6 @@
 #
 #             f.read # Raises IOError.
 #
-#
 # *   `'w+'`:
 #
 #     *   File's initial position is 0:
@@ -476,7 +463,6 @@
 #             f.read
 #             # => "bah"
 #
-#
 # *   `'a+'`:
 #
 #     *   File's initial write position is 0:
@@ -515,8 +501,6 @@
 #             f.pos = 800
 #             f.read # => ""
 #
-#
-#
 # #### Data Mode
 #
 # To specify whether data is to be treated as text or as binary data, either of
@@ -529,7 +513,6 @@
 #     `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:
@@ -550,7 +533,6 @@
 # *   `'x'`: Creates the file if it does not exist; raises an exception if the
 #     file exists.
 #
-#
 # Example:
 #
 #     File.new('t.tmp', 'wx')
@@ -571,7 +553,6 @@
 # *   `File::RDWR`: Open for reading and writing.
 # *   `File::APPEND`: Open for appending only.
 #
-#
 # Examples:
 #
 #     File.new('t.txt', File::RDONLY)
@@ -588,7 +569,6 @@
 # *   `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
@@ -699,7 +679,6 @@
 #     methods for creating, reading, and writing files
 # *   Includes module FileTest, which provides dozens of additional methods.
 #
-#
 # Here, class File provides methods that are useful for:
 #
 # *   [Creating](rdoc-ref:File@Creating)
@@ -707,7 +686,6 @@
 # *   [Settings](rdoc-ref:File@Settings)
 # *   [Other](rdoc-ref:File@Other)
 #
-#
 # ### Creating
 #
 # *   ::new: Opens the file at the given path; returns the file.
@@ -717,7 +695,6 @@
 # *   ::mkfifo: Returns the FIFO file created at the given path.
 # *   ::symlink: Creates a symbolic link for the given file path.
 #
-#
 # ### Querying
 #
 # *Paths*
@@ -744,7 +721,6 @@
 # *   #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.
@@ -758,7 +734,6 @@
 # *   #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.
@@ -805,7 +780,6 @@
 # *   #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
@@ -815,7 +789,6 @@
 #     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.
@@ -829,7 +802,6 @@
 #     given paths.
 # *   #flock: Locks or unlocks `self`.
 #
-#
 # ### Other
 #
 # *   ::truncate: Truncates the file at the given file path to the given size.
@@ -1193,10 +1165,13 @@ class File < IO
   #
   #     `*`
   # :       Matches all regular files
+  #
   #     `c*`
   # :       Matches all files beginning with `c`
+  #
   #     `*c`
   # :       Matches all files ending with `c`
+  #
   #     `*c*`
   # :       Matches all files that have `c` in them (including at the beginning or
   #         end).
@@ -1205,19 +1180,24 @@ class File < IO
   #     To match hidden files (that start with a `.`) set the File::FNM_DOTMATCH
   #     flag.
   #
+  #
   # `**`
   # :   Matches directories recursively or files expansively.
   #
+  #
   # `?`
   # :   Matches any one character. Equivalent to `/.{1}/` in regexp.
   #
+  #
   # `[set]`
   # :   Matches any one character in `set`.  Behaves exactly like character sets
   #     in Regexp, including set negation (`[^a-z]`).
   #
+  #
   # `\`
   # :   Escapes the next metacharacter.
   #
+  #
   # `{a,b}`
   # :   Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled.
   #     Behaves like a Regexp union (`(?:a|b)`).
@@ -1836,46 +1816,19 @@ class File < IO
   #   rdoc-file=file.c
   #   - flock(locking_constant) -> 0 or false
   # -->
-  # Locks or unlocks a file according to the given `locking_constant`,
+  # Locks or unlocks file `self` according to the given `locking_constant`,
   # a bitwise OR of the values in the table below.
   # Not available on all platforms.
   # Returns `false` if `File::LOCK_NB` is specified and the operation would have
   # blocked;
   # otherwise returns `0`.
-  #
-  # <table>
-  #   <tr>
-  #     <th colspan="3">Locking Constants</th>
-  #   </tr>
-  #   <tr>
-  #     <th>Constant</th>
-  #     <th>Lock</th>
-  #     <th>Effect</th>
-  #   </tr>
-  #   <tr>
-  #   <td><tt>File::LOCK_EX</tt></td>
-  #   <td>Exclusive</td>
-  #     <td>Only one process may hold an exclusive lock for <tt>self</tt> at a time.</td>
-  #   </tr>
-  #   <tr>
-  #     <td><tt>File::LOCK_NB</tt></td>
-  #     <td>Non-blocking</td>
-  #     <td>
-  #       No blocking; may be combined with other <tt>File::LOCK_SH</tt> or <tt>File::LOCK_EX</tt>
-  #       using the bitwise OR operator <tt>|</tt>.
-  #     </td>
-  #   </tr>
-  #   <tr>
-  #     <td><tt>File::LOCK_SH</tt></td>
-  #     <td>Shared</td>
-  #     <td>Multiple processes may each hold a shared lock for <tt>self</tt> at the same time.</td>
-  #   </tr>
-  #   <tr>
-  #     <td><tt>File::LOCK_UN</tt></td>
-  #     <td>Unlock</td>
-  #     <td>Remove an existing lock held by this process.</td>
-  #   </tr>
-  # </table>
+  #    Constant    |    Lock    |                                                    Effect
+  # ---------------|------------|--------------------------------------------------------------------------------------------------------------
+  # +File::LOCK_EX+| Exclusive  |                      Only one process may hold an exclusive lock for +self+ at a time.
+  # +File::LOCK_NB+|Non-blocking|No blocking; may be combined with +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <tt>|</tt>.
+  # +File::LOCK_SH+|   Shared   |                 Multiple processes may each hold a shared lock for +self+ at the same time.
+  # +File::LOCK_UN+|   Unlock   |                                Remove an existing lock held by this process.
+  # Example:
   #     # Update a counter using an exclusive lock.
   # # Don't use File::WRONLY because it truncates the file.
   # File.open('counter', File::RDWR | File::CREAT, 0644) do |f|
@@ -2010,7 +1963,6 @@ File::Separator: String
 #     globbing](rdoc-ref:File::Constants@Filename+Globbing+Constants+-28File-3A-
 #     3AFNM_-2A-29).
 #
-#
 # File constants defined for the local process may be retrieved with method
 # File::Constants.constants:
 #
@@ -2034,7 +1986,6 @@ File::Separator: String
 # *   StringIO.open.
 # *   StringIO#reopen.
 #
-#
 # ### Read/Write Access
 #
 # Read-write access for a stream may be specified by a file-access constant.
@@ -2045,7 +1996,7 @@ File::Separator: String
 #
 # #### File::RDONLY
 #
-# Flag File::RDONLY specifies the the stream should be opened for reading only:
+# Flag File::RDONLY specifies the stream should be opened for reading only:
 #
 #     filepath = '/tmp/t.tmp'
 #     f = File.new(filepath, File::RDONLY)
@@ -2133,7 +2084,6 @@ File::Separator: String
 # *   File::NOFOLLOW.
 # *   File::TMPFILE.
 #
-#
 # #### File::SYNC, File::RSYNC, and File::DSYNC
 #
 # Flag File::SYNC, File::RSYNC, or File::DSYNC specifies synchronization of I/O
@@ -2160,7 +2110,6 @@ File::Separator: String
 #     be flushed to the underlying storage device; this differs from File::SYNC,
 #     which requires that *metadata* also be synchronized.
 #
-#
 # Note that the behavior of these flags may vary slightly depending on the
 # operating system and filesystem being used. Additionally, using these flags
 # can have an impact on performance due to the synchronous nature of the I/O
@@ -2214,11 +2163,13 @@ File::Separator: String
 #
 # Flag File::BINARY specifies that the stream is to be accessed in binary mode.
 #
-# #### File::SHARE_DELETE (Windows Only)
+# #### File::SHARE_DELETE
 #
 # Flag File::SHARE_DELETE enables other processes to open the stream with delete
 # access.
 #
+# Windows only.
+#
 # If the stream is opened for (local) delete access without File::SHARE_DELETE,
 # and another process attempts to open it with delete access, the attempt fails
 # and the stream is not opened for that process.
@@ -2257,7 +2208,6 @@ File::Separator: String
 # *   Pathname.glob.
 # *   Pathname#glob.
 #
-#
 # The constants are:
 #
 # #### File::FNM_CASEFOLD
@@ -2290,9 +2240,11 @@ File::Separator: String
 # Flag File::FNM_PATHNAME specifies that patterns `'*'` and `'?'` do not match
 # the directory separator (the value of constant File::SEPARATOR).
 #
-# #### File::FNM_SHORTNAME (Windows Only)
+# #### File::FNM_SHORTNAME
+#
+# Flag File::FNM_SHORTNAME allows patterns to match short names if they exist.
 #
-# Flag File::FNM_SHORTNAME Allows patterns to match short names if they exist.
+# Windows only.
 #
 # #### File::FNM_SYSCASE
 #
@@ -2343,36 +2295,43 @@ File::Constants::DSYNC: Integer
 File::Constants::EXCL: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_CASEFOLD
 # [File::FNM_CASEFOLD](rdoc-ref:File::Constants@File-3A-3AFNM_CASEFOLD)
 #
 File::Constants::FNM_CASEFOLD: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_DOTMATCH
 # [File::FNM_DOTMATCH](rdoc-ref:File::Constants@File-3A-3AFNM_DOTMATCH)
 #
 File::Constants::FNM_DOTMATCH: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_EXTGLOB
 # [File::FNM_EXTGLOB](rdoc-ref:File::Constants@File-3A-3AFNM_EXTGLOB)
 #
 File::Constants::FNM_EXTGLOB: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_NOESCAPE
 # [File::FNM_NOESCAPE](rdoc-ref:File::Constants@File-3A-3AFNM_NOESCAPE)
 #
 File::Constants::FNM_NOESCAPE: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_PATHNAME
 # [File::FNM_PATHNAME](rdoc-ref:File::Constants@File-3A-3AFNM_PATHNAME)
 #
 File::Constants::FNM_PATHNAME: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_SHORTNAME
 # [File::FNM_SHORTNAME](rdoc-ref:File::Constants@File-3A-3AFNM_SHORTNAME)
 #
 File::Constants::FNM_SHORTNAME: Integer
 
 # <!-- rdoc-file=dir.c -->
+# FNM_SYSCASE
 # [File::FNM_SYSCASE](rdoc-ref:File::Constants@File-3A-3AFNM_SYSCASE)
 #
 File::Constants::FNM_SYSCASE: Integer
@@ -2439,8 +2398,7 @@ File::Constants::RDWR: Integer
 File::Constants::RSYNC: Integer
 
 # <!-- rdoc-file=file.c -->
-# [File::SHARE_DELETE](rdoc-ref:File::Constants@File-3A-3ASHARE_DELETE+-28Window
-# s+Only-29)
+# [File::SHARE_DELETE](rdoc-ref:File::Constants@File-3A-3ASHARE_DELETE)
 #
 File::Constants::SHARE_DELETE: Integer