class File

Overview

A File instance represents a file entry in the local file system and allows using it as an IO.

file = File.new("path/to/file")
content = file.gets_to_end
file.close

# Implicit close with `open` and a block:
content = File.open("path/to/file") do |file|
  file.gets_to_end
end

# Shortcut of the above:
content = File.read("path/to/file")

# Write to a file by opening with a "write mode" specified.
File.open("path/to/file", "w") do |file|
  file.print "hello"
end
# Content of file on disk will now be "hello".

# Shortcut of the above:
File.write("path/to/file", "hello")

See .new for various options mode can be.

Temporary Files

Every tempfile is operated as a File, including initializing, reading and writing.

tempfile = File.tempfile("foo")

File.size(tempfile.path)                   # => 6
File.info(tempfile.path).modification_time # => 2015-10-20 13:11:12 UTC
File.exists?(tempfile.path)                # => true
File.read_lines(tempfile.path)             # => ["foobar"]

Files created from .tempfile are stored in a directory that handles temporary files (Dir.tempdir):

File.tempfile("foo").path # => "/tmp/foo.ulBCPS"

It is encouraged to delete a tempfile after using it, which ensures they are not left behind in your filesystem until garbage collected.

tempfile = File.tempfile("foo")
tempfile.delete

Included Modules

Defined in:

file.cr:1
file.cr:61
file/error.cr
file/info.cr
file/tempfile.cr

Constant Summary

NULL = {% if flag?(:win32) %} "NUL" {% else %} "/dev/null" {% end %}

The name of the null device on the host platform. /dev/null on UNIX and NUL on win32.

When this device is opened using File.open, read operations will always return EOF, and any data written will be immediately discarded.

File.open(File::NULL, "w") do |file|
  file.puts "this is discarded"
end
SEPARATOR = '/'

The file/directory separator character. '/' on all platforms.

SEPARATOR_STRING = "/"

The file/directory separator string. "/" on all platforms.

Constructors

Class Method Summary

Instance Method Summary

Class methods inherited from module Crystal::System::File

chmod(path, mode) chmod, chown(path, uid : Int, gid : Int, follow_symlinks) chown, delete(path, *, raise_on_missing : Bool) : Bool delete, executable?(path) : Bool executable?, exists?(path) exists?, fchown(path, fd, uid : Int, gid : Int) fchown, fstat(path, stat) fstat, info(path, follow_symlinks) info, info?(path : String, follow_symlinks : Bool) : ::File::Info | Nil info?, link(old_path, new_path) link, lstat(path, stat) lstat, mktemp(prefix : String | Nil, suffix : String | Nil, dir : String, random : ::Random = ::Random::DEFAULT) : Tuple(LibC::Int, String) mktemp, open(filename : String, mode : String, perm : Int32 | ::File::Permissions)
open(filename : String, flags : Int32, perm : ::File::Permissions) : Tuple(LibC::Int, Errno)
open
, readable?(path) : Bool readable?, readlink(path) : String readlink, realpath(path) realpath, rename(old_filename, new_filename) : ::File::Error | Nil rename, stat(path, stat) stat, symlink(old_path, new_path) symlink, utime(atime : ::Time, mtime : ::Time, filename : String) : Nil utime, writable?(path) : Bool writable?

Instance methods inherited from class IO::FileDescriptor

blocking blocking, blocking=(value) blocking=, close_on_exec=(value : Bool) close_on_exec=, close_on_exec? : Bool close_on_exec?, close_on_finalize=(close_on_finalize : Bool) close_on_finalize=, close_on_finalize? : Bool close_on_finalize?, closed? : Bool closed?, cooked(& : self -> _) cooked, cooked! : Nil cooked!, echo(& : self -> _) echo, echo! : Nil echo!, fcntl(cmd, arg = 0) fcntl, fd : Int fd, finalize finalize, flock_exclusive(blocking = true, &)
flock_exclusive(blocking = true) : Nil
flock_exclusive
, flock_shared(blocking = true, &)
flock_shared(blocking = true) : Nil
flock_shared
, flock_unlock : Nil flock_unlock, fsync(flush_metadata = true) : Nil fsync, info : File::Info info, inspect(io : IO) : Nil inspect, noecho(& : self -> _) noecho, noecho! : Nil noecho!, pos=(value) pos=, pretty_print(pp) pretty_print, raw(& : self -> _) raw, raw! : Nil raw!, reopen(other : IO::FileDescriptor) reopen, seek(offset, whence : Seek = Seek::Set)
seek(offset, whence : Seek = Seek::Set, &)
seek
, tty? : Bool tty?

