class Dir

Overview

Objects of class Dir are directory streams representing directories in the underlying file system. They provide a variety of ways to list directories and their contents.

The directory used in these examples contains the two regular files (config.h and main.rb), the parent directory (..), and the directory itself (.).

See also: File.

Included Modules

Defined in:

dir.cr
dir/glob.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Iterable(String)

chunk(reuse = false, &block : T -> U) forall U chunk, chunk_while(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B chunk_while, cycle(n)
cycle cycle, each each, each_cons(count : Int, reuse = false) each_cons, each_cons_pair each_cons_pair, each_slice(count : Int, reuse = false) each_slice, each_with_index(offset = 0) each_with_index, each_with_object(obj) each_with_object, slice_after(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_after(pattern, reuse : Bool | Array(T) = false) slice_after, slice_before(reuse : Bool | Array(T) = false, &block : T -> B) forall B
slice_before(pattern, reuse : Bool | Array(T) = false) slice_before, slice_when(reuse : Bool | Array(T) = false, &block : T, T -> B) forall B slice_when

Instance methods inherited from module Enumerable(String)

accumulate(initial : U) : Array(U) forall U
accumulate : Array(T)
accumulate(initial : U, &block : U, T -> U) : Array(U) forall U
accumulate(&block : T, T -> T) : Array(T) accumulate, all?(& : T -> ) : Bool
all?(pattern) : Bool
all? : Bool all?, any?(& : T -> ) : Bool
any?(pattern) : Bool
any? : Bool any?, chunks(&block : T -> U) forall U chunks, compact_map(& : T -> _) compact_map, count(& : T -> ) : Int32
count(item) : Int32 count, cycle(n, & : T -> ) : Nil
cycle(& : T -> ) : Nil cycle, each(& : T -> ) each, each_cons(count : Int, reuse = false, &) each_cons, each_cons_pair(& : T, T -> ) : Nil each_cons_pair, each_slice(count : Int, reuse = false, &) each_slice, each_with_index(offset = 0, &) each_with_index, each_with_object(obj : U, & : T, U -> ) : U forall U each_with_object, empty? : Bool empty?, find(if_none = nil, & : T -> ) find, find!(& : T -> ) : T find!, first(&)
first(count : Int) : Array(T)
first : T first, first? : T | Nil first?, flat_map(& : T -> _) flat_map, group_by(& : T -> U) forall U group_by, in_groups_of(size : Int, filled_up_with : U = nil) forall U
in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &) forall U in_groups_of, in_slices_of(size : Int) : Array(Array(T)) in_slices_of, includes?(obj) : Bool includes?, index(& : T -> ) : Int32 | Nil
index(obj) : Int32 | Nil index, index!(& : T -> ) : Int32
index!(obj) : Int32 index!, index_by(& : T -> U) : Hash(U, T) forall U index_by, join(io : IO, separator = "") : Nil
join(separator, io : IO) : Nil
join(separator = "") : String
join(io : IO, separator = "", & : T, IO -> )
join(separator, io : IO, &)
join(separator = "", & : T -> ) join, map(& : T -> U) : Array(U) forall U map, map_with_index(offset = 0, & : T, Int32 -> U) : Array(U) forall U map_with_index, max(count : Int) : Array(T)
max : T max, max? : T | Nil max?, max_by(& : T -> U) : T forall U max_by, max_by?(& : T -> U) : T | Nil forall U max_by?, max_of(& : T -> U) : U forall U max_of, max_of?(& : T -> U) : U | Nil forall U max_of?, min(count : Int) : Array(T)
min : T min, min? : T | Nil min?, min_by(& : T -> U) : T forall U min_by, min_by?(& : T -> U) : T | Nil forall U min_by?, min_of(& : T -> U) : U forall U min_of, min_of?(& : T -> U) : U | Nil forall U min_of?, minmax : Tuple(T, T) minmax, minmax? : Tuple(T | Nil, T | Nil) minmax?, minmax_by(& : T -> U) : Tuple(T, T) forall U minmax_by, minmax_by?(& : T -> U) : Tuple(T, T) | Tuple(Nil, Nil) forall U minmax_by?, minmax_of(& : T -> U) : Tuple(U, U) forall U minmax_of, minmax_of?(& : T -> U) : Tuple(U, U) | Tuple(Nil, Nil) forall U minmax_of?, none?(& : T -> ) : Bool
none?(pattern) : Bool
none? : Bool none?, one?(& : T -> ) : Bool
one?(pattern) : Bool
one? : Bool one?, partition(& : T -> ) : Tuple(Array(T), Array(T))
partition(type : U.class) forall U partition, product(initial : Number)
product
product(initial : Number, & : T -> )
product(& : T -> _) product, reduce(memo, &)
reduce(&) reduce, reduce?(&) reduce?, reject(& : T -> )
reject(type : U.class) forall U
reject(pattern) : Array(T) reject, sample(n : Int, random : Random = Random::DEFAULT) : Array(T)
sample(random : Random = Random::DEFAULT) : T sample, select(& : T -> )
select(type : U.class) : Array(U) forall U
select(pattern) : Array(T) select, size : Int32 size, skip(count : Int) skip, skip_while(& : T -> ) : Array(T) skip_while, sum(initial)
sum
sum(initial, & : T -> )
sum(& : T -> ) sum, take_while(& : T -> ) : Array(T) take_while, tally(hash)
tally : Hash(T, Int32) tally, tally_by(hash, &)
tally_by(&block : T -> U) : Hash(U, Int32) forall U tally_by, to_a to_a, to_h
to_h(& : T -> Tuple(K, V)) forall K, V to_h, to_set : Set(T) to_set, zip(*others : Indexable | Iterable | Iterator, &)
zip(*others : Indexable | Iterable | Iterator) zip, zip?(*others : Indexable | Iterable | Iterator, &)
zip?(*others : Indexable | Iterable | Iterator) zip?

Class methods inherited from module Enumerable(String)

element_type(x) element_type

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

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

Constructor Detail

def self.new(path : Path | String) #

Returns a new directory object for the named directory.


[View source]
def self.open(path : Path | String) : self #

Alias for .new(path)


[View source]

Class Method Detail

def self.[](patterns : Enumerable, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.[](patterns : Enumerable, match_hidden, follow_symlinks = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.[](*patterns : Path | String, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.[](*patterns : Path | String, match_hidden, follow_symlinks = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.cd(path : Path | String) : String #

Changes the current working directory of the process to the given string.


[View source]
def self.cd(path : Path | String, &) #

Changes the current working directory of the process to the given string and invokes the block, restoring the original working directory when the block exits.


[View source]
def self.children(dirname : Path | String) : Array(String) #

See #children.


[View source]
def self.current : String #

Returns an absolute path to the current working directory.

The result is similar to the shell commands pwd (POSIX) and .cd (Windows).

On POSIX systems, it respects the environment value $PWD if available and if it points to the current working directory.


[View source]
def self.delete(path : Path | String) : Nil #

Removes the directory at path. Raises File::Error on failure.

On Windows, also raises File::Error if path points to a directory that is a reparse point, such as a symbolic link. Those directories can be deleted using File.delete instead.


[View source]
def self.delete?(path : Path | String) : Bool #

Removes the directory at path, or returns false if the directory does not exist. Raises File::Error on other kinds of failure.

On Windows, also raises File::Error if path points to a directory that is a reparse point, such as a symbolic link. Those directories can be deleted using File.delete? instead.


[View source]
def self.each(dirname : Path | String, & : String -> ) #

See #each.


[View source]
def self.each_child(dirname : Path | String, & : String -> ) #

See #each_child.


[View source]
def self.empty?(path : Path | String) : Bool #

Returns true if the directory at path is empty, otherwise returns false. Raises File::NotFoundError if the directory at path does not exist.

Dir.mkdir("bar")
Dir.empty?("bar") # => true
File.write("bar/a_file", "The content")
Dir.empty?("bar") # => false

[View source]
def self.entries(dirname : Path | String) : Array(String) #

See #entries.


[View source]
def self.exists?(path : Path | String) : Bool #

Returns true if the given path exists and is a directory

Dir.mkdir("testdir")
Dir.exists?("testdir") # => true

[View source]
def self.glob(patterns : Enumerable, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.glob(patterns : Enumerable, match_hidden, follow_symlinks = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.glob(*patterns : Path | String, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.glob(*patterns : Path | String, match_hidden, follow_symlinks = false) : Array(String) #

Returns an array of all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.glob(patterns : Enumerable, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false, &block : String -> _) #

Yields all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.glob(patterns : Enumerable, match_hidden, follow_symlinks = false, &block : String -> _) #

Yields all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.glob(*patterns : Path | String, match : File::MatchOptions = File::MatchOptions.glob_default, follow_symlinks : Bool = false, &block : String -> _) #

Yields all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.


[View source]
def self.glob(*patterns : Path | String, match_hidden, follow_symlinks = false, &block : String -> _) #

Yields all files that match against any of patterns.

The pattern syntax is similar to shell filename globbing, see File.match? for details.

NOTE Path separator in patterns needs to be always /. The returned file names use system-specific path separators.

For compatibility, a falsey match_hidden argument is equivalent to passing match: File::MatchOptions.glob_default, and a truthy match_hidden is equivalent to match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles.

DEPRECATED Use the overload with a match parameter instead


[View source]
def self.mkdir(path : Path | String, mode = 511) : Nil #

Creates a new directory at the given path. The linux-style permission mode can be specified, with a default of 777 (0o777).

NOTE mode is ignored on windows.

Dir.mkdir("testdir")
Dir.exists?("testdir") # => true

[View source]
def self.mkdir_p(path : Path | String, mode = 511) : Nil #

Creates a new directory at the given path, including any non-existing intermediate directories. The linux-style permission mode can be specified, with a default of 777 (0o777).


[View source]
def self.open(path : Path | String, & : self -> ) #

Opens a directory and yields it, closing it at the end of the block. Returns the value of the block.


[View source]
def self.tempdir : String #

Returns the tmp dir used for tempfile.

Dir.tempdir # => "/tmp"

[View source]

Instance Method Detail

def children : Array(String) #

Returns an array containing all of the filenames except for . and .. in the given directory.


[View source]
def close : Nil #

Closes the directory stream.


[View source]
def each(& : String -> ) : Nil #

Calls the block once for each entry in this directory, passing the filename of each entry as a parameter to the block.

Dir.mkdir("testdir")
File.write("testdir/config.h", "")

d = Dir.new("testdir")
d.each { |x| puts "Got #{x}" }

produces:

Got .
Got ..
Got config.h

[View source]
def each : Iterator(String) #
Description copied from module Iterable(String)

Must return an Iterator over the elements in this collection.


[View source]
def each_child(& : String -> ) : Nil #

Calls the block once for each entry except for . and .. in this directory, passing the filename of each entry as a parameter to the block.

Dir.mkdir("testdir")
File.write("testdir/config.h", "")

d = Dir.new("testdir")
d.each_child { |x| puts "Got #{x}" }

produces:

Got config.h

[View source]
def each_child : Iterator(String) #

Returns an iterator over of the all entries in this directory except for . and ...

See #each_child(&)

Dir.mkdir("test")
File.touch("test/foo")
File.touch("test/bar")

dir = Dir.new("test")
iter = d.each_child

iter.next # => "foo"
iter.next # => "bar"

[View source]
def entries : Array(String) #

Returns an array containing all of entries in the given directory including "." and "..".

Dir.mkdir("testdir")
File.touch("testdir/file_1")
File.touch("testdir/file_2")

Dir.new("testdir").entries # => ["..", "file_1", "file_2", "."]

[View source]
def info : File::Info #

This method is faster than .info and avoids race conditions if a Dir is already open on POSIX systems, but not necessarily on windows.


[View source]
def inspect(io : IO) : Nil #
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>

[View source]
def path : String #

Returns the path of this directory.

Dir.mkdir("testdir")
dir = Dir.new("testdir")
Dir.mkdir("testdir/extendeddir")
dir2 = Dir.new("testdir/extendeddir")

dir.path  # => "testdir"
dir2.path # => "testdir/extendeddir"

[View source]
def pretty_print(pp) #

[View source]
def read : String | Nil #

Reads the next entry from dir and returns it as a string. Returns nil at the end of the stream.

d = Dir.new("testdir")
array = [] of String
while file = d.read
  array << file
end
array.sort # => [".", "..", "config.h"]

[View source]
def rewind : self #

Repositions this directory to the first entry.


[View source]
def to_s(io : IO) : Nil #
Description copied from class Reference

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

[View source]