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

data/core/dir.rbs

@@ -11,135 +11,83 @@
 #
 # First, what's elsewhere. Class Dir:
 #
-# *   Inherits from [class
-#     Object](Object.html#class-Object-label-What-27s+Here).
-# *   Includes [module
-#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
 #     provides dozens of additional methods.
 #
 #
 # Here, class Dir provides methods that are useful for:
 #
-# *   [Reading](#class-Dir-label-Reading)
-# *   [Setting](#class-Dir-label-Setting)
-# *   [Querying](#class-Dir-label-Querying)
-# *   [Iterating](#class-Dir-label-Iterating)
-# *   [Other](#class-Dir-label-Other)
+# *   [Reading](rdoc-ref:Dir@Reading)
+# *   [Setting](rdoc-ref:Dir@Setting)
+# *   [Querying](rdoc-ref:Dir@Querying)
+# *   [Iterating](rdoc-ref:Dir@Iterating)
+# *   [Other](rdoc-ref:Dir@Other)
 #
 #
 # ### Reading
 #
-#     #close
-# :       Closes the directory stream for `self`.
-#
-#     #pos=
-# :       Sets the position in the directory stream for `self`.
-#
-#     #read
-# :       Reads and returns the next entry in the directory stream for `self`.
-#
-#     #rewind
-# :       Sets the position in the directory stream for `self` to the first
-#         entry.
-#
-#     #seek
-# :       Sets the position in the directory stream for `self` the entry at the
-#         given offset.
-#
+# *   #close: Closes the directory stream for `self`.
+# *   #pos=: Sets the position in the directory stream for `self`.
+# *   #read: Reads and returns the next entry in the directory stream for
+#     `self`.
+# *   #rewind: Sets the position in the directory stream for `self` to the first
+#     entry.
+# *   #seek: Sets the position in the directory stream for `self` the entry at
+#     the given offset.
 #
 #
 # ### Setting
 #
-#     ::chdir
-# :       Changes the working directory of the current process to the given
-#         directory.
-#
-#     ::chroot
-# :       Changes the file-system root for the current process to the given
-#         directory.
-#
+# *   ::chdir: Changes the working directory of the current process to the given
+#     directory.
+# *   ::chroot: Changes the file-system root for the current process to the
+#     given directory.
 #
 #
 # ### Querying
 #
-#     ::[]
-# :       Same as ::glob without the ability to pass flags.
-#
-#     ::children
-# :       Returns an array of names of the children (both files and directories)
-#         of the given directory, but not including `.` or `..`.
-#
-#     ::empty?
-# :       Returns whether the given path is an empty directory.
-#
-#     ::entries
-# :       Returns an array of names of the children (both files and directories)
-#         of the given directory, including `.` and `..`.
-#
-#     ::exist?
-# :       Returns whether the given path is a directory.
-#
-#     ::getwd (aliased as #pwd)
-# :       Returns the path to the current working directory.
-#
-#     ::glob
-# :       Returns an array of file paths matching the given pattern and flags.
-#
-#     ::home
-# :       Returns the home directory path for a given user or the current user.
-#
-#     #children
-# :       Returns an array of names of the children (both files and directories)
-#         of `self`, but not including `.` or `..`.
-#
-#     #fileno
-# :       Returns the integer file descriptor for `self`.
-#
-#     #path (aliased as #to_path)
-# :       Returns the path used to create `self`.
-#
-#     #tell (aliased as #pos)
-# :       Returns the integer position in the directory stream for `self`.
-#
+# *   ::[]: Same as ::glob without the ability to pass flags.
+# *   ::children: Returns an array of names of the children (both files and
+#     directories) of the given directory, but not including `.` or `..`.
+# *   ::empty?: Returns whether the given path is an empty directory.
+# *   ::entries: Returns an array of names of the children (both files and
+#     directories) of the given directory, including `.` and `..`.
+# *   ::exist?: Returns whether the given path is a directory.
+# *   ::getwd (aliased as #pwd): Returns the path to the current working
+#     directory.
+# *   ::glob: Returns an array of file paths matching the given pattern and
+#     flags.
+# *   ::home: Returns the home directory path for a given user or the current
+#     user.
+# *   #children: Returns an array of names of the children (both files and
+#     directories) of `self`, but not including `.` or `..`.
+# *   #fileno: Returns the integer file descriptor for `self`.
+# *   #path (aliased as #to_path): Returns the path used to create `self`.
+# *   #tell (aliased as #pos): Returns the integer position in the directory
+#     stream for `self`.
 #
 #
 # ### Iterating
 #
