123456789_123456789_123456789_123456789_123456789_

Class: Dir

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::Enumerable
Inherits: Object
Defined in: dir.c

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. See also ::File.

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

Class Method Summary

Instance Attribute Summary

::Enumerable - Included

#all?

Passes each element of the collection to the given block.
#any?

Passes each element of the collection to the given block.
#none?

Passes each element of the collection to the given block.
#one?

Passes each element of the collection to the given block.

Instance Method Summary

::Enumerable - Included

#chunk

Enumerates over the items, chunking them together based on the return value of the block.
#chunk_while

Creates an enumerator for each chunked elements.
#collect

Alias for Enumerable#map.
#collect_concat

Alias for Enumerable#flat_map.
#count

Returns the number of items in enum through enumeration.
#cycle

Calls block for each element of enum repeatedly n times or forever if none or nil is given.
#detect

Alias for Enumerable#find.
#drop

Drops first n elements from enum, and returns rest elements in an array.
#drop_while

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.
#each_cons

Iterates the given block for each array of consecutive <n> elements.
#each_entry

Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.
#each_slice

Iterates the given block for each slice of <n> elements.
#each_with_index

Calls block with two arguments, the item and its index, for each item in enum.
#each_with_object

Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
#entries

Alias for Enumerable#to_a.
#find

Passes each entry in enum to block.
#find_all

Alias for Enumerable#select.
#find_index

Compares each entry in enum with value or passes to block.
#first

Returns the first element, or the first n elements, of the enumerable.
#flat_map

Returns a new array with the concatenated results of running block once for every element in enum.
#grep

Returns an array of every element in enum for which Pattern === element.
#grep_v

Inverted version of Enumerable#grep.
#group_by

Groups the collection by result of the block.
#include?

Alias for Enumerable#member?.
#inject

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
#lazy

Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis.
#map

Returns a new array with the results of running block once for every element in enum.
#max

Returns the object in enum with the maximum value.
#max_by

Returns the object in enum that gives the maximum value from the given block.
#member?

Returns true if any member of enum equals obj.
#min

Returns the object in enum with the minimum value.
#min_by

Returns the object in enum that gives the minimum value from the given block.
#minmax

Returns a two element array which contains the minimum and the maximum value in the enumerable.
#minmax_by

Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
#partition

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
#reduce

Alias for Enumerable#inject.
#reject

Returns an array for all elements of enum for which the given block returns false.
#reverse_each

Builds a temporary array and traverses that array in reverse order.
#select

Returns an array containing all elements of enum for which the given block returns a true value.
#slice_after

Creates an enumerator for each chunked elements.
#slice_before

Creates an enumerator for each chunked elements.
#slice_when

Creates an enumerator for each chunked elements.
#sort

Returns an array containing the items in enum sorted.
#sort_by

Sorts enum using a set of keys generated by mapping the values in enum through the given block.
#sum

Returns the sum of elements in an ::Enumerable.
#take

Returns first n elements from enum.
#take_while

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.
#to_a

Returns an array containing the items in enum.
#to_h

Returns the result of interpreting enum as a list of [key, value] pairs.
#uniq

Returns a new array by removing duplicate values in self.
#zip

Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new(string) ⇒ Dir .new(string, encoding: enc) ⇒ Dir

Returns a new directory object for the named directory.

The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

Class Method Details

.[](string [, string ...] ) ⇒ Array

Equivalent to calling Dir.glob([string,...],0).

.chdir([ string]) ⇒ 0 .chdir([ string]) {|path| ... } ⇒ Object

Changes the current working directory of the process to the given string. When called without an argument, changes the directory to the value of the environment variable HOME, or LOGDIR. ::SystemCallError (probably Errno::ENOENT) if the target directory does not exist.

If a block is given, it is passed the name of the new current directory, and the block is executed with that as the current directory. The original working directory is restored when the block exits. The return value of chdir is the value of the block. chdir blocks can be nested, but in a multi-threaded program an error will be raised if a thread attempts to open a chdir block while another thread has one open.