Constructor methods inherited from class IO::FileDescriptor

new(fd, blocking = nil, *, close_on_finalize : Bool = true) new

Class methods inherited from class IO::FileDescriptor

fcntl(fd, cmd, arg = 0) fcntl

Macros inherited from class IO::FileDescriptor

cooked_from_tc_mode! cooked_from_tc_mode!, noecho_from_tc_mode! noecho_from_tc_mode!, raw_from_tc_mode! raw_from_tc_mode!

Instance methods inherited from module IO::Buffered

buffer_size : Int32 buffer_size, buffer_size=(value) buffer_size=, close : Nil close, flush flush, flush_on_newline=(flush_on_newline) flush_on_newline=, flush_on_newline? : Bool flush_on_newline?, peek : Bytes peek, pos : Int64 pos, read(slice : Bytes) : Int32 read, read_buffering=(read_buffering) read_buffering=, read_buffering? : Bool read_buffering?, rewind rewind, sync=(sync) sync=, sync? : Bool sync?, unbuffered_close unbuffered_close, unbuffered_flush unbuffered_flush, unbuffered_read(slice : Bytes) unbuffered_read, unbuffered_rewind unbuffered_rewind, unbuffered_write(slice : Bytes) unbuffered_write, write(slice : Bytes) : Nil write

Instance methods inherited from module Crystal::System::FileDescriptor

file_descriptor_close : Nil file_descriptor_close

Class methods inherited from module Crystal::System::FileDescriptor

cfmakeraw(termios_p) cfmakeraw, fcntl(fd, cmd, arg = 0) fcntl, from_stdio(fd) from_stdio, pipe(read_blocking, write_blocking) pipe, pread(fd, buffer, offset) pread, system_info(fd) system_info, tcgetattr(fd) tcgetattr, tcsetattr(fd, optional_actions, termios_p) tcsetattr

Instance methods inherited from module IO::Evented

evented_close : Nil evented_close, evented_read(slice : Bytes, errno_msg : String, &) : Int32 evented_read, evented_reopen : Nil evented_reopen, evented_send(slice : Bytes, errno_msg : String, &) : Int32 evented_send, evented_write(slice : Bytes, errno_msg : String, &) : Nil evented_write, read_timeout : Time::Span | Nil read_timeout, read_timeout=(read_timeout : Number) : Number
read_timeout=(timeout : Time::Span | Nil) : Time::Span | Nil
read_timeout=
, write_timeout : Time::Span | Nil write_timeout, write_timeout=(write_timeout : Number) : Number
write_timeout=(timeout : Time::Span | Nil) : Time::Span | Nil
write_timeout=

Instance methods inherited from class IO

