File - Crystal 1.20.1

# class File

- File
- IO::FileDescriptor
- IO
- Reference
- Object

##
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:12Z
    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

- Crystal::System::File

##
Defined in:

file.cr:1
file.cr:62
file/error.cr
file/info.cr
file/match.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

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

  Opens the file named by filename.

  DEPRECATED parameter `blocking`

- .open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = nil) : self

  Opens the file named by filename.

  DEPRECATED parameter `blocking`

##
Class Method Summary

- .basename(path : Path | String, suffix : String) : String

  Returns the last component of the given path.

- .basename(path : Path | String) : String

  Returns the last component of the given path.

- .chmod(path : Path | String, permissions : Int | Permissions) : Nil

  Changes the permissions of the specified file.

- .chown(path : Path | String, uid : Int = -1, gid : Int = -1, follow_symlinks = false) : Nil

  Changes the owner of the specified file.

- .copy(src : String | Path, dst : String | Path) : Nil

  Copies the file src to the file dst.

- .delete(path : Path | String) : Nil

  Deletes the file at path.

- .delete?(path : Path | String) : Bool

  Deletes the file at path, or returns `false` if the file does not exist.

- .directory?(path : Path | String) : Bool

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

- .dirname(path : Path | String) : String

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

- .each_line(filename : Path | String, encoding = nil, invalid = nil, chomp = true, blocking = nil, &)

  Yields each line in filename to the given block.

  DEPRECATED parameter `blocking`

- .empty?(path : Path | String) : Bool

  Returns `true` if the file at path is empty, otherwise returns `false`.

- .executable?(path : Path | String) : Bool

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

  DEPRECATED Use `File::Info.executable?` instead

- .exists?(path : Path | String) : Bool

  Returns whether the file given by path exists.

- .expand_path(path : Path | String, dir = nil, *, home = false) : String

  Converts path to an absolute path.

- .extname(filename : Path | String) : String

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

- .file?(path : Path | String) : Bool

  Returns `true` if given path exists and is a file.

- .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.

- .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.

- .join(parts : Enumerable) : String

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

- .join(*parts : String | Path) : String

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

- .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.

- .match?(pattern : String, path : Path | String) : Bool

  Matches path against pattern.

- .open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = nil, &)

  Opens the file named by filename.

  DEPRECATED parameter `blocking`

- .read(filename : Path | String, encoding = nil, invalid = nil, blocking = nil) : String

  Returns the content of filename as a string.

  DEPRECATED parameter `blocking`

- .read_lines(filename : Path | String, encoding = nil, invalid = nil, chomp = true, blocking = nil) : Array(String)

  Returns all lines in filename as an array of strings.

  DEPRECATED parameter `blocking`

- .readable?(path : Path | String) : Bool

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

  DEPRECATED Use `File::Info.readable?` instead

- .readlink(path : Path | String) : String

  Returns the target of a symbolic link.

- .readlink?(path : Path | String) : String | Nil

  Returns the target of a symbolic link.

- .real_path(path : Path | String) : String

  Resolves the real path of path by following symbolic links.

  DEPRECATED Use `.realpath` instead.

- .realpath(path : Path | String) : String

  Resolves the real path of path by following symbolic links.

- .rename(old_filename : Path | String, new_filename : Path | String) : Nil

  Moves old_filename to new_filename.

- .same?(path1 : Path | String, path2 : Path | String, follow_symlinks = false) : Bool

  Returns `true` if path1 and path2 represents the same file.

- .same_content?(path1 : Path | String, path2 : Path | String) : Bool

  Compares two files filename1 to filename2 to determine if they are identical.

- .size(filename : Path | String) : Int64

  Returns the size of the file at filename in bytes.

- .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.

- .symlink?(path : Path | String) : Bool

  Returns `true` if the path is a symbolic link.

- .tempfile(prefix : String | Nil, suffix : String | Nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil)

  Creates a temporary file.

- .tempfile(suffix : String | Nil = nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil)

  Creates a temporary file.

- .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.

- .tempfile(suffix : String | Nil = nil, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil, &)

  Creates a temporary file and yields it to the given block.

- .tempname(prefix : String | Nil, suffix : String | Nil, *, dir : String = Dir.tempdir)

  Returns a fully-qualified path to a temporary file.

- .tempname(suffix : String | Nil = nil, *, dir : String = Dir.tempdir)

  Returns a fully-qualified path to a temporary file.

