new($path)

    # single text string
    $path = Badger::Filesystem::Path->new('/path/to/something');

    # reference to list
    $path = Badger::Filesystem::Path->new(['path', 'to', 'something']);

It can also be specified as a "path" named parameter.

    # named parameter list
    $path = Badger::Filesystem::Path->new(
        path => '/path/to/something'
    );

    # reference to hash of named parameter(s)
    $path = Badger::Filesystem::Path->new({
        path => '/path/to/something'
    });

The constructor method also recognises the "filesystem" named parameter which can contain a reference to the Badger::Filesystem object or class that created it. In most cases you can rely on the Badger::Filesystem to create path objects for you, using either the path() method, or the Path() subroutine.

    use Badger::Filesystem 'FS Path';

    # FS is alias for 'Badger::Filesystem'
    # Path() is constructor subrooutine
    my $path;

    # using the path() method
    $path = FS->path('/path/to/something');
    $path = FS->path('path', 'to', 'something');
    $path = FS->path(['path', 'to', 'something']);

    # using the Path() subroutine
    $path = Path('/path/to/something');
    $path = Path('path', 'to', 'something');
    $path = Path(['path', 'to', 'something']);

The examples that follow will use the "Path()" constructor subroutine.

init(\%config)

path()

is_absolute()

is_relative()

absolute($base)

    # assume cwd is /foo/bar,
    my $path = Path('/baz/bam');

    print $path->absolute;                  # /foo/bar/baz/bam
    print $path->absolute('/wiz');          # /wiz/baz/bam

relative($base)

    # assume cwd is /foo/bar,
    my $path = Path('/foo/bar/baz/bam');

    print $path->relative;                  # /baz/bam
    print $path->relative('/foo');          # /bar/baz/bam

definitive()

However, if you're using a virtual filesystem, then the definitive path will include the virtual root directory, whereas a the absolute path will not.

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

canonical()

    print Path('foo')->canonical;               # /your/current/path/foo
    print Path('/foo/bar')->canonical;          # /foo/bar
    print Path('/foo/bar/')->canonical;         # /foo/bar
    print Path('/foo/bar.txt')->canonical;      # /foo/bar.txt

Note that the "Badger::Filesystem::Path" base class will remove any trailing slashes (or whatever the appropriate directory separator is for your filesystem) from the end of an absolute path.

In the case of directories, implemented by the Badger::Filesystem::Directory subclass, a trailing slash (or relevant separator for your filesystem) will be added.

    print Dir('/foo/bar')->canonical;          # /foo/bar/

This is done by delegation to the slash_directory() method in Badger::Filesystem.

collapse()

    my $path = Path('/foo/bar/../baz')->collapse;
    print $path;   # /foo/baz

See the collapse_dir() method in Badger::Filesystem for further information.

above($child)

    my $parent = Path('/foo/bar');
    my $child  = Path('/foo/bar/baz');
    $parent->above($child);                 # true

This is implemented as a simple prefix match. That is, the parent path must appear at the start of the child path. Consequently, this method will not account for symbolic links or other similar filesystem features, and it may not work properly on systems that don't follow this convention (although there are none that I'm aware of).

below($parent)

    my $parent = Path('/foo/bar');
    my $child  = Path('/foo/bar/baz');
    $child->below($parent);                 # true

Like above(), this is implemented using a simple prefix match.

base()

    print Path('/foo/bar')->base;           # /foo/bar
    print Directory('/foo/bar')->base;      # /foo/bar

However the Badger::Filesystem::File module returns the parent directory in which the file is located.

    print File('/foo/bar')->base;           # /foo

parent($skip_generations) / up($skip_generations)

    Path->('/foo/bar')->parent;             # path object for /foo

A numerical argument can be provided to indicate the number of generation you want to skip. A value of 0 is the same as providing no argument - it returns the parent. A value of 1 skips the parent and returns the grand-parent, and so on.

    Path->('/foo/bar/baz/bam')->parent(2);  # path object for /foo

The root directory will be returned if you try to skip too many generations.

    Path->('/foo/bar/baz/bam')->parent(20); # path object for /

path_up()

exists()

    if ($path->exists) {
        print "$path already exists\n";
    }
    else {
        print "Creating $path\n";
        # ...etc...
    }