<<(obj) : self <<, close close, closed? : Bool closed?, each_byte(&) : Nil
each_byte
each_byte
, each_char(&) : Nil
each_char
each_char
, each_line(*args, **options, &block : String -> ) : Nil
each_line(*args, **options)
each_line
, encoding : String encoding, flush flush, getb_to_end : Bytes getb_to_end, gets(limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, chomp = false) : String | Nil
gets(delimiter : String, chomp = false) : String | Nil
gets(chomp = true) : String | Nil
gets
, gets_to_end : String gets_to_end, peek : Bytes | Nil peek, pos pos, pos=(value) pos=, print(obj : _) : Nil
print(*objects : _) : Nil
print
, printf(format_string, args : Array | Tuple) : Nil
printf(format_string, *args) : Nil
printf
, puts(string : String) : Nil
puts(obj : _) : Nil
puts : Nil
puts(*objects : _) : Nil
puts
, read(slice : Bytes) read, read_at(offset, bytesize, & : IO -> ) read_at, read_byte : UInt8 | Nil read_byte, read_bytes(type, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) read_bytes, read_char : Char | Nil read_char, read_fully(slice : Bytes) : Int32 read_fully, read_fully?(slice : Bytes) : Int32 | Nil read_fully?, read_line(*args, **options) : String read_line, read_string(bytesize : Int) : String read_string, read_utf8(slice : Bytes) read_utf8, read_utf8_byte : UInt8 | Nil read_utf8_byte, rewind rewind, seek(offset, whence : Seek = Seek::Set) seek, set_encoding(encoding : String, invalid : Symbol | Nil = nil) : Nil set_encoding, skip(bytes_count : Int) : Nil skip, skip_to_end : Nil skip_to_end, tell tell, tty? : Bool tty?, write(slice : Bytes) : Nil write, write_byte(byte : UInt8) : Nil write_byte, write_bytes(object, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) : Nil write_bytes, write_string(slice : Bytes) : Nil write_string, write_utf8(slice : Bytes) : Nil write_utf8

Class methods inherited from class IO

copy(src, dst, limit : Int) : Int64
copy(src, dst) : Int64
copy
, pipe(read_blocking = false, write_blocking = false) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
pipe(read_blocking = false, write_blocking = false, &)
pipe
, same_content?(stream1 : IO, stream2 : IO) : Bool same_content?

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil)
same?
, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash
hash
, in?(collection : Object) : Bool
in?(*values : Object) : Bool
in?
, inspect(io : IO) : Nil
inspect : String
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil!
not_nil!
, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String
to_json
, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil
to_pretty_json
, to_s(io : IO) : Nil
to_s : String
to_s
, to_yaml(io : IO) : Nil
to_yaml : String
to_yaml
, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io)
from_json
, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.new(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = true) #

Opens the file named by filename.

mode must be one of the following file open modes:

Mode       | Description
-----------+------------------------------------------------------
r rb       | Read-only, starts at the beginning of the file.
r+ r+b rb+ | Read-write, starts at the beginning of the file.
w wb       | Write-only, truncates existing file to zero length or
           | creates a new file if the file doesn't exist.
w+ w+b wb+ | Read-write, truncates existing file to zero length or
           | creates a new file if the file doesn't exist.
a ab       | Write-only, all writes seek to the end of the file,
           | creates a new file if the file doesn't exist.
a+ a+b ab+ | Read-write, all writes seek to the end of the file,
           | creates a new file if the file doesn't exist.

Line endings are preserved on all platforms. The b mode flag has no effect; it is provided only for POSIX compatibility.

blocking is set to true by default because system event queues (e.g. epoll, kqueue) will always report the file descriptor of regular disk files as ready.

blocking must be set to false on POSIX targets when the file to open isn't a regular file but a character device (e.g. /dev/tty) or fifo. These files depend on another process or thread to also be reading or writing, and system event queues will properly report readyness.

blocking may also be set to nil in which case the blocking or non-blocking flag will be determined automatically, at the expense of an additional syscall.


[View source]
def self.open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = true) : self #

Opens the file named by filename. If a file is being created, its initial permissions may be set using the perm parameter.

See self.new for what mode can be.


[View source]

Class Method Detail

def self.basename(path : Path | String, suffix : String) : String #

Returns the last component of the given path.

If suffix is present at the end of path, it is removed.

File.basename("/foo/bar/file.cr", ".cr") # => "file"

[View source]
def self.basename(path : Path | String) : String #

Returns the last component of the given path.

File.basename("/foo/bar/file.cr") # => "file.cr"

[View source]
def self.chmod(path : Path | String, permissions : Int | Permissions) : Nil #

