class File
Included Modules
- Crystal::System::File
Direct Known Subclasses
Defined in:
file.crfile/info.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_PERMISSIONS, encoding = nil, invalid = nil)
-
.open(filename, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, 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, permissions : Int | Permissions)
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)
Returns an
Iterator
for each line in filename. -
.each_line(filename, encoding = nil, invalid = nil, chomp = true, &block)
Yields each line in filename to the given block.
-
.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. -
.info(path, follow_symlinks = true) : Info
Returns a
File::Info
object for the file given by path or raisesErrno
in case of an error. -
.info?(path : String, follow_symlinks = true) : Info?
Returns a
File::Info
object for the file given by path or returnsnil
if the file does not exist. -
.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.
-
.match?(pattern : String, path : String)
Matches path against pattern.
-
.open(filename, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, 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) : Nil
Moves old_filename to new_filename.
-
.same?(path1 : String, path2 : String, follow_symlinks = false) : Bool
Returns
true
if path1 and path2 represents the same file. -
.size(filename) : UInt64
Returns the size of filename bytes.
-
.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_PERMISSIONS, encoding = nil, invalid = nil, mode = "w")
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) : Nil
Truncates the file to the specified size.
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(name, extension)
mktemp,
open(filename, mode, perm)
open,
readable?(path) : Bool
readable?,
real_path(path)
real_path,
rename(old_filename, new_filename)
rename,
symlink(old_path, new_path)
symlink,
tempdir
tempdir,
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)
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
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
Class methods inherited from module Crystal::System::FileDescriptor
fcntl(fd, cmd, arg = 0)
fcntl
Instance methods inherited from module IO::Syscall
read_syscall_helper(slice : Bytes, errno_msg : String, &block) : Int32
read_syscall_helper,
read_timeout : Time::Span?
read_timeout,
read_timeout=(read_timeout : Number) : Numberread_timeout=(timeout : Time::Span?) : Time::Span? read_timeout=, write_syscall_helper(slice : Bytes, errno_msg : String, &block) : Nil write_syscall_helper, 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
<<(obj) : self
<<,
close
close,
closed?
closed?,
each_byte(&block) : Nileach_byte 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(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 : _) : Nil
print(obj) : Nil print, printf(format_string, *args) : Nil
printf(format_string, args : Array | Tuple) : Nil printf, puts(*objects : _) : 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)copy(src, dst) 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)
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 : String | 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.info("foo").permissions # => 0o755
File.chmod("foo", 0o700)
File.info("foo").permissions # => 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"
Returns an Iterator
for each line in filename.
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 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 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
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
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/
."*"
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 an unlimited number of arbitrary charachters including/
.?
matches any one charachter excluding/
.- character sets:
[abc]
matches any one of these character.[^abc]
matches any one character other than these.[a-z]
matches any one charachter in the range.{a,b}
matches subpatterna
orb
.\\
escapes the next character.
NOTE Only /
is recognized as path separator in both pattern and 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.
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 true
if path1 and path2 represents the same file.
The comparison take symlinks in consideration if follow_symlinks is true
.
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
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.
The mode parameter can be used to change the file's .open
mode, e.g. to "a"
for appending.
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).
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.
Multiple sections can be read concurrently.
Truncates the file to the specified size. Requires that the current file is opened for writing.