rbs 3.7.0 → 3.8.0

data/stdlib/tempfile/0/tempfile.rbs

@@ -1,16 +1,58 @@
 # <!-- rdoc-file=lib/tempfile.rb -->
-# A utility class for managing temporary files. When you create a Tempfile
-# object, it will create a temporary file with a unique filename. A Tempfile
-# objects behaves just like a File object, and you can perform all the usual
-# file operations on it: reading data, writing data, changing its permissions,
-# etc. So although this class does not explicitly document all instance methods
-# supported by File, you can in fact call any File instance method on a Tempfile
-# object.
+# A utility class for managing temporary files.
+#
+# There are two kind of methods of creating a temporary file:
+#
+# *   Tempfile.create (recommended)
+# *   Tempfile.new and Tempfile.open (mostly for backward compatibility, not
+#     recommended)
+#
+# Tempfile.create creates a usual File object. The timing of file deletion is
+# predictable. Also, it supports open-and-unlink technique which removes the
+# temporary file immediately after creation.
+#
+# Tempfile.new and Tempfile.open creates a Tempfile object. The created file is
+# removed by the GC (finalizer). The timing of file deletion is not predictable.
 #
 # ## Synopsis
 #
 #     require 'tempfile'
 #
+#     # Tempfile.create with a block
+#     # The filename are choosen automatically.
+#     # (You can specify the prefix and suffix of the filename by an optional argument.)
+#     Tempfile.create {|f|
+#       f.puts "foo"
+#       f.rewind
+#       f.read                # => "foo\n"
+#     }                       # The file is removed at block exit.
+#
+#     # Tempfile.create without a block
+#     # You need to unlink the file in non-block form.
+#     f = Tempfile.create
+#     f.puts "foo"
+#     f.close
+#     File.unlink(f.path)     # You need to unlink the file.
+#
+#     # Tempfile.create(anonymous: true) without a block
+#     f = Tempfile.create(anonymous: true)
+#     # The file is already removed because anonymous.
+#     f.path                  # => "/tmp/"  (no filename since no file)
+#     f.puts "foo"
+#     f.rewind
+#     f.read                  # => "foo\n"
+#     f.close
+#
+#     # Tempfile.create(anonymous: true) with a block
+#     Tempfile.create(anonymous: true) {|f|
+#       # The file is already removed because anonymous.
+#       f.path                # => "/tmp/"  (no filename since no file)
+#       f.puts "foo"
+#       f.rewind
+#       f.read                # => "foo\n"
+#     }
+#
+#     # Not recommended: Tempfile.new without a block
 #     file = Tempfile.new('foo')
 #     file.path      # => A unique filename in the OS's temp directory,
 #                    #    e.g.: "/tmp/foo.24722.0"
@@ -21,7 +63,27 @@
 #     file.close
 #     file.unlink    # deletes the temp file
 #
-# ## Good practices
+# ## About Tempfile.new and Tempfile.open
+#
+# This section does not apply to Tempfile.create because it returns a File
+# object (not a Tempfile object).
+#
+# When you create a Tempfile object, it will create a temporary file with a
+# unique filename. A Tempfile objects behaves just like a File object, and you
+# can perform all the usual file operations on it: reading data, writing data,
+# changing its permissions, etc. So although this class does not explicitly
+# document all instance methods supported by File, you can in fact call any File
+# instance method on a Tempfile object.
+#
+# A Tempfile object has a finalizer to remove the temporary file. This means
+# that the temporary file is removed via GC. This can cause several problems:
+#
+# *   Long GC intervals and conservative GC can accumulate temporary files that
+#     are not removed.
+# *   Temporary files are not removed if Ruby exits abnormally (such as SIGKILL,
+#     SEGV).
+#
+# There are legacy good practices for Tempfile.new and Tempfile.open as follows.
 #
 # ### Explicit close
 #
@@ -61,12 +123,17 @@
 # this if you do not want any other processes to be able to read from or write
 # to the Tempfile, and you do not need to know the Tempfile's filename either.
 #