Dir.chdir("/var/spool/mail")
puts Dir.pwd
Dir.chdir("/tmp") do
  puts Dir.pwd
  Dir.chdir("/usr") do
    puts Dir.pwd
  end
  puts Dir.pwd
end
puts Dir.pwd

produces:

/var/spool/mail
/tmp
/usr
/tmp
/var/spool/mail

.chroot(string) ⇒ 0

Changes this process's idea of the file system root. Only a privileged process may make this call. Not available on all platforms. On Unix systems, see chroot(2) for more information.

.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0

Alias for .rmdir.

.empty?(path_name) ⇒ Boolean

Returns true if the named file is an empty directory, false if it is not a directory or non-empty.

.entries(dirname) ⇒ Array .entries(dirname, encoding: enc) ⇒ Array

Returns an array containing all of the filenames in the given directory. Will raise a ::SystemCallError if the named directory doesn't exist.

The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

Dir.entries("testdir")   #=> [".", "..", "config.h", "main.rb"]

.exist?(file_name) ⇒ Boolean

Returns true if the named file is a directory, false otherwise.

.exists?(file_name) ⇒ Boolean

Deprecated method. Don't use.

.foreach(dirname) {|filename| ... } ⇒ nil .foreach(dirname, encoding: enc) {|filename| ... } ⇒ nil .foreach(dirname) ⇒ Enumerator .foreach(dirname, encoding: enc) ⇒ Enumerator

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

If no block is given, an enumerator is returned instead.

Dir.foreach("testdir") {|x| puts "Got #{x}" }

produces:

Got .
Got ..
Got config.h
Got main.rb

.getwd ⇒ String .pwd ⇒ String

Alias for .pwd.

.glob(pattern, [flags]) ⇒ matches .glob(pattern, [flags]) {|filename| ... } ⇒ nil

Expands pattern, which is an ::Array of patterns or a pattern ::String, and returns the results as matches or as arguments given to the block.

Note that this pattern is not a regexp, it's closer to a shell glob. See File.fnmatch for the meaning of the flags parameter. Note that case sensitivity depends on your system (so File::FNM_CASEFOLD is ignored), as does the order in which the results are returned.

*

Matches any file. Can be restricted by other values in the glob. Equivalent to / .* /x in regexp.

*

Matches all files

c*

Matches all files beginning with c

*c

Matches all files ending with c

*c*

Match all files that have c in them (including at the beginning or end).

Note, this will not match Unix-like hidden files (dotfiles). In order to include those in the match results, you must use the File::FNM_DOTMATCH flag or something like "{*,.*}".

**

Matches directories recursively.

?

Matches any one character. Equivalent to /.{1}/ in regexp.

[set]

Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

{p,q}

Matches either literal p or literal q. Equivalent to pattern alternation in regexp.

Matching literals may be more than one character in length. More than two literals may be specified.

\

Escapes the next metacharacter.

Note that this means you cannot use backslash on windows as part of a glob, i.e. Dir["c:\foo*"] will not work, use Dir["c:/foo*"] instead.

Examples:

Dir["config.?"]                     #=> ["config.h"]
Dir.glob("config.?")                #=> ["config.h"]
Dir.glob("*.[a-z][a-z]")            #=> ["main.rb"]
Dir.glob("*.[^r]*")                 #=> ["config.h"]
Dir.glob("*.{rb,h}")                #=> ["main.rb", "config.h"]
Dir.glob("*")                       #=> ["config.h", "main.rb"]
Dir.glob("*", File::FNM_DOTMATCH)   #=> [".", "..", "config.h", "main.rb"]

rbfiles = File.join("**", "*.rb")
Dir.glob(rbfiles)                   #=> ["main.rb",
                                    #    "lib/song.rb",
                                    #    "lib/song/karaoke.rb"]
libdirs = File.join("**", "lib")
Dir.glob(libdirs)                   #=> ["lib"]

