.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Badger::Filesystem 3pm"
.TH Badger::Filesystem 3pm "2023-08-28" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Badger::Filesystem \- filesystem functionality
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
The \f(CW\*(C`Badger::Filesystem\*(C'\fR module defines a number of importable constructor
functions for creating objects that represents files, directories and generic
paths in a filesystem.
.PP
.Vb 2
\&    use Badger::Filesystem \*(Aqcwd Cwd Path File Dir Directory\*(Aq;
\&    use Badger::Filesystem \*(Aqcwd :types\*(Aq;        # 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(\*(Aq/path/to/file/or/dir\*(Aq);
\&    $file = File(\*(Aq/path/to/file\*(Aq);
\&    $dir  = Dir(\*(Aq/path/to/directory\*(Aq);           # short name
\&    $dir  = Directory(\*(Aq/path/to/directory\*(Aq);     # long name
\&    
\&    # or generic OS\-independant paths
\&    $path = File(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq, \*(Aqor\*(Aq, \*(Aqdir\*(Aq);
\&    $file = File(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);
\&    $dir  = Dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdirectory\*(Aq);
\&    $dir  = Directory(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdirectory\*(Aq);
.Ve
.PP
These constructor functions are simply shortcuts to \f(CW\*(C`Badger::Filesystem\*(C'\fR
class methods.
.PP
.Vb 1
\&    use Badger::Filesystem;
\&    
\&    # we\*(Aqll just show native paths from now on for brevity
\&    $path = Badger::Filesystem\->path(\*(Aq/path/to/file/or/dir\*(Aq);
\&    $file = Badger::Filesystem\->file(\*(Aq/path/to/file\*(Aq);
\&    $dir  = Badger::Filesystem\->dir(\*(Aq/path/to/directory\*(Aq);
\&
\&    # \*(AqFS\*(Aq is an alias for \*(AqBadger::Filesystem\*(Aq 4 lzy ppl lk me
\&    use Badger::Filesystem \*(AqFS\*(Aq
\&    
\&    $path = FS\->path(\*(Aq/path/to/file/or/dir\*(Aq);
\&    $file = FS\->file(\*(Aq/path/to/file\*(Aq);
\&    $dir  = FS\->dir(\*(Aq/path/to/directory\*(Aq);
.Ve
.PP
You can also create \f(CW\*(C`Badger::Filesystem\*(C'\fR objects.
.PP
.Vb 1
\&    my $fs = Badger::Filesystem\->new;
\&    
\&    $path = $fs\->path(\*(Aq/path/to/file/or/dir\*(Aq);
\&    $file = $fs\->file(\*(Aq/path/to/file\*(Aq);
\&    $dir  = $fs\->dir(\*(Aq/path/to/directory\*(Aq);
.Ve
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
This is the documentation for the \f(CW\*(C`Badger::Filesystem\*(C'\fR 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:
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqFile Dir\*(Aq;
\&    
\&    my $file = File(\*(Aq/path/to/file\*(Aq);       # Badger::Filesystem::File
\&    my $dir  = Dir(\*(Aq/path/to/directory\*(Aq);   # Badger::Filesystem::Directory
.Ve
.PP
The \fBFile()\fR and \fBDir()\fR 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.
.PP
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!
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Badger::Filesystem\*(C'\fR 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:
.PP
.Vb 3
\&    # path manipulation
\&    my $dir  = Badger::Filesystem\->join_dir(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq);
\&    my @dirs = Badger::Filesystem\->split_dir(\*(Aqfoo/bar/baz\*(Aq);
\&    
\&    # path inspection
\&    Badger::Filesystem\->is_relative(\*(Aqfoo/bar/baz\*(Aq);     # true
\&    Badger::Filesystem\->is_absolute(\*(Aqfoo/bar/baz\*(Aq);     # false
\&    
\&    # file manipulation
\&    Badger::Filesystem\->write_file(\*(Aq/path/to/file\*(Aq, \*(AqHello World\*(Aq);
\&    Badger::Filesystem\->delete_file(\*(Aq/path/to/file\*(Aq)
\&    
\&    # directory manipulation
\&    Badger::Filesystem\->cwd;
\&    Badger::Filesystem\->mkdir(\*(Aq/path/to/dir\*(Aq)
.Ve
.PP
If you get tired of writing \f(CW\*(C`Badger::Filesystem\*(C'\fR over and over again,
you can import the \f(CW\*(C`FS\*(C'\fR symbol which is an alias to it (or you can define
your own alias of course).
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqFS\*(Aq;
\&    
\&    FS\->is_relative(\*(Aqfoo/bar/baz\*(Aq);     # true
\&    FS\->is_absolute(\*(Aqfoo/bar/baz\*(Aq);     # false
.Ve
.PP
The \f(CW\*(C`Badger::Filesystem\*(C'\fR 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 \s-1URI\s0).
.PP
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 \f(CW\*(C`Badger\*(C'\fR files, directories and paths are
\&\fIflyweight\fR objects that call back to the \f(CW\*(C`Badger::Filesystem\*(C'\fR 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).
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqFS\*(Aq;
\&    
\&    # file manipulation \- via Badger::Filesystem::File object
\&    my $file = FS\->file(\*(Aq/path/to/file\*(Aq);
\&    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(\*(Aq/path/to/dir\*(Aq);
\&    print $dir\->mode;                   # metadata
\&    print $dir\->modified;               # more metadata
\&    my @entries = $dir\->read;           # read directory entries
\&    my $file = $dir\->file(\*(Aqfoo\*(Aq);       # fetch a file
\&    my $sub  = $dir\->dir(\*(Aqbar\*(Aq);        # fetch a sub\-directory
.Ve
.PP
The module also defines the \fBPath()\fR, \fBFile()\fR and \fBDirectory()\fR
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.
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqPath File Dir\*(Aq;
\&    
\&    my $path = Path(\*(Aq/any/generic/path\*(Aq);
\&    my $file = File(\*(Aq/path/to/file\*(Aq);
\&    my $dir  = Dir(\*(Aq/path/to/dir\*(Aq);
.Ve
.PP
These subroutines are provided as a convenient way to call the \fBpath()\fR,
\&\fBfile()\fR and \fBdir()\fR class methods. The above examples are functionally
equivalent to those shown below.
.PP
.Vb 1
\&    use Badger::Filesystem;
\&    
\&    my $path = Badger::Filesystem\->path(\*(Aq/any/generic/path\*(Aq);
\&    my $file = Badger::Filesystem\->file(\*(Aq/path/to/file\*(Aq);
\&    my $dir  = Badger::Filesystem\->dir(\*(Aq/path/to/dir\*(Aq);
.Ve
.PP
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.
.PP
.Vb 4
\&    # these all do the same thing (assuming you\*(Aqre on a Unix\-like system)
\&    File(\*(Aq/path/to/file\*(Aq);          
\&    File(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);
\&    File([\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq]);
\&    
\&    # these too
\&    Badger::Filesystem\->file(\*(Aq/path/to/file\*(Aq);
\&    Badger::Filesystem\->file(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);
\&    Badger::Filesystem\->file([\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq]);
.Ve
.PP
The above examples assume a Unix-like filesystem using \f(CW\*(C`/\*(C'\fR 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.
.PP
.Vb 3
\&    # if you\*(Aqre stuck on windows :\-(
\&    File(\*(Aq\epath\eto\efile\*(Aq);                  # OS specific
\&    File(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);             # OS agnostic
.Ve
.PP
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.
.PP
You can also create a \f(CW\*(C`Badger::Filesystem\*(C'\fR object and call object methods
against it.
.PP
.Vb 1
\&    use Badger::Filesystem;
\&    
\&    my $fs   = Badger::Filesystem\->new;
\&    my $file = $fs\->file(\*(Aq/path/to/file\*(Aq);
\&    my $dir  = $fs\->dir(\*(Aq/path/to/dir\*(Aq);
.Ve
.PP
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.
.SH "EXPORTABLE SUBROUTINES"
.IX Header "EXPORTABLE SUBROUTINES"
The \f(CW\*(C`Badger::Filesystem\*(C'\fR 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.
.PP
To use these subroutines you must import them explicitly when you 
\&\f(CW\*(C`use Badger::Filesystem\*(C'\fR.
.PP
.Vb 3
\&    use Badger::Filesystem \*(AqFile Dir\*(Aq;
\&    my $file = File(\*(Aq/path/to/file\*(Aq);
\&    my $dir  = Dir(\*(Aq/path/to/dir\*(Aq);
.Ve
.PP
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.
.PP
.Vb 1
\&    use Badger::Filesystem qw(File Dir);
.Ve
.PP
You can pass multiple arguments to these subroutines if you want to specify
your path in a platform-agnostic way.
.PP
.Vb 2
\&    my $file = File(\*(Aqpath\*(Aq, \*(Aqto, \*(Aqfile\*(Aq);
\&    my $dir  = Dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdir\*(Aq);
.Ve
.PP
A reference to a list works equally well.
.PP
.Vb 2
\&    my $file = File([\*(Aqpath\*(Aq, \*(Aqto, \*(Aqfile\*(Aq]);
\&    my $dir  = Dir(\e@paths);
.Ve
.PP
If you don't provide any arguments then the subroutines return the class name
associated with the object. For example, the \fBFile()\fR 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.
.PP
.Vb 2
\&    my $file = File\->new(\*(Aqpath/to/file\*(Aq);
\&    my $dir  = Dir\->new(\*(Aqpath/to/dir\*(Aq);
.Ve
.PP
The above examples are functionally identical to:
.PP
.Vb 2
\&    my $file = Badger::Filesystem::File\->new(\*(Aqpath/to/file\*(Aq);
\&    my $dir  = Badger::Filesystem::Directory\->new(\*(Aqpath/to/dir\*(Aq);
.Ve
.PP
A summary of the constructor subroutines follows.
.SS "Path(@path)"
.IX Subsection "Path(@path)"
Creates a new Badger::Filesystem::Path object.  You can specify the 
path as a single string or list of path components.
.PP
.Vb 2
\&    $path = Path(\*(Aq/path/to/something\*(Aq);
\&    $path = Path(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqsomething\*(Aq);
.Ve
.SS "File(@path)"
.IX Subsection "File(@path)"
Creates a new Badger::Filesystem::File object.  You can specify the 
path as a single string or list of path components.
.PP
.Vb 2
\&    $file = File(\*(Aq/path/to/file\*(Aq);
\&    $file = File(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);
.Ve
.SS "Dir(@path) / Directory(@path)"
.IX Subsection "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.
.PP
.Vb 2
\&    $dir = Dir(\*(Aq/path/to/dir\*(Aq);
\&    $dir = Dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdir\*(Aq);
.Ve
.SS "\fBCwd()\fP"
.IX Subsection "Cwd()"
This returns a Badger::Filesystem::Directory object for the current
working directory.
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqCwd\*(Aq;
\&    
\&    print Cwd;              # /foraging/for/nuts/and/berries
\&    print Cwd\->parent;      # /foraging/for/nuts/and
.Ve
.SS "\fBBin()\fP"
.IX Subsection "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 \f(CW$Bin\fR.
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqBin\*(Aq;
\&    
\&    print Bin;              # /path/to/current/script
\&    print Bin\->parent;      # /path/to/current
.Ve
.SS "\fBcwd()\fP"
.IX Subsection "cwd()"
This returns a simple text string representing the current working directory.
It is a a wrapper around the \f(CW\*(C`getcwd\*(C'\fR function in Cwd.  It also 
sanitises the path (via the \fBcanonpath()\fR function
in File::Spec) to ensure that the path is returned in the local 
filesystem convention (e.g. \f(CW\*(C`/\*(C'\fR is converted to \f(CW\*(C`\e\*(C'\fR on Win32).
.ie n .SS "$Bin"
.el .SS "\f(CW$Bin\fP"
.IX Subsection "$Bin"
This load the FindBin module and exports the \f(CW$Bin\fR variable into 
the caller's namespace.
.PP
.Vb 2
\&    use Badger::Filesystem \*(Aq$Bin\*(Aq;
\&    use lib "$Bin/../lib";
.Ve
.PP
This is exactly the same as:
.PP
.Vb 2
\&    use FindBin \*(Aq$Bin\*(Aq;
\&    use lib "$Bin/../lib";
.Ve
.PP
One benefit is that you can use it in conjunction with other import options
to save on a little typing.  For example:
.PP
.Vb 1
\&    use Badger::Filesystem \*(AqCwd File $Bin\*(Aq;
.Ve
.PP
Compared to something like:
.PP
.Vb 4
\&    use Cwd;
\&    use Path::Class;
\&    use FindBin \*(Aq$Bin\*(Aq;
\&    use lib "$Bin/../lib";
.Ve
.SS "\fBgetcwd()\fP"
.IX Subsection "getcwd()"
This is a direct alias to the \f(CW\*(C`getcwd\*(C'\fR function in Cwd.
.ie n .SS """:types"" Import Option"
.el .SS "\f(CW:types\fP Import Option"
.IX Subsection ":types Import Option"
Specifying this an an import option will export all of the \fBPath()\fR, 
File, Dir, Directory and Cwd subroutines to the caller.
.PP
.Vb 1
\&    use Badger::Filesystem \*(Aq:types\*(Aq;
\&    
\&    my $path   = Path(\*(Aq/some/where\*(Aq);
\&    my $dir    = Dir(\*(Aq/over/there\*(Aq);
\&    my $file   = File(\*(Aqexample.html\*(Aq);
\&    my $parent = Cwd\->parent;
.Ve
.SH "CONSTRUCTOR METHODS"
.IX Header "CONSTRUCTOR METHODS"
.SS "new(%config)"
.IX Subsection "new(%config)"
This is a constructor method to create a new \f(CW\*(C`Badger::Filesystem\*(C'\fR object.
.PP
.Vb 1
\&    my $fs = Badger::Filesystem\->new;
.Ve
.PP
In most cases there's no need to create a \f(CW\*(C`Badger::Filesystem\*(C'\fR object at
all.  You can either call class methods, like this:
.PP
.Vb 1
\&    my $file = Badger::Filesystem\->file(\*(Aq/path/to/file\*(Aq);
.Ve
.PP
Or use the constructor subroutines like this:
.PP
.Vb 2
\&    use Badger::Filesystem \*(AqFile\*(Aq;
\&    my $file = File(\*(Aq/path/to/file\*(Aq);
.Ve
.PP
However, you might want to create a filesystem object to pass to some other
method or object to work with.  In that case, the \f(CW\*(C`Badger::Filesystem\*(C'\fR 
methods work equally well being called as object or class methods.
.PP
You may also want to use a subclass of \f(CW\*(C`Badger::Filesystem\*(C'\fR such as 
Badger::Filesystem::Virtual which requires configuration parameters
to be properly initialised.
.SS "path(@path)"
.IX Subsection "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.
.PP
.Vb 2
\&    # single path (platform specific)
\&    my $path = $fs\->path(\*(Aq/path/to/something\*(Aq);
\&    
\&    # list or list ref of path components (platform agnostic)
\&    my $path = $fs\->path(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqsomething\*(Aq);
\&    my $path = $fs\->path([\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqsomething\*(Aq]);
.Ve
.SS "file(@path)"
.IX Subsection "file(@path)"
Creates a new Badger::Filesystem::File object to represent a file in a 
filesystem.
.PP
.Vb 2
\&    # single file path (platform specific)
\&    my $file = $fs\->file(\*(Aq/path/to/file\*(Aq);
\&    
\&    # list or list ref of file path components (platform agnostic)
\&    my $file = $fs\->file(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq);
\&    my $file = $fs\->file([\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqfile\*(Aq]);
.Ve
.SS "dir(@path) / directory(@path)"
.IX Subsection "dir(@path) / directory(@path)"
Creates a new Badger::Filesystem::Directory object to represent a file in a
filesystem.  \fBdir()\fR is an alias for \fBdirectory()\fR to save on typing.
.PP
.Vb 2
\&    # single directory path (platform specific)
\&    my $dir = $fs\->dir(\*(Aq/path/to/directory\*(Aq);
\&
\&    # list or list ref of directory path components (platform agnostic)
\&    my $dir = $fs\->dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdirectory\*(Aq);
\&    my $dir = $fs\->dir([\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqdirectory\*(Aq]);
.Ve
.PP
If you don't specify a directory path explicitly then it will default to 
the current working directory, as returned by \fBcwd()\fR.
.PP
.Vb 1
\&    my $cwd = $fs\->dir;
.Ve
.SH "PATH MANIPULATION METHODS"
.IX Header "PATH MANIPULATION METHODS"
.SS "merge_paths($path1,$path2)"
.IX Subsection "merge_paths($path1,$path2)"
Joins two paths into one.
.PP
.Vb 1
\&    $fs\->merge_paths(\*(Aq/path/one\*(Aq, \*(Aqpath/two\*(Aq);      # /path/one/path/two
.Ve
.PP
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)
.PP
.Vb 1
\&    $fs\->merge_paths(\*(Aq/path/one\*(Aq, \*(Aq/path/two\*(Aq);     # /path/one/path/two
.Ve
.PP
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.
.PP
.Vb 3
\&    $fs\->merge_paths(\*(AqC:\epath\eone\*(Aq, \*(Aqpath\etwo\*(Aq);    # C:\epath\eone\epath\etwo
\&    $fs\->merge_paths(\*(Aq\epath\eone\*(Aq, \*(AqC:\epath\etwo\*(Aq);   # C:\epath\eone\epath\etwo
\&    $fs\->merge_paths(\*(AqC:\epath\eone\*(Aq, \*(AqC:\epath\etwo\*(Aq); # C:\epath\eone\epath\etwo
.Ve
.SS "split_path($path)"
.IX Subsection "split_path($path)"
Splits a composite path into volume, directory name and file name components.
This is a wrapper around the \fBsplitpath()\fR function 
in File::Spec.
.PP
.Vb 1
\&    ($vol, $dir, $file) = $fs\->split_path($path);
.Ve
.ie n .SS "join_path($volume, $dir, $file)"
.el .SS "join_path($volume, \f(CW$dir\fP, \f(CW$file\fP)"
.IX Subsection "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 
\&\fBcatpath()\fR and \fBcanonpath()\fR 
functions in File::Spec.
.PP
.Vb 1
\&    my $path = $fs\->join_path($volume, $directory, $file);
.Ve
.SS "split_dir($dir) / split_directory($dir)"
.IX Subsection "split_dir($dir) / split_directory($dir)"
Splits a directory path into individual directory names.  This is a wrapper
around the \fBsplitdir()\fR function in File::Spec.
.PP
.Vb 1
\&    @dirs = $fs\->split_dir($dir);
.Ve
.SS "join_dir(@dirs) / join_directory(@dirs)"
.IX Subsection "join_dir(@dirs) / join_directory(@dirs)"
Combines multiple directory names into a single path.  This is a wrapper
around the \fBcatdir()\fR function in File::Spec.
.PP
.Vb 1
\&    my $dir = $fs\->join_dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqmy\*(Aq, \*(Aqdir\*(Aq);
.Ve
.PP
The final element can also be a file name.   \s-1TODO:\s0 is that portable?
.PP
.Vb 1
\&    my $dir = $fs\->join_dir(\*(Aqpath\*(Aq, \*(Aqto\*(Aq, \*(Aqmy\*(Aq, \*(Aqfile\*(Aq);
.Ve
.SS "collapse_dir($dir) / collapse_directory($dir)"
.IX Subsection "collapse_dir($dir) / collapse_directory($dir)"
Reduces a directory to its simplest form by resolving and removing any \f(CW\*(C`.\*(C'\fR
(current directory) and \f(CW\*(C`..\*(C'\fR (parent directory) components (or whatever the
corresponding tokens are for the current and parent directories of your
filesystem).
.PP
.Vb 1
\&    print $fs\->collapse_dir(\*(Aq/foo/bar/../baz\*(Aq);   # /foo/baz
.Ve
.PP
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.
.PP
Note that this may not work portably across all operating systems.  If you're
using a Unix-based filesystem (including Mac \s-1OSX\s0) or \s-1MS\s0 Windows then you 
should be \s-1OK.\s0  If you're using an old MacOS machine (pre-OSX), \s-1VMS,\s0 or 
something made out of clockwork, then be warned that this method is untested
on those platforms.
.PP
\&\f(CW\*(C`collapse_dir()\*(C'\fR is a direct alias of \f(CW\*(C`collapse_directory()\*(C'\fR to save on 
typing.
.SS "slash_directory($path)"
.IX Subsection "slash_directory($path)"
Returns the directory \f(CW$path\fR with a trailing \f(CW\*(C`/\*(C'\fR appended (or whatever
the directory separator is for your filesystem) if it doesn't already 
have one.
.PP
.Vb 1
\&    print $fs\->slash_directory(\*(Aqfoo\*(Aq);      # foo/
.Ve
.SH "PATH INSPECTION METHODS"
.IX Header "PATH INSPECTION METHODS"
.SS "is_absolute($path)"
.IX Subsection "is_absolute($path)"
Returns true if the path specified is absolute.  That is, if it starts
with a \f(CW\*(C`/\*(C'\fR, or whatever the corresponding token for the root directory is
for your file system.
.PP
.Vb 2
\&    $fs\->is_absolute(\*(Aq/foo\*(Aq);               # true
\&    $fs\->is_absolute(\*(Aqfoo\*(Aq);                # false
.Ve
.SS "is_relative($path)"
.IX Subsection "is_relative($path)"
Returns true if the path specified is relative. That is, if it does not start
with a \f(CW\*(C`/\*(C'\fR, or whatever the corresponding token for the root directory is for
your file system.
.PP
.Vb 2
\&    $fs\->is_relative(\*(Aq/foo\*(Aq);               # false
\&    $fs\->is_relative(\*(Aqfoo\*(Aq);                # true
.Ve
.SH "PATH CONVERSION METHODS"
.IX Header "PATH CONVERSION METHODS"
.ie n .SS "absolute($path, $base)"
.el .SS "absolute($path, \f(CW$base\fP)"
.IX Subsection "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 \f(CW$base\fR parameter.
.PP
.Vb 3
\&    $fs\->cwd;                               # /foo/bar  (for example)
\&    $fs\->absolute(\*(Aqbaz\*(Aq);                   # /foo/bar/baz
\&    $fs\->absolute(\*(Aqbaz\*(Aq, \*(Aq/wam/bam\*(Aq);       # /wam/bam/baz
.Ve
.PP
Note how potentially confusing that last example is. The base path is the
\&\fIsecond\fR argument which ends up in front of the \fIfirst\fR 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.
.ie n .SS "relative($path, $base)"
.el .SS "relative($path, \f(CW$base\fP)"
.IX Subsection "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 \f(CW$base\fR
parameter.
.PP
.Vb 3
\&    $fs\->cwd;                               # /foo/bar  (for example)
\&    $fs\->relative(\*(Aq/foo/bar/wam/bam\*(Aq);      # wam/bam
\&    $fs\->relative(\*(Aq/baz/wam/bam\*(Aq, \*(Aq/baz\*(Aq);  # wam/bam
.Ve
.PP
Again note that last example where
.SS "definitive($path)"
.IX Subsection "definitive($path)"
Converts an absolute or relative path to a definitive one.  In most cases,
a definitive path is identical to an absolute one.
.PP
.Vb 1
\&    $fs\->definitive(\*(Aq/foo/bar\*(Aq);            # /foo/bar
.Ve
.PP
However, if you're using a virtual filesystem
with a virtual root directory, then a \fIdefinitive\fR path \fIwill\fR include the
virtual root directory, whereas a an \fIabsolute\fR path will \fInot\fR.
.PP
.Vb 3
\&    my $vfs = Badger::Filesystem::Virtual\->new( root => \*(Aq/my/vfs\*(Aq );
\&    $vfs\->absolute(\*(Aq/foo/bar\*(Aq);              # /foo/bar
\&    $vfs\->definitive(\*(Aq/foo/bar\*(Aq);            # /my/vfs/foo/bar
.Ve
.PP
The \f(CW\*(C`Badger::Filesystem\*(C'\fR 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.
.PP
In the \f(CW\*(C`Badger::Filesystem\*(C'\fR base class, the \f(CW\*(C`definitive()\*(C'\fR method is
mapped directly to the \fBdefinitive_write()\fR method.  This has no real
effect in this module, but provides the relevant hooks that allow the 
Badger::Filesystem::Virtual subclass to work properly.
.SS "definitive_read($path)"
.IX Subsection "definitive_read($path)"
Converts an absolute or relative path to a definitive one for a read
operation.  See \fBdefinitive()\fR.
.SS "definitive_write($path)"
.IX Subsection "definitive_write($path)"
Converts an absolute or relative path to a definitive one for a write 
operation.  See \fBdefinitive()\fR.
.SH "PATH TEST METHODS"
.IX Header "PATH TEST METHODS"
.SS "path_exists($path)"
.IX Subsection "path_exists($path)"
Returns true if the path exists, false if not.
.SS "file_exists($path)"
.IX Subsection "file_exists($path)"
Returns true if the path exists and is a file, false if not.
.SS "dir_exists($path) / directory_exists($path)"
.IX Subsection "dir_exists($path) / directory_exists($path)"
Returns true if the path exists and is a directory, false if not.
.SS "stat_path($path)"
.IX Subsection "stat_path($path)"
Performs a \f(CW\*(C`stat()\*(C'\fR 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 \f(CW\*(C`stat()\*(C'\fR 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.
.PP
A summary of the fields is shown below. See \f(CW\*(C`perldoc \-f stat\*(C'\fR and the
\&\fBstat()\fR method in
Badger::Filesystem::Path for further details.
.PP
.Vb 10
\&    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
.Ve
.SS "chmod_path($path)"
.IX Subsection "chmod_path($path)"
Changes the file permissions on a path.
.PP
.Vb 1
\&    $fs\->chmod_path(\*(Aq/path/to/file\*(Aq, 0755);
.Ve
.SH "FILE MANIPULATION METHODS"
.IX Header "FILE MANIPULATION METHODS"
.SS "create_file($path)"
.IX Subsection "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.
.PP
.Vb 1
\&    $fs\->create_file(\*(Aq/path/to/file\*(Aq);
.Ve
.SS "touch_file($path) / touch($path)"
.IX Subsection "touch_file($path) / touch($path)"
Creates a file if it doesn't exists, or updates the timestamp if it does.
.PP
.Vb 1
\&    $fs\->touch_file(\*(Aq/path/to/file\*(Aq);
.Ve
.SS "delete_file($path)"
.IX Subsection "delete_file($path)"
Deletes a file.
.PP
.Vb 1
\&    $fs\->delete_file(\*(Aq/path/to/file\*(Aq);      # Careful with that axe, Eugene!
.Ve
.ie n .SS "open_file($path, $mode, $perms)"
.el .SS "open_file($path, \f(CW$mode\fP, \f(CW$perms\fP)"
.IX Subsection "open_file($path, $mode, $perms)"
Opens a file for reading (by default) or writing/appending (by passing
\&\f(CW$mode\fR and optionally \f(CW$perms\fR). Accepts the same parameters as for the
\&\fBIO::File::open()\fR method and returns an IO::File object.
.PP
.Vb 3
\&    my $fh = $fs\->open_file(\*(Aq/path/to/file\*(Aq);
\&    my $fh = $fs\->open_file(\*(Aq/path/to/file\*(Aq, \*(Aqw\*(Aq);      
\&    my $fh = $fs\->open_file(\*(Aq/path/to/file\*(Aq, \*(Aqw\*(Aq, 0644);
.Ve
.SS "read_file($path)"
.IX Subsection "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).
.PP
.Vb 2
\&    my $text  = $fs\->read_file(\*(Aq/path/to/file\*(Aq);
\&    my @lines = $fs\->read_file(\*(Aq/path/to/file\*(Aq);
.Ve
.ie n .SS "write_file($path, @content)"
.el .SS "write_file($path, \f(CW@content\fP)"
.IX Subsection "write_file($path, @content)"
When called with a single \f(CW$path\fR argument, this method opens the specified 
file for writing and returns an IO::File object.
.PP
.Vb 3
\&    my $fh = $fs\->write_file(\*(Aq/path/to/file\*(Aq);
\&    $fh\->print("Hello World!\en");
\&    $fh\->close;
.Ve
.PP
If any additional \f(CW@content\fR 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.
.PP
.Vb 1
\&    $fs\->write_file(\*(Aq/path/to/file\*(Aq, "Hello World\en", "Regards, Badger\en");
.Ve
.ie n .SS "append_file($path, @content)"
.el .SS "append_file($path, \f(CW@content\fP)"
.IX Subsection "append_file($path, @content)"
This method is similar to \fBwrite_file()\fR, but opens the file for appending
instead of overwriting.  When called with a single \f(CW$path\fR argument, it opens 
the file for appending and returns an IO::File object.
.PP
.Vb 3
\&    my $fh = $fs\->append_file(\*(Aq/path/to/file\*(Aq);
\&    $fh\->print("Hello World!\en");
\&    $fh\->close;
.Ve
.PP
If any additional \f(CW@content\fR 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.
.PP
.Vb 1
\&    $fs\->append_file(\*(Aq/path/to/file\*(Aq, "Hello World\en", "Regards, Badger\en");
.Ve
.ie n .SS "copy_file($from, $to, %params)"
.el .SS "copy_file($from, \f(CW$to\fP, \f(CW%params\fP)"
.IX Subsection "copy_file($from, $to, %params)"
Copies a file from the \f(CW$from\fR path to the \f(CW$to\fR path, using File::Copy
.PP
.Vb 1
\&    $fs\->copy_file($from, $to);
.Ve
.PP
The \f(CW$from\fR and \f(CW$to\fR arguments can be file names, file objects, or file
handles.
.PP
An optional list or reference to a hash array of named parameters can follow
the file names.  The \f(CW\*(C`mkdir\*(C'\fR option can be set to indicate that 
the destination direction should be created if it doesn't already exist,
along with any intermediate directories.
.PP
.Vb 1
\&    $fs\->copy_file($from, $to, mkdir => 1);
.Ve
.PP
The \f(CW\*(C`dir_mode\*(C'\fR parameter can be used to specify the octal file 
permissions for any directories created.
.PP
.Vb 1
\&    $fs\->copy_file($from, $to, 1, mkdir => 1, dir_mode => 0770);
.Ve
.PP
The \f(CW\*(C`file_mode\*(C'\fR parameter (or \f(CW\*(C`mode\*(C'\fR for short) can be used to specify the
octal file permissions for the created file.
.PP
.Vb 1
\&    $fs\->copy_file($from, $to, file_mode => 0644);
.Ve
.ie n .SS "move_file($from, $to, %params)"
.el .SS "move_file($from, \f(CW$to\fP, \f(CW%params\fP)"
.IX Subsection "move_file($from, $to, %params)"
Moves a file from the \f(CW$from\fR path to the \f(CW$to\fR path, using File::Copy.
The arguments are as per \fBcopy_file()\fR.
.SH "DIRECTORY MANIPULATION METHODS"
.IX Header "DIRECTORY MANIPULATION METHODS"
.SS "create_dir($path) / create_directory($path) / mkdir($path)"
.IX Subsection "create_dir($path) / create_directory($path) / mkdir($path)"
Creates the directory specified by \f(CW$path\fR. Errors are thrown as exceptions.
.PP
.Vb 1
\&    $fs\->create_dir(\*(Aq/path/to/directory\*(Aq);
.Ve
.PP
Additional arguments can be specified as per the File::Path \f(CW\*(C`mkpath()\*(C'\fR
method. \s-1NOTE:\s0 this is subject to change. Better to use \f(CW\*(C`File::Path\*(C'\fR directly
for now if you're relying on this.
.SS "delete_dir($path) / delete_directory($path) / rmdir($path)"
.IX Subsection "delete_dir($path) / delete_directory($path) / rmdir($path)"
Deletes the directory specified by \f(CW$path\fR. Errors are thrown as exceptions.
.PP
.Vb 1
\&    $fs\->delete_dir(\*(Aq/path/to/directory\*(Aq);
.Ve
.SS "open_dir($path) / open_directory($path)"
.IX Subsection "open_dir($path) / open_directory($path)"
Returns an IO::Dir handle opened for reading a directory or throws
an error if the open failed.
.PP
.Vb 4
\&    my $dh = $fs\->open_dir(\*(Aq/path/to/directory\*(Aq);
\&    while (defined ($path = $dh\->read)) {
\&        print " \- $path\en";
\&    }
.Ve
.ie n .SS "read_dir($dir, $all) / read_directory($dir, $all)"
.el .SS "read_dir($dir, \f(CW$all\fP) / read_directory($dir, \f(CW$all\fP)"
.IX Subsection "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.
.PP
.Vb 1
\&    my @paths = $fs\->read_dir(\*(Aq/path/to/directory\*(Aq);
.Ve
.PP
By default, this excludes the current and parent entries (\f(CW\*(C`.\*(C'\fR and \f(CW\*(C`..\*(C'\fR or
whatever the equivalents are for your filesystem. Pass a true value for the
optional second argument to include these items.
.PP
.Vb 1
\&    my @paths = $fs\->read_dir(\*(Aq/path/to/directory\*(Aq, 1);
.Ve
.ie n .SS "dir_children($dir, $all) / directory_children($dir, $all)"
.el .SS "dir_children($dir, \f(CW$all\fP) / directory_children($dir, \f(CW$all\fP)"
.IX Subsection "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
\&\fBread_dir()\fR, the current (\f(CW\*(C`.\*(C'\fR) and parent (\f(CW\*(C`..\*(C'\fR) directories
are excluded unless you set the \f(CW$all\fR 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.
.SS "dir_child($path) / directory_child($path)"
.IX Subsection "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.
.SH "TEMPORARY DIRECTORY AND FILE METHODS"
.IX Header "TEMPORARY DIRECTORY AND FILE METHODS"
.SS "temp_dir($dir) / temp_directory($dir)"
.IX Subsection "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 \f(CW\*(C`tmpdir\*(C'\fR in File::Spec).
.PP
.Vb 1
\&    my $tmp = $fs\->temp_dir;
.Ve
.PP
If any arguments are specified then they are appended as sub-directories to
the temporary directory path.
.PP
.Vb 1
\&    my $tmp = $fs\->temp_dir(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);  # e.g. /tmp/foo/bar
.Ve
.SS "temp_file($name)"
.IX Subsection "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 \fBtemp_directory()\fR
method.
.PP
.Vb 1
\&    my $file = $fs\->temp_file(\*(Aqfoo.tmp\*(Aq);   # e.g. /tmp/foo.tmp
.Ve
.SH "VISITOR METHODS"
.IX Header "VISITOR METHODS"
.SS "visitor(\e%params)"
.IX Subsection "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.
.PP
.Vb 2
\&    # list of named parameters.
\&    $fs\->visitor( files => 1, dirs => 0 );
\&    
\&    # reference to hash array of named parameters
\&    $fs\->visitor( files => 1, dirs => 0 );
.Ve
.PP
If the first argument is already a reference to a
Badger::Filesystem::Visitor object or subclass then it will be returned
unmodified.
.SS "visit(\e%params)"
.IX Subsection "visit(%params)"
This methods forwards all arguments onto the
\&\fBvisit()\fR method of the 
\&\fBroot()\fR directory.
.SS "accept($visitor)"
.IX Subsection "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
\&\fBaccept()\fR method for the \fBroot()\fR
directory.
.SS "collect(\e%params)"
.IX Subsection "collect(%params)"
This is a short-cut to call the \fBvisit()\fR method and then the 
\&\fBcollect()\fR method on the 
Badger::Filesystem::Visitor object returned.
.PP
.Vb 2
\&    # short form
\&    my @items = $fs\->collect( files => 1, dirs => 0 );
\&
\&    # long form
\&    my @items = $fs\->visit( files => 1, dirs => 0 )\->collect;
.Ve
.SH "MISCELLANEOUS METHODS"
.IX Header "MISCELLANEOUS METHODS"
.SS "\fBcwd()\fP"
.IX Subsection "cwd()"
Returns the current working directory. This is a text string rather than a
Badger::Filesystem::Directory object. Call the \fBCwd()\fR method
if you want a Badger::Filesystem::Directory object instead.
.PP
.Vb 1
\&    my $cwd = $fs\->cwd;
.Ve
.SS "\fBroot()\fP"
.IX Subsection "root()"
Returns a Badger::Filesystem::Directory object representing the root
directory for the filesystem.
.SS "rootdir"
.IX Subsection "rootdir"
Returns a text string containing the representation of the root directory
for your filesystem.
.PP
.Vb 1
\&    print $fs\->rootdir;             # e.g. \*(Aq/\*(Aq on Unix\-based file systems
.Ve
.SS "updir"
.IX Subsection "updir"
Returns a text string containing the representation of the parent directory
for your filesystem.
.PP
.Vb 1
\&    print $fs\->updir;               # e.g. \*(Aq..\*(Aq on Unix\-based file systems
.Ve
.SS "curdir"
.IX Subsection "curdir"
Returns a text string containing the representation of the current directory
for your filesystem.
.PP
.Vb 1
\&    print $fs\->curdir;              # e.g. \*(Aq.\*(Aq on Unix\-based file systems
.Ve
.SS "separator"
.IX Subsection "separator"
Returns a text string containing the representation of the path separator
for your filesystem.
.PP
.Vb 1
\&    print $fs\->separator;           # e.g. \*(Aq/\*(Aq on Unix\-based file systems
.Ve
.SS "spec"
.IX Subsection "spec"
Returns a text string containing the class name of \f(CW\*(C`File::Spec\*(C'\fR or some 
other user-definable module that implements the same functionality.  This
is used internally for splitting and joining file paths.
.SH "EXPORTABLE CONSTANTS"
.IX Header "EXPORTABLE CONSTANTS"
.SS "\s-1FS\s0"
.IX Subsection "FS"
An alias for \f(CW\*(C`Badger::Filesystem\*(C'\fR
.SS "\s-1VFS\s0"
.IX Subsection "VFS"
An alias for Badger::Filesystem::Virtual.  This also ensures that the
Badger::Filesystem::Virtual module is loaded.
.SS "\s-1PATH\s0"
.IX Subsection "PATH"
An alias for \f(CW\*(C`Badger::Filesystem::Path\*(C'\fR
.SS "\s-1FILE\s0"
.IX Subsection "FILE"
An alias for \f(CW\*(C`Badger::Filesystem::File\*(C'\fR
.SS "\s-1DIR / DIRECTORY\s0"
.IX Subsection "DIR / DIRECTORY"
An alias for \f(CW\*(C`Badger::Filesystem::Directory\*(C'\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <http://wardley.org/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2005\-2009 Andy Wardley. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
The \f(CW\*(C`Badger::Filesystem\*(C'\fR 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.
.PP
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.
.PP
File::Path by Tim Bunce and Charles Bailey.
.PP
Cwd by Ken Williams and the Perl 5 Porters.
.PP
IO::File and IO::Dir by Graham Barr.
.PP
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 \f(CW\*(C`Template::Plugin::File\*(C'\fR and \f(CW\*(C`Template::Plugin::Directory\*(C'\fR
modules which were based on code originally by Michael Stevens.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Badger::Filesystem::Path, 
Badger::Filesystem::Directory,
Badger::Filesystem::File,
Badger::Filesystem::Visitor
Badger::Filesystem::Virtual.