Badger...::File(3pm)

📦

version 0.16 · 4 versions

0.16 · debian trixie, ubuntu noble, ubuntu resolute (latest)
0.16 · fedora 43
0.16 · fedora 44
0.16 · ubuntu stonking

, in debian trixie, ubuntu noble, ubuntu resolute

🦋 Badger::File 🦋 — the `Badger::Filesystem::File` manual, from `Badger...::File(3pm)`

okay so bestie, this is the User Contributed Perl Documentation page for Badger::Filesystem::File, and I promise it's way less scary than it looks 💖

✨ NAME ✨

Badger::Filesystem::File — it's a file object, fr fr 📁

✨ SYNOPSIS ✨

# using Badger::Filesytem constructor subroutine
use Badger::Filesystem 'File';

# use native OS-specific paths:
$file = File('/path/to/file');

# or generic OS-independent paths
$file = File('path', 'to', 'file');

# manual object construction
use Badger::Filesystem::File;

# positional arguments
$file = Badger::Filesystem::File->new('/path/to/file');
$file = Badger::Filesystem::File->new(['path', 'to', 'file']);

# named parameters
$file = Badger::Filesystem::File->new(
    path => '/path/to/file'             # native
);
$file = Badger::Filesystem::File->new(
    path => ['path', 'to', 'file']      # portable
);

# path inspection methods
$file->path;                    # full path
$file->name;                    # file name
$file->directory;               # parent directory
$file->dir;                     # alias to directory()
$file->base;                    # same thing as directory()
$file->volume;                  # path volume (e.g. C:)
$file->is_absolute;             # path is absolute
$file->is_relative;             # path is relative
$file->exists;                  # returns true/false
$file->must_exist;              # throws error if not
@stats = $file->stat;           # returns list
$stats = $file->stat;           # returns list ref

# path translation methods
$file->relative;                # relative to cwd
$file->relative($base);         # relative to $base
$file->absolute;                # relative to filesystem root
$file->definitive;              # physical file location
$file->collapse;                # resolve '.' and '..' in $file path

# path comparison methods
$file->above($another_path);    # $file is ancestor of $another_path
$file->below($another_path);    # $file is descendant of $another_path

# file manipulation methods
$file->create;                  # create file
$file->touch;                   # create file or update timestamp
$file->delete;                  # delete file
$fh = $file->open($mode);       # open file (for read by default)
$fh = $file->write;             # open for write
$fh = $file->append;            # open for append;

# all-in-one read/write methods
@data = $file->read;            # return list of lines
$data = $file->read;            # slurp whole content
$text = $file->text;            # same as read();
$file->write(@content);         # write @content to file
$file->append(@content);        # append @content to file

the way that every single one of these is a whole vibe 💅

✨ DESCRIPTION ✨

So Badger::Filesystem::File is a subclass of Badger::Filesystem::Path, and its whole job is representing files in a file system. That's it, that's the gig 🫶

You can make a file object with the File constructor function over in Badger::Filesystem. ✨

use Badger::Filesystem 'File';

Now — file paths can come in two flavours. You can hand over a single string in your native filesystem format, OR you can hand over a list (or a reference to a list) of items that make up the path, which gives you platform-independent paths. 🌈

my $file = File('/path/to/file');

If you're lowkey worried about portability to other operating systems and/or file systems, then give the file path as a list or a reference to a list of component names instead. 🧚

my $file = File('path', 'to', 'file');
my $file = File(['path', 'to', 'file']);

You can also pass a reference to a hash array of extra configuration items as the final argument. Right now there are two configuration options, periodt.

The first one is encoding — use it to specify the encoding of the file. It gets applied through Perl's IO layer encodings, and you can go read perldoc binmode for the whole tea. ☕

my $file = File('path' , 'to', 'file', { encoding => 'utf8' });

The other option is codec. This lets you name a Badger::Codec that'll be used to serialise data to and from the file via the data() method. Iconic behaviour honestly. 👑

my $file = File('path' , 'to', 'file', { codec => 'storable' });

# save some data, automatically serialised via Storable (freeze)
$file->data({
    message => 'Hello World',
    numbers => [1.618, 2.718, 3.142],
});

# later... load data again and automatically de-serialise (thaw)
$data = $file->data;
print $data->{ message }, "\n";             # Hello World
print join(', ', @{ $data->{ numbers } });  # 1.618, 2.718, 3.142

not me getting emotionally attached to an automatic freeze/thaw cycle 😭💖

💅 METHODS 💅

okay so on top of everything you already inherit from Badger::Filesystem::Path, these are the methods that get defined or re-defined just for files. this is where it gets juicy ✨