-#     ::each_child
-# :       Calls the given block with each entry in the given directory, but not
-#         including `.` or `..`.
-#
-#     ::foreach
-# :       Calls the given block with each entryin the given directory, including
-#         `.` and `..`.
-#
-#     #each
-# :       Calls the given block with each entry in `self`, including `.` and
-#         `..`.
-#
-#     #each_child
-# :       Calls the given block with each entry in `self`, but not including `.`
-#         or `..`.
-#
+# *   ::each_child: Calls the given block with each entry in the given
+#     directory, but not including `.` or `..`.
+# *   ::foreach: Calls the given block with each entry in the given directory,
+#     including `.` and `..`.
+# *   #each: Calls the given block with each entry in `self`, including `.` and
+#     `..`.
+# *   #each_child: Calls the given block with each entry in `self`, but not
+#     including `.` or `..`.
 #
 #
 # ### Other
 #
-#     ::mkdir
-# :       Creates a directory at the given path, with optional permissions.
-#
-#     ::new
-# :       Returns a new Dir for the given path, with optional encoding.
-#
-#     ::open
-# :       Same as ::new, but if a block is given, yields the Dir to the block,
-#         closing it upon block exit.
-#
-#     ::unlink (aliased as ::delete and ::rmdir)
-# :       Removes the given directory.
-#
-#     #inspect
-# :       Returns a string description of `self`.
+# *   ::mkdir: Creates a directory at the given path, with optional permissions.
+# *   ::new: Returns a new Dir for the given path, with optional encoding.
+# *   ::open: Same as ::new, but if a block is given, yields the Dir to the
+#     block, closing it upon block exit.
+# *   ::unlink (aliased as ::delete and ::rmdir): Removes the given directory.
+# *   #inspect: Returns a string description of `self`.
 #
 class Dir
   include Enumerable[String]

data/core/encoding.rbs

@@ -1,195 +1,31 @@
 # <!-- rdoc-file=encoding.c -->
 # An Encoding instance represents a character encoding usable in Ruby. It is
-# defined as a constant under the Encoding namespace. It has a name and
+# defined as a constant under the Encoding namespace. It has a name and,
 # optionally, aliases:
 #
-#     Encoding::ISO_8859_1.name
-#     #=> "ISO-8859-1"
+#     Encoding::US_ASCII.name  # => "US-ASCII"
+#     Encoding::US_ASCII.names # => ["US-ASCII", "ASCII", "ANSI_X3.4-1968", "646"]
 #
-#     Encoding::ISO_8859_1.names
-#     #=> ["ISO-8859-1", "ISO8859-1"]
+# A Ruby method that accepts an encoding as an argument will accept:
 #
-# Ruby methods dealing with encodings return or accept Encoding instances as
-# arguments (when a method accepts an Encoding instance as an argument, it can
-# be passed an Encoding name or alias instead).
+# *   An Encoding object.
+# *   The name of an encoding.
+# *   An alias for an encoding name.
 #
-#     "some string".encoding
-#     #=> #<Encoding:UTF-8>
 #
-#     string = "some string".encode(Encoding::ISO_8859_1)
-#     #=> "some string"
-#     string.encoding
-#     #=> #<Encoding:ISO-8859-1>
+# These are equivalent:
 #
-#     "some string".encode "ISO-8859-1"
-#     #=> "some string"
+#     'foo'.encode(Encoding::US_ASCII) # Encoding object.
+#     'foo'.encode('US-ASCII')         # Encoding name.
+#     'foo'.encode('ASCII')            # Encoding alias.
 #
-# Encoding::ASCII_8BIT is a special encoding that is usually used for a byte
-# string, not a character string. But as the name insists, its characters in the
-# range of ASCII are considered as ASCII characters.  This is useful when you
-# use ASCII-8BIT characters with other ASCII compatible characters.
+# For a full discussion of encodings and their uses, see [the Encodings
+# document](rdoc-ref:encodings.rdoc).
 #
