W3cubDocs

/Crystal 0.31

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`
content = File.open("path/to/file") do |file|
  file.gets_to_end
end

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

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

  • Crystal::System::File

Defined in:

file.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) delete, executable?(path) : Bool executable?, exists?(path) exists?, info?(path : String, follow_symlinks : Bool) : ::File::Info? info?, link(old_path, new_path) link, mktemp(prefix, suffix, dir) : Tuple(LibC::Int, String) mktemp, open(filename, mode, perm) open, readable?(path) : Bool readable?, readlink(path) : String readlink, real_path(path) real_path, rename(old_filename, new_filename) rename, 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? close_on_exec?, closed? : Bool closed?, cooked(&block) cooked, cooked! cooked!, fcntl(cmd, arg = 0) fcntl, fd : Int32 fd, finalize finalize, info info, inspect(io : IO) : Nil inspect, noecho(&block) noecho, noecho! noecho!, pos pos, pos=(value) pos=, pretty_print(pp) pretty_print, raw(&block) raw, raw! raw!, reopen(other : IO::FileDescriptor) reopen, seek(offset, whence : Seek = Seek::Set)
seek(offset, whence : Seek = Seek::Set, &block) seek
, tty? tty?

Constructor methods inherited from class IO::FileDescriptor

new(fd, blocking = false) new

Class methods inherited from class IO::FileDescriptor

fcntl(fd, cmd, arg = 0) fcntl

Instance methods inherited from module IO::Buffered

buffer_size buffer_size, buffer_size=(value) buffer_size=, close : Nil close, flush flush, peek : Bytes? peek, read(slice : Bytes) read, read_buffering=(read_buffering) read_buffering=, read_buffering? read_buffering?, rewind rewind, sync=(sync) sync=, sync? 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

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

fcntl(fd, cmd, arg = 0) fcntl, pipe(read_blocking, write_blocking) pipe, pread(fd, buffer, offset) pread

Instance methods inherited from module IO::Evented

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

Instance methods inherited from class IO

<self <<, close close, closed? closed?, each_byte(&block) : Nil
each_byte each_byte
, each_char(&block) : Nil
each_char each_char
, each_line(*args, **options, &block : String -> ) : Nil
each_line(*args, **options) each_line
, encoding : String encoding, flush flush, gets(delimiter : Char, limit : Int, chomp = false) : String?
gets(delimiter : Char, chomp = false) : String?
gets(chomp = true) : String?
gets(limit : Int, chomp = false) : String?
gets(delimiter : String, chomp = false) : String? gets
, gets_to_end : String gets_to_end, peek : Bytes? peek, pos pos, pos=(value) pos=, print(*objects : UNDERSCORE) : Nil
print(obj) : Nil print
, printf(format_string, *args) : Nil
printf(format_string, args : Array | Tuple) : Nil printf
, puts(*objects : UNDERSCORE) : Nil
puts : Nil
puts(obj) : Nil
puts(string : String) : Nil puts
, read(slice : Bytes) read, read_at(offset, bytesize, &block) read_at, read_byte : UInt8? read_byte, read_bytes(type, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) read_bytes, read_char : Char? read_char, read_fully(slice : Bytes) read_fully, read_fully?(slice : Bytes) 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 read_utf8_byte, rewind rewind, seek(offset, whence : Seek = Seek::Set) seek, set_encoding(encoding : String, invalid : Symbol? = 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) write_byte, write_bytes(object, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) write_bytes, write_utf8(slice : Bytes) write_utf8

Class methods inherited from class IO

copy(src, dst, limit : Int) : UInt64
copy(src, dst) : UInt64 copy
, pipe(read_blocking = false, write_blocking = false) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
pipe(read_blocking = false, write_blocking = false, &block) pipe

Instance methods inherited from class Reference

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

Constructor methods inherited from class Reference

new new

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===
, =~(other) =~, class class, dup dup, hash(hasher)
hash hash
, inspect(io : IO) : Nil
inspect : String inspect
, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json
, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json
, to_s : String
to_s(io : IO) : Nil to_s
, to_yaml(io : IO)
to_yaml to_yaml
, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

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

Constructor Detail

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

Opens the file named by filename.

mode must be one of the following file open modes:

Mode | Description
-----+------------------------------------------------------
r    | Read-only, starts at the beginning of the file.
r+   | Read-write, starts at the beginning of the file.
w    | Write-only, truncates existing file to zero length or
     | creates a new file if the file doesn't exists.
w+   | Read-write, truncates existing file to zero length or
     | creates a new file if the file doesn't exists.
a    | Write-only, starts at the end of the file,
     | creates a new file if the file doesn't exists.
a+   | Read-write, starts at the end of the file,
     | creates a new file if the file doesn't exists.
rb   | Same as the 'r' mode but in binary file mode.
wb   | Same as the 'w' mode but in binary file mode.
ab   | Same as the 'a' mode but in binary file mode.

In binary file mode, line endings are not converted to CRLF on Windows.

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

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.

Class Method Detail

def self.basename(path, suffix) : StringSource

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) : StringSource

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)Source

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

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

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

def self.delete(path : Path | String)Source

Deletes the file at path. Deleting non-existent file will raise an exception.

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

def self.directory?(path : Path | String) : BoolSource

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) : StringSource

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

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

def self.each_line(filename, encoding = nil, invalid = nil, chomp = true, &block)Source

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

def self.empty?(path : Path | String) : BoolSource

Returns true if the file at path is empty, otherwise returns false. Raises Errno 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) : BoolSource

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

def self.exists?(path : Path | String) : BoolSource

Returns true if path exists else returns false

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

def self.expand_path(path, dir = nil) : StringSource

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.

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

def self.extname(filename) : StringSource

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

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

def self.file?(path : Path | String) : BoolSource

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) : InfoSource

Returns a File::Info object for the file given by path or raises Errno 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

def self.info?(path : Path | String, follow_symlinks = true) : Info?Source

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

def self.join(parts : Array | Tuple) : StringSource

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) : StringSource

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, new_path)Source

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)Source

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 /.
    • "*" 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 an unlimited number of arbitrary characters including /.
  • ? matches any one character excluding /.
  • character sets:
    • [abc] matches any one of these character.
    • [^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.

NOTE Only / is recognized as path separator in both pattern and path.

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

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.

def self.read(filename, encoding = nil, invalid = nil) : StringSource

Returns the content of filename as a string.

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

def self.read_lines(filename, encoding = nil, invalid = nil, chomp = true) : Array(String)Source

Returns all lines in filename as an array of strings.

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

def self.readable?(path : Path | String) : BoolSource

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

def self.readlink(path) : StringSource

Returns value of a symbolic link .

def self.real_path(path) : StringSource

Resolves the real path of path by following symbolic links.

def self.rename(old_filename, new_filename) : NilSource

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 : String, path2 : String, follow_symlinks = false) : BoolSource

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

def self.size(filename : Path | String) : UInt64Source

Returns the size of filename bytes. Raises Errno if the file at path does not exist.

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

def self.symlink(old_path, new_path)Source

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

def self.symlink?(path) : BoolSource

Returns true if the path is a symbolic link.

def self.tempfile(prefix : String?, suffix : String?, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil)Source

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. 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, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil)Source

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. 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(prefix : String?, suffix : String?, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil, &block)Source

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, *, dir : String = Dir.tempdir, encoding = nil, invalid = nil, &block)Source

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. 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.tempname(prefix : String?, suffix : String?, *, dir : String = Dir.tempdir)Source

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. These values may contain directory separators.

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

def self.tempname(suffix : String? = nil, *, dir : String = Dir.tempdir)Source

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 : String, time : Time = Time.utc)Source

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.

def self.utime(atime : Time, mtime : Time, filename : String) : NilSource

Sets the access and modification times of filename.

def self.writable?(path : Path | String) : BoolSource

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

def self.write(filename, content, perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, mode = "w")Source

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.

Instance Method Detail

def deleteSource

Deletes this file.

def flock_exclusive(blocking = true, &block)Source

def flock_exclusive(blocking = true)Source

Places an exclusive advisory lock. Only one process may hold an exclusive lock for a given file at a given time. Errno::EWOULDBLOCK is raised if blocking is set to false and any existing lock is set.

def flock_shared(blocking = true, &block)Source

def flock_shared(blocking = true)Source

Places a shared advisory lock. More than one process may hold a shared lock for a given file at a given time. Errno::EWOULDBLOCK is raised if blocking is set to false and an existing exclusive lock is set.

def flock_unlockSource

Removes an existing advisory lock held by this process.

def fsync(flush_metadata = true) : NilSource

Flushes all data written to this File to the disk device so that all changed information can be retrieved even if the system crashes or is rebooted. The call blocks until the device reports that the transfer has completed. To reduce disk activity the flush_metadata parameter can be set to false, then the syscall fdatasync will be used and only data required for subsequent data retrieval is flushed. Metadata such as modified time and access time is not written.

def inspect(io : IO) : NilSource

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>

def path : StringSource

def read_at(offset, bytesize, &block)Source

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

def sizeSource

Returns the size in bytes of the currently opened file.

def truncate(size = 0) : NilSource

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

© 2012–2019 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.31.1/File.html