- .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.

- .utime(atime : Time, mtime : Time, filename : Path | String) : Nil

  Sets the access and modification times of filename.

- .writable?(path : Path | String) : Bool

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

  DEPRECATED Use `File::Info.writable?` instead

- .write(filename : Path | String, content, perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, mode = "w", blocking = nil)

  Writes the given content to filename.

  DEPRECATED parameter `blocking`

##
Instance Method Summary

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

  Changes the permissions of the specified file.

- #chown(uid : Int = -1, gid : Int = -1) : Nil

  Changes the owner of the specified file.

- #delete : Nil

  Deletes this file.

- #inspect(io : IO) : Nil

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

- #path : String
- #read_at(offset, bytesize, & : IO -> )

  Yields an `IO` to read a section inside this file.

- #rename(new_filename : Path | String) : Nil

  Rename the current `File`

- #size : Int64

  Returns the size in bytes of the currently opened file.

- #touch(time : Time = Time.utc) : Nil

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

- #truncate(size = 0) : Nil

  Truncates the file to the specified size.

- #utime(atime : Time, mtime : Time) : Nil

  Sets the access and modification times

### 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?, 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 | Nil = nil) : Tuple(FileDescriptor::Handle, String, Bool) mktemp, open(filename : String, mode : String, perm : Int32 | ::File::Permissions, blocking : Bool | Nil) : Tuple(FileDescriptor::Handle, Bool) open, readable?(path) : Bool readable?, readlink(path, &) : String readlink, realpath(path) realpath, rename(old_filename, new_filename) : ::File::Error | Nil rename, special_type?(fd) special_type?, 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 : Bool blocking, blocking=(value : Bool) : Nil blocking=, close_on_exec=(value : Bool) : 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 : Int, arg : Int = 0) : Int fcntl, fd : Handle fd, finalize : Nil finalize, flock_exclusive(blocking = true, &)
flock_exclusive(blocking : Bool = true) : Nil flock_exclusive, flock_shared(blocking = true, &)
flock_shared(blocking : Bool = true) : Nil flock_shared, flock_unlock : Nil flock_unlock, fsync(flush_metadata : Bool = 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!, read_timeout : Time::Span | Nil read_timeout, read_timeout=(read_timeout : Number) : Number
read_timeout=(read_timeout : Time::Span | Nil) read_timeout=, reopen(other : IO::FileDescriptor) : IO::FileDescriptor reopen, seek(offset, whence : Seek = Seek::Set)
seek(offset, whence : Seek = Seek::Set, &) seek, tty? : Bool tty?, write_timeout : Time::Span | Nil write_timeout, write_timeout=(write_timeout : Number) : Number
write_timeout=(write_timeout : Time::Span | Nil) write_timeout=

### Constructor methods inherited from class `IO::FileDescriptor`

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

### Class methods inherited from class `IO::FileDescriptor`

fcntl(fd, cmd, arg = 0) fcntl, get_blocking(fd : Handle) : Bool get_blocking, set_blocking(fd : Handle, value : Bool) set_blocking

### 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 : self flush, flush_on_newline=(flush_on_newline : Bool) : Bool 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 : Bool) : Bool read_buffering=, read_buffering? : Bool read_buffering?, rewind : self rewind, sync=(sync : Bool) : Bool 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`

__evloop_data : EventLoop::Polling::Arena::Index __evloop_data, __evloop_data=(__evloop_data : EventLoop::Polling::Arena::Index) __evloop_data=, close_volatile_fd? : Int32 | Nil close_volatile_fd?, file_descriptor_close(&) : Nil
file_descriptor_close file_descriptor_close

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

cfmakeraw(termios) cfmakeraw, fcntl(fd, cmd, arg = 0) fcntl, from_stdio(fd) from_stdio, pread(file, buffer, offset) pread, system_info(fd) system_info, system_pipe : StaticArray(LibC::Int, 2) system_pipe, write_fully(fd : LibC::Int, pointer : Pointer, size : Int32 = 1) : Nil
write_fully(fd : LibC::Int, slice : Slice(UInt8)) : Nil write_fully

### 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(delimiter : Char, limit : Int, chomp = false) : String | Nil
gets(chomp : Bool = true) : String | Nil
gets(limit : Int, chomp : Bool = false) : String | Nil
gets(delimiter : Char, chomp : Bool = false) : String | Nil
gets(delimiter : String, chomp = false) : 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 : String, args : Array | Tuple) : Nil
printf(format_string : 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_greedy(slice : Bytes) : Int32 read_greedy, read_line(*args, **options) : String read_line, read_string(bytesize : Int) : String read_string, read_utf8(slice : Bytes) : Int32 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 : IO, dst : IO, limit : Int) : Int64
copy(src : IO, dst : IO) : Int64 copy, pipe(read_blocking : Bool | Nil = nil, write_blocking : Bool | Nil = nil) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
pipe(read_blocking = nil, write_blocking = nil, &) 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 : String | IO, root : String)
from_json(string_or_io : String | 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 = nil) #

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.