must_exist($create)

    $path->must_exist;                      # no need to check return value

The $create flag can be set to have it attempt to create() itself if it doesn't already exist. However, this only makes sense for file and directory subclasses and not base class paths.

    $dir->must_exist(1);                    # create if it doesn't

create()

    $path->create;                          # FAIL
    $dir->create;                           # OK
    $file->create;                          # OK

chmod($perms)

    $file->chmod(0775);

stat()

    @list = $path->stat;                    # list context
    $list = $path->stat;                    # scalar context

A summary of the fields is shown below. See "perldoc -f stat" for complete details. Each of the individual fields can also be accessed via their own methods, also listed in the table.

    Field   Method          Description
    ------------------------------------------------------------------------
      0     device()        device number of filesystem
      1     inoode()        inode number
      2     mode()          file mode  (type and permissions)
      3     links()         number of (hard) links to the file
      4     user()          numeric user ID of file’s owner
      5     group()         numeric group ID of file’s owner
      6     device_type()   the device identifier (special files only)
      7     size()          total size of file, in bytes
      8     atime()         last access time in seconds since the epoch
      9     mtime()         last modify time in seconds since the epoch
     10     ctime()         inode change time in seconds since the epoch (*)
     11     block_size()    preferred block size for file system I/O
     12     blocks()        actual number of blocks allocated

In addition to those that are returned by Perl's inbuilt "stat" function, this method returns four additional flags.

     13     readable()      file is readable by current process
     14     writeable()     file is writeable by current process
     15     executable()    file is executable by current process
     16     owner()         file is owned by current process

stats()

    @list = $path->stats;                   # list context
    $list = $path->stats;                   # scalar context

Note that the accessed(), created() and modified() methods also cache the Badger::Timestamp objects they create to represent the access, creation and modification times respectively.

restat()

device()

inode()

mode()

permissions() / perms()

links()

user()

group()

device_type()

size()

atime()

accessed()

    print $file->accessed;              # 2009/04/20 16:25:00
    print $file->accessed->date;        # 2009/04/20
    print $file->accessed->year;        # 2009

mtime()

modified()

    print $file->modified;              # 2009/04/20 16:25:00
    print $file->modified->time;        # 16:25:0
    print $file->modified->hour;        # 16

ctime()

created()

    print $file->created;               # 2009/04/20 16:25:00
    print $file->created->date;         # 2009/04/20
    print $file->created->time;         # 16:25:00

block_size()

blocks()

readable()

writeable()

executable()

owner()

filesystem()

The end result is that you can use the "filesystem" method to access a Badger::Filesystem object or class through which you can perform other filesystem related operations. This is used internally by a number of method.

    # access filesystem via existing path
    $path->filesystem->dir('/a/new/directory/object');

    # same as
    Badger::Filesystem->dir('/a/new/directory/object');

visit($visitor)

    use Badger::Filesystem::Visitor;

    my $visitor = Badger::Filesystem::Visitor->new( recurse => 1 );
    $path->visit($visitor);

Alternately, a list or reference to a hash array of named parameters may be provided. These will be used to instantiate a new Badger::Filesystem::Visitor object (via the Badger::Filesystem visitor() method) which will then be applied to the path. If no arguments are passed then a visitor is created with a default configuration.

    # either list of named params
    $path->visit( recurse => 1 );

    # or reference to hash array
    $path->visit({ recurse => 1});

The method then calls the visitor visit() passing $self as an argument to begin the visit.

accept($visitor)

enter($visitor)

collect(\%params)

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

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

metadata() / meta()

    $path->metadata( title => 'An Example', author => 'Arthur Dent' );

It also accepts a single argument to fetch a metadata item:

    print $path->metadata('author');        # Arthur Dent

You can also call it without arguments. The method returns a reference to a hash array of metadata items.

    my $meta = $path->metadata;
    print $meta->{ author };                # Arthur Dent

is_file()

is_directory() / is_dir()

volume() / vol()

directory() / dir()

name()

extension() / ext()

    print Path('/foo/bar.txt')->extension;      # txt

basename() / base_name()

    print Path('/foo/bar.txt')->basename;       # /foo/bar

However, in most cases you would be using this through a Badger::Filesystem::File subclass which will product the correct results.

    print File('/foo/bar.txt')->basename;       # bar