class

File

Inherits Crystal::System::File / IO::FileDescriptor / IO::Buffered / Crystal::System::FileDescriptor / IO / Reference / Object

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

Constants

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.

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.

Temporary Files

Constants

Constructors

Class methods

Instance methods

Nested types