+# Also, this guarantees the temporary file is removed even if Ruby exits
+# abnormally. The OS reclaims the storage for the temporary file when the file
+# is closed or the Ruby process exits (normally or abnormally).
+#
 # For example, a practical use case for unlink-after-creation would be this: you
 # need a large byte buffer that's too large to comfortably fit in RAM, e.g. when
 # you're writing a web server and you want to buffer the client's file upload
 # data.
 #
-# Please refer to #unlink for more information and a code example.
+# `Tempfile.create(anonymous: true)` supports this behavior. It also works on
+# Windows.
 #
 # ## Minor notes
 #
@@ -80,7 +147,7 @@
 class Tempfile < File
   # <!--
   #   rdoc-file=lib/tempfile.rb
-  #   - create(basename="", tmpdir=nil, mode: 0, **options) { |tmpfile| ... }
+  #   - create(basename="", tmpdir=nil, mode: 0, anonymous: false, **options, &block)
   # -->
   # Creates a file in the underlying file system; returns a new File object based
   # on that file.
@@ -94,9 +161,9 @@ class Tempfile < File
   #     Permissions](rdoc-ref:File@File+Permissions).
   # *   Mode is `'w+'` (read/write mode, positioned at the end).
   #
-  #
-  # With no block, the file is not removed automatically, and so should be
-  # explicitly removed.
+  # The temporary file removal depends on the keyword argument `anonymous` and
+  # whether a block is given or not. See the description about the `anonymous`
+  # keyword argument later.
   #
   # Example:
   #
@@ -104,11 +171,36 @@ class Tempfile < File
   #     f.class                 # => File
   #     f.path                  # => "/tmp/20220505-9795-17ky6f6"
   #     f.stat.mode.to_s(8)     # => "100600"
+  #     f.close
   #     File.exist?(f.path)     # => true
   #     File.unlink(f.path)
   #     File.exist?(f.path)     # => false
   #
-  # Argument `basename`, if given, may be one of:
+  #     Tempfile.create {|f|
+  #       f.puts "foo"
+  #       f.rewind
+  #       f.read                # => "foo\n"
+  #       f.path                # => "/tmp/20240524-380207-oma0ny"
+  #       File.exist?(f.path)   # => true
+  #     }                       # The file is removed at block exit.
+  #
+  #     f = Tempfile.create(anonymous: true)
+  #     # The file is already removed because anonymous
+  #     f.path                  # => "/tmp/"  (no filename since no file)
+  #     f.puts "foo"
+  #     f.rewind
+  #     f.read                  # => "foo\n"
+  #     f.close
+  #
+  #     Tempfile.create(anonymous: true) {|f|
+  #       # The file is already removed because anonymous
+  #       f.path                # => "/tmp/"  (no filename since no file)
+  #       f.puts "foo"
+  #       f.rewind
+  #       f.read                # => "foo\n"
+  #     }
+  #
+  # The argument `basename`, if given, may be one of the following:
   #
   # *   A string: the generated filename begins with `basename`:
   #
@@ -119,31 +211,50 @@ class Tempfile < File
   #
   #         Tempfile.create(%w/foo .jpg/) # => #<File:/tmp/foo20220505-17839-tnjchh.jpg>
   #
-  #
-  # With arguments `basename` and `tmpdir`, the file is created in directory
+  # With arguments `basename` and `tmpdir`, the file is created in the directory
   # `tmpdir`:
   #
   #     Tempfile.create('foo', '.') # => #<File:./foo20220505-9795-1emu6g8>
   #
-  # Keyword arguments `mode` and `options` are passed directly to method
+  # Keyword arguments `mode` and `options` are passed directly to the method
   # [File.open](rdoc-ref:File.open):
   #
-  # *   The value given with `mode` must be an integer, and may be expressed as
-  #     the logical OR of constants defined in
+  # *   The value given for `mode` must be an integer and may be expressed as the
+  #     logical OR of constants defined in
   #     [File::Constants](rdoc-ref:File::Constants).
   # *   For `options`, see [Open Options](rdoc-ref:IO@Open+Options).
   #
+  # The keyword argument `anonymous` specifies when the file is removed.
+  #
+  # *   `anonymous=false` (default) without a block: the file is not removed.
+  # *   `anonymous=false` (default) with a block: the file is removed after the
+  #     block exits.
+  # *   `anonymous=true` without a block: the file is removed before returning.
+  # *   `anonymous=true` with a block: the file is removed before the block is
+  #     called.
+  #
+  # In the first case (`anonymous=false` without a block), the file is not removed
+  # automatically. It should be explicitly closed. It can be used to rename to the
+  # desired filename. If the file is not needed, it should be explicitly removed.
   #