-# ## Changing an encoding
-#
-# The associated Encoding of a String can be changed in two different ways.
-#
-# First, it is possible to set the Encoding of a string to a new Encoding
-# without changing the internal byte representation of the string, with
-# String#force_encoding. This is how you can tell Ruby the correct encoding of a
-# string.
-#
-#     string
-#     #=> "R\xC3\xA9sum\xC3\xA9"
-#     string.encoding
-#     #=> #<Encoding:ISO-8859-1>
-#     string.force_encoding(Encoding::UTF_8)
-#     #=> "R\u00E9sum\u00E9"
-#
-# Second, it is possible to transcode a string, i.e. translate its internal byte
-# representation to another encoding. Its associated encoding is also set to the
-# other encoding. See String#encode for the various forms of transcoding, and
-# the Encoding::Converter class for additional control over the transcoding
-# process.
-#
-#     string
-#     #=> "R\u00E9sum\u00E9"
-#     string.encoding
-#     #=> #<Encoding:UTF-8>
-#     string = string.encode!(Encoding::ISO_8859_1)
-#     #=> "R\xE9sum\xE9"
-#     string.encoding
-#     #=> #<Encoding::ISO-8859-1>
-#
-# ## Script encoding
-#
-# All Ruby script code has an associated Encoding which any String literal
-# created in the source code will be associated to.
-#
-# The default script encoding is Encoding::UTF_8 after v2.0, but it can be
-# changed by a magic comment on the first line of the source code file (or
-# second line, if there is a shebang line on the first). The comment must
-# contain the word `coding` or `encoding`, followed by a colon, space and the
-# Encoding name or alias:
-#
-#     # encoding: UTF-8
-#
-#     "some string".encoding
-#     #=> #<Encoding:UTF-8>
-#
-# The `__ENCODING__` keyword returns the script encoding of the file which the
-# keyword is written:
-#
-#     # encoding: ISO-8859-1
-#
-#     __ENCODING__
-#     #=> #<Encoding:ISO-8859-1>
-#
-# `ruby -K` will change the default locale encoding, but this is not
-# recommended. Ruby source files should declare its script encoding by a magic
-# comment even when they only depend on US-ASCII strings or regular expressions.
-#
-# ## Locale encoding
-#
-# The default encoding of the environment. Usually derived from locale.
-#
-# see Encoding.locale_charmap, Encoding.find('locale')
-#
-# ## Filesystem encoding
-#
-# The default encoding of strings from the filesystem of the environment. This
-# is used for strings of file names or paths.
-#
-# see Encoding.find('filesystem')
-#
-# ## External encoding
-#
-# Each IO object has an external encoding which indicates the encoding that Ruby
-# will use to read its data. By default Ruby sets the external encoding of an IO
-# object to the default external encoding. The default external encoding is set
-# by locale encoding or the interpreter `-E` option. Encoding.default_external
-# returns the current value of the external encoding.
-#
-#     ENV["LANG"]
-#     #=> "UTF-8"
-#     Encoding.default_external
-#     #=> #<Encoding:UTF-8>
-#
-#     $ ruby -E ISO-8859-1 -e "p Encoding.default_external"
-#     #<Encoding:ISO-8859-1>
-#
-#     $ LANG=C ruby -e 'p Encoding.default_external'
-#     #<Encoding:US-ASCII>
-#
-# The default external encoding may also be set through
-# Encoding.default_external=, but you should not do this as strings created
-# before and after the change will have inconsistent encodings.  Instead use
-# `ruby -E` to invoke ruby with the correct external encoding.
-#
-# When you know that the actual encoding of the data of an IO object is not the
-# default external encoding, you can reset its external encoding with
-# IO#set_encoding or set it at IO object creation (see IO.new options).
-#
-# ## Internal encoding
-#
-# To process the data of an IO object which has an encoding different from its
-# external encoding, you can set its internal encoding. Ruby will use this
-# internal encoding to transcode the data when it is read from the IO object.
-#
-# Conversely, when data is written to the IO object it is transcoded from the
-# internal encoding to the external encoding of the IO object.
-#
-# The internal encoding of an IO object can be set with IO#set_encoding or at IO
-# object creation (see IO.new options).
-#
-# The internal encoding is optional and when not set, the Ruby default internal
-# encoding is used. If not explicitly set this default internal encoding is
-# `nil` meaning that by default, no transcoding occurs.
-#
-# The default internal encoding can be set with the interpreter option `-E`.
-# Encoding.default_internal returns the current internal encoding.
-#
-#     $ ruby -e 'p Encoding.default_internal'
-#     nil
-#
-#     $ ruby -E ISO-8859-1:UTF-8 -e "p [Encoding.default_external, \
-#       Encoding.default_internal]"
-#     [#<Encoding:ISO-8859-1>, #<Encoding:UTF-8>]
-#
-# The default internal encoding may also be set through
-# Encoding.default_internal=, but you should not do this as strings created
-# before and after the change will have inconsistent encodings.  Instead use
-# `ruby -E` to invoke ruby with the correct internal encoding.
-#
-# ## IO encoding example
-#
-# In the following example a UTF-8 encoded string "Ru00E9sumu00E9" is transcoded
-# for output to ISO-8859-1 encoding, then read back in and transcoded to UTF-8:
-#
-#     string = "R\u00E9sum\u00E9"
-#
-#     open("transcoded.txt", "w:ISO-8859-1") do |io|
-#       io.write(string)
-#     end
-#
-#     puts "raw text:"
-#     p File.binread("transcoded.txt")
-#     puts
-#
-#     open("transcoded.txt", "r:ISO-8859-1:UTF-8") do |io|
-#       puts "transcoded text:"
-#       p io.read
-#     end
-#
-# While writing the file, the internal encoding is not specified as it is only
-# necessary for reading.  While reading the file both the internal and external
-# encoding must be specified to obtain the correct result.
-#
-#     $ ruby t.rb
-#     raw text:
-#     "R\xE9sum\xE9"
-#
-#     transcoded text:
-#     "R\u00E9sum\u00E9"
+# Encoding::ASCII_8BIT is a special-purpose encoding that is usually used for a
+# string of bytes, not a string of characters. But as the name indicates, its
+# characters in the ASCII range are considered as ASCII characters. This is
+# useful when you use other ASCII-compatible encodings.
 #
 class Encoding < Object
   # <!--
