Class: Dir

Inherits:
Object show all
Includes:
Enumerable
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 collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #collect, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_slice, #each_with_index, #entries, #enum_cons, #enum_slice, #enum_with_index, #find, #find_all, #find_index, #first, #grep, #group_by, #include?, #inject, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #select, #sort, #sort_by, #take, #take_while, #to_a, #zip

Constructor Details

#new(string) ⇒ Dir

Returns a new directory object for the named directory.



389
390
391
 
# File 'dir.c', line 389

static VALUE
dir_initialize(dir, dirname)
VALUE dir, dirname;

Class Method Details

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

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

Overloads:



1681
1682
1683
1684
1685
1686
1687
1688
 
# File 'dir.c', line 1681

static VALUE
dir_s_aref(int argc, VALUE *argv, VALUE obj)
{
   if (argc == 1) {
return rb_push_glob(argv[0], 0);
   }
   return dir_globs(argc, argv, 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

Overloads:

  • .chdir([ string]) ⇒ 0

    Returns:

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

    Yields:

    Returns:



784
785
786
 
# File 'dir.c', line 784

static VALUE
dir_s_chdir(argc, argv, obj)
int argc;

.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.

Returns:

  • (0) 


874
875
876
 
# File 'dir.c', line 874

static VALUE
dir_s_chroot(dir, path)
VALUE dir, path;

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

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


936
937
938
 
# File 'dir.c', line 936

static VALUE
dir_s_rmdir(obj, dir)
VALUE obj, dir;

.entries(dirname) ⇒ Array

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

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

Returns:



1835
1836
1837
 
# File 'dir.c', line 1835

static VALUE
dir_entries(io, dirname)
VALUE io, dirname;

.foreach(dirname) {|filename| ... } ⇒ nil

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

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

produces:

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

Yields:

  • (filename)

Returns:

  • (nil) 


1812
1813
1814
 
# File 'dir.c', line 1812

static VALUE
dir_foreach(io, dirname)
VALUE io, dirname;

.getwd ⇒ String .pwd ⇒ String

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

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

Overloads:



835
836
837
 
# File 'dir.c', line 835

static VALUE
dir_s_getwd(dir)
VALUE dir;

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

Returns the filenames found by expanding pattern which is an Array of the patterns or the pattern String, either as an array or as parameters 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)

*

Matches any file. Can be restricted by other values in the glob. * will match all files; c* will match all files beginning with c; *c will match all files ending with c; and c will match all files that have c in them (including at the beginning or end). Equivalent to / .* /x in regexp.

**

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. Matching literals may be more than one character in length. More than two literals may be specified. Equivalent to pattern alternation in regexp.

<code></code>

Escapes the next metacharacter.

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"]

Overloads:

  • .glob(pattern, [flags]) ⇒ Array

    Returns:

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

    Yields:

    • (filename)

    Returns:

    • (nil) 


1750
1751
1752
 
# File 'dir.c', line 1750

static VALUE
dir_s_glob(argc, argv, obj)
int argc;

.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.

Returns:

  • (0) 


904
905
906
 
# File 'dir.c', line 904

static VALUE
dir_s_mkdir(argc, argv, obj)
int argc;

.open(string) ⇒ Dir .open(string) {|aDir| ... } ⇒ Object

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

Overloads:

  • .open(string) ⇒ Dir

    Returns:

  • .open(string) {|aDir| ... } ⇒ Object

    Yields:

    • (aDir)

    Returns:



428
429
430
 
# File 'dir.c', line 428

static VALUE
dir_s_open(klass, dirname)
VALUE klass, dirname;

.getwd ⇒ String .pwd ⇒ String

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

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

Overloads:



835
836
837
 
# File 'dir.c', line 835

static VALUE
dir_s_getwd(dir)
VALUE dir;

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

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


936
937
938
 
# File 'dir.c', line 936

static VALUE
dir_s_rmdir(obj, dir)
VALUE obj, dir;

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

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


936
937
938
 
# File 'dir.c', line 936

static VALUE
dir_s_rmdir(obj, dir)
VALUE obj, dir;

Instance Method Details

#close ⇒ nil

Closes the directory stream. Any further attempts to access dir will raise an IOError.

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

Returns:

  • (nil) 


691
692
693
 
# File 'dir.c', line 691

static VALUE
dir_close(dir)
VALUE dir;

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

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

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

produces:

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

Yields:

  • (filename)

Returns:



558
559
560
 
# File 'dir.c', line 558

static VALUE
dir_each(dir)
VALUE dir;

#inspect ⇒ String

Return a string describing this Dir object.

Returns:



470
471
472
 
# File 'dir.c', line 470

static VALUE
dir_inspect(dir)
VALUE dir;

#path ⇒ String?

Returns the path parameter passed to dir’s constructor.

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

Returns:



496
497
498
 
# File 'dir.c', line 496

static VALUE
dir_path(dir)
VALUE dir;

#pos ⇒ Integer #tell ⇒ Integer

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

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

Overloads:



588
589
590
 
# File 'dir.c', line 588

static VALUE
dir_tell(dir)
VALUE dir;

#pos(integer) ⇒ Integer

Synonym for Dir#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                   #=> ".."

Returns:



648
649
650
 
# File 'dir.c', line 648

static VALUE
dir_set_pos(dir, pos)
VALUE dir, pos;

#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"

Returns:



519
520
521
 
# File 'dir.c', line 519

static VALUE
dir_read(dir)
VALUE dir;

#rewind ⇒ Dir

Repositions dir to the first entry.

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

Returns:



667
668
669
 
# File 'dir.c', line 667

static VALUE
dir_rewind(dir)
VALUE dir;

#seek(integer) ⇒ Dir

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

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

Returns:



618
619
620
 
# File 'dir.c', line 618

static VALUE
dir_seek(dir, pos)
VALUE dir, pos;

#pos ⇒ Integer #tell ⇒ Integer

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

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

Overloads:



588
589
590
 
# File 'dir.c', line 588

static VALUE
dir_tell(dir)
VALUE dir;