-  # With a block given, creates the file as above, passes it to the block, and
-  # returns the block's value; before the return, the file object is closed and
-  # the underlying file is removed:
+  # The File#path method of the created file object returns the temporary
+  # directory with a trailing slash when `anonymous` is true.
+  #
+  # When a block is given, it creates the file as described above, passes it to
+  # the block, and returns the block's value. Before the returning, the file
+  # object is closed and the underlying file is removed:
   #
   #     Tempfile.create {|file| file.path } # => "/tmp/20220505-9795-rkists"
   #
+  # Implementation note:
+  #
+  # The keyword argument +anonymous=true+ is implemented using FILE_SHARE_DELETE
+  # on Windows. O_TMPFILE is used on Linux.
+  #
   # Related: Tempfile.new.
   #
-  def self.create: (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, **untyped) -> File
-                 | [A] (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, **untyped) { (File) -> A } -> A
+  def self.create: (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, ?anonymous: bool, **untyped) -> File
+                 | [A] (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, ?anonymous: bool, **untyped) { (File) -> A } -> A
 
   # <!--
   #   rdoc-file=lib/tempfile.rb
@@ -315,7 +426,6 @@ class Tempfile < File
   # *   Does not rely on a finalizer to close and unlink the file, which can be
   #     unreliable.
   #
-  #
   # Creates and returns file whose:
   #
   # *   Class is Tempfile (not File, as in Tempfile.create).
@@ -325,7 +435,6 @@ class Tempfile < File
   #     Permissions](rdoc-ref:File@File+Permissions).
   # *   Mode is `'w+'` (read/write mode, positioned at the end).
   #
-  #
   # The underlying file is removed when the Tempfile object dies and is reclaimed
   # by the garbage collector.
   #
@@ -350,7 +459,6 @@ class Tempfile < File
   #
   #         Tempfile.new(%w/foo .jpg/) # => #<Tempfile:/tmp/foo20220505-17839-58xtfi.jpg>
   #
-  #
   # With arguments `basename` and `tmpdir`, the file is created in directory
   # `tmpdir`:
   #
@@ -364,7 +472,6 @@ class Tempfile < File
   #     [File::Constants](rdoc-ref:File::Constants).
   # *   For `options`, see [Open Options](rdoc-ref:IO@Open+Options).
   #
-  #
   # Related: Tempfile.create.
   #
   def self.new: (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, **untyped) -> instance

data/stdlib/time/0/time.rbs

@@ -43,7 +43,7 @@ class Time
   #
   # This method **does not** function as a validator.  If the input string does
   # not match valid formats strictly, you may get a cryptic result.  Should
-  # consider to use `Time.strptime` instead of this method as possible.
+  # consider to use Time.strptime instead of this method as possible.
   #
   #     require 'time'
   #
@@ -147,6 +147,8 @@ class Time
   # the format of the input string, you provide a second argument that describes
   # the format of the string.
   #
+  # Raises ArgumentError if the date or format is invalid.
+  #
   # If a block is given, the year described in `date` is converted by the block.
   # For example:
   #
@@ -156,95 +158,139 @@ class Time
   #
   # %a
   # :   The abbreviated weekday name ("Sun")
+  #
   # %A
   # :   The  full  weekday  name ("Sunday")
+  #
   # %b
   # :   The abbreviated month name ("Jan")
+  #
   # %B
   # :   The  full  month  name ("January")
+  #
   # %c
   # :   The preferred local date and time representation
+  #
   # %C
   # :   Century (20 in 2009)
+  #
   # %d
   # :   Day of the month (01..31)
+  #
   # %D
   # :   Date (%m/%d/%y)
+  #
   # %e
   # :   Day of the month, blank-padded ( 1..31)
+  #
   # %F
   # :   Equivalent to %Y-%m-%d (the ISO 8601 date format)
+  #
   # %g
   # :   The last two digits of the commercial year
