File::Fu(3pm)

💖 NAME 💖

File::Fu — file and directory objects, bestie. that's the whole vibe ✨

---

🎀 SYNOPSIS 🎀

okay so the directory constructor? iconic. watch this:

use File::Fu;

my $dir = File::Fu->dir("bar");
print "$dir\n"; # 'bar/'

my $file = $dir + 'bar.txt';
print "$file\n"; # 'bar/bar.txt'

my $d2 = $dir % 'baz'; # 'barbaz/'
my $d3 = $dir / 'bat'; # 'bar/bat/'

my $file2 = $dir / 'bat' + 'foo.txt'; # 'bar/bat/foo.txt'

and now the file constructor, she's cute too:

my $file = File::Fu->file("foo");
$file->e and warn "$file exists";
$file->l and warn "$file is a link";
warn "file is in ", $file->dir;

like. the syntax? chef's kiss. 💅

---

🌸 ABOUT 🌸

this class is the toplevel interface to the File::Fu directory and file objects, and she comes with operator overloading which lets you do precise path composition, plus support for most builtin methods, plus making temporary files/directories, plus finding files, plus more. no cap.

the interface and style are quite different than the perl builtins or File::Spec. the syntax is concise. errors are thrown with croak(), so you never need to check a return code. periodt. 🙌

---

🦋 Constructors 🦋

the actual objects live in the 'Dir' and 'File' sub-namespaces, iykyk.

✨ dir ✨

my $dir = File::Fu->dir($path);

see "new" in File::Fu::Dir

✨ file ✨

my $file = File::Fu->file($path);

see "new" in File::Fu::File

---

⭐ Class Constants ⭐

🌈 tmp

your system's '/tmp/' directory (or equivalent of that.)

my $dir = File::Fu->tmp;

🌈 home

user's $HOME directory.

my $dir = File::Fu->home;

🌈 program_name

the absolute name of your program. this will be relative from the time File::Fu was loaded. it dies if the name is '-e'.

my $prog = File::Fu->program_name;

if File::Fu was loaded after a chdir and the $0 was relative, calling program_name() throws an error. (unless you set $0 correctly before requireing File::Fu.)

🌈 program_dir

returns what typically corresponds to program_name()->dirname, but just the compile-time cwd() when $0 is -e/-E.

my $dir = File::Fu->program_dir;

---

🫶 Class Methods 🫶

💜 THIS_FILE

a nicer way to say __FILE__. obsessed.

my $file = File::Fu->THIS_FILE;

💜 cwd

the current working directory.

my $dir = File::Fu->cwd;

💜 which

returns File::Fu::File objects of ordered candidates for $name found in the path.

my @prog = File::Fu->which($name) or die "cannot find $name";

if called in scalar context, returns a single File::Fu::File object or throws an error if no candidates were found.

my $prog = File::Fu->which($name);

---

🎀 Temporary Directories and Files 🎀

these class methods call the corresponding File::Fu::Dir methods on the value of tmp(). that is, you get a temporary file/dir in the '/tmp/' directory. 💫

🌸 temp_dir

my $dir = File::Fu->temp_dir;

🌸 temp_file

my $handle = File::Fu->temp_file;

---

💅 Operators 💅

if you choose not to use the overloaded operators, you can just say "$obj->stringify()" or "$obj" whenever you want to drop the object-y nature and treat the path as a string. fr.

the operators can be convenient for building-up path names, but you probably don't want to think of them as "math on filenames", because they are nothing like that.

the '+' and '/' operators only apply to directory objects.

op   method                     mnemonic
--   ----------------           --------------------
+    $d->file($b) ............. plus (not "add")
/    $d->subdir($b) ........... slash (not "divide")

the other operators apply to both files and directories.

op   method                     mnemonic
--   ----------------           --------------------
%=   $p->append($b) ........... mod(ify)
%    $p->clone->append($b)
&=   $p->map(sub{...}) ........ invoke subref
&    $p->clone->map(sub {...})

aside: it would be more natural to use ".=" as append(), but the way perl compiles "$obj foo" into "$obj . " foo"" makes it impossible to do the right thing because the lines between object and string are too ambiguous. 😭

---

🧚 Subclassing 🧚

you may wish to subclass File:Fu and override the dir_class() and/or file_class() class methods to point to your own Dir/File subclasses. main character energy.

my $class = 'My::FileFu';
my $dir = $class->dir("foo");

see File::Fu::File and File::Fu::Dir for more info.

💖 dir_class

File::Fu->dir_class # File::Fu::Dir

💖 file_class

File::Fu->file_class # File::Fu::File

---

🌟 See Also 🌟

File::Fu::why if I need to explain my motivations. 🫠

Path::Class, from which many an idea was taken.

File::stat, IO::File, File::Spec, File::Find, File::Temp, File::Path, File::Basename, perlfunc, perlopentut.

---

👑 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>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. bestie customer service honestly.

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.

---

perl v5.36.0 · 2022-12-07 — ok that's the whole page, you ate that, go build some paths bestie 🦋✨💖