File::Fu::File(3pm)

🌸 NAME 🌸

okay bestie, gather round 💖 this is File::Fu::File — a filename object. that's it, that's the vibe. it's giving "a file, but make it an object." (also hi, this is a User Contributed Perl Documentation page, section 3pm, and we're about to have a whole moment together 🫶)

---

✨ SYNOPSIS ✨

use File::Fu;

my $file = File::Fu->file("path/to/file");
$file %= '.extension';
$file->e and warn "$file exists";

$file->l and warn "$file is a link to ", $file->readlink;

---

🎀 Constructor 🎀

new

make a whole new file object, slay 💅

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

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

new_direct

the ✨direct✨ route — you hand it the dir object and the name, no mystery:

my $file = File::Fu::File->new_direct(
  dir => $dir_obj,
  file => $name
);

---

👑 Class Constants 👑

dir_class

gives you back the dir class that matches this file object. default is literally File::Fu::Dir, no cap.

my $dc = $class->dir_class;

is_dir

always false for a file. bestie... it's a file. that's the whole point 😭

is_file

always true for a file. correct. iconic. periodt 💅

---

🧚 Parts 🧚

basename

returns a brand new object holding just the file part of the name — the little guy at the end of the path 🥺

my $obj = $file->basename;

---

🌈 Methods 🌈

stringify

my $string = $file->stringify;

append

appends a string to only the filename part, not the whole path. so specific, so thoughtful:

$file->append('.gz');

$file %= '.gz';

(yes... I tried to use .=, but overloading hates me. it's giving toxic relationship 💀)

map

$file->map(sub {...});

$file &= sub {...};

absolute

get an absolute name — and without checking the filesystem, so it's not out here verifying anything, it just says the thing.

my $abs = $file->absolute;

absolutely

get an absolute name, but this time resolved on the filesystem. yes, she actually looked 🔍

my $abs = $file->absolutely;

---

🔥 Doing stuff 🔥

open

opens the file with $mode ('<', 'r', '>', 'w', etc) — go see IO::File for the deets.

my $fh = $file->open($mode, $permissions);

throws an error if anything goes wrong, OR if the resulting filehandle happens to be a directory. like, excuse me?? a directory?? not on her watch 🙈

sysopen

interface to the sysopen() builtin. $mode is a text string joined by '|' characters, and those have to be valid O_* constants from Fcntl. no random vibes allowed.

my $fh = $file->sysopen($mode, $perms);

piped_open

opens a read pipe, and the file gets appended to @command. 📎

my $fh = $file->piped_open(@command);

example: useless use of cat. classic.

my $fh = $file->piped_open('cat');

this interface is deprecated (maybe) 💀 because it's limited to commands that take the $file as the last argument. see run() for the way of the future, bestie.

run

treats $file as a program and executes a pipe open.

my $fh = $file->run(@args);

if you call it in void context, it runs "system()" with autodie semantics and the multi-arg form (which suppresses shell interpolation — safety girlie 🫶).

$file->run(@args);

no special treatment is made for whether $file is relative or not (the underlying "system()"/"exec()" will search your path). use File::Fu->which() to get an absolute path beforehand:

File::Fu->which('ls')->run('-l');

touch

updates the timestamp of a file (or creates it). glow up ✨

$file->touch;

mkfifo

my $file = $file->mkfifo($mode);

link

my $link = $file->link($name);

symlink

my $link = $file->symlink($linkname);

note that symlinks are relative to where they live. this matters, okay?? watch:

my $dir = File::Fu->dir("foo");
my $file = $dir+'file';
# $file->symlink($dir+'link'); is a broken link
my $link = $file->basename->symlink($dir+'link');

relative_symlink

see "relative_symlink" in File::Fu::Base. iykyk 💜

unlink

$file->unlink;

remove

a forced unlink — it chmods the file if it's not writable. she does not take no for an answer 💅

$file->remove;

readlink

my $to = $file->readlink;

read

reads the entire file into memory (or swap!). or swap. 😭

my @lines = $file->read;

my $file = $file->read;

if File::Slurp is available, options to read_file will be passed along. see "read_file" in File::Slurp.

write

writes the file's contents. returns the $file object so you can chain, because we love a fluent queen 👑

$file = $file->write($content);

if File::Slurp is available, $content may be either a scalar, a scalar ref, or an array ref.

$file->write($content, %args);

copy

copies $file to $dest (which can be a file or a directory) and returns the name of the new file as an object.

my $new = $file->copy($dest);

note that if $dest is already a File object, that existing object will be returned. no dupe, no drama ✨

move

my $new = $file->move($dest);

---

💖 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. we love a notification pipeline 🫶

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.

bestie this is the realest part of the whole page. no takebacks, no refunds, no cap 🚨

---

🌸 LICENSE 🌸

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🎀 mwah 💋 this was perl v5.36.0, dated 2022-12-07, and it's File::Fu::File(3pm) — go make some filename objects, you absolute icon 👑✨