@@ -1352,11 +1188,13 @@ class Encoding::Converter < Object
   #       :undef => :replace         # replace undefined conversion
   #       :replace => string         # replacement string ("?" or "\uFFFD" if not specified)
   #       :newline => :universal     # decorator for converting CRLF and CR to LF
+  #       :newline => :lf            # decorator for converting CRLF and CR to LF when writing
   #       :newline => :crlf          # decorator for converting LF to CRLF
   #       :newline => :cr            # decorator for converting LF to CR
   #       :universal_newline => true # decorator for converting CRLF and CR to LF
   #       :crlf_newline => true      # decorator for converting LF to CRLF
   #       :cr_newline => true        # decorator for converting LF to CR
+  #       :lf_newline => true        # decorator for converting CRLF and CR to LF when writing
   #       :xml => :text              # escape as XML CharData.
   #       :xml => :attr              # escape as XML AttValue
   #     integer form:
@@ -1364,6 +1202,7 @@ class Encoding::Converter < Object
   #       Encoding::Converter::UNDEF_REPLACE
   #       Encoding::Converter::UNDEF_HEX_CHARREF
   #       Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR
+  #       Encoding::Converter::LF_NEWLINE_DECORATOR
   #       Encoding::Converter::CRLF_NEWLINE_DECORATOR
   #       Encoding::Converter::CR_NEWLINE_DECORATOR
   #       Encoding::Converter::XML_TEXT_DECORATOR
@@ -1406,6 +1245,8 @@ class Encoding::Converter < Object
   # :   Convert LF to CRLF.
   # :cr_newline => true
   # :   Convert LF to CR.
+  # :lf_newline => true
+  # :   Convert CRLF and CR to LF (when writing).
   # :xml => :text
   # :   Escape as XML CharData. This form can be used as an HTML 4.0 #PCDATA.
   #     *   '&' -> '&amp;'