Badger...system(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

💖 NAME 💖

Badger::Filesystem — filesystem functionality, bestie ✨

(also hi, this page is from the User Contributed Perl Documentation corner of the 3pm section, and it's a whole vibe 🫶)

🌸 SYNOPSIS 🌸

okay so Badger::Filesystem hands you a bunch of importable constructor functions, and those functions make objects that represent files, directories, and generic paths in a filesystem. literally that's it.

use Badger::Filesystem 'cwd Cwd Path File Dir Directory';
use Badger::Filesystem 'cwd :types';        # same thing

# cwd returns current working directory as text string,
# Cwd return it as a Badger::Filesystem::Directory object
print cwd;                                  # /path/to/cwd
print Cwd->parent;                          # /path/to

# create Badger::Filesystem::Path/File/Directory objects using
# native OS-specific paths:
$path = Path('/path/to/file/or/dir');
$file = File('/path/to/file');
$dir  = Dir('/path/to/directory');           # short name
$dir  = Directory('/path/to/directory');     # long name

# or generic OS-independant paths
$path = File('path', 'to', 'file', 'or', 'dir');
$file = File('path', 'to', 'file');
$dir  = Dir('path', 'to', 'directory');
$dir  = Directory('path', 'to', 'directory');

these constructor functions? they're literally just shortcuts to Badger::Filesystem class methods. no cap.

use Badger::Filesystem;

# we'll just show native paths from now on for brevity
$path = Badger::Filesystem->path('/path/to/file/or/dir');
$file = Badger::Filesystem->file('/path/to/file');
$dir  = Badger::Filesystem->dir('/path/to/directory');

# 'FS' is an alias for 'Badger::Filesystem' 4 lzy ppl lk me
use Badger::Filesystem 'FS'

$path = FS->path('/path/to/file/or/dir');
$file = FS->file('/path/to/file');
$dir  = FS->dir('/path/to/directory');

and you can also make Badger::Filesystem objects, bestie 💅

my $fs = Badger::Filesystem->new;

$path = $fs->path('/path/to/file/or/dir');
$file = $fs->file('/path/to/file');
$dir  = $fs->dir('/path/to/directory');

🦋 INTRODUCTION 🦋

so this is the documentation for the Badger::Filesystem module. honestly? you probably don't need to read it 🙈. if all you want is an easy way to poke at files and directories, here's the entire starter pack:

use Badger::Filesystem 'File Dir';

my $file = File('/path/to/file');       # Badger::Filesystem::File
my $dir  = Dir('/path/to/directory');   # Badger::Filesystem::Directory

the File() and Dir() subroutines are the ones that create Badger::Filesystem::File and Badger::Filesystem::Directory objects. and listen — go read the docs for those modules first, because they cover pretty much everything you need for simple day-to-day file and directory tasks. actually no wait, start with Badger::Filesystem::Path first, because that's the base class for both of them. iconic hierarchy behavior 👑

and if you wanna do something a lil more involved than just inspecting, reading and writing files? or if you're dying to know what filesystem functionality is hiding behind the file and directory objects? then keep reading, babe.

💜 DESCRIPTION 💜

Badger::Filesystem defines an object class for accessing and manipulating files and directories in a file system. it wraps up the behaviours of a whole squad of other filesystem-related modules, including File::Spec, File::Path, IO::File, IO::Dir and Cwd. for example:

# path manipulation
my $dir  = Badger::Filesystem->join_dir('foo', 'bar', 'baz');
my @dirs = Badger::Filesystem->split_dir('foo/bar/baz');

# path inspection
Badger::Filesystem->is_relative('foo/bar/baz');     # true
Badger::Filesystem->is_absolute('foo/bar/baz');     # false

# file manipulation
Badger::Filesystem->write_file('/path/to/file', 'Hello World');
Badger::Filesystem->delete_file('/path/to/file')

# directory manipulation
Badger::Filesystem->cwd;
Badger::Filesystem->mkdir('/path/to/dir')

if you get tired of typing Badger::Filesystem over and over (and over 😭), just import the FS symbol — it's an alias to it. or define your own alias, you do you, main character.

use Badger::Filesystem 'FS';

FS->is_relative('foo/bar/baz');     # true
FS->is_absolute('foo/bar/baz');     # false

Badger::Filesystem also defines methods that create objects representing files (Badger::Filesystem::File), directories (Badger::Filesystem::Directory), and generic paths (Badger::Filesystem::Path) — and those generic paths might point at a file, a directory, or a resource that doesn't even physically exist (a URI, for example 👀).

these are very similar — although not identical — to the corresponding Path::Class modules you might already know and love. the big difference? Badger files, directories and paths are flyweight objects that call back to Badger::Filesystem to actually perform any filesystem operations. which means we get more control over restricting certain operations (like writing files), and more flexibility in what we even call a filesystem (like virtually mounted and/or composite file systems — go see Badger::Filesystem::Virtual for the tea ☕).

use Badger::Filesystem 'FS';

# file manipulation - via Badger::Filesystem::File object
my $file = FS->file('/path/to/file');
print $file->size;                  # metadata
print $file->modified;              # more metadata
my $text = $file->read;             # read file content
$file->write("New content");        # write file content

# directory manipulation - via Badger::Filesystem::Directory object
my $dir = FS->directory('/path/to/dir');
print $dir->mode;                   # metadata
print $dir->modified;               # more metadata
my @entries = $dir->read;           # read directory entries
my $file = $dir->file('foo');       # fetch a file
my $sub  = $dir->dir('bar');        # fetch a sub-directory

the module also defines the Path(), File() and Directory() subroutines so you can easily create Badger::Filesystem::Path, Badger::Filesystem::File and Badger::Filesystem::Directory objects respectively. and Dir is just there as an alias for Directory. slay.

use Badger::Filesystem 'Path File Dir';

my $path = Path('/any/generic/path');
my $file = File('/path/to/file');
my $dir  = Dir('/path/to/dir');

these subroutines are just a convenient way to call the path(), file() and dir() class methods. the examples above are functionally equivalent to the ones below. fr fr.

use Badger::Filesystem;

my $path = Badger::Filesystem->path('/any/generic/path');
my $file = Badger::Filesystem->file('/path/to/file');
my $dir  = Badger::Filesystem->dir('/path/to/dir');

so the constructor subroutines — and the methods hiding behind them — accept a list of path components (or a reference to a list) as well as a single path string. which is the whole trick for specifying paths in an operating system agnostic way. obsessed. 🌈

# these all do the same thing (assuming you're on a Unix-like system)
File('/path/to/file');
File('path', 'to', 'file');
File(['path', 'to', 'file']);

# these too
Badger::Filesystem->file('/path/to/file');
Badger::Filesystem->file('path', 'to', 'file');
Badger::Filesystem->file(['path', 'to', 'file']);

all those examples above assume a Unix-like filesystem using / as the path separator. on a windows machine, for example, you'd have to specify paths using backslashes to satisfy their brain-dead file system 😭. but specifying a list of separate path components stays portable. that's the move.

# if you're stuck on windows :-(
File('\path\to\file');                  # OS specific
File('path', 'to', 'file');             # OS agnostic

and ngl, if you're using Perl on a windows machine then you should probably consider getting a new machine. try a nice shiny Mac, or an Ubuntu box. go on, you know you deserve better. 💅✨

you can also create a Badger::Filesystem object and call object methods against it:

use Badger::Filesystem;

my $fs   = Badger::Filesystem->new;
my $file = $fs->file('/path/to/file');
my $dir  = $fs->dir('/path/to/dir');

making an object lets you define additional configuration parameters for the filesystem. there aren't any interesting parameters worth mentioning in the base class Badger::Filesystem module right now, but subclasses (like Badger::Filesystem::Virtual) do use them. iykyk 🎀

🌈 EXPORTABLE SUBROUTINES 🌈

Okay bestie, so Badger::Filesystem hands out three little constructor subroutines — Path, File and Dir — and they make you Badger::Filesystem::Path, Badger::Filesystem::File and Badger::Filesystem::Directory objects respectively. And because typing "Directory" over and over is exhausting, there's a Dir alias for it. Slay.

But here's the thing — these are ✨explicit✨ girlies. You have to actually ask for them when you use Badger::Filesystem.

use Badger::Filesystem 'File Dir';
my $file = File('/path/to/file');
my $dir  = Dir('/path/to/dir');

You can list them all in one cute string like up there 👆, or do the whole traditional Perl thing with separate items, like so:

use Badger::Filesystem qw(File Dir);

And if you're feeling platform-agnostic (iconic behaviour, honestly), you can pass multiple arguments and let it stitch your path together for you. Obsessed.

my $file = File('path', 'to, 'file');
my $dir  = Dir('path', 'to', 'dir');

A reference to a list works equally well, because of course it does:

my $file = File(['path', 'to, 'file']);
my $dir  = Dir(\@paths);

Now, plot twist 🎀 — if you pass no arguments at all, the subroutines just hand you back the class name associated with the object. So File() gives you Badger::Filesystem::File. Which means you can use them as virtual classes (aka lil shortcuts) for those long class names, if doing things the Object Oriented way is your thing. No judgement. Main character energy either way.

my $file = File->new('path/to/file');
my $dir  = Dir->new('path/to/dir');

And just so we're clear, those two lines above are functionally identical to:

my $file = Badger::Filesystem::File->new('path/to/file');
my $dir  = Badger::Filesystem::Directory->new('path/to/dir');

A lil summary of the constructor subroutines coming right up. 💅

🦋 `Path(@path)`

Makes you a brand new Badger::Filesystem::Path object. You can hand it the path as a single string, or as a list of path components. Whatever vibes.

$path = Path('/path/to/something');
$path = Path('path', 'to', 'something');

🦋 `File(@path)`

Makes you a brand new Badger::Filesystem::File object. Same deal — single string, or a list of path components.

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

🦋 `Dir(@path)` / `Directory(@path)`

Makes you a brand new Badger::Filesystem::Directory object. Again: single string, or a list of path components. You already know the drill, bestie.

$dir = Dir('/path/to/dir');
$dir = Dir('path', 'to', 'dir');

🦋 `Cwd()`

This one returns a Badger::Filesystem::Directory object for the current working directory. Like, where you're standing right now in the filesystem. 📍

use Badger::Filesystem 'Cwd';

print Cwd;              # /foraging/for/nuts/and/berries
print Cwd->parent;      # /foraging/for/nuts/and

🦋 `Bin()`

This returns a Badger::Filesystem::Directory object for the directory where the currently executing script lives. It's just a lil wrapper around whatever's in $Bin. 🎀

use Badger::Filesystem 'Bin';

print Bin;              # /path/to/current/script
print Bin->parent;      # /path/to/current

🦋 `cwd()`

This returns a plain old text string for the current working directory. It's a wrapper around the getcwd function in Cwd, and it also sanitises the path (via the canonpath() function in File::Spec) so your path comes back in the local filesystem convention — like, "/" gets converted to "\" on Win32. Considerate. 💖

🦋 `$Bin`

This loads the FindBin module and exports the $Bin variable straight into the caller's namespace. Sneaky but efficient.

use Badger::Filesystem '$Bin';
use lib "$Bin/../lib";

Which is exactly the same as:

use FindBin '$Bin';
use lib "$Bin/../lib";

The benefit? You can bundle it up with your other import options and save yourself a little typing. Watch:

use Badger::Filesystem 'Cwd File $Bin';

Versus, like... this whole situation:

use Cwd;
use Path::Class;
use FindBin '$Bin';
use lib "$Bin/../lib";

Yeah. One line. Ate. 🔥

🦋 `getcwd()`

This is a direct alias to the getcwd function in Cwd. No middleman, no extra steps.

🦋 `":types"` Import Option

Pass this as an import option and it exports all of Path(), File, Dir, Directory and Cwd subroutines to the caller. Everything. The whole squad. 👑

use Badger::Filesystem ':types';

my $path   = Path('/some/where');
my $dir    = Dir('/over/there');
my $file   = File('example.html');
my $parent = Cwd->parent;

💅 CONSTRUCTOR METHODS 💅

✨ `new(%config)`

This is the constructor method that makes you a fresh Badger::Filesystem object.

my $fs = Badger::Filesystem->new;

Honestly though, in most cases you don't even need to make a Badger::Filesystem object at all. You can either call class methods, like this:

my $file = Badger::Filesystem->file('/path/to/file');

Or use the constructor subroutines, like this:

use Badger::Filesystem 'File';
my $file = File('/path/to/file');

But — you might wanna make a filesystem object to pass off to some other method or object to play with. And in that case, the Badger::Filesystem methods work equally well being called as object or class methods. Flexible queen. 💅

You might also wanna use a subclass of Badger::Filesystem, like Badger::Filesystem::Virtual, which needs configuration parameters to be properly initialised.

✨ `path(@path)`

Creates a new Badger::Filesystem::Path object. This is typically what you reach for when you're manipulating paths that don't relate to a specific file or directory in a real filesystem.

# single path (platform specific)
my $path = $fs->path('/path/to/something');

# list or list ref of path components (platform agnostic)
my $path = $fs->path('path', 'to', 'something');
my $path = $fs->path(['path', 'to', 'something']);

✨ `file(@path)`

Creates a new Badger::Filesystem::File object to represent a file in a filesystem.

# single file path (platform specific)
my $file = $fs->file('/path/to/file');

# list or list ref of file path components (platform agnostic)
my $file = $fs->file('path', 'to', 'file');
my $file = $fs->file(['path', 'to', 'file']);

✨ `dir(@path)` / `directory(@path)`

Creates a new Badger::Filesystem::Directory object to represent a file in a filesystem. And dir() is an alias for directory() — again, purely to save on typing, because we're all busy. 💅

# single directory path (platform specific)
my $dir = $fs->dir('/path/to/directory');

# list or list ref of directory path components (platform agnostic)
my $dir = $fs->dir('path', 'to', 'directory');
my $dir = $fs->dir(['path', 'to', 'directory']);

And if you don't specify a directory path explicitly? It defaults to the current working directory, as returned by cwd(). It just knows. 🎀

my $cwd = $fs->dir;

🧚 PATH MANIPULATION METHODS 🧚

🌸 `merge_paths($path1,$path2)`

Joins two paths into one. Simple as that, bestie.

$fs->merge_paths('/path/one', 'path/two');      # /path/one/path/two

Now, it makes no attempt to verify that the second argument is an absolute path. And honestly? That's a feature, not a bug — it's considered a feature that this method will do its best to merge two paths even if they look like they shouldn't go together. (Super relevant when you're using virtual filesystems — go peek at Badger::Filesystem::Virtual.)

$fs->merge_paths('/path/one', '/path/two');     # /path/one/path/two

If either of them defines a volume, then that volume gets used for the combined path. But if both paths define a volume, they have to be the same volume, or an error gets thrown. No mixing. 😭

$fs->merge_paths('C:\path\one', 'path\two');    # C:\path\one\path\two
$fs->merge_paths('\path\one', 'C:\path\two');   # C:\path\one\path\two
$fs->merge_paths('C:\path\one', 'C:\path\two'); # C:\path\one\path\two

🌸 `split_path($path)`

Splits a composite path into volume, directory name and file name components. It's a wrapper around the splitpath() function in File::Spec.

($vol, $dir, $file) = $fs->split_path($path);

🌸 `join_path($volume, $dir, $file)`

Combines a filesystem volume (where applicable), a directory name and a file name into one single path. This one's a wrapper around the catpath() and canonpath() functions in File::Spec.

my $path = $fs->join_path($volume, $directory, $file);

🌸 `split_dir($dir)` / `split_directory($dir)`

Splits a directory path into individual directory names. Wrapper around the splitdir() function in File::Spec.

@dirs = $fs->split_dir($dir);

🌸 `join_dir(@dirs)` / `join_directory(@dirs)`

Combines multiple directory names into a single path. Wrapper around the catdir() function in File::Spec.

my $dir = $fs->join_dir('path', 'to', 'my', 'dir');

And the final element can also be a file name. TODO: is that portable?

my $dir = $fs->join_dir('path', 'to', 'my', 'file');

🌸 `collapse_dir($dir)` / `collapse_directory($dir)`

Reduces a directory to its simplest form by resolving and removing any "." (current directory) and ".." (parent directory) components — or whatever the corresponding tokens are for the current and parent directories of your filesystem. ✨

print $fs->collapse_dir('/foo/bar/../baz');   # /foo/baz

Okay important caveat, bestie: the reduction is purely syntactic. No attempt is made to verify that the directories exist, and no attempt is made to intelligently resolve a parent directory where symbolic links are involved. It is not doing detective work. It is doing vibes-based string math. 💀

Also note that this may not work portably across all operating systems. If you're on a Unix-based filesystem (including Mac OSX) or MS Windows then you should be OK. But if you're on an old MacOS machine (pre-OSX), VMS, or something made out of clockwork — consider yourself warned, because this method is untested on those platforms. 🙈

And collapse_dir() is a direct alias of collapse_directory(), to save on typing. Obviously.

🌸 `slash_directory($path)`

Returns the directory $path with a trailing "/" appended (or whatever the directory separator is for your filesystem) — but only if it doesn't already have one. It's not gonna double up on you. 🫶

print $fs->slash_directory('foo');      # foo/

⭐ PATH INSPECTION METHODS ⭐

💜 `is_absolute($path)`

Returns true if the path you specified is absolute. Which means it starts with a "/", or whatever the corresponding token for the root directory is for your file system. 👑

$fs->is_absolute('/foo');               # true
$fs->is_absolute('foo');                # false

💜 `is_relative($path)`

Returns true if the path you specified is relative. Which means it does not start with a "/", or whatever the corresponding token for the root directory is for your file system.

$fs->is_relative('/foo');               # false
$fs->is_relative('foo');                # true

🔄 PATH CONVERSION METHODS 🔄

`absolute($path, $base)`

Bestie, this one takes a relative path and makes it absolute ✨ The path you hand over is assumed to be relative to the current working directory — unless you explicitly pass in a $base parameter.

$fs->cwd;                               # /foo/bar  (for example)
$fs->absolute('baz');                   # /foo/bar/baz
$fs->absolute('baz', '/wam/bam');       # /wam/bam/baz

And okay, real talk, look at how lowkey confusing that last example is 😭 The base path is the second argument, but it ends up sitting in front of the first argument. It's an unfortunately consequence of the way the parameters are ordered (the optional parameter must come after the mandatory one) and can't be avoided. Not a vibe, but we live here 💅

`relative($path, $base)`

The reverse glow-up: takes an absolute path and makes it relative 🦋 It's assumed to be relative to the current working direct unless you explicitly provide a $base parameter.

$fs->cwd;                               # /foo/bar  (for example)
$fs->relative('/foo/bar/wam/bam');      # wam/bam
$fs->relative('/baz/wam/bam', '/baz');  # wam/bam

Again note that last example where

`definitive($path)`

Takes an absolute or relative path and turns it definitive 💖 In most cases, a definitive path is identical to an absolute one.

$fs->definitive('/foo/bar');            # /foo/bar

BUT — and this is the plot twist 🌈 — if you're using a virtual filesystem with a virtual root directory, then a definitive path will include the virtual root directory, whereas a an absolute path will not.

my $vfs = Badger::Filesystem::Virtual->new( root => '/my/vfs' );
$vfs->absolute('/foo/bar');              # /foo/bar
$vfs->definitive('/foo/bar');            # /my/vfs/foo/bar

The Badger::Filesystem module uses definitive paths when performing any operations on the file system (e.g. opening and reading files and directories). You can think of absolute paths as being like conceptual URIs (identifiers) and definitive paths as being like concrete URLs (locators). In practice, they'll both have the same value unless unless you're using a virtual file system. 👑

In the Badger::Filesystem base class, the definitive() method is mapped directly to the definitive_write() method. This has no real effect in this module, but provides the relevant hooks that allow the Badger::Filesystem::Virtual subclass to work properly. iykyk 🧚

`definitive_read($path)`

Converts an absolute or relative path to a definitive one for a read operation. See definitive(). 📖

`definitive_write($path)`

Converts an absolute or relative path to a definitive one for a write operation. See definitive(). ✍️

🧪 PATH TEST METHODS 🧪

`path_exists($path)`

Returns true if the path exists, false if not. Simple as, fr fr ✅

`file_exists($path)`

Returns true if the path exists and is a file, false if not. 🍓

`dir_exists($path)` / `directory_exists($path)`

Returns true if the path exists and is a directory, false if not. 🎀

`stat_path($path)`

Performs a stat() on the filesystem path. It returns a list (in list context) or a reference to a list (in scalar context) containing 17 items 👀 The first 13 are those returned by Perl's inbuilt stat() function. The next 3 items are flags indicating if the file is readable, writeable and/or executable. The final item is a flag indicating if the file is owned by the current user (i.e. owner of the current process.

A summary of the fields is shown below. See perldoc -f stat and the stat() method in Badger::Filesystem::Path for further details.

0 — device number of filesystem
1 — inode number
2 — file mode (type and permissions)
3 — number of (hard) links to the file
4 — numeric user ID of file’s owner
5 — numeric group ID of file’s owner
6 — the device identifier (special files only)
7 — total size of file, in bytes
8 — last access time in seconds since the epoch
9 — last modify time in seconds since the epoch
10 — inode change time in seconds since the epoch (*)
11 — preferred block size for file system I/O
12 — actual number of blocks allocated
13 — file is readable by current process
14 — file is writeable by current process
15 — file is executable by current process
16 — file is owned by current process

`chmod_path($path)`

Changes the file permissions on a path. Permission slip: signed 💅

$fs->chmod_path('/path/to/file', 0755);

📁 FILE MANIPULATION METHODS 📁

`create_file($path)`

Creates an empty file if it doesn't already exist. Returns a true value if the file is created and a false value if it already exists. Errors are thrown as exceptions. ✨

$fs->create_file('/path/to/file');

`touch_file($path)` / `touch($path)`

Creates a file if it doesn't exists, or updates the timestamp if it does. No cap, it's giving "gentle little poke" 🫶

$fs->touch_file('/path/to/file');

`delete_file($path)`

Deletes a file. 💀

$fs->delete_file('/path/to/file');      # Careful with that axe, Eugene!

Okay bestie, that comment in the example is not me being cute, that's literally in the docs. Careful with that axe, Eugene. 🔥

`open_file($path, $mode, $perms)`

Opens a file for reading (by default) or writing/appending (by passing $mode and optionally $perms). Accepts the same parameters as for the IO::File::open() method and returns an IO::File object. 🎀

my $fh = $fs->open_file('/path/to/file');
my $fh = $fs->open_file('/path/to/file', 'w');
my $fh = $fs->open_file('/path/to/file', 'w', 0644);

`read_file($path)`

Reads the content of a file, returning it as a list of lines (in list context) or a single text string (in scalar context). 📖

my $text  = $fs->read_file('/path/to/file');
my @lines = $fs->read_file('/path/to/file');

`write_file($path, @content)`

When called with a single $path argument, this method opens the specified file for writing and returns an IO::File object. ✍️

my $fh = $fs->write_file('/path/to/file');
$fh->print("Hello World!\n");
$fh->close;

If any additional @content argument(s) are passed then they will be written to the file. The file is then closed and a true value returned to indicate success. Errors are thrown as exceptions.

$fs->write_file('/path/to/file', "Hello World\n", "Regards, Badger\n");

`append_file($path, @content)`

This method is similar to write_file(), but opens the file for appending instead of overwriting. When called with a single $path argument, it opens the file for appending and returns an IO::File object. 🦋

my $fh = $fs->append_file('/path/to/file');
$fh->print("Hello World!\n");
$fh->close;

If any additional @content argument(s) are passed then they will be appended to the file. The file is then closed and a true value returned to indicate success. Errors are thrown as exceptions.

$fs->append_file('/path/to/file', "Hello World\n", "Regards, Badger\n");

`copy_file($from, $to, %params)`

Copies a file from the $from path to the $to path, using File::Copy 🌸

$fs->copy_file($from, $to);

The $from and $to arguments can be file names, file objects, or file handles.

An optional list or reference to a hash array of named parameters can follow the file names. The mkdir option can be set to indicate that the destination direction should be created if it doesn't already exist, along with any intermediate directories.

$fs->copy_file($from, $to, mkdir => 1);

The dir_mode parameter can be used to specify the octal file permissions for any directories created.

$fs->copy_file($from, $to, 1, mkdir => 1, dir_mode => 0770);

The file_mode parameter (or mode for short) can be used to specify the octal file permissions for the created file.

$fs->copy_file($from, $to, file_mode => 0644);

`move_file($from, $to, %params)`

Moves a file from the $from path to the $to path, using File::Copy. The arguments are as per copy_file(). 🚚

🗂️ DIRECTORY MANIPULATION METHODS 🗂️

`create_dir($path)` / `create_directory($path)` / `mkdir($path)`

Creates the directory specified by $path. Errors are thrown as exceptions. ✨

$fs->create_dir('/path/to/directory');

Additional arguments can be specified as per the File::Path mkpath() method. NOTE: this is subject to change. Better to use File::Path directly for now if you're relying on this. ⚠️

`delete_dir($path)` / `delete_directory($path)` / `rmdir($path)`

Deletes the directory specified by $path. Errors are thrown as exceptions. 💀

$fs->delete_dir('/path/to/directory');

`open_dir($path)` / `open_directory($path)`

Returns an IO::Dir handle opened for reading a directory or throws an error if the open failed. 🎀

my $dh = $fs->open_dir('/path/to/directory');
while (defined ($path = $dh->read)) {
    print " - $path\n";
}

`read_dir($dir, $all)` / `read_directory($dir, $all)`

Returns a list (in list context) or a reference to a list (in scalar context) containing the entries in the directory. These are simple text strings containing the names of the files and/or sub-directories in the directory. 📝

my @paths = $fs->read_dir('/path/to/directory');

By default, this excludes the current and parent entries (. and .. or whatever the equivalents are for your filesystem. Pass a true value for the optional second argument to include these items.

my @paths = $fs->read_dir('/path/to/directory', 1);

`dir_children($dir, $all)` / `directory_children($dir, $all)`

Returns a list (in list context) or a reference to a list (in scalar context) of objects to represent the contents of a directory. 🧚 As per read_dir(), the current (.) and parent (..) directories are excluded unless you set the $all flag to a true value. Files are returned as Badger::Filesystem::File objects, directories as Badger::Filesystem::File objects. Anything else is returned as a generic Badger::Filesystem::Path object.

`dir_child($path)` / `directory_child($path)`

Returns an object to represent a single item in a directory. 🍓 Files are returned as Badger::Filesystem::File objects, directories as Badger::Filesystem::File objects. Anything else is returned as a generic Badger::Filesystem::Path object.

🧊 TEMPORARY DIRECTORY AND FILE METHODS 🧊

`temp_dir($dir)` / `temp_directory($dir)`

This returns a reference to a Badger::Filesystem::Directory object for the temporary directory on your system (as reported by tmpdir in File::Spec). 🌈

my $tmp = $fs->temp_dir;

If any arguments are specified then they are appended as sub-directories to the temporary directory path.

my $tmp = $fs->temp_dir('foo', 'bar');  # e.g. /tmp/foo/bar

`temp_file($name)`

This returns a reference to a Badger::Filesystem::File object for a named file created in the temporary directory returned by the temp_directory() method. ⭐

my $file = $fs->temp_file('foo.tmp');   # e.g. /tmp/foo.tmp

🦋 VISITOR METHODS 🦋

✨ `visitor(\%params)` ✨

Okay bestie, this method builds you a Badger::Filesystem::Visitor object out of whatever arguments you hand it — you can pass a plain list or a reference to a hash array of named parameters, either way works 💖

# list of named parameters.
$fs->visitor( files => 1, dirs => 0 );

# reference to hash array of named parameters
$fs->visitor( files => 1, dirs => 0 );

And here's the cute part: if that first argument is already a reference to a Badger::Filesystem::Visitor object (or a subclass of one), it just gets handed right back to you unmodified. No clone, no copy, same object, periodt. 👑

🌸 `visit(\%params)` 🌸

This one forwards every single argument straight onto the visit() method of the root() directory. That's it, that's the whole job. 💅

🎀 `accept($visitor)` 🎀

This is the lowkey low-level one — it's called to dispatch a visitor to the correct method for a filesystem object. It forwards the visitor onto the accept() method for the root() directory. iykyk 🧚

🌈 `collect(\%params)` 🌈

This is the short-cut glow-up: it calls the visit() method and then calls the collect() method on the Badger::Filesystem::Visitor object that comes back. Two steps, one vibe ✨

# short form
my @items = $fs->collect( files => 1, dirs => 0 );

# long form
my @items = $fs->visit( files => 1, dirs => 0 )->collect;

💅 MISCELLANEOUS METHODS 💅

🍓 `cwd()` 🍓

Returns the current working directory. And listen — this is a text string, not a Badger::Filesystem::Directory object, okay? If you want the actual object version, call the Cwd() method instead. Don't mix them up bestie 😭

my $cwd = $fs->cwd;

👑 `root()` 👑

Returns a Badger::Filesystem::Directory object representing the root directory for the filesystem. Main character object energy only 💜

⭐ `rootdir` ⭐

Returns a text string containing the representation of the root directory for your filesystem.

print $fs->rootdir;             # e.g. '/' on Unix-based file systems

🦋 `updir` 🦋

Returns a text string containing the representation of the parent directory for your filesystem.

print $fs->updir;               # e.g. '..' on Unix-based file systems

🌸 `curdir` 🌸

Returns a text string containing the representation of the current directory for your filesystem.

print $fs->curdir;              # e.g. '.' on Unix-based file systems

✨ `separator` ✨

Returns a text string containing the representation of the path separator for your filesystem.

print $fs->separator;           # e.g. '/' on Unix-based file systems

🎀 `spec` 🎀

Returns a text string containing the class name of File::Spec — or some other user-definable module that implements the same functionality. This is what's used internally for splitting and joining file paths. Behind the scenes slay 💅

🌈 EXPORTABLE CONSTANTS 🌈

FS — an alias for Badger::Filesystem
VFS — an alias for Badger::Filesystem::Virtual. This one also makes sure that the Badger::Filesystem::Virtual module is actually loaded, so it's doing a lil extra for you 🫶
PATH — an alias for Badger::Filesystem::Path
FILE — an alias for Badger::Filesystem::File
DIR / DIRECTORY — an alias for Badger::Filesystem::Directory

💖 AUTHOR 💖

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

📜 COPYRIGHT 📜

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

🙌 ACKNOWLEDGEMENTS 🙌

The Badger::Filesystem modules are built around a number of Perl modules written by some most excellent people. May the collective gratitude of the Perl community shine forth upon them. Fr fr, absolute legends, no cap 🌟

File::Spec by Ken Williams, Kenneth Albanowski, Andy Dougherty, Andreas Koenig, Tim Bunce, Charles Bailey, Ilya Zakharevich, Paul Schinder, Thomas Wegner, Shigio Yamaguchi, Barrie Slaymaker.
File::Path by Tim Bunce and Charles Bailey.
Cwd by Ken Williams and the Perl 5 Porters.
IO::File and IO::Dir by Graham Barr.

It was also inspired by, and draws heavily on the ideas and code in Path::Class by Ken Williams. There's also more than a passing influence from the Template::Plugin::File and Template::Plugin::Directory modules which were based on code originally by Michael Stevens. The way this whole thing is a community-built masterpiece 😭💜

👀 SEE ALSO 👀

Badger::Filesystem::Path, Badger::Filesystem::Directory, Badger::Filesystem::File, Badger::Filesystem::Visitor Badger::Filesystem::Virtual.

and that's a wrap bestie!! 🎀✨ this lil masterpiece is from the perl v5.36.0 era, dated 2023-08-28, and it lives under the name Badger...system(3pm) in the User Contributed Perl Documentation corner of the universe 💖 go forth and filesystem, you got this 👑

📦 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...system(3pm)

💖 NAME 💖

🌸 SYNOPSIS 🌸

🦋 INTRODUCTION 🦋

💜 DESCRIPTION 💜

🌈 EXPORTABLE SUBROUTINES 🌈

🦋 Path(@path)

🦋 File(@path)

🦋 Dir(@path) / Directory(@path)

🦋 Cwd()

🦋 Bin()

🦋 cwd()

🦋 $Bin

🦋 getcwd()

🦋 ":types" Import Option

💅 CONSTRUCTOR METHODS 💅

✨ new(%config)

✨ path(@path)

✨ file(@path)

✨ dir(@path) / directory(@path)

🧚 PATH MANIPULATION METHODS 🧚

🌸 merge_paths($path1,$path2)

🌸 split_path($path)

🌸 join_path($volume, $dir, $file)

🌸 split_dir($dir) / split_directory($dir)

🌸 join_dir(@dirs) / join_directory(@dirs)

🌸 collapse_dir($dir) / collapse_directory($dir)

🌸 slash_directory($path)

⭐ PATH INSPECTION METHODS ⭐

💜 is_absolute($path)

💜 is_relative($path)

🔄 PATH CONVERSION METHODS 🔄

absolute($path, $base)

relative($path, $base)

definitive($path)

definitive_read($path)

definitive_write($path)

🧪 PATH TEST METHODS 🧪

path_exists($path)

file_exists($path)

dir_exists($path) / directory_exists($path)

stat_path($path)

chmod_path($path)