File::Fu::Dir(3pm)

🌸 File::Fu::Dir 🌸

okay bestie, so this is the User Contributed Perl Documentation page for File::Fu::Dir — and literally all it does is give you a directoryname object. that's it. that's the girl. and she is iconic for it 💅

---

✨ 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

gives you the matching file class for this dir object, no cap. Default: File::Fu::File.

my $fc = $class->file_class;

is_dir

always true for a directory. always. periodt.

is_file

always false for a directory. she's simply not that 💀

temp_dir_class

the 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, but without the trailing slash / the assertion bit.

my $str = $self->bare;

okay so here's the tea 🫖: that trailing slash causes trouble when you're trying to address a symlink to a directory through a dir object. so like, -l $dir does not work, but $dir->l does the exact same thing as -l $dir->bare.

file

make a filename object with $dir as its parent.

my $file = $dir->file($filename);

my $file = $dir + $filename;

append

appends a string to only the last directory part. not all of them. just the last one. iykyk.

$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 it's not an object and it's not quite like File::Basename::basename() when it comes to the / directory. little gremlin behaviour, sorry 💅

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 yes it can also start or end at negative indices, she's flexible like that 🦋

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

runs a callback on each part of $dir. the sub should modify $_ — and yes bestie, this is slightly unlike the map() builtin, i'm just the messenger 🙈

if $parts is defined as an integer or an array reference of integers, it gets treated as a slice on the directory parts that the map should be applied to.

$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. she's trusting like that.

my $abs = $dir->absolute;

absolutely

get an absolute path, resolved on the filesystem, so it must exist or she simply cannot.

my $abs = $dir->absolutely;

---

💅 Doing Stuff 💅

open

calls opendir(), but throws an error if it fails. dramatic? maybe. correct? yes.

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 (croaks if it doesn't exist. rip).

$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, it returns hidden names too (but not the '.' and '..' entries, absolutely not).

the return values are strings, not File::Fu objects. important!!

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 searches a directory's contents for items where the supplied coderef (the matcher) returns true. the matcher gets invoked with the topic ($_) set to the current path — which is either a Dir or a File object. the return values will be File::Fu::File or File::Fu::Dir objects.

if your matcher returns true, the topic gets added to the return values. slay.

my @paths = $dir->find(sub {m/foo/});

there's a knob for controlling recursion, and it's 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's always only one starting path. one girl, one path 💅
• the topic is always absolute in the same sense as the invocant. like, if $dir is relative to your current directory, then the topics and return values are relative too. if $dir is absolute, so are the topics and the return values.

finder

returns an iterator for finding files. this iterator does everything that find() does, but it returns one path at a time. returns undef when it's exhausted, and zero when it's just taking a break ✨

my $subref = $dir->finder(sub {$_->is_file and $_->file =~ m/foo/});

this allows a non-blocking find. main character scheduling energy.

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() — just a while() loop accumulating the return values. no cap.

The FindKnob object

the FindKnob object lets you 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. hence the idiom:

$dir->find(sub {return shift->prune if(condition); ...})

prune

do not recurse into the topic directory. returns false.

mkdir

creates the directory, or croaks with an error.

$dir->mkdir;

$dir->mkdir(0700);

create

creates the directory, with parents if needed 🫶 (she'll bring the whole family)

$dir->create;

rmdir

removes the directory, or croaks with an error.

$dir->rmdir;

remove

removes the directory and all of its children. this is not a drill bestie 💀

$dir->remove;

unlink

$link->unlink;

symlink

creates 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. the way that works is genuinely so annoying but okay.

readlink

my $to = $file->readlink;

---

🎀 Changing Directories 🎀

chdir

changes to the directory in self, returning a new '.' directory object.

$dir = $dir->chdir;

chdir_for

changes to $dir and runs the given subroutine. the sub will be passed a './' directory object.

$dir->chdir_for(sub {...});

chdir_local

changes to $dir, but returns to the current cwd when $token goes out of scope. she always comes home 🥺

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'. easy.

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

returns a temporary directory in $dir.

my $dir = $dir->temp_dir;

temp_file

returns a filehandle to a temporary file in $dir.

my $handle = $dir->temp_file;

---

⭐ AUTHOR ⭐

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

---

😭 BUGS 😭

if you found this module on CPAN, please report any bugs or feature requests through the web interface at <http://rt.cpan.org>. he will be notified, and then you'll automatically be notified of progress on your bug as he makes changes. teamwork bestie 🫶

if you pulled this development version from his /svn/, please contact him 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.

---

okay and that's the whole page!! the source/version line at the bottom says perl v5.36.0 and it's dated 2022-12-07, so yeah — she's been out here since 2022 doing her directoryname thing. mwah, go read the other File::Fu pages, love u bye 🧚💖