NAME

Filesys::POSIX::Path - Pathname manipulation utility class

SYNOPSIS

use Filesys::POSIX::Path;

my $path = Filesys::POSIX::Path->new('/foo/bar/baz');

printf("%s\n", $path->basename); # outputs 'baz'
printf("%s\n", $path->dirname);  # outputs '/foo/bar'

# outputs '/foo/bar/../baz'
printf("%s\n", $path->full('/foo/./././bar/../baz'));

DESCRIPTION

This module provides an object-oriented approach to path cleanup and introspection.

CREATING AN OBJECT

Filesys::POSIX::Path->new($path)

Creates a new path object.

The path is split on the forward slash (/) character into tokens; empty and redundant tokens are discarded. Enough context is kept to help the methods implemented in this module determine the nature of the path; if it is relative to root, prefixed with './', or relative to the "current working directory". An ARRAY reference blessed into this package's namespace is returned upon success. An EINVAL is thrown if the path provided is empty.

PATH INTROSPECTION

$path->components

Return a list of the components parsed at object construction time.

$path->full

Returns a string representation of the full path. This is the same as:

join('/', @$path);

$path->dirname

Returns a string representation of all of the leading path elements, of course save for the final path element.

$path->basename

$path->basename($ext)

Returns the final path component. If called with an extension, then the method will return the path component with the extension chopped off, if found.

$path->shift

Useful for iterating over the components of the path object. Shifts the internal start-of-array pointer by one, and returns the previous first value.

$path->push(@parts)

Push new components onto the current path object. Each part will be tokenized on the forward slash (/) character, and useless items will be discarded.

$path->concat($pathname)

A new Filesys::POSIX::Path object is created based on $pathname, and the current path object's non-empty components are pushed onto that new instance. The new path object is returned.

$path->concat($pathname)

A new Filesys::POSIX::Path object is created based on $pathname, and the new path object's non-empty components are pushed onto the current path object. The current $path reference is then returned.

$path->pop

Pops the final path component off of the path object list, and returns that value.

$path->count

Returns the number of components in the current path object.

$path->is_absolute

Returns true if the current path object represents an absolute path.

AUTHOR

Written by Xan Tronix <xan@cpan.org>

CONTRIBUTORS

Rikus Goodell <rikus.goodell@cpanel.net>

Brian Carlson <brian.carlson@cpanel.net>

COPYRIGHT

Copyright (c) 2014, cPanel, Inc. Distributed under the terms of the Perl Artistic license.