Returns an array of the entry names in the directory at dirpath
; sets the given encoding onto each returned entry name:
Dir.entries('/example') # => ["config.h", "lib", "main.rb", "..", "."] Dir.entries('/example').first.encoding # => #<Encoding:UTF-8> Dir.entries('/example', encoding: 'US-ASCII').first.encoding # => #<Encoding:US-ASCII>
See String Encoding.
Raises an exception if the directory does not exist.
Returns the file descriptor used in dir.
d = Dir.new('..') d.fileno # => 8
This method uses the dirfd() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError
).
Returns the dirpath
string that was used to create self
(or nil
if created by method Dir.for_fd
):
Dir.new('example').path # => "example"
Reads and returns the next entry name from self
; returns nil
if at end-of-stream; see Dir As Stream-Like:
dir = Dir.new('example') dir.read # => "." dir.read # => ".." dir.read # => "config.h"
Sets the position in self
to zero; see Dir As Stream-Like:
dir = Dir.new('example') dir.read # => "." dir.read # => ".." dir.pos # => 2 dir.rewind # => #<Dir:example> dir.pos # => 0
Returns the current position of self
; see Dir As Stream-Like:
dir = Dir.new('example') dir.tell # => 0 dir.read # => "." dir.tell # => 1
Sets the position in self
and returns self
. The value of position
should have been returned from an earlier call to tell
; if not, the return values from subsequent calls to read
are unspecified.
See Dir As Stream-Like.
Examples:
dir = Dir.new('example') dir.pos # => 0 dir.seek(3) # => #<Dir:example> dir.pos # => 3 dir.seek(30) # => #<Dir:example> dir.pos # => 5
Returns the current position of self
; see Dir As Stream-Like:
dir = Dir.new('example') dir.tell # => 0 dir.read # => "." dir.tell # => 1
Sets the position in self
and returns position
. The value of position
should have been returned from an earlier call to tell
; if not, the return values from subsequent calls to read
are unspecified.
See Dir As Stream-Like.
Examples:
dir = Dir.new('example') dir.pos # => 0 dir.pos = 3 # => 3 dir.pos # => 3 dir.pos = 30 # => 30 dir.pos # => 5
Closes the stream in self
, if it is open, and returns nil
; ignored if self
is already closed:
dir = Dir.new('example') dir.read # => "." dir.close # => nil dir.close # => nil dir.read # Raises IOError.
Returns the path to the current working directory:
Dir.chdir("/tmp") # => 0 Dir.pwd # => "/tmp"
Returns the path to the current working directory:
Dir.chdir("/tmp") # => 0 Dir.pwd # => "/tmp"
Removes the directory at dirpath
from the underlying file system:
Dir.rmdir('foo') # => 0
Raises an exception if the directory is not empty.
Removes the directory at dirpath
from the underlying file system:
Dir.rmdir('foo') # => 0
Raises an exception if the directory is not empty.
Returns the home directory path of the user specified with user_name
if it is not nil
, or the current login user:
Dir.home # => "/home/me" Dir.home('root') # => "/root"
Raises ArgumentError
if user_name
is not a user name.
Returns whether dirpath
is a directory in the underlying file system:
Dir.exist?('/example') # => true Dir.exist?('/nosuch') # => false Dir.exist?('/example/main.rb') # => false
Same as File.directory?
.
Returns whether dirpath
specifies an empty directory:
dirpath = '/tmp/foo' Dir.mkdir(dirpath) Dir.empty?(dirpath) # => true Dir.empty?('/example') # => false Dir.empty?('/example/main.rb') # => false
Raises an exception if dirpath
does not specify a directory or file in the underlying file system.
Creates a new Dir object dir for the directory at dirpath
.
With no block, the method equivalent to Dir.new(dirpath, encoding)
:
Dir.open('.') # => #<Dir:.>
With a block given, the block is called with the created dir; on block exit dir is closed and the block’s value is returned:
Dir.open('.') {|dir| dir.inspect } # => "#<Dir:.>"
The value given with optional keyword argument encoding
specifies the encoding for the directory entry names; if nil
(the default), the file system’s encoding is used:
Dir.open('.').read.encoding # => #<Encoding:UTF-8> Dir.open('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII>
Returns a new Dir object for the directory at dirpath
:
Dir.new('.') # => #<Dir:.>
The value given with optional keyword argument encoding
specifies the encoding for the directory entry names; if nil
(the default), the file system’s encoding is used:
Dir.new('.').read.encoding # => #<Encoding:UTF-8> Dir.new('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII>
Calls Dir.glob
with argument patterns
and the values of keyword arguments base
and sort
; returns the array of selected entry names.
Forms an array entry_names of the entry names selected by the arguments.
Argument patterns
is a string pattern or an array of string patterns; note that these are not regexps; see below.
Notes for the following examples:
'*'
is the pattern that matches any entry name except those that begin with '.'
.
We use method Array#take
to shorten returned arrays that otherwise would be very large.
With no block, returns array entry_names; example (using the simple file tree):
Dir.glob('*') # => ["config.h", "lib", "main.rb"]
With a block, calls the block with each of the entry_names and returns nil
:
Dir.glob('*') {|entry_name| puts entry_name } # => nil
Output:
config.h lib main.rb
If optional keyword argument flags
is given, the value modifies the matching; see below.
If optional keyword argument base
is given, its value specifies the base directory. Each pattern string specifies entries relative to the base directory; the default is '.'
. The base directory is not prepended to the entry names in the result:
Dir.glob(pattern, base: 'lib').take(5) # => ["abbrev.gemspec", "abbrev.rb", "base64.gemspec", "base64.rb", "benchmark.gemspec"] Dir.glob(pattern, base: 'lib/irb').take(5) # => ["cmd", "color.rb", "color_printer.rb", "completion.rb", "context.rb"]
If optional keyword sort
is given, its value specifies whether the array is to be sorted; the default is true
. Passing value false
with that keyword disables sorting (though the underlying file system may already have sorted the array).
Patterns
Each pattern string is expanded according to certain metacharacters; examples below use the Ruby file tree:
'*'
: Matches any substring in an entry name, similar in meaning to regexp /.*/mx
; may be restricted by other values in the pattern strings:
'*'
matches all entry names:
Dir.glob('*').take(3) # => ["BSDL", "CONTRIBUTING.md", "COPYING"]
'c*'
matches entry names beginning with 'c'
:
Dir.glob('c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"]
'*c'
matches entry names ending with 'c'
:
Dir.glob('*c').take(3) # => ["addr2line.c", "array.c", "ast.c"]
'*c*'
matches entry names that contain 'c'
, even at the beginning or end:
Dir.glob('*c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"]
Does not match Unix-like hidden entry names (“dot files”). To include those in the matched entry names, use flag IO::FNM_DOTMATCH or something like '{*,.*}'
.
'**'
: Matches entry names recursively if followed by the slash character '/'
:
Dir.glob('**/').take(3) # => ["basictest/", "benchmark/", "benchmark/gc/"]
If the string pattern contains other characters or is not followed by a slash character, it is equivalent to '*'
.
'?'
Matches any single character; similar in meaning to regexp /./
:
Dir.glob('io.?') # => ["io.c"]
'[set]'
: Matches any one character in the string set; behaves like a Regexp character class, including set negation ('[^a-z]'
):
Dir.glob('*.[a-z][a-z]').take(3) # => ["CONTRIBUTING.md", "COPYING.ja", "KNOWNBUGS.rb"]
'{abc,xyz}'
: Matches either string abc or string xyz; behaves like Regexp alternation:
Dir.glob('{LEGAL,BSDL}') # => ["LEGAL", "BSDL"]
More than two alternatives may be given.
\
: Escapes the following metacharacter.
Note that on Windows, the backslash character may not be used in a string pattern: Dir['c:\foo*']
will not work, use Dir['c:/foo*']
instead.
More examples (using the simple file tree):
# We're in the example directory. File.basename(Dir.pwd) # => "example" 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", "lib", "main.rb"] Dir.glob('*', File::FNM_DOTMATCH) # => [".", "config.h", "lib", "main.rb"] Dir.glob(["*.rb", "*.h"]) # => ["main.rb", "config.h"] Dir.glob('**/*.rb') => ["lib/song/karaoke.rb", "lib/song.rb", "main.rb"] Dir.glob('**/*.rb', base: 'lib') # => ["song/karaoke.rb", "song.rb"] Dir.glob('**/lib') # => ["lib"] Dir.glob('**/lib/**/*.rb') # => ["lib/song/karaoke.rb", "lib/song.rb"] Dir.glob('**/lib/*.rb') # => ["lib/song.rb"]
Flags
If optional keyword argument flags
is given (the default is zero – no flags), its value should be the bitwise OR of one or more of the constants defined in module File::Constants
.
Example:
flags = File::FNM_EXTGLOB | File::FNM_DOTMATCH
Specifying flags can extend, restrict, or otherwise modify the matching.
The flags for this method (other constants in File::Constants
do not apply):
File::FNM_DOTMATCH: specifies that entry names beginning with '.'
should be considered for matching:
Dir.glob('*').take(5) # => ["BSDL", "CONTRIBUTING.md", "COPYING", "COPYING.ja", "GPL"] Dir.glob('*', flags: File::FNM_DOTMATCH).take(5) # => [".", ".appveyor.yml", ".cirrus.yml", ".dir-locals.el", ".document"]
File::FNM_EXTGLOB: enables the pattern extension '{a,b}'
, which matches pattern a and pattern b; behaves like a regexp union (e.g., '(?:a|b)'
):
pattern = '{LEGAL,BSDL}' Dir.glob(pattern) # => ["LEGAL", "BSDL"]
File::FNM_NOESCAPE: specifies that escaping with the backslash character '\'
is disabled; the character is not an escape character.
File::FNM_PATHNAME: specifies that metacharacters '*'
and '?'
do not match directory separators.
File::FNM_SHORTNAME: specifies that patterns may match short names if they exist; Windows only.
Return the target directory where the gem is to be installed. This directory is not guaranteed to be populated.