NOTE The blocking arg is deprecated since Crystal 1.17. It used to be true by default to denote a regular disk file (always ready in system event loops) and could be set to false when the file was known to be a fifo, pipe, or character device (for example `/dev/tty`). The event loop now chooses the appropriate blocking mode automatically and there are no reasons to change it anymore.

NOTE On macOS files are always opened in blocking mode because non-blocking FIFO files don't work — the OS exhibits issues with readiness notifications.

DEPRECATED parameter `blocking`

def self.open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = nil) : 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.

DEPRECATED parameter `blocking`

##
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"

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

Returns the last component of the given path.

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

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.

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.

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

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)

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

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

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"

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

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"]

DEPRECATED parameter `blocking`

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

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

DEPRECATED Use `File::Info.executable?` instead

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

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"

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"

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

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:19Z

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

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

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.

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/"

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/"

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.

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:

- `*`: Wildcard matches zero or more characters, except for directory separators.
- `**`: Globstar matches zero or more characters, including directory separators. It must match a complete path segment, i.e. it must be wrapped in `/` except for the beginning and end of the pattern.
- `?`: Matches a single Unicode character, except for directory separators.
- Character classes:
  - `[abc]`: Character set matches one of the Unicode characters contained in the brackets.
  - `[^abc]`: Negated character set matches any Unicode character except those contained in the brackets.
  - `[a-z]`: Character range matches one Unicode character contained in the character range.
  - `[^a-z]`: Negated character range matches one Unicode character except those contained in the character range.
- `{a,b}`: Branches matches one of the subpatterns contained in the braces. Subpatterns may contain any other pattern feature, including nested branches (max nesting depth is 10 levels deep).
- `\\`: Backslash escapes the next character.

Multiple character pattern can be combined in the same brackets to define a character class (for example: `[0-9a-f]`).

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.

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

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.

DEPRECATED parameter `blocking`

def self.read(filename : Path | String, encoding = nil, invalid = nil, blocking = nil) : String #

Returns the content of filename as a string.

Raises `File::Error` if the file cannot be read.

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

    File.read("non-existent") # raises File::NotFoundError

DEPRECATED parameter `blocking`

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

Returns all lines in filename as an array of strings.

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

DEPRECATED parameter `blocking`

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

DEPRECATED Use `File::Info.readable?` instead

def self.readlink(path : Path | String) : String #

Returns the target of a symbolic link.

def self.readlink?(path : Path | String) : String | Nil #

Returns the target of a symbolic link.

Returns `nil` if path does not exist or is not a symbolic link.

def self.real_path(path : Path | String) : String #

Resolves the real path of path by following symbolic links.

DEPRECATED Use `.realpath` instead.

def self.realpath(path : Path | String) : String #

Resolves the real path of path by following symbolic links.

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

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`.

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

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

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.

def self.symlink?(path : Path | String) : Bool #

Returns `true` if the path is a symbolic link.

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.

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.

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.

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.

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`.

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"

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.

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.

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

DEPRECATED Use `File::Info.writable?` instead

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

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.

DEPRECATED parameter `blocking`

##
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

def chown(uid : Int = -1, gid : Int = -1) : Nil #

Changes the owner of the specified file.

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

def delete : Nil #

Deletes this file.

def inspect(io : IO) : Nil #
Description copied from class IO::FileDescriptor

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>

def path : String #
def read_at(offset, bytesize, & : IO -> ) #

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

def rename(new_filename : Path | String) : Nil #

Rename the current `File`

def size : Int64 #

Returns the size in bytes of the currently opened file.

def touch(time : Time = Time.utc) : Nil #

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

def truncate(size = 0) : Nil #

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

def utime(atime : Time, mtime : Time) : Nil #

Sets the access and modification times