Path::Abstract - Fast and featureful UNIX-style path parsing and manipulation
version 0.096
use Path::Abstract; my $path = Path::Abstract->new( '/apple/banana' ) # $parent is '/apple' my $parent = $path->parent # $cherry is '/apple/banana/cherry.txt' my $cherry = $path->child( "cherry.txt" ) path( '/a/b/c/' )->list # ( 'a', 'b', 'c' ) path( '/a/b/c/' )->split # ( '/a', 'b', 'c/' ) path( '/a/b/c/' )->first # a path( '/a/b/c/' )->beginning # /a path( '/a/b/c/' )->last # c path( '/a/b/c/' )->ending # c/ path( '/a/b/c/' ).at(0) # a (equivalent to ->first) path( '/a/b/c/' ).at(-1) # c (equivalent to ->last) path( '/a/b/c/' ).at(1) # b $path = path( 'a/b/c' ) $path->append( 'd', 'ef/g', 'h' ) # a/b/cd/ef/g/h path( 'a/b/c.html' )->extension # .html path( 'a/b/c' )->extension # '' path( 'a/b/c.tar.gz' )->extension # .gz path( 'a/b/c.tar.gz' )-> extension({ match: '*' }) # .tar.gz path( 'a/b/c.html' )->extension( '.txt' ) # a/b/c.txt path( 'a/b/c.html' )->extension( 'zip' ) # a/b/c.zip path( 'a/b/c.html' )->extension( '' ) # a/b/c path( 'a/b/c' )->down( 'd/e' ) # a/b/c/d/e path( 'a/b/c' )->child( 'd/e' ) # a/b/c/d/e (Same as ->down except # returning a new path instead of # modifying the original) path( 'a/b/c' )->up # a/b path( 'a/b/c' )->parent # a/b (Same as ->up except # returning a new path instead of # modifying the original)
Path::Abstract is a tool for parsing, interrogating, and modifying a UNIX-style path. The parsing behavior is similar to File::Spec::Unix, except that trailing slashes are preserved (converted into a single slash).
Some methods of Path::Abstract have changed since 0.093 with the goal of having better/more consistent behavior
Unfortunately, this MAY result in code that worked with 0.093 and earlier be updated to reflect the new behavior
The following has changed:
The old behavior (kept the leading slash but dropped trailing slash):
path('/a/b/c/')->list # ( '/a', 'b', 'c' ) path('a/b/c/')->list # ( 'a', 'b', 'c' )
The new behavior (neither slash is kept):
path('/a/b/c/')->list # ( 'a', 'b', 'c' ) path('a/b/c/')->list # ( 'a', 'b', 'c' )
In addition, $path->split was an alias for $path->list, but this has changed. Now split WILL keep BOTH leading and trailing slashes (if any):
path('/a/b/c/')->split # ( '/a', 'b', 'c/' ) path('a/b/c/')->split # ( 'a', 'b', 'c/' ) path('a/b/c')->split # ( 'a', 'b', 'c' ) Effectively equivalent to ->list
See the above note on $path->list
The old behavior:
1. Would return undef for the empty path 2. Would include the leading slash (if present) 3. Would NOT include the trailing slash (if present) path(undef)->first # undef path('')->first # undef path('/a')->first # /a path('/a/')->first # /a path('a')->first # a
The new behavior:
1. Always returns at least the empty string 2. Never includes any slashes path(undef)->first # '' path('')->first # '' path('/a')->first # a path('/a/')->first # a path('a')->first # a
For an alternative to ->first, try ->beginning
Simlar to ->first
1. Would return undef for the empty path 2. Would include the leading slash (if present) 3. Would NOT include the trailing slash (if present) path(undef)->last # undef path('')->last # undef path('/a')->last # /a path('/a/')->last # /a path('a')->last # a path('a/b')->last # b path('a/b/')->last # b
1. Always returns at least the empty string 2. Never includes any slashes path(undef)->last # '' path('')->last # '' path('/a')->last # a path('/a/')->last # a path('a')->last # a path('a/b')->last # b path('a/b/')->last # b
For an alternative to ->last, try ->ending
1. The empty patch ('') would not be considered a branch
1. The empty patch ('') IS considered a branch
Create a new Path::Abstract object using <path> or by joining each <part> with "/"
Path::Abstract
Returns the new Path::Abstract object
Returns an exact copy of $path
Set the path of $path to <path> or the concatenation of each <part> (separated by "/")
Returns $path
Returns true if $path is equal to ""
Returns true if $path is equal to "/"
Returns true if $path begins with "/"
path("/a/b")->is_tree # Returns true path("c/d")->is_tree # Returns false
Returns true if $path does NOT begin with a "/"
path("")->is_branch # Returns true path("/")->is_branch # Returns false path("c/d")->is_branch # Returns true path("/a/b")->is_branch # Returns false
Change $path by prefixing a "/" if it doesn't have one already
Change $path by removing a leading "/" if it has one
Returns the path in list form by splitting at each "/"
path("c/d")->list # Returns ("c", "d") path("/a/b/")->last # Returns ("a", "b")
NOTE: This behavior is different since 0.093 (see above)
Returns the first part of $path up to the first "/" (but not including the leading slash, if any)
path("c/d")->first # Returns "c" path("/a/b")->first # Returns "a"
This is equivalent to $path->at(0)
Returns the last part of $path up to the last "/"
path("c/d")->last # Returns "d" path("/a/b/")->last # Returns "b"
This is equivalent to $path->at(-1)
Returns the part of path at $index, not including any slashes You can use a negative $index to start from the end of path
path("/a/b/c/").at(0) # a (equivalent to $path->first) path("/a/b/c/").at(-1) # c (equivalent to $path->last) path("/a/b/c/").at(1) # b
Returns the first part of path, including the leading slash, if any
path("/a/b/c/")->beginning # /a path("a/b/c/")->beginning # a
path("/a/b/c/")->ending # c/ path("/a/b/c")->ending # c
Returns the path in string or scalar form
path("c/d")->list # Returns "c/d" path("/a/b/")->last # Returns "/a/b"
Modify $path by appending each <part> to the end of \$path, separated by "/"
path( "a/b/c" )->down( "d/e" ) # a/b/c/d/e
Make a copy of $path and push each <part> to the end of the new path.
Returns the new child path
path( "a/b/c" )->child( "d/e" ) # a/b/c/d/e
Modify path by appending $part1 WITHOUT separating it by a slash. Any, optional, following $part2, ..., will be separated by slashes as normal
$path = path( "a/b/c" ) $path->append( "d", "ef/g", "h" ) # "a/b/cd/ef/g/h"
Returns the extension of path, including the leading the dot
Returns "" if path does not have an extension
path( "a/b/c.html" )->extension # .html path( "a/b/c" )->extension # "" path( "a/b/c.tar.gz" )->extension # .gz path( "a/b/c.tar.gz" )->extension({ match: "*" }) # .tar.gz
Modify path by changing the existing extension of path, if any, to $extension
path( "a/b/c.html" )->extension( ".txt" ) # a/b/c.txt path( "a/b/c.html" )->extension( "zip" ) # a/b/c.zip path( "a/b/c.html" )->extension( "" ) # a/b/c
Returns path
Modify $path by removing <count> parts from the end of $path
Returns the removed path as a Path::Abstract object
Make a copy of $path and pop <count> parts from the end of the new path
Returns the new parent path
Create a new Path::Class::File object using $path as a base, and optionally extending it by each <part>
Path::Class::File
Returns the new file object
Create a new Path::Class::Dir object using $path as a base, and optionally extending it by each <part>
Path::Class::Dir
Returns the new dir object
Path::Class
File::Spec::Unix
File::Spec
Path::Resource
Path::Abstract::Underload
URI::PathAbstract
Thanks to Joshua ben Jore, Max Kanat-Alexander, and Scott McWhirter for discovering the "use overload ..." slowdown issue.
Robert Krimen <robertkrimen@gmail.com>
This software is copyright (c) 2010 by Robert Krimen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
1 POD Error
The following errors were encountered while parsing the POD:
=back without =over
To install Path::Abstract, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Path::Abstract
CPAN shell
perl -MCPAN -e shell install Path::Abstract
For more information on module installation, please visit the detailed CPAN module installation guide.