Class

Dir

Inheritance
< Object
Included Modules
Enumerable

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

Methods

Class

Visibility Signature
public [] (...)
public chdir (...)
public chroot (p1)
public delete (p1)
public entries (p1)
public foreach (p1)
public getwd ()
public glob (...)
public mkdir (...)
public mktmpdir (prefix_suffix=nil, tmpdir=nil) {|path| ...}
public new (p1)
public open (p1)
public pwd ()
public rmdir (p1)
public tmpdir ()
public unlink (p1)

Instance

Visibility Signature
public close ()
public each ()
public inspect ()
public path ()
public pos ()
public pos= (p1)
public read ()
public rewind ()
public seek (p1)
public tell ()

Class Method Detail

Dir[ array ] => array
Dir[ string [, string ...] ] => array

Equivalent to calling Dir.glob(array,0) and href="Dir.html#M002281">Dir.glob(,0).

Dir.chdir( [ string] ) => 0
Dir.chdir( [ string] ) {| path | block } => anObject

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

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

Dir.delete( string ) => 0
Dir.rmdir( string ) => 0
Dir.unlink( string ) => 0

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

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

Dir.foreach( dirname ) {| filename | block } => 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

Dir.getwd => string
Dir.pwd => string

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

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

Dir.glob( pattern, [flags] ) => array
Dir.glob( pattern, [flags] ) {| filename | block } => 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"]

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

mktmpdir(prefix_suffix=nil, tmpdir=nil) {|path| ...}

Dir.mktmpdir creates a temporary directory.

The directory is created with 0700 permission.

The prefix and suffix of the name of the directory is specified by the optional first argument, prefix_suffix.

  • If it is not specified or nil, "d" is used as the prefix and no suffix is used.
  • If it is a string, it is used as the prefix and no suffix is used.
  • If it is an array, first element is used as the prefix and second element is used as a suffix.
 Dir.mktmpdir {|dir| dir is ".../d..." }
 Dir.mktmpdir("foo") {|dir| dir is ".../foo..." }
 Dir.mktmpdir(["foo", "bar"]) {|dir| dir is ".../foo...bar" }

The directory is created under Dir.tmpdir or the optional second argument tmpdir if non-nil value is given.

 Dir.mktmpdir {|dir| dir is "#{Dir.tmpdir}/d..." }
 Dir.mktmpdir(nil, "/var/tmp") {|dir| dir is "/var/tmp/d..." }

If a block is given, it is yielded with the path of the directory. The directory and its contents are removed using FileUtils.remove_entry_secure before Dir.mktmpdir returns. The value of the block is returned.

 Dir.mktmpdir {|dir|
   # use the directory...
   open("#{dir}/foo", "w") { ... }
 }

If a block is not given, The path of the directory is returned. In this case, Dir.mktmpdir doesn‘t remove the directory.

 dir = Dir.mktmpdir
 begin
   # use the directory...
   open("#{dir}/foo", "w") { ... }
 ensure
   # remove the directory.
   FileUtils.remove_entry_secure dir
 end

Dir.new( string ) → aDir

Returns a new directory object for the named directory.

Dir.open( string ) => aDir
Dir.open( string ) {| aDir | block } => anObject

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.

Dir.getwd => string
Dir.pwd => string

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

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

Dir.delete( string ) => 0
Dir.rmdir( string ) => 0
Dir.unlink( string ) => 0

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

tmpdir()

Returns the operating system‘s temporary file path.

Dir.delete( string ) => 0
Dir.rmdir( string ) => 0
Dir.unlink( string ) => 0

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

Instance Method Detail

dir.close => nil

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

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

dir.each { |filename| block } => 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

dir.inspect => string

Return a string describing this Dir object.

dir.path => string or nil

Returns the path parameter passed to dir‘s constructor.

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

dir.pos => integer
dir.tell => integer

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

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

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

dir.read => string or 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")
   d.read   #=> "."
   d.read   #=> ".."
   d.read   #=> "config.h"

dir.rewind => dir

Repositions dir to the first entry.

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

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

dir.pos => integer
dir.tell => integer

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

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