+  #
   # %G
   # :   The week-based year according to ISO-8601 (week 1 starts on Monday and
   #     includes January 4)
+  #
   # %h
   # :   Equivalent to %b
+  #
   # %H
   # :   Hour of the day, 24-hour clock (00..23)
+  #
   # %I
   # :   Hour of the day, 12-hour clock (01..12)
+  #
   # %j
   # :   Day of the year (001..366)
+  #
   # %k
   # :   hour, 24-hour clock, blank-padded ( 0..23)
+  #
   # %l
   # :   hour, 12-hour clock, blank-padded ( 0..12)
+  #
   # %L
   # :   Millisecond of the second (000..999)
+  #
   # %m
   # :   Month of the year (01..12)
+  #
   # %M
   # :   Minute of the hour (00..59)
+  #
   # %n
   # :   Newline (n)
+  #
   # %N
   # :   Fractional seconds digits
+  #
   # %p
   # :   Meridian indicator ("AM" or "PM")
+  #
   # %P
   # :   Meridian indicator ("am" or "pm")
+  #
   # %r
   # :   time, 12-hour (same as %I:%M:%S %p)
+  #
   # %R
   # :   time, 24-hour (%H:%M)
+  #
   # %s
   # :   Number of seconds since 1970-01-01 00:00:00 UTC.
+  #
   # %S
   # :   Second of the minute (00..60)
+  #
   # %t
   # :   Tab character (t)
+  #
   # %T
   # :   time, 24-hour (%H:%M:%S)
+  #
   # %u
   # :   Day of the week as a decimal, Monday being 1. (1..7)
+  #
   # %U
   # :   Week number of the current year, starting with the first Sunday as the
   #     first day of the first week (00..53)
+  #
   # %v
   # :   VMS date (%e-%b-%Y)
+  #
   # %V
   # :   Week number of year according to ISO 8601 (01..53)
+  #
   # %W
   # :   Week  number  of the current year, starting with the first Monday as the
   #     first day of the first week (00..53)
+  #
   # %w
   # :   Day of the week (Sunday is 0, 0..6)
+  #
   # %x
   # :   Preferred representation for the date alone, no time
+  #
   # %X
   # :   Preferred representation for the time alone, no date
+  #
   # %y
   # :   Year without a century (00..99)
+  #
   # %Y
   # :   Year which may include century, if provided
+  #
   # %z
-  # :   Time zone as  hour offset from UTC (e.g. +0900)
+  # :   Time zone as hour offset from UTC (e.g. +0900)
+  #
   # %Z
   # :   Time zone name
+  #
   # %%
   # :   Literal "%" character
+  #
   # %+
   # :   date(1) (%a %b %e %H:%M:%S %Z %Y)
   #
@@ -383,37 +429,4 @@ class Time
   # You must require 'time' to use this method.
   #
   def httpdate: () -> String
-
-  # <!--
-  #   rdoc-file=lib/time.rb
-  #   - xmlschema(fraction_digits=0)
-  # -->
-  # Returns a string which represents the time as a dateTime defined by XML
-  # Schema:
-  #
-  #     CCYY-MM-DDThh:mm:ssTZD
-  #     CCYY-MM-DDThh:mm:ss.sssTZD
-  #
-  # where TZD is Z or [+-]hh:mm.
-  #
-  # If self is a UTC time, Z is used as TZD.  [+-]hh:mm is used otherwise.
-  #
-  # `fraction_digits` specifies a number of digits to use for fractional seconds.
-  # Its default value is 0.
-  #
-  #     require 'time'
-  #
-  #     t = Time.now
-  #     t.iso8601  # => "2011-10-05T22:26:12-04:00"
-  #
-  # You must require 'time' to use this method.
-  #
-  def xmlschema: (?Integer fraction_digits) -> String
-
-  # <!--
-  #   rdoc-file=lib/time.rb
-  #   - iso8601(fraction_digits=0)
-  # -->
-  #
-  alias iso8601 xmlschema
 end

data/stdlib/timeout/0/timeout.rbs

@@ -4,7 +4,7 @@
 # ## Synopsis
 #
 #     require 'timeout'
-#     status = Timeout::timeout(5) {
+#     status = Timeout.timeout(5) {
 #       # Something that should be interrupted if it takes more than 5 seconds...
 #     }
 #
