1Path::Class::Dir(3)   User Contributed Perl Documentation  Path::Class::Dir(3)
2
3
4

NAME

6       Path::Class::Dir - Objects representing directories
7

VERSION

9       version 0.37
10

SYNOPSIS

12         use Path::Class;  # Exports dir() by default
13
14         my $dir = dir('foo', 'bar');       # Path::Class::Dir object
15         my $dir = Path::Class::Dir->new('foo', 'bar');  # Same thing
16
17         # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
18         print "dir: $dir\n";
19
20         if ($dir->is_absolute) { ... }
21         if ($dir->is_relative) { ... }
22
23         my $v = $dir->volume; # Could be 'C:' on Windows, empty string
24                               # on Unix, 'Macintosh HD:' on Mac OS
25
26         $dir->cleanup; # Perform logical cleanup of pathname
27         $dir->resolve; # Perform physical cleanup of pathname
28
29         my $file = $dir->file('file.txt'); # A file in this directory
30         my $subdir = $dir->subdir('george'); # A subdirectory
31         my $parent = $dir->parent; # The parent directory, 'foo'
32
33         my $abs = $dir->absolute; # Transform to absolute path
34         my $rel = $abs->relative; # Transform to relative path
35         my $rel = $abs->relative('/foo'); # Relative to /foo
36
37         print $dir->as_foreign('Mac');   # :foo:bar:
38         print $dir->as_foreign('Win32'); #  foo\bar
39
40         # Iterate with IO::Dir methods:
41         my $handle = $dir->open;
42         while (my $file = $handle->read) {
43           $file = $dir->file($file);  # Turn into Path::Class::File object
44           ...
45         }
46
47         # Iterate with Path::Class methods:
48         while (my $file = $dir->next) {
49           # $file is a Path::Class::File or Path::Class::Dir object
50           ...
51         }
52

DESCRIPTION

54       The "Path::Class::Dir" class contains functionality for manipulating
55       directory names in a cross-platform way.
56

METHODS