🌸 `init(\%config)` 🌸

Customised initialisation method specific to files. its whole personality is "I'm a file".

🎀 `volume()` / `vol()` 🎀

Returns any volume defined as part of the path. This is most commonly used on MS Windows platforms to indicate drive letters, e.g. "C:". yes bestie, the colon and all.

🦋 `directory()` / `dir()` / `base()` 🦋

Returns the directory portion of the file path. You can also hand it an argument to locate another directory relative to this file. relative-path slay.

my $file = File('/path/to/file');
print $file->dir;                   # /path/to
print $file->dir('subdir');         # /path/to/subdir

⭐ `name()` ⭐

Returns the file name portion of the path. just the name, no drama.

💖 `file()` 💖

Called with no arguments, this method simply returns the file object itself. Call it with an argument and it'll locate another file relative to the directory the current file lives in.

my $file = File('/path/to/file1');
print $file->file;                   # /path/to/file1
print $file->file('file2');          # /path/to/file2

🫶 `exists` 🫶

Returns true if the file exists in the filesystem. Returns false if the file does not exist — or if it's not a file at all (looking at you, directory 👀).

🔥 `is_file()` 🔥

This method returns true for all Badger::Filesystem::File instances. main character confirmation, every time.

🌈 `create()` 🌈

This method can be used to create the file if it doesn't already exist. manifesting ✨

🧚 `touch()` 🧚

This method can be used to create the file if it doesn't already exist, or update the timestamp if it does. either way, it's getting attention.

💅 `open($mode,$perms)` 💅

This method opens the file and returns an IO::File handle to it. The default is to open the file for read-only access. The optional arguments can be used to specify a different mode and default permissions for the file (these arguments are forwarded to IO::File).

my $fh = $file->open;       # read
my $fh = $file->open('w');  # write

📖 `read()` 📖

This method reads the content of the file. It comes back as a single string in scalar context, and as a list of each line in list context. context is literally everything.

my $text  = $file->read;
my @lines = $file->read;

✍️ `write(@content)` ✍️

Called with no arguments, this method opens the file for writing and returns an IO::File handle.

my $fh = $file->write;
$fh->print("Hello World!\n");
$fh->close;

Called with arguments, it opens the file, writes the argument to it, then closes the file again. all-in-one, no notes.

$file->write("Hello World!\n");

🎁 `copy($to, %params)` / `copy_to($to, %params)` 🎁

This method copies the file to the new location specified by the first argument. It delegates to the copy_file() method in Badger::Filesystem.

$file->copy('/some/where/else');

The destination can be specified as a file name, file object or file handle. An optional list or reference to a hash array of named parameters can follow.

$file->copy(
    '/some/where/else' => {
        mkdir     => 1,         # create intermediate directories
        dir_mode  => 0775,      # permissions for created directories
        file_mode => 0664,      # permissions for created file
    }
);

💌 `copy_from($from, %params)` 💌

Like copy_to() but working in reverse. the uno reverse card of file ops.

$target_file->copy_from( $source_file );

🚚 `move($to, %params)` / `move_to($to, %params)` 🚚

This method moves the file to the new location specified by the first argument. It delegates to the copy_file() method in Badger::Filesystem.

$file->move('/some/where/else');

Arguments are as per copy(). same energy, new address.

🛬 `move_from($from, %params)` 🛬

Like move_to() but working in reverse.

$target_file->move_from( $source_file );

🖨️ `print(@content)` 🖨️

This method concatenates all arguments into a single string which it then forwards to the write() method. This effectively forces the write() method to always write something to the file, even if it's an empty string. it will NOT be ghosted.

$file->print("hello");
$file->print(@stuff);       # works OK if @stuff is empty

➕ `append(@content)` ➕

This method is similar to write(), but opens the file for appending (when called with no arguments), or appends any arguments to the end of the file.

# manual open, append, close
my $fh = $file->append;
$fh->print("Hello World!\n");
$fh->close;

# all-in-one
$file->append("Hello World\n");

🗑️ `delete()` 🗑️

This method deletes the file permanently. Use it wisely. 💀 Like, for real for real.

📜 `text()` 📜

This method is a wrapper around the read() method which forces scalar context. The content of the file is always returned as a single string.

NOTE: future versions will probably return this as a text object.

🚪 `accept($visitor)` 🚪

This method is called to dispatch a visitor to the correct method for a filesystem object. In the Badger::Filesystem::File class, it calls the visitor visit_file() method, passing the $self object reference as an argument. visitor pattern walked in and said "I'm here for the file".