Changes the permissions of the specified file.

Symlinks are dereferenced, so that only the permissions of the symlink destination are changed, never the permissions of the symlink itself.

File.chmod("foo", 0o755)
File.info("foo").permissions.value # => 0o755

File.chmod("foo", 0o700)
File.info("foo").permissions.value # => 0o700

Use #chmod if the File is already open.


[View source]
def self.chown(path : Path | String, uid : Int = -1, gid : Int = -1, follow_symlinks = false) : Nil #

Changes the owner of the specified file.

File.chown("/foo/bar/baz.cr", 1001, 100)
File.chown("/foo/bar", gid: 100)

Unless follow_symlinks is set to true, then the owner symlink itself will be changed, otherwise the owner of the symlink destination file will be changed. For example, assuming symlinks as foo -> bar -> baz:

File.chown("foo", gid: 100)                        # changes foo's gid
File.chown("foo", gid: 100, follow_symlinks: true) # changes baz's gid

Use #chown if the File is already open.


[View source]
def self.copy(src : String | Path, dst : String | Path) : Nil #

Copies the file src to the file dst. Permission bits are copied too.

File.touch("afile")
File.chmod("afile", 0o600)
File.copy("afile", "afile_copy")
File.info("afile_copy").permissions.value # => 0o600

[View source]
def self.delete(path : Path | String) : Nil #

Deletes the file at path. Raises File::Error on failure.

On Windows, this also deletes reparse points, including symbolic links, regardless of whether the reparse point is a directory.

File.write("foo", "")
File.delete("./foo")
File.delete("./bar") # raises File::NotFoundError (No such file or directory)

[View source]
def self.delete?(path : Path | String) : Bool #

Deletes the file at path, or returns false if the file does not exist. Raises File::Error on other kinds of failure.

On Windows, this also deletes reparse points, including symbolic links, regardless of whether the reparse point is a directory.

File.write("foo", "")
File.delete?("./foo") # => true
File.delete?("./bar") # => false

[View source]
def self.directory?(path : Path | String) : Bool #

Returns true if the given path exists and is a directory.

File.write("foo", "")
Dir.mkdir("dir2")
File.directory?("foo")    # => false
File.directory?("dir2")   # => true
File.directory?("foobar") # => false

[View source]
def self.dirname(path : Path | String) : String #

Returns all components of the given path except the last one.

File.dirname("/foo/bar/file.cr") # => "/foo/bar"

[View source]
def self.each_line(filename : Path | String, encoding = nil, invalid = nil, chomp = true, blocking = true, &) #

Yields each line in filename to the given block.

File.write("foobar", "foo\nbar")

array = [] of String
File.each_line("foobar") do |line|
  array << line
end
array # => ["foo", "bar"]

[View source]
def self.empty?(path : Path | String) : Bool #

Returns true if the file at path is empty, otherwise returns false. Raises File::NotFoundError if the file at path does not exist.

File.write("foo", "")
File.empty?("foo") # => true
File.write("foo", "foo")
File.empty?("foo") # => false

[View source]
def self.executable?(path : Path | String) : Bool #

Returns true if path is executable by the real user id of this process else returns false.

File.write("foo", "foo")
File.executable?("foo") # => false

[View source]
def self.exists?(path : Path | String) : Bool #

Returns whether the file given by path exists.

Symbolic links are dereferenced, possibly recursively. Returns false if a symbolic link refers to a non-existent file.

File.delete("foo") if File.exists?("foo")
File.exists?("foo") # => false
File.write("foo", "foo")
File.exists?("foo") # => true

[View source]
def self.expand_path(path : Path | String, dir = nil, *, home = false) : String #

Converts path to an absolute path. Relative paths are referenced from the current working directory of the process unless dir is given, in which case it will be used as the starting point. "~" is expanded to the value passed to home. If it is false (default), home is not expanded. If true, it is expanded to the user's home directory (Path.home).

