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 ⇒ 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 ⇒ Object
Deletes the named directory.
-
.entries ⇒ Object
Returns an array containing all of the filenames in the given directory.
-
.exist? ⇒ Boolean
Returns
true
if the named file is a directory,false
otherwise. - .exists? ⇒ Boolean
-
.foreach ⇒ 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 ⇒ 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 ⇒ 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 ⇒ 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 ⇒ Object
Deletes the named directory.
-
.unlink ⇒ 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.
-
#initialize ⇒ 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_before, #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.
421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 |
# File 'dir.c', line 421
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];
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;
dp->dir = opendir(RSTRING_PTR(dirname));
if (dp->dir == NULL) {
if (errno == EMFILE || errno == ENFILE) {
rb_gc();
dp->dir = opendir(RSTRING_PTR(dirname));
}
if (dp->dir == NULL) {
rb_sys_fail_path(orig);
}
}
dp->path = orig;
return dir;
}
|
Class Method Details
.[](string[, string ...)) ⇒ Array
Equivalent to calling Dir.glob([
string,…],0)
.
1793 1794 1795 1796 1797 1798 1799 1800 |
# File 'dir.c', line 1793
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
848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 |
# File 'dir.c', line 848
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.
946 947 948 949 950 951 952 953 954 |
# File 'dir.c', line 946
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.
1003 1004 1005 1006 1007 1008 1009 1010 1011 |
# File 'dir.c', line 1003
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"]
1962 1963 1964 1965 1966 1967 1968 1969 |
# File 'dir.c', line 1962
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 .exists?(file_name) ⇒ Boolean
Returns true
if the named file is a directory, false
otherwise.
2163 2164 2165 2166 |
# File 'dir.c', line 2163 VALUE rb_file_directory_p() { } |
.exists? ⇒ Boolean
2169 2170 2171 2172 2173 2174 |
# File 'dir.c', line 2169
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
1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 |
# File 'dir.c', line 1936
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
910 911 912 913 914 |
# File 'dir.c', line 910
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"]
1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 |
# File 'dir.c', line 1877
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 {
volatile VALUE v = ary;
ary = dir_globs(RARRAY_LEN(v), RARRAY_CONST_PTR(v), flags);
}
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.
2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 |
# File 'dir.c', line 2133
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
974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 |
# File 'dir.c', line 974
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.
486 487 488 489 490 491 492 493 494 495 496 497 498 |
# File 'dir.c', line 486
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
910 911 912 913 914 |
# File 'dir.c', line 910
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.
1003 1004 1005 1006 1007 1008 1009 1010 1011 |
# File 'dir.c', line 1003
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.
1003 1004 1005 1006 1007 1008 1009 1010 1011 |
# File 'dir.c', line 1003
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
759 760 761 762 763 764 765 766 767 768 769 |
# File 'dir.c', line 759
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
617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 |
# File 'dir.c', line 617
static VALUE
dir_each(VALUE dir)
{
struct dir_data *dirp;
struct dirent *dp;
IF_HAVE_HFS(int hfs_p);
RETURN_ENUMERATOR(dir, 0, 0);
GetDIR(dir, dirp);
rewinddir(dirp->dir);
IF_HAVE_HFS(hfs_p = is_hfs(dirp->dir));
while ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
const char *name = dp->d_name;
size_t namlen = NAMLEN(dp);
VALUE path;
#if HAVE_HFS
if (hfs_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;
}
|
#inspect ⇒ String
Return a string describing this Dir object.
525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 |
# File 'dir.c', line 525
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?
552 553 554 555 556 557 558 559 560 |
# File 'dir.c', line 552
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
660 661 662 663 664 665 666 667 668 669 |
# File 'dir.c', line 660
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
718 719 720 721 722 723 |
# File 'dir.c', line 718
static VALUE
dir_set_pos(VALUE dir, VALUE pos)
{
dir_seek(dir, pos);
return pos;
}
|
#read ⇒ String?
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 |
# File 'dir.c', line 580
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
739 740 741 742 743 744 745 746 747 |
# File 'dir.c', line 739
static VALUE
dir_rewind(VALUE dir)
{
struct dir_data *dirp;
GetDIR(dir, dirp);
rewinddir(dirp->dir);
return dir;
}
|
#seek(integer) ⇒ Dir
689 690 691 692 693 694 695 696 697 698 |
# File 'dir.c', line 689
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
660 661 662 663 664 665 666 667 668 669 |
# File 'dir.c', line 660
static VALUE
dir_tell(VALUE dir)
{
struct dir_data *dirp;
long pos;
GetDIR(dir, dirp);
pos = telldir(dirp->dir);
return rb_int2inum(pos);
}
|