@@ -13,14 +13,11 @@
 # Timeout provides a way to auto-terminate a potentially long-running operation
 # if it hasn't finished in a fixed amount of time.
 #
-# Previous versions didn't use a module for namespacing, however #timeout is
-# provided for backwards compatibility.  You should prefer Timeout.timeout
-# instead.
-#
 # ## Copyright
 #
 # Copyright
 # :   (C) 2000  Network Applied Communication Laboratory, Inc.
+#
 # Copyright
 # :   (C) 2000  Information-technology Promotion Agency, Japan
 #
@@ -33,12 +30,15 @@ module Timeout
   # `sec` seconds to complete.
   #
   # `sec`
-  # :   Number of seconds to wait for the block to terminate. Any number may be
-  #     used, including Floats to specify fractional seconds. A value of 0 or
-  #     `nil` will execute the block without any timeout.
+  # :   Number of seconds to wait for the block to terminate. Any non-negative
+  #     number or nil may be used, including Floats to specify fractional seconds.
+  #     A value of 0 or `nil` will execute the block without any timeout. Any
+  #     negative number will raise an ArgumentError.
+  #
   # `klass`
   # :   Exception Class to raise if the block fails to terminate in `sec` seconds.
   #      Omitting will use the default, Timeout::Error
+  #
   # `message`
   # :   Error message to raise with Exception Class. Omitting will use the
   #     default, "execution expired"
@@ -75,4 +75,7 @@ class Timeout::Error < RuntimeError
   attr_reader thread: Thread?
 end
 
+# <!-- rdoc-file=lib/timeout.rb -->
+# The version
+#
 Timeout::VERSION: String

data/stdlib/tmpdir/0/tmpdir.rbs

@@ -6,6 +6,9 @@ class Dir
   # -->
   # Returns the operating system's temporary file path.
   #
+  #     require 'tmpdir'
+  #     Dir.tmpdir # => "/tmp"
+  #
   def self.tmpdir: () -> String
 
   # <!--
@@ -14,6 +17,11 @@ class Dir
   # -->
   # Dir.mktmpdir creates a temporary directory.
   #
+  #     require 'tmpdir'
+  #     Dir.mktmpdir {|dir|
+  #       # use the directory
+  #     }
+  #
   # The directory is created with 0700 permission. Application should not change
   # the permission to make the temporary directory accessible from other users.
   #
@@ -25,7 +33,6 @@ class Dir
   # *   If it is an array, first element is used as the prefix and second element
   #     is used as a suffix.
   #
-  #
   #     Dir.mktmpdir {|dir| dir is ".../d..." }
   #     Dir.mktmpdir("foo") {|dir| dir is ".../foo..." }
   #     Dir.mktmpdir(["foo", "bar"]) {|dir| dir is ".../foo...bar" }
@@ -57,6 +64,6 @@ class Dir
   #       FileUtils.remove_entry dir
   #     end
   #
-  def self.mktmpdir: (?String | [ String, String ] | nil, ?String?, ?max_try: Integer?) -> String
-                   | [X] (?String | [ String, String ] | nil, ?String?, ?max_try: Integer?) { (String) -> X } -> X
+  def self.mktmpdir: (?string | [ string, string ] | nil, ?path?, ?max_try: Integer?) -> String
+                   | [X] (?string | [string, string ] | nil, ?path?, ?max_try: Integer?) { (String) -> X } -> X
 end

data/stdlib/tsort/0/tsort.rbs

@@ -11,7 +11,6 @@
 # *   tsort_each_node is used to iterate for all nodes over a graph.
 # *   tsort_each_child is used to iterate for child nodes of a given node.
 #
-#
 # The equality of nodes are defined by eql? and hash since TSort uses Hash
 # internally.
 #
@@ -109,12 +108,9 @@
 #     strongly connected components. Although 'strongly_connected_components.rb'
 #     is correct but too long.
 #
-#
 # ## References
 #
 #     1.  Tarjan, "Depth First Search and Linear Graph Algorithms",
-#
-#
 # *SIAM Journal on Computing*, Vol. 1, No. 2, pp. 146-160, June 1972.
 #
 module TSort[Node] : TSort::_Sortable[Node]