File.expand_path("foo")                 # => "/home/.../foo"
File.expand_path("~/foo", home: "/bar") # => "/bar/foo"
File.expand_path("baz", "/foo/bar")     # => "/foo/bar/baz"

[View source]
def self.extname(filename : Path | String) : String #

Returns filename's extension, or an empty string if it has no extension.

File.extname("foo.cr") # => ".cr"

[View source]
def self.file?(path : Path | String) : Bool #

Returns true if given path exists and is a file.

File.write("foo", "")
Dir.mkdir("dir1")
File.file?("foo")    # => true
File.file?("dir1")   # => false
File.file?("foobar") # => false

[View source]
def self.info(path : Path | String, follow_symlinks = true) : Info #

Returns a File::Info object for the file given by path or raises File::Error in case of an error.

If follow_symlinks is set (the default), symbolic links are followed. Otherwise, symbolic links return information on the symlink itself.

File.write("foo", "foo")
File.info("foo").size              # => 3
File.info("foo").modification_time # => 2015-09-23 06:24:19 UTC

File.symlink("foo", "bar")
File.info("bar", follow_symlinks: false).type.symlink? # => true

Use IO::FileDescriptor#info if the file is already open.


[View source]
def self.info?(path : Path | String, follow_symlinks = true) : Info | Nil #

Returns a File::Info object for the file given by path or returns nil if the file does not exist.

If follow_symlinks is set (the default), symbolic links are followed. Otherwise, symbolic links return information on the symlink itself.

File.write("foo", "foo")
File.info?("foo").try(&.size) # => 3
File.info?("non_existent")    # => nil

File.symlink("foo", "bar")
File.info?("bar", follow_symlinks: false).try(&.type.symlink?) # => true

Use IO::FileDescriptor#info if the file is already open.


[View source]
def self.join(parts : Enumerable) : String #

Returns a new string formed by joining the strings using File::SEPARATOR.

File.join({"foo", "bar", "baz"})       # => "foo/bar/baz"
File.join({"foo/", "/bar/", "/baz"})   # => "foo/bar/baz"
File.join(["/foo/", "/bar/", "/baz/"]) # => "/foo/bar/baz/"

[View source]
def self.join(*parts : String | Path) : String #

Returns a new string formed by joining the strings using File::SEPARATOR.

File.join("foo", "bar", "baz")       # => "foo/bar/baz"
File.join("foo/", "/bar/", "/baz")   # => "foo/bar/baz"
File.join("/foo/", "/bar/", "/baz/") # => "/foo/bar/baz/"

[View source]
def self.link(old_path : Path | String, new_path : Path | String) : Nil #

Creates a new link (also known as a hard link) at new_path to an existing file given by old_path.


[View source]
def self.match?(pattern : String, path : Path | String) : Bool #

Matches path against pattern.

The pattern syntax is similar to shell filename globbing. It may contain the following metacharacters:

  • * matches an unlimited number of arbitrary characters, excluding any directory separators.
    • "*" 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).
  • ** matches directories recursively if followed by /. If this path segment contains any other characters, it is the same as the usual *.
  • ? matches one arbitrary character, excluding any directory separators.
  • character sets:
    • [abc] matches any one of these characters.
    • [^abc] matches any one character other than these.
    • [a-z] matches any one character in the range.
  • {a,b} matches subpattern a or b.
  • \\ escapes the next character.

If path is a Path, all directory separators supported by path are recognized, according to the path's kind. If path is a String, only / is considered a directory separator.

NOTE Only / in pattern matches directory separators in path.


[View source]
def self.open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = true, &) #

Opens the file named by filename. If a file is being created, its initial permissions may be set using the perm parameter. Then given block will be passed the opened file as an argument, the file will be automatically closed when the block returns.

See self.new for what mode can be.


[View source]
def self.read(filename : Path | String, encoding = nil, invalid = nil, blocking = true) : String #

Returns the content of filename as a string.

File.write("bar", "foo")
File.read("bar") # => "foo"

