class File

Defined in:

file.cr
file/flock.cr
file/stat.cr

Constant Summary

SEPARATOR = {% if flag?(:windows) %} '\\' {% else %} '/' {% end %}

The file/directory separator character. '/' in unix, '\\' in windows.

SEPARATOR_STRING = {% if flag?(:windows) %} "\\" {% else %} "/" {% end %}

The file/directory separator string. "/" in unix, "\\" in windows.

Class Method Summary

Instance Method Summary

Instance methods inherited from class IO::FileDescriptor

blocking blocking, blocking=(value) blocking=, close_on_exec=(arg : 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, inspect(io) inspect, noecho(&block) noecho, noecho! noecho!, pos pos, pos=(value) pos=, raw(&block) raw, raw! raw!, read_timeout=(read_timeout : Time::Span)
read_timeout=(read_timeout : Number)
read_timeout=(read_timeout : Nil) read_timeout=, reopen(other : IO::FileDescriptor) reopen, seek(offset, whence : Seek = Seek::Set) seek, stat stat, tell tell, tty? tty?, write_timed_out : Bool write_timed_out, write_timed_out=(write_timed_out : Bool) write_timed_out=, write_timeout=(write_timeout : Number)
write_timeout=(write_timeout : Nil)
write_timeout=(write_timeout : Time::Span) write_timeout=

Class methods inherited from class IO::FileDescriptor

fcntl(fd, cmd, arg = 0) fcntl, new(fd : Int32, blocking = false, edge_triggerable = false) new

Instance methods inherited from module IO::Buffered

close close, flush flush, flush_on_newline=(flush_on_newline) flush_on_newline=, flush_on_newline? flush_on_newline?, read(slice : Slice(UInt8)) read, rewind rewind, sync=(sync) sync=, sync? sync?, unbuffered_close unbuffered_close, unbuffered_flush unbuffered_flush, unbuffered_read(slice : Slice(UInt8)) unbuffered_read, unbuffered_rewind unbuffered_rewind, unbuffered_write(slice : Slice(UInt8)) unbuffered_write, write(slice : Slice(UInt8)) write

Instance methods inherited from module IO

<<(obj) : self <<, close close, closed? closed?, each_byte(&block)
each_byte each_byte, each_char(&block)
each_char each_char, each_line(*args, **options)
each_line(*args, **options, &block) each_line, encoding : String encoding, flush flush, gets(limit : Int) : String | Nil
gets(delimiter : Char, limit : Int) : String | Nil
gets(delimiter : Char) : String | Nil
gets : String | Nil
gets(delimiter : String) : String | Nil gets, gets_to_end : String gets_to_end, print(obj) : Nil
print(*objects : _) : Nil print, printf(format_string, *args) : Nil
printf(format_string, args : Array | Tuple) : Nil printf, puts(*objects : _) : Nil
puts : Nil
puts(string : String) : Nil
puts(obj) : Nil puts, read(slice : Slice(UInt8)) read, 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 : Slice(UInt8)) read_fully, read_line(*args, **options) : String | Nil read_line, read_utf8(slice : Slice(UInt8)) read_utf8, read_utf8_byte read_utf8_byte, rewind rewind, set_encoding(encoding : String, invalid : Symbol | Nil = nil) set_encoding, skip(bytes_count : Int) : Nil skip, tty? : Bool tty?, write(slice : Slice(UInt8)) : Nil write, write_byte(byte : UInt8) write_byte, write_bytes(object, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) write_bytes, write_utf8(slice : Slice(UInt8)) write_utf8

Class methods inherited from module IO

copy(src, dst, limit : Int)
copy(src, dst) copy, pipe(read_blocking = false, write_blocking = false, &block)
pipe(read_blocking = false, write_blocking = false) pipe, select(read_ios, write_ios, error_ios, timeout_sec : LibC::TimeT | Int | Float | Nil)
select(read_ios, write_ios = nil, error_ios = nil) select

