--- name: "File::Fu::Dir" section: "3pm" platform: "linux" package: "libfile-fu-perl" version: "0.0.8-5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/File::Fu::Dir" --- # File::Fu::Dir(3pm) a directoryname object ## NAME File::Fu::Dir - a directoryname object ## SYNOPSIS ``` use File::Fu; my $dir = File::Fu->dir("path/to/dir"); $dir->e and warn "$dir exists"; $dir->l and warn "$dir is a link to ", $dir->readlink; foreach my $entry ($dir->list) { warn $entry . ': ' . $entry->stat->size, "\n" if($entry->f); } ``` ## Constructor ### new ``` my $dir = File::Fu::Dir->new($path); my $dir = File::Fu::Dir->new(@path); ``` ## Class Constants/Methods ### file\_class Return the corresponding file class for this dir object. Default: File::Fu::File. ``` my $fc = $class->file_class; ``` ### is\_dir Always true for a directory. ### is\_file Always false for a directory. ### temp\_dir\_class Class for "temp\_dir" objects. Default: File::Fu::Dir::Temp. ``` my $class = File::Fu::Dir->temp_dir_class; ``` ### temp\_file\_class ``` my $class = File::Fu::Dir->temp_file_class; ``` ## Methods ### stringify ``` my $string = $dir->stringify; ``` ### bare Stringify without the trailing slash/assertion. ``` my $str = $self->bare; ``` The trailing slash causes trouble when trying to address a symlink to a directory via a dir object. Thus, `"-l $dir"` doesn't work, but `"$dir->l"` does the same thing as `"-l $dir->bare"`. ### file Create a filename object with `$dir` as its parent. ``` my $file = $dir->file($filename); my $file = $dir + $filename; ``` ### append Append a string only to the last directory part. ``` $dir->append('.tmp'); $dir %= "something"; ``` ### subdir ``` $newdir = $dir->subdir('foo'); $newdir = $dir / 'foo'; ``` ### part Returns the `$i`'th part of the directory list. ``` my $part = $dir->part($i); ``` `$dir`-\>part(-1) is like `$dir`-\>basename, but not an object and not quite like **File::Basename::basename()** when it comes to the / directory. ### end Shorthand for part(-1); ### parts Retrieve the inner list of the directory's parts. ``` my @parts = $dir->parts; my @parts = $dir->parts(0..2); ``` The returned parts will be contiguous, but the request can be a two-element list (and can also start or end at negative indices.) ``` my @parts = $dir->parts(3, 7); my @parts = $dir->parts(3, -1); my @parts = $dir->parts(-5, -1); ``` ### slice Returns a new dir object as the return of **parts()**. ``` my $slice = $dir->slice(0); my $slice = $dir->slice(0,3); ``` ### map Execute a callback on each part of `$dir`. The sub should modify `$_` (yes, this is slightly unlike the **map()** builtin.) If `$parts` is defined as an integer or array reference of integers, it will be treated as a slice on the directory parts to which the map should be applied. ``` $dir->map(sub {...}, [@parts]); $dir &= sub {s/foo$/bar/}; ``` So, to modify only the first directory part: ``` $dir->map(sub {s/foo$/bar/}, 0); ``` ## Properties ### is\_cwd True if the `$dir` represents a relative (e.g. '.') directory. ``` my $bool = $dir->is_cwd; ``` ### basename Returns the last part of the path as a Dir object. ``` my $bit = $dir->basename; ``` ### dirname Returns the parent parts of the path as a Dir object. ``` my $parent = $dir->dirname; ``` ### absolute Get an absolute name (without checking the filesystem.) ``` my $abs = $dir->absolute; ``` ### absolutely Get an absolute path (resolved on filesystem, so it must exist.) ``` my $abs = $dir->absolutely; ``` ## Doing stuff ### open Calls **opendir()**, but throws an error if it fails. ``` my $dh = $dir->open; ``` Returns a directory handle, for e.g. **readdir()**. ``` my @files = map({$dir + $_} grep({$_ !~ m/^\./} readdir($dh))); ``` ### touch Update the timestamp of a directory (croak if it doesn't exist.) ``` $dir->touch; ``` ### list ``` my @paths = $dir->list(all => 1); ``` ### lister ``` my $subref = $dir->lister(all => 1); ``` ### contents Equivalent to readdir. With the 'all' option true, returns hidden names too (but not the '.' and '..' entries.) The return values are strings, not File::Fu objects. ``` my @names = $dir->contents(all => 1); ``` ### iterate\_contents Returns a subref which will iterate over the directory's contents. ``` my $subref = $dir->iterate_contents(all => 1); ``` ### find Recursively search a directory's contents for items where the supplied coderef (matcher) returns true. The matcher will be invoked with the topic (`$_`) set to the current path (which is either a Dir or File object.) The return values will be File::Fu::File or File::Fu::Dir objects. If your matcher returns true, the topic will be added to the return values. ``` my @paths = $dir->find(sub {m/foo/}); ``` There is a knob for controlling recursion, which is the first argument to your matcher. ``` my @pm_files = $dir->find(sub { return shift->prune if($_->is_dir and $_->part(-1) =~ m/^\.svn$/); $_->is_file and m/\.pm$/; }); ``` - Differences from **File::Find::find()** The invocant (`$dir` aka '.') is not examined (because this is an object method, there is always only one starting path.) The topic is always absolute in the same sense as the invocant. That is, if `$dir` is relative to your current directory, then so are the topics and return values. If `$dir` is absolute, so are the topics and return values. ### finder Returns an iterator for finding files. This iterator does everything that **find()** does, but returns one path at a time. Returns undef when exhausted and zero when it is just taking a break. ``` my $subref = $dir->finder(sub {$_->is_file and $_->file =~ m/foo/}); ``` This allows a non-blocking find. ``` while(defined(my $path = $subref->())) { $path or next; # 0 means 'not done yet' # do something with $path (a file or dir object) } ``` The **find()** method is implemented in terms of **finder()** by simply using a **while()** loop and accumulating the return values. ### The FindKnob object The FindKnob object allows you to control the next steps of **find()**. Methods called on it will typically return a value which also makes sense as a return value of your matcher sub. Thus the idiom: ``` $dir->find(sub {return shift->prune if(condition); ...}) ``` - prune Do not recurse into the topic directory. Returns false. ### mkdir Create the directory or croak with an error. ``` $dir->mkdir; $dir->mkdir(0700); ``` ### create Create the directory, with parents if needed. ``` $dir->create; ``` ### rmdir Remove the directory or croak with an error. ``` $dir->rmdir; ``` ### remove Remove the directory and all of its children. ``` $dir->remove; ``` ### unlink ``` $link->unlink; ``` ### symlink Create a symlink which points to `$dir`. ``` my $link = $dir->symlink($linkname); ``` Note that symlinks are relative to where they live, so if `$dir` is a relative path, it must be relative to `$linkname`. ### readlink ``` my $to = $file->readlink; ``` ## Changing Directories ### chdir Change to the directory in self, returning a new '.' directory object. ``` $dir = $dir->chdir; ``` ### chdir\_for Change to `$dir` and run the given subroutine. The sub will be passed a './' directory object. ``` $dir->chdir_for(sub {...}); ``` ### chdir\_local Change to `$dir`, but return to the current cwd when `$token` goes out of scope. ``` my $token = $self->chdir_local; ``` ## Temporary Directories and Files These methods use the `$dir` object as a parent location for the temp path. To use your system's global temp space (e.g. '/tmp/'), just replace `$dir` with 'File::Fu'. ``` File::Fu->temp_dir; # '/tmp/' File::Fu->dir->temp_dir; # './' File::Fu->dir("foo")->temp_dir; # 'foo/' File::Fu->temp_file; # '/tmp/' File::Fu->dir->temp_file; # './' File::Fu->dir("foo")->temp_file; # 'foo/' ``` ### temp\_dir Return a temporary directory in `$dir`. ``` my $dir = $dir->temp_dir; ``` ### temp\_file Return a filehandle to a temporary file in `$dir`. ``` my $handle = $dir->temp_file; ``` ## AUTHOR Eric Wilhelm @ \ http://scratchcomputing.com/ ## BUGS If you found this module on CPAN, please report any bugs or feature requests through the web interface at \. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. If you pulled this development version from my /svn/, please contact me directly. ## COPYRIGHT Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved. ## NO WARRANTY Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned. ## LICENSE This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.