[View source]
def self.read_lines(filename : Path | String, encoding = nil, invalid = nil, chomp = true, blocking = true) : Array(String) #

Returns all lines in filename as an array of strings.

File.write("foobar", "foo\nbar")
File.read_lines("foobar") # => ["foo", "bar"]

[View source]
def self.readable?(path : Path | String) : Bool #

Returns true if path is readable by the real user id of this process else returns false.

File.write("foo", "foo")
File.readable?("foo") # => true

[View source]
def self.readlink(path : Path | String) : String #

Returns value of a symbolic link .


[View source]
def self.real_path(path : Path | String) : String #

Resolves the real path of path by following symbolic links.

DEPRECATED Use .realpath instead.


[View source]
def self.realpath(path : Path | String) : String #

Resolves the real path of path by following symbolic links.


[View source]
def self.rename(old_filename : Path | String, new_filename : Path | String) : Nil #

Moves old_filename to new_filename.

File.write("afile", "foo")
File.exists?("afile") # => true

File.rename("afile", "afile.cr")
File.exists?("afile")    # => false
File.exists?("afile.cr") # => true

[View source]
def self.same?(path1 : Path | String, path2 : Path | String, follow_symlinks = false) : Bool #

Returns true if path1 and path2 represents the same file. The comparison take symlinks in consideration if follow_symlinks is true.


[View source]
def self.same_content?(path1 : Path | String, path2 : Path | String) : Bool #

Compares two files filename1 to filename2 to determine if they are identical. Returns true if content are the same, false otherwise.

File.write("file.cr", "1")
File.write("bar.cr", "1")
File.same_content?("file.cr", "bar.cr") # => true

[View source]
def self.size(filename : Path | String) : Int64 #

Returns the size of the file at filename in bytes. Raises File::NotFoundError if the file at filename does not exist.

File.size("foo") # raises File::NotFoundError
File.write("foo", "foo")
File.size("foo") # => 3

[View source]
def self.symlink(old_path : Path | String, new_path : Path | String) : Nil #

Creates a symbolic link at new_path to an existing file given by old_path.


[View source]
def self.symlink?(path : Path | String) : Bool #

Returns true if the path is a symbolic link.


[View source]
def self.tempfile(prefix : String | Nil, suffix : String | Nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil) #

Creates a temporary file.

tempfile = File.tempfile("foo", ".bar")
tempfile.delete

prefix and suffix are appended to the front and end of the file name, respectively.

NOTE These path values may contain directory separators. It's the caller's responsibility to ensure they are used safely. For example by rejecting user-provided values that would result in navigating the directory tree.

The file will be placed in dir which defaults to the standard temporary directory Dir.tempdir.

encoding and invalid are passed to IO#set_encoding.

It is the caller's responsibility to remove the file when no longer needed.


[View source]
def self.tempfile(suffix : String | Nil = nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil) #

Creates a temporary file.

tempfile = File.tempfile(".bar")
tempfile.delete

prefix and suffix are appended to the front and end of the file name, respectively.

NOTE These path values may contain directory separators. It's the caller's responsibility to ensure they are used safely. For example by rejecting user-provided values that would result in navigating the directory tree.

The file will be placed in dir which defaults to the standard temporary directory Dir.tempdir.

encoding and invalid are passed to IO#set_encoding.

It is the caller's responsibility to remove the file when no longer needed.


[View source]
def self.tempfile(prefix : String | Nil, suffix : String | Nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil, &) #

Creates a temporary file and yields it to the given block. It is closed and returned at the end of this method call.

tempfile = File.tempfile("foo", ".bar") do |file|
  file.print("bar")
end
File.read(tempfile.path) # => "bar"
tempfile.delete

prefix and suffix are appended to the front and end of the file name, respectively. These values may contain directory separators.

The file will be placed in dir which defaults to the standard temporary directory Dir.tempdir.

encoding and invalid are passed to IO#set_encoding.

It is the caller's responsibility to remove the file when no longer needed.


