Provided by: libbadger-perl_0.16-3_all 
NAME
Badger::Filesystem - filesystem functionality
SYNOPSIS
The "Badger::Filesystem" module defines a number of importable constructor functions for
creating objects that represents files, directories and generic paths in a filesystem.
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 are simply shortcuts to "Badger::Filesystem" class methods.
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');
You can also create "Badger::Filesystem" objects.
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
This is the documentation for the "Badger::Filesystem" module. You probably don't need to
read it. If you're looking for an easy way to access and manipulate files and
directories, then all you need to know to get started is this:
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 used to create Badger::Filesystem::File and
Badger::Filesystem::Directory objects. You should read the documentation for those modules
first as they cover pretty much everything you need to know about working with files and
directories for simple day-to-day tasks. In fact, you should start with the documentation
for Badger::Filesystem::Path because that's the base class for both of them.
If you want to do something a little more involved than inspecting, reading and writing
files, or if you want to find out more about the filesystem functionality hidden behind
the file and directory objects, then read on!
DESCRIPTION
The "Badger::Filesystem" module defines an object class for accessing and manipulating
files and directories in a file system. It provides a number of methods that encapsulate
the behaviours of various 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 writing "Badger::Filesystem" over and over again, you can import the
"FS" symbol which is an alias to it (or you can define your own alias of course).
use Badger::Filesystem 'FS';
FS->is_relative('foo/bar/baz'); # true
FS->is_absolute('foo/bar/baz'); # false
The "Badger::Filesystem" module also defines methods that create objects to represent
files (Badger::Filesystem::File), directories (Badger::Filesystem::Directory), and generic
paths (Badger::Filesystem::Path) that may refer to a file, directory, or a resource that
doesn't physically exist (e.g. a URI).
These are very similar (although not identical) to the corresponding Path::Class modules
which you may already be familiar with. The main difference between them is that "Badger"
files, directories and paths are flyweight objects that call back to the
"Badger::Filesystem" to perform any filesystem operations. This gives us a more control
over restricting certain filesystem operations (e.g. writing files) and more flexibility
in what we define a filesystem to be (e.g. allowing virtually mounted and/or composite
file systems - see Badger::Filesystem::Virtual for further details).
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 to easily create
Badger::Filesystem::Path, Badger::Filesystem::File and Badger::Filesystem::Directory
objects, respectively. The Dir subroutine is provided as an alias for Directory.
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 provided as a convenient way to call the path(), file() and dir()
class methods. The above examples are functionally equivalent to those shown below.
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');
The constructor subroutines and the corresponding methods behind them accept a list (or
reference to a list) of path components as well as a single path string. This allows you
to specify paths in an operating system agnostic manner.
# 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']);
The above examples assume a Unix-like filesystem using "/" as the path separator. On a
windows machine, for example, you would need to specify paths using backslashes to satisfy
their brain-dead file system. However, specifying a list of separate path components
remains portable.
# if you're stuck on windows :-(
File('\path\to\file'); # OS specific
File('path', 'to', 'file'); # OS agnostic
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');
Creating an object allows you to define additional configuration parameters for the
filesystem. There aren't any interesting parameters worth mentioning in the base class
Badger::Filesystem module at the moment, but subclasses (like Badger::Filesystem::Virtual)
do use them.
EXPORTABLE SUBROUTINES
The "Badger::Filesystem" module defines the Path, File and Directory subroutines which can
be used to create Badger::Filesystem::Path, Badger::Filesystem::File and
Badger::Filesystem::Directory objects, respectively. The Dir subroutine is provided as an
alias for Directory.
To use these subroutines you must import them explicitly when you "use
Badger::Filesystem".
use Badger::Filesystem 'File Dir';
my $file = File('/path/to/file');
my $dir = Dir('/path/to/dir');
You can specify multiple items in a single string as shown in the example above, or as
multiple items in more traditional Perl style, as shown below.
use Badger::Filesystem qw(File Dir);
You can pass multiple arguments to these subroutines if you want to specify your path in a
platform-agnostic way.
my $file = File('path', 'to, 'file');
my $dir = Dir('path', 'to', 'dir');
A reference to a list works equally well.
my $file = File(['path', 'to, 'file']);
my $dir = Dir(\@paths);
If you don't provide any arguments then the subroutines return the class name associated
with the object. For example, the File() subroutine returns Badger::Filesystem::File. This
allows you to use them as virtual classes, (i.e. short-cuts) for the longer class names,
if doing things the Object Oriented way is your thing.
my $file = File->new('path/to/file');
my $dir = Dir->new('path/to/dir');
The above examples are functionally identical to:
my $file = Badger::Filesystem::File->new('path/to/file');
my $dir = Badger::Filesystem::Directory->new('path/to/dir');
A summary of the constructor subroutines follows.
Path(@path)
Creates a new Badger::Filesystem::Path object. You can specify the path as a single
string or list of path components.
$path = Path('/path/to/something');
$path = Path('path', 'to', 'something');
File(@path)
Creates a new Badger::Filesystem::File object. You can specify the path as a single
string or list of path components.
$file = File('/path/to/file');
$file = File('path', 'to', 'file');
Dir(@path) / Directory(@path)
Creates a new Badger::Filesystem::Directory object. You can specify the path as a single
string or list of path components.
$dir = Dir('/path/to/dir');
$dir = Dir('path', 'to', 'dir');
Cwd()
This returns a Badger::Filesystem::Directory object for the current working directory.
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 in which the
currently executing script is located. It is a simple wrapper around the value defined in
$Bin.
use Badger::Filesystem 'Bin';
print Bin; # /path/to/current/script
print Bin->parent; # /path/to/current
cwd()
This returns a simple text string representing the current working directory. It is a a
wrapper around the "getcwd" function in Cwd. It also sanitises the path (via the
canonpath() function in File::Spec) to ensure that the path is returned in the local
filesystem convention (e.g. "/" is converted to "\" on Win32).
$Bin
This load the FindBin module and exports the $Bin variable into the caller's namespace.
use Badger::Filesystem '$Bin';
use lib "$Bin/../lib";
This is exactly the same as:
use FindBin '$Bin';
use lib "$Bin/../lib";
One benefit is that you can use it in conjunction with other import options to save on a
little typing. For example:
use Badger::Filesystem 'Cwd File $Bin';
Compared to something like:
use Cwd;
use Path::Class;
use FindBin '$Bin';
use lib "$Bin/../lib";
getcwd()
This is a direct alias to the "getcwd" function in Cwd.
":types" Import Option
Specifying this an an import option will export all of the Path(), File, Dir, Directory
and Cwd subroutines to the caller.
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 a constructor method to create a new "Badger::Filesystem" object.
my $fs = Badger::Filesystem->new;
In most cases there's no need to create 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');
However, you might want to create a filesystem object to pass to some other method or
object to work with. In that case, the "Badger::Filesystem" methods work equally well
being called as object or class methods.
You may also want to use a subclass of "Badger::Filesystem" such as
Badger::Filesystem::Virtual which requires configuration parameters to be properly
initialised.
path(@path)
Creates a new Badger::Filesystem::Path object. This is typically used for 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.
dir() is an alias for directory() to save on typing.
# 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']);
If you don't specify a directory path explicitly then it will default to the current
working directory, as returned by cwd().
my $cwd = $fs->dir;
PATH MANIPULATION METHODS
merge_paths($path1,$path2)
Joins two paths into one.
$fs->merge_paths('/path/one', 'path/two'); # /path/one/path/two
No attempt will be made to verify that the second argument is an absolute path. In fact,
it is considered a feature that this method will do its best to merge two paths even if
they look like they shouldn't go together (this is particularly relevant when using
virtual filesystems - see Badger::Filesystem::Virtual)
$fs->merge_paths('/path/one', '/path/two'); # /path/one/path/two
If either defines a volume then it will be used as the volume for the combined path. If
both paths define a volume then it must be the same or an error will be thrown.
$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. This is 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), directory name and file name into a
single path. This is 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. This is a 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. This is a wrapper around the
catdir() function in File::Spec.
my $dir = $fs->join_dir('path', 'to', 'my', 'dir');
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
The reduction is purely syntactic. No attempt is made to verify that the directories
exist, or to intelligently resolve parent directory where symbolic links are involved.
Note that this may not work portably across all operating systems. If you're using a
Unix-based filesystem (including Mac OSX) or MS Windows then you should be OK. If you're
using an old MacOS machine (pre-OSX), VMS, or something made out of clockwork, then be
warned that this method is untested on those platforms.
"collapse_dir()" is a direct alias of "collapse_directory()" to save on typing.
slash_directory($path)
Returns the directory $path with a trailing "/" appended (or whatever the directory
separator is for your filesystem) if it doesn't already have one.
print $fs->slash_directory('foo'); # foo/
PATH INSPECTION METHODS
is_absolute($path)
Returns true if the path specified is absolute. That is, if 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 specified is relative. That is, if 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)
Converts a relative path to an absolute one. The path passed as an argument is assumed to
be relative to the current working directory unless you explicitly provide a $base
parameter.
$fs->cwd; # /foo/bar (for example)
$fs->absolute('baz'); # /foo/bar/baz
$fs->absolute('baz', '/wam/bam'); # /wam/bam/baz
Note how potentially confusing that last example is. The base path is the second argument
which ends up 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.
relative($path, $base)
Converts an absolute path to a relative one. It is 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)
Converts an absolute or relative path to a definitive one. In most cases, a definitive
path is identical to an absolute one.
$fs->definitive('/foo/bar'); # /foo/bar
However, 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.
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.
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.
Field Description
--------------------------------------------------------
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.
$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.
$fs->touch_file('/path/to/file');
delete_file($path)
Deletes a file.
$fs->delete_file('/path/to/file'); # 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)
This method creates a Badger::Filesystem::Visitor object from the arguments passed as a
list or reference to a hash array of named parameters.
# list of named parameters.
$fs->visitor( files => 1, dirs => 0 );
# reference to hash array of named parameters
$fs->visitor( files => 1, dirs => 0 );
If the first argument is already a reference to a Badger::Filesystem::Visitor object or
subclass then it will be returned unmodified.
visit(\%params)
This methods forwards all arguments onto the visit() method of the root() directory.
accept($visitor)
This lower-level method is called to dispatch a visitor to the correct method for a
filesystem object. It forward the visitor onto the accept() method for the root()
directory.
collect(\%params)
This is a short-cut to call the visit() method and then the collect() method on the
Badger::Filesystem::Visitor object returned.
# 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. This is a text string rather than a
Badger::Filesystem::Directory object. Call the Cwd() method if you want a
Badger::Filesystem::Directory object instead.
my $cwd = $fs->cwd;
root()
Returns a Badger::Filesystem::Directory object representing the root directory for the
filesystem.
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 used internally for
splitting and joining file paths.
EXPORTABLE CONSTANTS
FS
An alias for "Badger::Filesystem"
VFS
An alias for Badger::Filesystem::Virtual. This also ensures that the
Badger::Filesystem::Virtual module is loaded.
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
Copyright (C) 2005-2009 Andy Wardley. All rights reserved.
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.
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.
SEE ALSO
Badger::Filesystem::Path, Badger::Filesystem::Directory, Badger::Filesystem::File,
Badger::Filesystem::Visitor Badger::Filesystem::Virtual.