view release on metacpan or  search on metacpan

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

    return $fs->join_directory($path);
}

sub exists {
    shift->stat;
}

sub must_exist {
    my $self = shift;

    unless ($self->exists) {
        if (@_ && $_[0]) {
            my $flag = shift;
            # true flag indicates we should attempt to create it
            $self->create(@_);      # pass any other args, like dir file permission
        }
        else {
            return $self->error_msg( no_exist => $self->type, $self->{ path } );
        }
    }
    return $self;
}

sub create {
    shift->not_implemented;
}

sub stat {
    my $self  = shift->must_exist;
    my $stats = $self->filesystem->stat_path($self->{ path })
            ||  return $self->decline_msg( not_found => file => $self->{ path } );

    # the definitive path can be tagged on the end
#    $self->{ definitive } = $stats->[STAT_PATH]
#        if defined $stats->[STAT_PATH];

    return wantarray
        ? @$stats
        :  $stats;
}

sub stats {
    my $stats = $_[0]->{ stats } ||= $_[0]->stat;
    return wantarray
        ? @$stats
        :  $stats;
}

sub restat {
    my $self = shift;
    delete $self->{ stats };
    delete @$self{ keys %$TS_FIELD }; # timestamps for created, modified, etc.
    return $self->stats;
}

sub permissions {
    shift->mode & 0777;
}

sub chmod {
    my $self = shift;
    $self->filesystem->chmod_path($self->{ path }, @_);
    return $self;
}

sub basename {
    my $self = shift;
    my $name = $self->name;
    $name = $self->{ path } unless defined $name;
    $name =~ s/$MATCH_EXT//g;
    return $name;
}

sub extension {
    my $self = shift;
    return $self->{ path } =~ $MATCH_EXT
        ? $1
        : '';
}

sub filesystem {
    my $self = shift;
    return $self->class->any_var('FILESYSTEM')->prototype
        unless ref $self;
    $self->{ filesystem }
        ||= $self->class->any_var('FILESYSTEM')->prototype;
}

sub visit {
    my $self    = shift;
    my $visitor = $self->filesystem->visitor(@_);
    $visitor->visit($self);
    return $visitor;
}

sub collect {
    shift->visit(@_)->collect;
}

sub enter {
    # enter() is a custom accept() method for the entry point of a visitor
    shift->accept;
}

sub accept {
    $_[1]->visit_path($_[0]);
}

sub metadata {
    my $self = shift;
    my $meta = $self->{ metadata } ||= { };
    if (@_ == 1) {
        return $meta->{ $_[0] };
    }
    elsif (@_ > 1) {
        while (@_) {
            my $key = shift;
            $meta->{ $key } = shift;
        }
    }
    return $meta;
}

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

A numerical argument can be provided to indicate the number of generation
you want to skip.  A value of C<0> is the same as providing no argument - it
returns the parent.  A value of C<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 /

=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()>.