Current File : /var/lib/rbenv/versions/3.2.2/lib64/ruby/gems/3.2.0/gems/rbs-2.8.2/stdlib/tempfile/0/tempfile.rbs
# <!-- 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.
#
# ## Synopsis
#
# require 'tempfile'
#
# file = Tempfile.new('foo')
# file.path # => A unique filename in the OS's temp directory,
# # e.g.: "/tmp/foo.24722.0"
# # This filename contains 'foo' in its basename.
# file.write("hello world")
# file.rewind
# file.read # => "hello world"
# file.close
# file.unlink # deletes the temp file
#
# ## Good practices
#
# ### Explicit close
#
# When a Tempfile object is garbage collected, or when the Ruby interpreter
# exits, its associated temporary file is automatically deleted. This means that
# it's unnecessary to explicitly delete a Tempfile after use, though it's a good
# practice to do so: not explicitly deleting unused Tempfiles can potentially
# leave behind a large number of temp files on the filesystem until they're
# garbage collected. The existence of these temp files can make it harder to
# determine a new Tempfile filename.
#
# Therefore, one should always call #unlink or close in an ensure block, like
# this:
#
# file = Tempfile.new('foo')
# begin
# # ...do something with file...
# ensure
# file.close
# file.unlink # deletes the temp file
# end
#
# Tempfile.create { ... } exists for this purpose and is more convenient to use.
# Note that Tempfile.create returns a File instance instead of a Tempfile, which
# also avoids the overhead and complications of delegation.
#
# Tempfile.open('foo') do |file|
# # ...do something with file...
# end
#
# ### Unlink after creation
#
# On POSIX systems, it's possible to unlink a file right after creating it, and
# before closing it. This removes the filesystem entry without closing the file
# handle, so it ensures that only the processes that already had the file handle
# open can access the file's contents. It's strongly recommended that you do
# 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.
#
# 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.
#
# ## Minor notes
#
# Tempfile's filename picking method is both thread-safe and inter-process-safe:
# it guarantees that no other threads or processes will pick the same filename.
#
# Tempfile itself however may not be entirely thread-safe. If you access the
# same Tempfile object from multiple threads then you should protect it with a
# mutex.
#
class Tempfile < File
# <!--
# rdoc-file=lib/tempfile.rb
# - create(basename="", tmpdir=nil, mode: 0, **options) { |tmpfile| ... }
# -->
# Creates a temporary file as a usual File object (not a Tempfile). It does not
# use finalizer and delegation, which makes it more efficient and reliable.
#
# If no block is given, this is similar to Tempfile.new except creating File
# instead of Tempfile. In that case, the created file is not removed
# automatically. You should use File.unlink to remove it.
#
# If a block is given, then a File object will be constructed, and the block is
# invoked with the object as the argument. The File object will be automatically
# closed and the temporary file is removed after the block terminates, releasing
# all resources that the block created. The call returns the value of the block.
#
# In any case, all arguments (`basename`, `tmpdir`, `mode`, and `**options`)
# will be treated the same as for Tempfile.new.
#
# Tempfile.create('foo', '/home/temp') do |f|
# # ... do something with f ...
# end
#
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
# <!--
# rdoc-file=lib/tempfile.rb
# - open(*args, **kw) { |tempfile| ... }
# -->
# Creates a new Tempfile.
#
# This method is not recommended and exists mostly for backward compatibility.
# Please use Tempfile.create instead, which avoids the cost of delegation, does
# not rely on a finalizer, and also unlinks the file when given a block.
#
# Tempfile.open is still appropriate if you need the Tempfile to be unlinked by
# a finalizer and you cannot explicitly know where in the program the Tempfile
# can be unlinked safely.
#
# If no block is given, this is a synonym for Tempfile.new.
#
# If a block is given, then a Tempfile object will be constructed, and the block
# is run with the Tempfile object as argument. The Tempfile object will be
# automatically closed after the block terminates. However, the file will
# **not** be unlinked and needs to be manually unlinked with Tempfile#close! or
# Tempfile#unlink. The finalizer will try to unlink but should not be relied
# upon as it can keep the file on the disk much longer than intended. For
# instance, on CRuby, finalizers can be delayed due to conservative stack
# scanning and references left in unused memory.
#
# The call returns the value of the block.
#
# In any case, all arguments (`*args`) will be passed to Tempfile.new.
#
# Tempfile.open('foo', '/home/temp') do |f|
# # ... do something with f ...
# end
#
# # Equivalent:
# f = Tempfile.open('foo', '/home/temp')
# begin
# # ... do something with f ...
# ensure
# f.close
# end
#
def self.open: (*untyped args, **untyped) -> Tempfile
| [A] (*untyped args, **untyped) { (Tempfile) -> A } -> A
public
# <!--
# rdoc-file=lib/tempfile.rb
# - close(unlink_now=false)
# -->
# Closes the file. If `unlink_now` is true, then the file will be unlinked
# (deleted) after closing. Of course, you can choose to later call #unlink if
# you do not unlink it now.
#
# If you don't explicitly unlink the temporary file, the removal will be delayed
# until the object is finalized.
#
def close: (?boolish unlink_now) -> void
# <!--
# rdoc-file=lib/tempfile.rb
# - close!()
# -->
# Closes and unlinks (deletes) the file. Has the same effect as called
# `close(true)`.
#
def close!: () -> void
# <!--
# rdoc-file=lib/tempfile.rb
# - delete()
# -->
#
alias delete unlink
def inspect: () -> String
# <!--
# rdoc-file=lib/tempfile.rb
# - length()
# -->
#
alias length size
# <!--
# rdoc-file=lib/tempfile.rb
# - open()
# -->
# Opens or reopens the file with mode "r+".
#
def open: () -> File
# <!--
# rdoc-file=lib/tempfile.rb
# - path()
# -->
# Returns the full path name of the temporary file. This will be nil if #unlink
# has been called.
#
def path: () -> String?
# <!--
# rdoc-file=lib/tempfile.rb
# - size()
# -->
# Returns the size of the temporary file. As a side effect, the IO buffer is
# flushed before determining the size.
#
def size: () -> Integer
# <!--
# rdoc-file=lib/tempfile.rb
# - unlink()
# -->
# Unlinks (deletes) the file from the filesystem. One should always unlink the
# file after using it, as is explained in the "Explicit close" good practice
# section in the Tempfile overview:
#
# file = Tempfile.new('foo')
# begin
# # ...do something with file...
# ensure
# file.close
# file.unlink # deletes the temp file
# end
#
# ### Unlink-before-close
#
# On POSIX systems it's possible to unlink a file before closing it. This
# practice is explained in detail in the Tempfile overview (section "Unlink
# after creation"); please refer there for more information.
#
# However, unlink-before-close may not be supported on non-POSIX operating
# systems. Microsoft Windows is the most notable case: unlinking a non-closed
# file will result in an error, which this method will silently ignore. If you
# want to practice unlink-before-close whenever possible, then you should write
# code like this:
#
# file = Tempfile.new('foo')
# file.unlink # On Windows this silently fails.
# begin
# # ... do something with file ...
# ensure
# file.close! # Closes the file handle. If the file wasn't unlinked
# # because #unlink failed, then this method will attempt
# # to do so again.
# end
#
def unlink: () -> void
class Remover
public
def call: (*untyped args) -> void
private
def initialize: (::Tempfile tmpfile) -> void
end
# <!--
# rdoc-file=lib/tempfile.rb
# - new(basename="", tmpdir=nil, mode: 0, **options)
# -->
# Creates a temporary file with permissions 0600 (= only readable and writable
# by the owner) and opens it with mode "w+".
#
# It is recommended to use Tempfile.create { ... } instead when possible,
# because that method avoids the cost of delegation and does not rely on a
# finalizer to close and unlink the file, which is unreliable.
#
# The `basename` parameter is used to determine the name of the temporary file.
# You can either pass a String or an Array with 2 String elements. In the former
# form, the temporary file's base name will begin with the given string. In the
# latter form, the temporary file's base name will begin with the array's first
# element, and end with the second element. For example:
#
# file = Tempfile.new('hello')
# file.path # => something like: "/tmp/hello2843-8392-92849382--0"
#
# # Use the Array form to enforce an extension in the filename:
# file = Tempfile.new(['hello', '.jpg'])
# file.path # => something like: "/tmp/hello2843-8392-92849382--0.jpg"
#
# The temporary file will be placed in the directory as specified by the
# `tmpdir` parameter. By default, this is `Dir.tmpdir`.
#
# file = Tempfile.new('hello', '/home/aisaka')
# file.path # => something like: "/home/aisaka/hello2843-8392-92849382--0"
#
# You can also pass an options hash. Under the hood, Tempfile creates the
# temporary file using `File.open`. These options will be passed to `File.open`.
# This is mostly useful for specifying encoding options, e.g.:
#
# Tempfile.new('hello', '/home/aisaka', encoding: 'ascii-8bit')
#
# # You can also omit the 'tmpdir' parameter:
# Tempfile.new('hello', encoding: 'ascii-8bit')
#
# Note: `mode` keyword argument, as accepted by Tempfile, can only be numeric,
# combination of the modes defined in File::Constants.
#
# ### Exceptions
#
# If Tempfile.new cannot find a unique filename within a limited number of
# tries, then it will raise an exception.
#
def self.new: (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, **untyped) -> instance
| [A] (?String | [ String, String ] basename, ?String? tmpdir, ?mode: Integer, **untyped) { (instance) -> A } -> A
end
Mini Shell