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` 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: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:1file.cr:61
file/error.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 andNUL
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 = true)
Opens the file named by filename.
-
.open(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, blocking = true) : self
Opens the file named by filename.
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 = true, &)
Yields each line in filename to the given block.
-
.empty?(path : Path | String) : Bool
Returns
true
if the file at path is empty, otherwise returnsfalse
. -
.executable?(path : Path | String) : Bool
Returns
true
if path is executable by the real user id of this process else returnsfalse
.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 raisesFile::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 returnsnil
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 = true, &)
Opens the file named by filename.
-
.read(filename : Path | String, encoding = nil, invalid = nil, blocking = true) : String
Returns the content of filename as a string.
-
.read_lines(filename : Path | String, encoding = nil, invalid = nil, chomp = true, blocking = true) : Array(String)
Returns all lines in filename as an array of strings.
-
.readable?(path : Path | String) : Bool
Returns
true
if path is readable by the real user id of this process else returnsfalse
.DEPRECATED Use
File::Info.readable?
instead -
.readlink(path : Path | String) : String
Returns value 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 returnsfalse
.DEPRECATED Use
File::Info.writable?
instead -
.write(filename : Path | String, content, perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil, mode = "w", blocking = true)
Writes the given content to filename.
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?,
fchown(path, fd, uid : Int, gid : Int)
fchown,
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 = ::Random::DEFAULT) : Tuple(FileDescriptor::Handle, String)
mktemp,
open(filename : String, mode : String, perm : Int32 | ::File::Permissions)open(filename : String, flags : Int32, perm : ::File::Permissions) : Tuple(LibC::Int, Errno) open, readable?(path) : Bool readable?, readlink(path) : String readlink, realpath(path) realpath, rename(old_filename, new_filename) : ::File::Error | Nil rename, 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
blocking,
blocking=(value)
blocking=,
close_on_exec=(value : 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, arg = 0)
fcntl,
fd : Handle
fd,
finalize
finalize,
flock_exclusive(blocking = true, &)flock_exclusive(blocking = true) : Nil flock_exclusive, flock_shared(blocking = true, &)
flock_shared(blocking = true) : Nil flock_shared, flock_unlock : Nil flock_unlock, fsync(flush_metadata = 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) 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 : Bool = true)
new
Class methods inherited from class IO::FileDescriptor
fcntl(fd, cmd, arg = 0)
fcntl
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
flush,
flush_on_newline=(flush_on_newline)
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)
read_buffering=,
read_buffering? : Bool
read_buffering?,
rewind
rewind,
sync=(sync)
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
file_descriptor_close : Nil
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,
pipe(read_blocking, write_blocking)
pipe,
pread(fd, buffer, offset)
pread,
system_info(fd)
system_info,
tcgetattr(fd)
tcgetattr,
tcsetattr(fd, optional_actions, termios_p)
tcsetattr
Instance methods inherited from module IO::Evented
evented_close : Nil
evented_close,
evented_read(errno_msg : String, &) : Int32
evented_read,
evented_write(errno_msg : String, &) : Int32
evented_write
Instance methods inherited from class IO
<<(obj) : self
<<,
close
close,
closed? : Bool
closed?,
each_byte(&) : Nileach_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(limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, limit : Int, chomp = false) : String | Nil
gets(delimiter : Char, chomp = false) : String | Nil
gets(delimiter : String, chomp = false) : String | Nil
gets(chomp = true) : 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, args : Array | Tuple) : Nil
printf(format_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_line(*args, **options) : String read_line, read_string(bytesize : Int) : String read_string, read_utf8(slice : Bytes) 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, dst, limit : Int) : Int64copy(src, dst) : Int64 copy, pipe(read_blocking = false, write_blocking = false) : Tuple(IO::FileDescriptor, IO::FileDescriptor)
pipe(read_blocking = false, write_blocking = false, &) 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, root : String)from_json(string_or_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
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.
blocking is set to true
by default because system event queues (e.g.
epoll, kqueue) will always report the file descriptor of regular disk files
as ready.
blocking must be set to false
on POSIX targets when the file to open
isn't a regular file but a character device (e.g. /dev/tty
) or fifo. These
files depend on another process or thread to also be reading or writing, and
system event queues will properly report readyness.
blocking may also be set to nil
in which case the blocking or
non-blocking flag will be determined automatically, at the expense of an
additional syscall.
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
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"
Returns the last component of the given path.
File.basename("/foo/bar/file.cr") # => "file.cr"
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
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
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
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)
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
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 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
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
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
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"
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 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:19 UTC
File.symlink("foo", "bar")
File.info("bar", follow_symlinks: false).type.symlink? # => true
Use IO::FileDescriptor#info
if the file is already open.
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.
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.
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 any directory separators."*"
matches all regular files."c*"
matches all files beginning withc
."*c"
matches all files ending withc
."*c*"
matches all files that havec
in them (including at the beginning or end).
**
matches directories recursively if followed by/
. If this path segment contains any other characters, it is the same as the usual*
.?
matches one arbitrary character, excluding any directory separators.- character sets:
[abc]
matches any one of these characters.[^abc]
matches any one character other than these.[a-z]
matches any one character in the range.
{a,b}
matches subpatterna
orb
.\\
escapes the next character.
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.
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.
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
DEPRECATED Use File::Info.readable?
instead
Resolves the real path of path by following symbolic links.
DEPRECATED Use .realpath
instead.
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 true
if path1 and path2 represents the same file.
The comparison take symlinks in consideration if follow_symlinks is true
.
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
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
Creates a symbolic link at new_path to an existing file given by old_path.
Returns true
if the path is a symbolic link.
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.
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.
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.
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.
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
.
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"
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.
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
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
Changes the permissions of the specified file.
file.chmod(0o755)
file.info.permissions.value # => 0o755
file.chmod(0o700)
file.info.permissions.value # => 0o700
Changes the owner of the specified file.
file.chown(1001, 100)
file.chown(gid: 100)
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>
Yields an IO
to read a section inside this file.
Multiple sections can be read concurrently.
Attempts to set the access and modification times to the value given in time.
Truncates the file to the specified size. Requires that the current file is opened for writing.