Instance methods inherited from module JSON::Builder

json_array(&block) json_array, json_object(&block) json_object

Instance methods inherited from class Reference

==(other)
==(other : self) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other)
===(other : YAML::Any)
===(other : JSON::Any) ===, =~(other) =~, class class, crystal_type_id crystal_type_id, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, tap(&block) tap, to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml
to_yaml(io : IO) to_yaml, try(&block) try

Class methods inherited from class Object

==(other : Class) ==, ===(other) ===, cast(other) : self cast, clone clone, dup dup, from_json(string_or_io) : self
from_json(string_or_io, root : String) : self from_json, from_yaml(string : String) : self from_yaml, hash hash, inspect(io) inspect, name : String name, nilable? nilable?, to_s(io) to_s, |(other : U.class) forall U |

Class Method Detail

def self.basename(path) : String #

Returns the last component of the given path.

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

[View source]
def self.basename(path, suffix) : 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.chmod(path, mode : Int) #

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/bin", 0o755)
File.chmod("foo/bin/exec", 0o700)

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

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

[View source]
def self.delete(path) #

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

File.write("foo", "")
File.delete("./foo")
File.delete("./bar") # => Error deleting file './bar': No such file or directory (Errno)

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

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

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

[View source]
def self.dirname(path) : 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, encoding = nil, invalid = nil) #

Returns an Iterator for each line in filename.


[View source]
def self.each_line(filename, encoding = nil, invalid = nil, &block) #

Yields each line in filename to the given block.

File.each_line("foo") do |line|
  # loop
end

[View source]
def self.executable?(path) : 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) : Bool #

Returns true if path exists else returns false

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

[View source]
def self.expand_path(path, dir = nil) : 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.

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

[View source]
def self.extname(filename) : 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) : Bool #

Returns true if given path exists and is a file.

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

[View source]
def self.join(parts : Array | Tuple) : 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 #

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

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.lstat(path) : Stat #

Returns a File::Stat object for the file given by path or raises Errno in case of an error. In case of a symbolic link information about it is returned.

File.write("foo", "foo")
File.lstat("foo").size  # => 4
File.lstat("foo").mtime # => 2015-09-23 06:24:19 UTC

[View source]
def self.new(filename : String, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil) #

[View source]
def self.open(filename, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil) : self #

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


[View source]
def self.open(filename, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil, &block) #

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.


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

Returns the content of filename as a string.

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

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

Returns all lines in filename as an array of strings.

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

[View source]
def self.readable?(path) : 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.real_path(path) : String #

Resolves the real path of path by following symbolic links.


[View source]
def self.rename(old_filename, new_filename) #

Moves old_filename to new_filename.

File.rename("afile", "afile.cr")

[View source]
def self.size(filename) : UInt64 #

Returns the size of filename bytes.


[View source]
def self.stat(path) : Stat #

Returns a File::Stat object for the file given by path or raises Errno in case of an error. In case of a symbolic link it is followed and information about the target is returned.

File.write("foo", "foo")
File.stat("foo").size  # => 4
File.stat("foo").mtime # => 2015-09-23 06:24:19 UTC

[View source]
def self.symlink(old_path, new_path) #

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


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

Returns true if the path is a symbolic link.


[View source]
def self.writable?(path) : 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, content, perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil) #

Write the given content to filename.

An existing file will be overwritten, else a file will be created.

File.write("foo", "bar")

[View source]

Instance Method Detail

def flock_exclusive(blocking = true, &block) #

[View source]
def flock_exclusive(blocking = true) #

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


[View source]
def flock_shared(blocking = true, &block) #

[View source]
def flock_shared(blocking = true) #

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


[View source]
def flock_unlock #

Remove an existing advisory lock held by this process.


[View source]
def inspect(io) #

[View source]
def path : String #

[View source]
def size #

Return the size in bytes of the currently opened file.


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

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


[View source]