58       $dir = Path::Class::Dir->new( <dir1>, <dir2>, ... )
59       $dir = dir( <dir1>, <dir2>, ... )
60           Creates a new "Path::Class::Dir" object and returns it.  The
61           arguments specify names of directories which will be joined to
62           create a single directory object.  A volume may also be specified
63           as the first argument, or as part of the first argument.  You can
64           use platform-neutral syntax:
65
66             my $dir = dir( 'foo', 'bar', 'baz' );
67
68           or platform-native syntax:
69
70             my $dir = dir( 'foo/bar/baz' );
71
72           or a mixture of the two:
73
74             my $dir = dir( 'foo/bar', 'baz' );
75
76           All three of the above examples create relative paths.  To create
77           an absolute path, either use the platform native syntax for doing
78           so:
79
80             my $dir = dir( '/var/tmp' );
81
82           or use an empty string as the first argument:
83
84             my $dir = dir( '', 'var', 'tmp' );
85
86           If the second form seems awkward, that's somewhat intentional -
87           paths like "/var/tmp" or "\Windows" aren't cross-platform concepts
88           in the first place (many non-Unix platforms don't have a notion of
89           a "root directory"), so they probably shouldn't appear in your code
90           if you're trying to be cross-platform.  The first form is perfectly
91           natural, because paths like this may come from config files, user
92           input, or whatever.
93
94           As a special case, since it doesn't otherwise mean anything useful
95           and it's convenient to define this way, "Path::Class::Dir->new()"
96           (or dir()) refers to the current directory ("File::Spec->curdir").
97           To get the current directory as an absolute path, do
98           "dir()->absolute".
99
100           Finally, as another special case dir(undef) will return undef,
101           since that's usually an accident on the part of the caller, and
102           returning the root directory would be a nasty surprise just asking
103           for trouble a few lines later.
104
105       $dir->stringify
106           This method is called internally when a "Path::Class::Dir" object
107           is used in a string context, so the following are equivalent:
108
109             $string = $dir->stringify;
110             $string = "$dir";
111
112       $dir->volume
113           Returns the volume (e.g. "C:" on Windows, "Macintosh HD:" on Mac
114           OS, etc.) of the directory object, if any.  Otherwise, returns the
115           empty string.
116
117       $dir->basename
118           Returns the last directory name of the path as a string.
119
120       $dir->is_dir
121           Returns a boolean value indicating whether this object represents a
122           directory.  Not surprisingly, Path::Class::File objects always
123           return false, and "Path::Class::Dir" objects always return true.
124
125       $dir->is_absolute
126           Returns true or false depending on whether the directory refers to
127           an absolute path specifier (like "/usr/local" or "\Windows").
128
129       $dir->is_relative
130           Returns true or false depending on whether the directory refers to
131           a relative path specifier (like "lib/foo" or "./dir").
132
133       $dir->cleanup
134           Performs a logical cleanup of the file path.  For instance:
135
136             my $dir = dir('/foo//baz/./foo')->cleanup;
137             # $dir now represents '/foo/baz/foo';
138
139       $dir->resolve
140           Performs a physical cleanup of the file path.  For instance:
141
142             my $dir = dir('/foo//baz/../foo')->resolve;
143             # $dir now represents '/foo/foo', assuming no symlinks
144
145           This actually consults the filesystem to verify the validity of the
146           path.
147
148       $file = $dir->file( <dir1>, <dir2>, ..., <file> )
149           Returns a Path::Class::File object representing an entry in $dir or
150           one of its subdirectories.  Internally, this just calls
151           "Path::Class::File->new( @_ )".
152
153       $subdir = $dir->subdir( <dir1>, <dir2>, ... )
154           Returns a new "Path::Class::Dir" object representing a subdirectory
155           of $dir.
156
157       $parent = $dir->parent
158           Returns the parent directory of $dir.  Note that this is the
159           logical parent, not necessarily the physical parent.  It really
160           means we just chop off entries from the end of the directory list
161           until we cain't chop no more.  If the directory is relative, we
162           start using the relative forms of parent directories.
163
164           The following code demonstrates the behavior on absolute and
165           relative directories:
166
167             $dir = dir('/foo/bar');
168             for (1..6) {
169               print "Absolute: $dir\n";
170               $dir = $dir->parent;
171             }
172
173             $dir = dir('foo/bar');
174             for (1..6) {
175               print "Relative: $dir\n";
176               $dir = $dir->parent;
177             }
178
179             ########### Output on Unix ################
180             Absolute: /foo/bar
181             Absolute: /foo
182             Absolute: /
183             Absolute: /
184             Absolute: /
185             Absolute: /
186             Relative: foo/bar
187             Relative: foo
188             Relative: .
189             Relative: ..
190             Relative: ../..
191             Relative: ../../..
192
193       @list = $dir->children
194           Returns a list of Path::Class::File and/or "Path::Class::Dir"
195           objects listed in this directory, or in scalar context the number
196           of such objects.  Obviously, it is necessary for $dir to exist and
197           be readable in order to find its children.
198
199           Note that the children are returned as subdirectories of $dir, i.e.
200           the children of foo will be foo/bar and foo/baz, not bar and baz.
201
202           Ordinarily children() will not include the self and parent entries
203           "." and ".." (or their equivalents on non-Unix systems), because
204           that's like I'm-my-own-grandpa business.  If you do want all
205           directory entries including these special ones, pass a true value
206           for the "all" parameter:
207
208             @c = $dir->children(); # Just the children
209             @c = $dir->children(all => 1); # All entries
210
211           In addition, there's a "no_hidden" parameter that will exclude all
212           normally "hidden" entries - on Unix this means excluding all
213           entries that begin with a dot ("."):
214
215             @c = $dir->children(no_hidden => 1); # Just normally-visible entries
216
217       $abs = $dir->absolute
218           Returns a "Path::Class::Dir" object representing $dir as an
219           absolute path.  An optional argument, given as either a string or a
220           "Path::Class::Dir" object, specifies the directory to use as the
221           base of relativity - otherwise the current working directory will
222           be used.
223
224       $rel = $dir->relative
225           Returns a "Path::Class::Dir" object representing $dir as a relative
226           path.  An optional argument, given as either a string or a
227           "Path::Class::Dir" object, specifies the directory to use as the
228           base of relativity - otherwise the current working directory will
229           be used.
230
231       $boolean = $dir->subsumes($other)
232           Returns true if this directory spec subsumes the other spec, and
233           false otherwise.  Think of "subsumes" as "contains", but we only
234           look at the specs, not whether $dir actually contains $other on the
235           filesystem.
236
237           The $other argument may be a "Path::Class::Dir" object, a
238           Path::Class::File object, or a string.  In the latter case, we
239           assume it's a directory.
240
241             # Examples:
242             dir('foo/bar' )->subsumes(dir('foo/bar/baz'))  # True
243             dir('/foo/bar')->subsumes(dir('/foo/bar/baz')) # True
244             dir('foo/..')->subsumes(dir('foo/../bar))      # True
245             dir('foo/bar' )->subsumes(dir('bar/baz'))      # False
246             dir('/foo/bar')->subsumes(dir('foo/bar'))      # False
247             dir('foo/..')->subsumes(dir('bar'))            # False! Use C<contains> to resolve ".."
248
249       $boolean = $dir->contains($other)
250           Returns true if this directory actually contains $other on the
251           filesystem.  $other doesn't have to be a direct child of $dir, it
252           just has to be subsumed after both paths have been resolved.
253
254       $foreign = $dir->as_foreign($type)
255           Returns a "Path::Class::Dir" object representing $dir as it would
256           be specified on a system of type $type.  Known types include
257           "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
258           there is a subclass of "File::Spec".
259
260           Any generated objects (subdirectories, files, parents, etc.) will
261           also retain this type.
262
263       $foreign = Path::Class::Dir->new_foreign($type, @args)
264           Returns a "Path::Class::Dir" object representing $dir as it would
265           be specified on a system of type $type.  Known types include
266           "Unix", "Win32", "Mac", "VMS", and "OS2", i.e. anything for which
267           there is a subclass of "File::Spec".
268
269           The arguments in @args are the same as they would be specified in
270           new().
271
272       @list = $dir->dir_list([OFFSET, [LENGTH]])
273           Returns the list of strings internally representing this directory
274           structure.  Each successive member of the list is understood to be
275           an entry in its predecessor's directory list.  By contract,
276           "Path::Class->new( $dir->dir_list )" should be equivalent to $dir.
277
278           The semantics of this method are similar to Perl's "splice" or
279           "substr" functions; they return "LENGTH" elements starting at
280           "OFFSET".  If "LENGTH" is omitted, returns all the elements
281           starting at "OFFSET" up to the end of the list.  If "LENGTH" is
282           negative, returns the elements from "OFFSET" onward except for
283           "-LENGTH" elements at the end.  If "OFFSET" is negative, it counts
284           backward "OFFSET" elements from the end of the list.  If "OFFSET"
285           and "LENGTH" are both omitted, the entire list is returned.
286
287           In a scalar context, dir_list() with no arguments returns the
288           number of entries in the directory list; dir_list(OFFSET) returns
289           the single element at that offset; "dir_list(OFFSET, LENGTH)"
290           returns the final element that would have been returned in a list
291           context.
292
293       $dir->components
294           Identical to dir_list().  It exists because there's an analogous
295           method dir_list() in the "Path::Class::File" class that also
296           returns the basename string, so this method lets someone call
297           components() without caring whether the object is a file or a
298           directory.
299
300       $fh = $dir->open()
301           Passes $dir to "IO::Dir->open" and returns the result as an IO::Dir
302           object.  If the opening fails, "undef" is returned and $! is set.
303
304       $dir->mkpath($verbose, $mode)
305           Passes all arguments, including $dir, to File::Path::mkpath() and
306           returns the result (a list of all directories created).
307
308       $dir->rmtree($verbose, $cautious)
309           Passes all arguments, including $dir, to File::Path::rmtree() and
310           returns the result (the number of files successfully deleted).
311
312       $dir->remove()
313           Removes the directory, which must be empty.  Returns a boolean
314           value indicating whether or not the directory was successfully
315           removed.  This method is mainly provided for consistency with
316           "Path::Class::File"'s remove() method.
317
318       $dir->tempfile(...)
319           An interface to File::Temp's tempfile() function.  Just like that
320           function, if you call this in a scalar context, the return value is
321           the filehandle and the file is "unlink"ed as soon as possible
322           (which is immediately on Unix-like platforms).  If called in a list
323           context, the return values are the filehandle and the filename.
324
325           The given directory is passed as the "DIR" parameter.
326
327           Here's an example of pretty good usage which doesn't allow race
328           conditions, won't leave yucky tempfiles around on your filesystem,
329           etc.:
330
331             my $fh = $dir->tempfile;
332             print $fh "Here's some data...\n";
333             seek($fh, 0, 0);
334             while (<$fh>) { do something... }
335
336           Or in combination with a "fork":
337
338             my $fh = $dir->tempfile;
339             print $fh "Here's some more data...\n";
340             seek($fh, 0, 0);
341             if ($pid=fork()) {
342               wait;
343             } else {
344               something($_) while <$fh>;
345             }
346
347       $dir_or_file = $dir->next()
348           A convenient way to iterate through directory contents.  The first
349           time next() is called, it will open() the directory and read the
350           first item from it, returning the result as a "Path::Class::Dir" or
351           Path::Class::File object (depending, of course, on its actual
352           type).  Each subsequent call to next() will simply iterate over the
353           directory's contents, until there are no more items in the
354           directory, and then the undefined value is returned.  For example,
355           to iterate over all the regular files in a directory:
356
357             while (my $file = $dir->next) {
358               next unless -f $file;
359               my $fh = $file->open('r') or die "Can't read $file: $!";
360               ...
361             }
362
363           If an error occurs when opening the directory (for instance, it
364           doesn't exist or isn't readable), next() will throw an exception
365           with the value of $!.
366
367       $dir->traverse( sub { ... }, @args )
368           Calls the given callback for the root, passing it a continuation
369           function which, when called, will call this recursively on each of
370           its children. The callback function should be of the form:
371
372             sub {
373               my ($child, $cont, @args) = @_;
374               # ...
375             }
376
377           For instance, to calculate the number of files in a directory, you
378           can do this:
379
380             my $nfiles = $dir->traverse(sub {
381               my ($child, $cont) = @_;
382               return sum($cont->(), ($child->is_dir ? 0 : 1));
383             });
384
385           or to calculate the maximum depth of a directory:
386
387             my $depth = $dir->traverse(sub {
388               my ($child, $cont, $depth) = @_;
389               return max($cont->($depth + 1), $depth);
390             }, 0);
391
392           You can also choose not to call the callback in certain situations:
393
394             $dir->traverse(sub {
395               my ($child, $cont) = @_;
396               return if -l $child; # don't follow symlinks
397               # do something with $child
398               return $cont->();
399             });
400
401       $dir->traverse_if( sub { ... }, sub { ... }, @args )
402           traverse with additional "should I visit this child" callback.
403           Particularly useful in case examined tree contains inaccessible
404           directories.
405
406           Canonical example:
407
408             $dir->traverse_if(
409               sub {
410                  my ($child, $cont) = @_;
411                  # do something with $child
412                  return $cont->();
413               },
414               sub {
415                  my ($child) = @_;
416                  # Process only readable items
417                  return -r $child;
418               });
419
420           Second callback gets single parameter: child. Only children for
421           which it returns true will be processed by the first callback.
422
423           Remaining parameters are interpreted as in traverse, in particular
424           "traverse_if(callback, sub { 1 }, @args" is equivalent to
425           "traverse(callback, @args)".
426
427       $dir->recurse( callback => sub {...} )
428           Iterates through this directory and all of its children, and all of
429           its children's children, etc., calling the "callback" subroutine
430           for each entry.  This is a lot like what the File::Find module
431           does, and of course "File::Find" will work fine on Path::Class
432           objects, but the advantage of the recurse() method is that it will
433           also feed your callback routine "Path::Class" objects rather than
434           just pathname strings.
435
436           The recurse() method requires a "callback" parameter specifying the
437           subroutine to invoke for each entry.  It will be passed the
438           "Path::Class" object as its first argument.
439
440           recurse() also accepts two boolean parameters, "depthfirst" and
441           "preorder" that control the order of recursion.  The default is a
442           preorder, breadth-first search, i.e. "depthfirst => 0, preorder =>
443           1".  At the time of this writing, all combinations of these two
444           parameters are supported except "depthfirst => 0, preorder => 0".
445
446           "callback" is normally not required to return any value. If it
447           returns special constant Path::Class::Entity::PRUNE() (more easily
448           available as "$item->PRUNE"),  no children of analyzed item will be
449           analyzed (mostly as if you set "$File::Find::prune=1"). Of course
450           pruning is available only in "preorder", in postorder return value
451           has no effect.
452
453       $st = $file->stat()
454           Invokes File::stat::stat() on this directory and returns a
455           "File::stat" object representing the result.
456
457       $st = $file->lstat()
458           Same as stat(), but if $file is a symbolic link, lstat() stats the
459           link instead of the directory the link points to.
460
461       $class = $file->file_class()
462           Returns the class which should be used to create file objects.
463
464           Generally overridden whenever this class is subclassed.
465

AUTHOR

467       Ken Williams, kwilliams@cpan.org
468

SEE ALSO

470       Path::Class, Path::Class::File, File::Spec
471
472
473
474perl v5.38.0                      2023-07-21               Path::Class::Dir(3)
Impressum