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. 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
-
.[](string[, string ...)) ⇒ Array
Equivalent to calling
Dir.glob([
string,…],0)
. -
.chdir(*args) ⇒ Object
Changes the current working directory of the process to the given string.
-
.chroot(string) ⇒ 0
Changes this process’s idea of the file system root.
-
.delete(dir) ⇒ Object
Deletes the named directory.
-
.entries(*args) ⇒ Object
Returns an array containing all of the filenames in the given directory.
-
.exist?(file_name) ⇒ Boolean
Returns
true
if the named file is a directory,false
otherwise. -
.exists?(file_name) ⇒ Boolean
Deprecated method.
-
.foreach(*args) ⇒ Object
Calls the block once for each entry in the named directory, passing the filename of each entry as a parameter to the block.
-
.getwd ⇒ Object
Returns the path to the current working directory of this process as a string.
-
.glob(*args) ⇒ Object
Expands
pattern
, which is an Array of patterns or a pattern String, and returns the results asmatches
or as arguments given to the block. -
.home(*args) ⇒ Object
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.
-
.open(*args) ⇒ Object
The optional enc argument specifies the encoding of the directory.
-
.pwd ⇒ Object
Returns the path to the current working directory of this process as a string.
-
.rmdir(dir) ⇒ Object
Deletes the named directory.
-
.unlink(dir) ⇒ Object
Deletes the named directory.
Instance Method Summary collapse
-
#close ⇒ nil
Closes the directory stream.
-
#each ⇒ Object
Calls the block once for each entry in this directory, passing the filename of each entry as a parameter to the block.
-
#fileno ⇒ Integer
Returns the file descriptor used in dir.
-
#initialize(*args) ⇒ Object
constructor
Returns a new directory object for the named directory.
-
#inspect ⇒ String
Return a string describing this Dir object.
-
#path ⇒ Object
Returns the path parameter passed to dir’s constructor.
-
#pos ⇒ Object
Returns the current position in dir.
-
#pos=(integer) ⇒ Integer
Synonym for
Dir#seek
, but returns the position parameter. -
#read ⇒ String?
Reads the next entry from dir and returns it as a string.
-
#rewind ⇒ Dir
Repositions dir to the first entry.
-
#seek(integer) ⇒ Dir
Seeks to a particular location in dir.
-
#tell ⇒ Object
Returns the current position in dir.
-
#to_path ⇒ Object
Returns the path parameter passed to dir’s constructor.
Methods included from Enumerable
#all?, #any?, #chunk, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #find, #find_all, #find_index, #first, #flat_map, #grep, #group_by, #include?, #inject, #lazy, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #select, #slice_after, #slice_before, #slice_when, #sort, #sort_by, #take, #take_while, #to_a, #to_h, #zip
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.
448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 |
# File 'dir.c', line 448
static VALUE
dir_initialize(int argc, VALUE *argv, VALUE dir)
{
struct dir_data *dp;
rb_encoding *fsenc;
VALUE dirname, opt, orig;
static ID keyword_ids[1];
const char *path;
if (!keyword_ids[0]) {
keyword_ids[0] = rb_intern("encoding");
}
fsenc = rb_filesystem_encoding();
rb_scan_args(argc, argv, "1:", &dirname, &opt);
if (!NIL_P(opt)) {
VALUE enc;
rb_get_kwargs(opt, keyword_ids, 0, 1, &enc);
if (enc != Qundef && !NIL_P(enc)) {
fsenc = rb_to_encoding(enc);
}
}
GlobPathValue(dirname, FALSE);
orig = rb_str_dup_frozen(dirname);
dirname = rb_str_encode_ospath(dirname);
dirname = rb_str_dup_frozen(dirname);
TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dp);
if (dp->dir) closedir(dp->dir);
dp->dir = NULL;
dp->path = Qnil;
dp->enc = fsenc;
path = RSTRING_PTR(dirname);
dp->dir = opendir(path);
if (dp->dir == NULL) {
if (errno == EMFILE || errno == ENFILE) {
rb_gc();
dp->dir = opendir(path);
}
#ifdef HAVE_GETATTRLIST
else if (errno == EIO) {
u_int32_t attrbuf[1];
struct attrlist al = {ATTR_BIT_MAP_COUNT, 0};
if (getattrlist(path, &al, attrbuf, sizeof(attrbuf), FSOPT_NOFOLLOW) == 0) {
dp->dir = opendir(path);
}
}
#endif
if (dp->dir == NULL) {
RB_GC_GUARD(dirname);
rb_sys_fail_path(orig);
}
}
dp->path = orig;
return dir;
}
|
Class Method Details
.[](string[, string ...)) ⇒ Array
Equivalent to calling Dir.glob([
string,…],0)
.
2067 2068 2069 2070 2071 2072 2073 2074 |
# File 'dir.c', line 2067
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
918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 |
# File 'dir.c', line 918
static VALUE
dir_s_chdir(int argc, VALUE *argv, VALUE obj)
{
VALUE path = Qnil;
rb_secure(2);
if (rb_scan_args(argc, argv, "01", &path) == 1) {
FilePathValue(path);
path = rb_str_encode_ospath(path);
}
else {
const char *dist = getenv("HOME");
if (!dist) {
dist = getenv("LOGDIR");
if (!dist) rb_raise(rb_eArgError, "HOME/LOGDIR not set");
}
path = rb_str_new2(dist);
}
if (chdir_blocking > 0) {
if (!rb_block_given_p() || rb_thread_current() != chdir_thread)
rb_warn("conflicting chdir during another chdir block");
}
if (rb_block_given_p()) {
struct chdir_data args;
args.old_path = rb_str_encode_ospath(rb_dir_getwd());
args.new_path = path;
args.done = FALSE;
return rb_ensure(chdir_yield, (VALUE)&args, chdir_restore, (VALUE)&args);
}
dir_chdir(path);
return INT2FIX(0);
}
|
.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.
1017 1018 1019 1020 1021 1022 1023 1024 1025 |
# File 'dir.c', line 1017
static VALUE
dir_s_chroot(VALUE dir, VALUE path)
{
check_dirname(&path);
if (chroot(RSTRING_PTR(path)) == -1)
rb_sys_fail_path(path);
return INT2FIX(0);
}
|
.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0
Deletes the named directory. Raises a subclass of SystemCallError
if the directory isn’t empty.
1074 1075 1076 1077 1078 1079 1080 1081 1082 |
# File 'dir.c', line 1074
static VALUE
dir_s_rmdir(VALUE obj, VALUE dir)
{
check_dirname(&dir);
if (rmdir(RSTRING_PTR(dir)) < 0)
rb_sys_fail_path(dir);
return INT2FIX(0);
}
|
.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"]
2237 2238 2239 2240 2241 2242 2243 2244 |
# File 'dir.c', line 2237
static VALUE
dir_entries(int argc, VALUE *argv, VALUE io)
{
VALUE dir;
dir = dir_open_dir(argc, argv);
return rb_ensure(rb_Array, dir, dir_close, dir);
}
|
.exist?(file_name) ⇒ Boolean
Returns true
if the named file is a directory, false
otherwise.
2437 2438 2439 2440 |
# File 'dir.c', line 2437 VALUE rb_file_directory_p(void) { } |
.exists?(file_name) ⇒ Boolean
Deprecated method. Don’t use.
2449 2450 2451 2452 2453 2454 |
# File 'dir.c', line 2449
static VALUE
rb_dir_exists_p(VALUE obj, VALUE fname)
{
rb_warning("Dir.exists? is a deprecated name, use Dir.exist? instead");
return rb_file_directory_p(obj, fname);
}
|
.foreach(dirname) {|filename| ... } ⇒ nil .foreach(dirname, encoding: enc) {|filename| ... } ⇒ nil .foreach(dirname) ⇒ Object .foreach(dirname, encoding: enc) ⇒ Object
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
2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 |
# File 'dir.c', line 2211
static VALUE
dir_foreach(int argc, VALUE *argv, VALUE io)
{
VALUE dir;
RETURN_ENUMERATOR(io, argc, argv);
dir = dir_open_dir(argc, argv);
rb_ensure(dir_each, dir, dir_close, dir);
return Qnil;
}
|
.getwd ⇒ String .pwd ⇒ String
981 982 983 984 985 |
# File 'dir.c', line 981
static VALUE
dir_s_getwd(VALUE dir)
{
return rb_dir_getwd();
}
|
.glob(pattern, [flags]) ⇒ Object .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 literalq
. 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, useDir["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"]
2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 |
# File 'dir.c', line 2151
static VALUE
dir_s_glob(int argc, VALUE *argv, VALUE obj)
{
VALUE str, rflags, ary;
int flags;
if (rb_scan_args(argc, argv, "11", &str, &rflags) == 2)
flags = NUM2INT(rflags);
else
flags = 0;
ary = rb_check_array_type(str);
if (NIL_P(ary)) {
ary = rb_push_glob(str, flags);
}
else {
VALUE v = ary;
ary = dir_globs(RARRAY_LEN(v), RARRAY_CONST_PTR(v), flags);
RB_GC_GUARD(v);
}
if (rb_block_given_p()) {
rb_ary_each(ary);
return Qnil;
}
return ary;
}
|
.home ⇒ Object .home("root") ⇒ Object
Returns the home directory of the current user or the named user if given.
2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 |
# File 'dir.c', line 2408
static VALUE
dir_s_home(int argc, VALUE *argv, VALUE obj)
{
VALUE user;
const char *u = 0;
rb_check_arity(argc, 0, 1);
user = (argc > 0) ? argv[0] : Qnil;
if (!NIL_P(user)) {
SafeStringValue(user);
rb_must_asciicompat(user);
u = StringValueCStr(user);
if (*u) {
return rb_home_dir_of(user, rb_str_new(0, 0));
}
}
return rb_default_home_dir(rb_str_new(0, 0));
}
|
.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
1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 |
# File 'dir.c', line 1045
static VALUE
dir_s_mkdir(int argc, VALUE *argv, VALUE obj)
{
VALUE path, vmode;
int mode;
if (rb_scan_args(argc, argv, "11", &path, &vmode) == 2) {
mode = NUM2INT(vmode);
}
else {
mode = 0777;
}
check_dirname(&path);
if (mkdir(RSTRING_PTR(path), mode) == -1)
rb_sys_fail_path(path);
return INT2FIX(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 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.
525 526 527 528 529 530 531 532 533 534 535 536 537 |
# File 'dir.c', line 525
static VALUE
dir_s_open(int argc, VALUE *argv, VALUE klass)
{
struct dir_data *dp;
VALUE dir = TypedData_Make_Struct(klass, struct dir_data, &dir_data_type, dp);
dir_initialize(argc, argv, dir);
if (rb_block_given_p()) {
return rb_ensure(rb_yield, dir, dir_close, dir);
}
return dir;
}
|
.getwd ⇒ String .pwd ⇒ String
981 982 983 984 985 |
# File 'dir.c', line 981
static VALUE
dir_s_getwd(VALUE dir)
{
return rb_dir_getwd();
}
|
.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0
Deletes the named directory. Raises a subclass of SystemCallError
if the directory isn’t empty.
1074 1075 1076 1077 1078 1079 1080 1081 1082 |
# File 'dir.c', line 1074
static VALUE
dir_s_rmdir(VALUE obj, VALUE dir)
{
check_dirname(&dir);
if (rmdir(RSTRING_PTR(dir)) < 0)
rb_sys_fail_path(dir);
return INT2FIX(0);
}
|
.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0
Deletes the named directory. Raises a subclass of SystemCallError
if the directory isn’t empty.
1074 1075 1076 1077 1078 1079 1080 1081 1082 |
# File 'dir.c', line 1074
static VALUE
dir_s_rmdir(VALUE obj, VALUE dir)
{
check_dirname(&dir);
if (rmdir(RSTRING_PTR(dir)) < 0)
rb_sys_fail_path(dir);
return INT2FIX(0);
}
|
Instance Method Details
#close ⇒ nil
829 830 831 832 833 834 835 836 837 838 839 |
# File 'dir.c', line 829
static VALUE
dir_close(VALUE dir)
{
struct dir_data *dirp;
GetDIR(dir, dirp);
closedir(dirp->dir);
dirp->dir = NULL;
return Qnil;
}
|
#each {|filename| ... } ⇒ Dir #each ⇒ Object
687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 |
# File 'dir.c', line 687
static VALUE
dir_each(VALUE dir)
{
struct dir_data *dirp;
struct dirent *dp;
IF_NORMALIZE_UTF8PATH(int norm_p);
RETURN_ENUMERATOR(dir, 0, 0);
GetDIR(dir, dirp);
rewinddir(dirp->dir);
IF_NORMALIZE_UTF8PATH(norm_p = need_normalization(dirp->dir));
while ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
const char *name = dp->d_name;
size_t namlen = NAMLEN(dp);
VALUE path;
#if NORMALIZE_UTF8PATH
if (norm_p && has_nonascii(name, namlen) &&
!NIL_P(path = rb_str_normalize_ospath(name, namlen))) {
path = rb_external_str_with_enc(path, dirp->enc);
}
else
#endif
path = rb_external_str_new_with_enc(name, namlen, dirp->enc);
rb_yield(path);
if (dirp->dir == NULL) dir_closed();
}
return dir;
}
|
#fileno ⇒ Integer
596 597 598 599 600 601 602 603 604 605 606 607 |
# File 'dir.c', line 596
static VALUE
dir_fileno(VALUE dir)
{
struct dir_data *dirp;
int fd;
GetDIR(dir, dirp);
fd = dirfd(dirp->dir);
if (fd == -1)
rb_sys_fail("dirfd");
return INT2NUM(fd);
}
|
#inspect ⇒ String
Return a string describing this Dir object.
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 |
# File 'dir.c', line 564
static VALUE
dir_inspect(VALUE dir)
{
struct dir_data *dirp;
TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
if (!NIL_P(dirp->path)) {
VALUE str = rb_str_new_cstr("#<");
rb_str_append(str, rb_class_name(CLASS_OF(dir)));
rb_str_cat2(str, ":");
rb_str_append(str, dirp->path);
rb_str_cat2(str, ">");
return str;
}
return rb_funcall(dir, rb_intern("to_s"), 0, 0);
}
|
#path ⇒ String? #to_path ⇒ String?
622 623 624 625 626 627 628 629 630 |
# File 'dir.c', line 622
static VALUE
dir_path(VALUE dir)
{
struct dir_data *dirp;
TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
if (NIL_P(dirp->path)) return Qnil;
return rb_str_dup(dirp->path);
}
|
#pos ⇒ Integer #tell ⇒ Integer
730 731 732 733 734 735 736 737 738 739 |
# File 'dir.c', line 730
static VALUE
dir_tell(VALUE dir)
{
struct dir_data *dirp;
long pos;
GetDIR(dir, dirp);
pos = telldir(dirp->dir);
return rb_int2inum(pos);
}
|
#pos=(integer) ⇒ Integer
788 789 790 791 792 793 |
# File 'dir.c', line 788
static VALUE
dir_set_pos(VALUE dir, VALUE pos)
{
dir_seek(dir, pos);
return pos;
}
|
#read ⇒ String?
650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 |
# File 'dir.c', line 650
static VALUE
dir_read(VALUE dir)
{
struct dir_data *dirp;
struct dirent *dp;
GetDIR(dir, dirp);
errno = 0;
if ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
return rb_external_str_new_with_enc(dp->d_name, NAMLEN(dp), dirp->enc);
}
else {
if (errno != 0) rb_sys_fail(0);
return Qnil; /* end of stream */
}
}
|
#rewind ⇒ Dir
809 810 811 812 813 814 815 816 817 |
# File 'dir.c', line 809
static VALUE
dir_rewind(VALUE dir)
{
struct dir_data *dirp;
GetDIR(dir, dirp);
rewinddir(dirp->dir);
return dir;
}
|
#seek(integer) ⇒ Dir
759 760 761 762 763 764 765 766 767 768 |
# File 'dir.c', line 759
static VALUE
dir_seek(VALUE dir, VALUE pos)
{
struct dir_data *dirp;
long p = NUM2LONG(pos);
GetDIR(dir, dirp);
seekdir(dirp->dir, p);
return dir;
}
|
#pos ⇒ Integer #tell ⇒ Integer
730 731 732 733 734 735 736 737 738 739 |
# File 'dir.c', line 730
static VALUE
dir_tell(VALUE dir)
{
struct dir_data *dirp;
long pos;
GetDIR(dir, dirp);
pos = telldir(dirp->dir);
return rb_int2inum(pos);
}
|