[View source]
def self.tempfile(suffix : String | Nil = nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil, &) #

Creates a temporary file and yields it to the given block. It is closed and returned at the end of this method call.

tempfile = File.tempfile(".bar") do |file|
  file.print("bar")
end
File.read(tempfile.path) # => "bar"
tempfile.delete

prefix and suffix are appended to the front and end of the file name, respectively.

NOTE These path values may contain directory separators. It's the caller's responsibility to ensure they are used safely. For example by rejecting user-provided values that would result in navigating the directory tree.

The file will be placed in dir which defaults to the standard temporary directory Dir.tempdir.

encoding and invalid are passed to IO#set_encoding.

It is the caller's responsibility to remove the file when no longer needed.


[View source]
def self.tempname(prefix : String | Nil, suffix : String | Nil, *, dir : String = Dir.tempdir) #

Returns a fully-qualified path to a temporary file. The file is not actually created on the file system.

File.tempname("foo", ".sock") # => "/tmp/foo20171206-1234-449386.sock"

prefix and suffix are appended to the front and end of the file name, respectively.

NOTE These path values may contain directory separators. It's the caller's responsibility to ensure they are used safely. For example by rejecting user-provided values that would result in navigating the directory tree.

The path will be placed in dir which defaults to the standard temporary directory Dir.tempdir.


[View source]
def self.tempname(suffix : String | Nil = nil, *, dir : String = Dir.tempdir) #

Returns a fully-qualified path to a temporary file. The optional suffix is appended to the file name.

File.tempname          # => "/tmp/20171206-1234-449386"
File.tempname(".sock") # => "/tmp/20171206-1234-449386.sock"

[View source]
def self.touch(filename : Path | String, time : Time = Time.utc) : Nil #

Attempts to set the access and modification times of the file named in the filename parameter to the value given in time.

If the file does not exist, it will be created.

Use #touch if the File is already open.


[View source]
def self.utime(atime : Time, mtime : Time, filename : Path | String) : Nil #

Sets the access and modification times of filename.

Use #utime if the File is already open.


[View source]
def self.writable?(path : Path | String) : Bool #

Returns true if path is writable by the real user id of this process else returns false.

File.write("foo", "foo")
File.writable?("foo") # => true

[View source]
def self.write(filename : Path | String, content, perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, mode = "w", blocking = true) #

Writes the given content to filename.

By default, an existing file will be overwritten.

filename will be created if it does not already exist.

File.write("foo", "bar")
File.write("foo", "baz", mode: "a")

NOTE If the content is a Slice(UInt8), those bytes will be written. If it's an IO, all bytes from the IO will be written. Otherwise, the string representation of content will be written (the result of invoking to_s on content).

See self.new for what mode can be.


[View source]

Instance Method Detail

def chmod(permissions : Int | Permissions) : Nil #

Changes the permissions of the specified file.

file.chmod(0o755)
file.info.permissions.value # => 0o755

file.chmod(0o700)
file.info.permissions.value # => 0o700

[View source]
def chown(uid : Int = -1, gid : Int = -1) : Nil #

Changes the owner of the specified file.

file.chown(1001, 100)
file.chown(gid: 100)

[View source]
def delete : Nil #

Deletes this file.


[View source]
def inspect(io : IO) : Nil #
Description copied from class Reference

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

[View source]
def path : String #

[View source]
def read_at(offset, bytesize, & : IO -> ) #

Yields an IO to read a section inside this file. Multiple sections can be read concurrently.


[View source]
def rename(new_filename : Path | String) : Nil #

Rename the current File


[View source]
def size : Int64 #

Returns the size in bytes of the currently opened file.


[View source]
def touch(time : Time = Time.utc) : Nil #

Attempts to set the access and modification times to the value given in time.


[View source]
def truncate(size = 0) : Nil #

Truncates the file to the specified size. Requires that the current file is opened for writing.


[View source]
def utime(atime : Time, mtime : Time) : Nil #

Sets the access and modification times


[View source]