view release on metacpan or  search on metacpan

lib/Badger/Filesystem/Path.pm  view on Meta::CPAN

    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 /

=head2 path_up()

This returns a text string representing the parent of a path.  If the path
contains multiple items (e.g. '/foo/bar' or 'foo/bar') then the last item
will be removed (e.g. resulting in '/foo' or 'foo' respectively).  If an
absolute path contains one item or none (e.g. '/foo' or '/') then the
root directory ('/') will be returned.  A relative path with only one item
(e.g. 'foo') is assumed to be relative to the current working directory
which will be returned (e.g. '/path/to/current/dir').

=head2 exists()

Returns true if the path exists in the filesystem (e.g. as a file, directory,
or some other entry), or false if not.

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

=head2 must_exist($create)

Checks that the path exists (by calling L<exists()>) and throws an error
if it doesn't.

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

The C<$create> flag can be set to have it attempt to L<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

=head2 create()

In the base class this will method will throw an error. You can't physically
create an abstract path unless you know what kind of concrete entity (e.g.
file or directory) it maps onto. In other words, the L<create()> method will
only work for the L<Badger::Filesystem::File> and
L<Badger::Filesystem::Directory> subclasses.

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

=head2 chmod($perms)

This method changes the file permissions on a file or directory.

    $file->chmod(0775);

=head2 stat()

Performs a filesystem C<stat> on the path and returns a list (in list
context), or a reference to a list (in scalar context) containing the 13
information elements.

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

A summary of the fields is shown below. See C<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 C<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

=head2 stats()

A wrapper around the L<stat()> method which caches the results to avoid
making repeated filesystem calls.

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

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

=head2 restat()

Clears any cached values stored by the L<stats()>, L<accessed()>,
L<created()> and L<modified()> methods and calls L<stats()> to reload
(and re-cache) the data from a L<stat()> call.

=head2 device()

Returns the device number for the file.  See L<stat()>.

=head2 inode()

Returns the inode number for the file.  See L<stat()>.

=head2 mode()

Returns the file mode for the file.  Note that this contains both the
file type and permissions.  See L<stat()>.

=head2 permissions() / perms()

Returns the file permissions.  This is equivalent to
C<< $file->mode & 0777 >>.

=head2 links()

Returns the number of hard links to the file.  See L<stat()>.

=head2 user()

Returns the numeric user ID of the file's owner.  See L<stat()>.

=head2 group()

Returns the numeric group ID of the file's group.  See L<stat()>.

=head2 device_type()

Returns the device identifier (for special files only).  See L<stat()>.

=head2 size()

Returns the total size of the file in bytes.  See L<stat()>.

=head2 atime()

Returns the time (in seconds since the epoch) that the file was last accessed.
See L<stat()>.

=head2 accessed()

Returns a L<Badger::Timestamp> object for the L<atime()> value.  This object
will auto-stringify to produce an ISO-8601 formatted date.  You can also
call various methods to access different parts of the time and/or date.

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

=head2 mtime()

Returns the time (in seconds since the epoch) that the file was last modified.
See L<stat()>.

=head2 modified()

Returns a L<Badger::Timestamp> object for the L<mtime()> value.

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

=head2 ctime()

Returns the time (in seconds since the epoch) that the file was created. See
L<stat()>.

=head2 created()

Returns a L<Badger::Timestamp> object for the L<ctime()> value.

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

=head2 block_size()

Returns the preferred block size for file system I/O on the file. See
L<stat()>.

=head2 blocks()

Returns the actual number of blocks allocated to the file. See L<stat()>.

=head2 readable()

Returns a true value if the file is readable by the current user (i.e. the
owner of the current process), false if not.  See L<stat()>.

=head2 writeable()

Returns a true value if the file is writeable by the current user (i.e. the
owner of the current process), false if not.  See L<stat()>.

=head2 executable()

Returns a true value if the file is executable by the current user (i.e. the
owner of the current process), false if not.  See L<stat()>.

=head2 owner()

Returns a true value if the file is owned by the current user (i.e. the
owner of the current process), false if not.  See L<stat()>.

=head2 filesystem()

Returns a reference to a L<Badger::Filesystem> object, or the name of the
filesystem class (e.g. L<Badger::Filesystem> or a subclass) that created
the path object.  If this is undefined then the default value defined in
the L<$FILESYSTEM> class variable is returned.   Unless you've changed it,
or re-defined it in a subclass, this value will be C<Badger::Filesystem>.

The end result is that you can use the C<filesystem> method to access a
L<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');

=head2 visit($visitor)

Entry point for a filesystem visitor to visit a filesystem path.  A
reference to a L<Badger::Filesystem::Visitor> object (or subclass) should
be passed as the first argument.

    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
L<Badger::Filesystem::Visitor> object (via the L<Badger::Filesystem>
L<visitor()|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
L<visit()|Badger::Filesystem::Visitor/visit()> passing C<$self> as an argument
to begin the visit.

=head2 accept($visitor)

This method is called to dispatch a visitor to the correct method for a
filesystem object. In the L<Badger::Filesystem::Path> base class, it calls the
visitor L<visit_path()|Badger::Filesystem::Visitor/visit_path()> method,
passing the C<$self> object reference as an argument. Subclasses redefine this
method to call other visitor methods.

=head2 enter($visitor)

This is a special case of the L<accept()> method which subclasses (e.g.
L<directory|Badger::Filesystem::Directory>) use to differentiate between the