librbfiles = File.join("**", "lib", "**", "*.rb")
Dir.glob(librbfiles)                #=> ["lib/song.rb",
                                    #    "lib/song/karaoke.rb"]

librbfiles = File.join("**", "lib", "*.rb")
Dir.glob(librbfiles)                #=> ["lib/song.rb"]

.home ⇒ "/home/me" .home("root") ⇒ "/root"

Returns the home directory of the current user or the named user if given.

.mkdir(string [, integer] ) ⇒ 0

Makes a new directory named by string, with permissions specified by the optional parameter anInteger. The permissions may be modified by the value of File.umask, and are ignored on NT. Raises a ::SystemCallError if the directory cannot be created. See also the discussion of permissions in the class documentation for ::File.

Dir.mkdir(File.join(Dir.home, ".foo"), 0700) #=> 0

.open(string) ⇒ Dir .open(string, encoding: enc) ⇒ Dir .open(string) {|aDir| ... } ⇒ Object .open(string, encoding: enc) {|aDir| ... } ⇒ Object

The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

With no block, open is a synonym for .new. If a block is present, it is passed aDir as a parameter. The directory is closed at the end of the block, and open returns the value of the block.

.getwd ⇒ String .pwd ⇒ String
Also known as: .getwd

Returns the path to the current working directory of this process as a string.

Dir.chdir("/tmp")   #=> 0
Dir.getwd           #=> "/tmp"
Dir.pwd             #=> "/tmp"

.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0
Also known as: .delete, .unlink

Deletes the named directory. Raises a subclass of ::SystemCallError if the directory isn't empty.

Instance Attribute Details

#pos ⇒ Integer (rw) #tell ⇒ Integer
Also known as: #tell

Returns the current position in dir. See also #seek.

d = Dir.new("testdir")
d.tell   #=> 0
d.read   #=> "."
d.tell   #=> 12

#pos=(integer) ⇒ Integer (rw)

Synonym for #seek, but returns the position parameter.

d = Dir.new("testdir")   #=> #<Dir:0x401b3c40>
d.read                   #=> "."
i = d.pos                #=> 12
d.read                   #=> ".."
d.pos = i                #=> 12
d.read                   #=> ".."

#pos ⇒ Integer (readonly) #tell ⇒ Integer

Alias for #pos.

Instance Method Details

#close ⇒ nil

Closes the directory stream. Calling this method on closed Dir object is ignored since Ruby 2.3.

d = Dir.new("testdir")
d.close   #=> nil

#each {|filename| ... } ⇒ Dir #each ⇒ Enumerator

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

If no block is given, an enumerator is returned instead.

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

produces:

Got .
Got ..
Got config.h
Got main.rb

#fileno ⇒ Integer

Returns the file descriptor used in dir.

d = Dir.new("..")
d.fileno   #=> 8

This method uses dirfd() function defined by POSIX 2008. ::NotImplementedError is raised on other platforms, such as Windows, which doesn't provide the function.

#inspect ⇒ String

Return a string describing this Dir object.

#path ⇒ String? #to_path ⇒ String?
Also known as: #to_path

Returns the path parameter passed to dir's constructor.

d = Dir.new("..")
d.path   #=> ".."

#read ⇒ String?

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

d = Dir.new("testdir")
d.read   #=> "."
d.read   #=> ".."
d.read   #=> "config.h"

#rewind ⇒ Dir

Repositions dir to the first entry.

d = Dir.new("testdir")
d.read     #=> "."
d.rewind   #=> #<Dir:0x401b3fb0>
d.read     #=> "."

#seek(integer) ⇒ Dir

Seeks to a particular location in dir. integer must be a value returned by #tell.

d = Dir.new("testdir")   #=> #<Dir:0x401b3c40>
d.read                   #=> "."
i = d.tell               #=> 12
d.read                   #=> ".."
d.seek(i)                #=> #<Dir:0x401b3c40>
d.read                   #=> ".."

#path ⇒ String? #to_path ⇒ String?

Alias for #path.