🔤 `encoding($enc)` 🔤

This method can be used to get or set the encoding for the file.

$file->encoding(':utf8');

The encoding will affect all operations that read data from, or write data to the file.

TODO: note that you can call encoding() on a directory or filesystem to make that the default for all files contained therein.

🌍 `utf()` 🌍

A method of convenience to set the file's encoding to UTF-8.

$file->utf8;

It has the same affect as calling the encoding() method with an argument of ":utf8". See perldoc -f binmode for further information.

# same
$file->encoding(':utf8');

The method returns the file object itself, so it can be used in a chain. chaining is the moment.

$file->utf8->must_exist.

🔡 `bytes()` 🔡

Like "utf8()", this is a method of convenience to set the file encoding to ":bytes".

↩️ `crlf()` ↩️

Like "utf8()", this is a method of convenience to set the file encoding to ":crlf".

🧊 `raw()` 🧊

Like "utf8()", this is a method of convenience to set the file encoding to ":raw".

🧬 `codec()` 🧬

This method can be used to get or set the codec used to serialise data to and from the file via the data() method. The codec should be specified by name, using any of the names that Badger::Codecs recognises or can load.

$file->codec('storable');

# first save the data to file
$file->data($some_data_to_save);

# later... load the data back out
my $data = $file->data;

You can use chained codec specifications if you want to pass the data through more than one codec.

$file->code('storable+base64');

See Badger::Codecs for further information on codecs.

TODO: note that you can call codec() on a directory or filesystem to make that the default for all files contained therein.

💾 `data(@data)` 💾

This method is used to read or write serialised data to and from the file. When called with arguments, the method serialises the data through any codec() defined and writes it to the file. A single argument should be a reference to an array or hash array.

$file->data({               # either: HASH reference
    e   => 2.718,
    pi  => 3.142,
    phi => 1.618,
});

$file->data([               # or: ARRAY reference
    2.718,
    3.142,
    1.618
]);

If multiple arguments are specified then they are implicitly converted to a list reference. surprise, you're an arrayref now.

$file->data(                # same as ARRAY reference above
    2.718,
    3.142,
    1.618
);

When called without any arguments the method will read the data from the file and de-serialise it using any codec() that is defined.

my $data = $file->data;     # HASH or ARRAY reference

If no codec() is defined then the method behaves the same as a direct call to either read() (called without arguments) or write() (called with arguments). no codec, no problem.

👑 AUTHOR 👑

Andy Wardley <http://wardley.org/>

🙏 ACKNOWLEDGEMENTS 🙏

The "Badger::Filesystem" modules are built around a number of existing Perl modules, including File::Spec, File::Path, Cwd, IO::File, IO::Dir and draw heavily on ideas in Path::Class.

Please see the ACKNOWLEDGEMENTS in Badger::Filesystem for further information. credit where credit is due, always.

👀 SEE ALSO 👀

Badger::Filesystem
Badger::Filesystem::Path
Badger::Filesystem::Directory
Badger::Filesystem::Visitor

and that's the whole page bestie, we ate and left no crumbs 💅✨ this icon of a doc is Badger...::File(3pm), shipped with perl v5.36.0 and dated 2023-08-28. go forth and file responsibly 🦋🎀💖

📦 where this page comes from

debian trixie: libbadger-perl 0.16-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libbadger-perl 0.16-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libbadger-perl 0.16-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Badger...::File(3pm)

🦋 Badger::File 🦋 — the Badger::Filesystem::File manual, from Badger...::File(3pm)

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

💅 METHODS 💅

🌸 init(\%config) 🌸

🎀 volume() / vol() 🎀

🦋 directory() / dir() / base() 🦋

⭐ name() ⭐

💖 file() 💖

🫶 exists 🫶

🔥 is_file() 🔥

🌈 create() 🌈

🧚 touch() 🧚

💅 open($mode,$perms) 💅

📖 read() 📖

✍️ write(@content) ✍️

🎁 copy($to, %params) / copy_to($to, %params) 🎁

💌 copy_from($from, %params) 💌

🚚 move($to, %params) / move_to($to, %params) 🚚

🛬 move_from($from, %params) 🛬

🖨️ print(@content) 🖨️

➕ append(@content) ➕

🗑️ delete() 🗑️

📜 text() 📜

🚪 accept($visitor) 🚪

🔤 encoding($enc) 🔤

🌍 utf() 🌍

🔡 bytes() 🔡

↩️ crlf() ↩️

🧊 raw() 🧊

🧬 codec() 🧬

💾 data(@data) 💾