class File
Defined in:
file.crfile/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.
Constructors
- .new(filename : String, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil)
-
.open(filename, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil) : self
Opens the file named by filename.
Class Method Summary
-
.basename(path) : String
Returns the last component of the given path.
-
.basename(path, suffix) : String
Returns the last component of the given path.
-
.chmod(path, mode : Int)
Changes the permissions of the specified file.
-
.chown(path, uid : Int? = -1, gid : Int = -1, follow_symlinks = false)
Changes the owner of the specified file.
-
.delete(path)
Delete the file at path.
-
.directory?(path) : Bool
Returns
true
if the given path exists and is a directory. -
.dirname(path) : String
Returns all components of the given path except the last one.
-
.each_line(filename, encoding = nil, invalid = nil, chomp = true, &block)
Yields each line in filename to the given block.
-
.each_line(filename, encoding = nil, invalid = nil, chomp = true)
Returns an
Iterator
for each line in filename. -
.empty?(path) : Bool
Returns
true
if the file at path is empty, otherwise returnsfalse
. -
.executable?(path) : Bool
Returns
true
if path is executable by the real user id of this process else returnsfalse
. -
.exists?(path) : Bool
Returns
true
if path exists else returnsfalse
-
.expand_path(path, dir = nil) : String
Converts path to an absolute path.
-
.extname(filename) : String
Returns filename's extension, or an empty string if it has no extension.
-
.file?(path) : Bool
Returns
true
if given path exists and is a file. -
.join(parts : Array | Tuple) : String
Returns a new string formed by joining the strings using
File::SEPARATOR
. -
.join(*parts) : String
Returns a new string formed by joining the strings using
File::SEPARATOR
. -
.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.
-
.lstat(path) : Stat
Returns a
File::Stat
object for the file given by path or raisesErrno
in case of an error. -
.open(filename, mode = "r", perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil, &block)
Opens the file named by filename.
-
.read(filename, encoding = nil, invalid = nil) : String
Returns the content of filename as a string.
-
.read_lines(filename, encoding = nil, invalid = nil, chomp = true) : Array(String)
Returns all lines in filename as an array of strings.
-
.readable?(path) : Bool
Returns
true
if path is readable by the real user id of this process else returnsfalse
. -
.real_path(path) : String
Resolves the real path of path by following symbolic links.
-
.rename(old_filename, new_filename)
Moves old_filename to new_filename.
-
.size(filename) : UInt64
Returns the size of filename bytes.
-
.stat(path) : Stat
Returns a
File::Stat
object for the file given by path or raisesErrno
in case of an error. -
.symlink(old_path, new_path)
Creates a symbolic link at new_path to an existing file given by *old_path.
-
.symlink?(path) : Bool
Returns
true
if the path is a symbolic link. -
.touch(filename : String, time : Time = Time.now)
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 : String) : Nil
Sets the access and modification times of filename.
-
.writable?(path) : Bool
Returns
true
if path is writable by the real user id of this process else returnsfalse
. -
.write(filename, content, perm = DEFAULT_CREATE_MODE, encoding = nil, invalid = nil)
Write the given content to filename.
Instance Method Summary
- #flock_exclusive(blocking = true, &block)
-
#flock_exclusive(blocking = true)
Place an exclusive advisory lock.
- #flock_shared(blocking = true, &block)
-
#flock_shared(blocking = true)
Place a shared advisory lock.
-
#flock_unlock
Remove an existing advisory lock held by this process.
- #inspect(io)
- #path : String
-
#read_at(offset, bytesize, &block)
Yields an
IO
to read a section inside this file. -
#size
Return the size in bytes of the currently opened file.
-
#truncate(size = 0)
Truncates the file to the specified size.
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=,
pretty_print(pp)
pretty_print,
raw(&block)
raw,
raw!
raw!,
read_timeout=(read_timeout : Time::Span)read_timeout=(read_timeout : Nil)
read_timeout=(read_timeout : Number) read_timeout=, reopen(other : IO::FileDescriptor) reopen, seek(offset, whence : Seek = Seek::Set)
seek(offset, whence : Seek = Seek::Set, &block) 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 : Time::Span)
write_timeout=(write_timeout : Nil) write_timeout=
Constructor methods inherited from class IO::FileDescriptor
new(fd : Int32, blocking = false, edge_triggerable = false)
new
Class methods inherited from class IO::FileDescriptor
fcntl(fd, cmd, arg = 0)
fcntl
Instance methods inherited from module IO::Buffered
close : Nil
close,
flush
flush,
flush_on_newline=(flush_on_newline)
flush_on_newline=,
flush_on_newline?
flush_on_newline?,
peek : Bytes?
peek,
read(slice : Bytes)
read,
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)
write
Instance methods inherited from module IO
<<(obj) : self
<<,
close
close,
closed?
closed?,
each_byteeach_byte(&block) : Nil each_byte, each_char(&block) : Nil
each_char each_char, each_line(*args, **options, &block) : Nil
each_line(*args, **options) each_line, encoding : String encoding, flush flush, gets(limit : Int, chomp = false) : String?
gets(delimiter : Char, chomp = false) : String?
gets(delimiter : String, chomp = false) : String?
gets(chomp = true) : String?
gets(delimiter : Char, limit : Int, chomp = false) : String? gets, gets_to_end : String gets_to_end, peek : Bytes? peek, print(*objects : _) : Nil
print(obj) : Nil print, printf(format_string, args : Array | Tuple) : Nil
printf(format_string, *args) : Nil printf, puts(*objects : _) : Nil
puts : Nil
puts(obj) : Nil
puts(string : String) : Nil puts, read(slice : Bytes) read, 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, set_encoding(encoding : String, invalid : Symbol? = nil) set_encoding, skip(bytes_count : Int) : Nil skip, skip_to_end : Nil skip_to_end, 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 module IO
copy(src, dst, limit : Int)copy(src, dst) copy, pipe(read_blocking = false, write_blocking = false)
pipe(read_blocking = false, write_blocking = false, &block) pipe
Instance methods inherited from class Reference
==(other : self)==(other) ==, dup dup, hash 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 hash, inspect(io : IO)
inspect 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
to_s(io : IO) 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) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io) : self from_yaml
Constructor Detail
Opens the file named by filename. If a file is being created, its initial permissions may be set using the perm parameter.
Class Method Detail
Returns the last component of the given path.
File.basename("/foo/bar/file.cr") # => "file.cr"
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"
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.stat("foo").perm # => 0o755
File.chmod("foo", 0o700)
File.stat("foo").perm # => 0o700
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
Delete 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)
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
Returns all components of the given path except the last one.
File.dirname("/foo/bar/file.cr") # => "/foo/bar"
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"]
Returns an Iterator
for each line in filename.
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
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
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
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"
Returns filename's extension, or an empty string if it has no extension.
File.extname("foo.cr") # => ".cr"
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
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/"
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/"
Creates a new link (also known as a hard link) at new_path to an existing file given by old_path.
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 # => 3
File.lstat("foo").mtime # => 2015-09-23 06:24:19 UTC
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.
Returns the content of filename as a string.
File.write("bar", "foo")
File.read("bar") # => "foo"
Returns all lines in filename as an array of strings.
File.write("foobar", "foo\nbar")
File.read_lines("foobar") # => ["foo", "bar"]
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
Resolves the real path of path by following symbolic links.
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
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 # => 3
File.stat("foo").mtime # => 2015-09-23 06:24:19 UTC
Creates a symbolic link at new_path to an existing file given by *old_path.
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.
Sets the access and modification times of filename.
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
Write the given content to filename.
An existing file will be overwritten, else a file will be created.
File.write("foo", "bar")
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).
Instance Method Detail
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.
Yields an IO
to read a section inside this file.
Mutliple sections can be read concurrently.
Truncates the file to the specified size. Requires that the current file is opened for writing.