NAME
   Path::Abstract - Fast and featureful UNIX-style path parsing and
   manipulation

VERSION
   Version 0.095

SYNOPSIS
     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)

DESCRIPTION
   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).

Different behavior since 0.093
   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:

 $path->list
   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

 $path->split
   See the above note on $path->list

 $path->first
   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

 $path->last
   Simlar to ->first

   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)->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

   The new behavior:

       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

 $path->is_branch
   The old behavior:

       1. The empty patch ('') would not be considered a branch

   The new behavior:

       1. The empty patch ('') IS considered a branch

METHODS
 Path::Abstract->new( <path> )
 Path::Abstract->new( <part>, [ <part>, ..., <part> ] )
   Create a new "Path::Abstract" object using <path> or by joining each
   <part> with "/"

   Returns the new "Path::Abstract" object

 Path::Abstract::path( <path> )
 Path::Abstract::path( <part>, [ <part>, ..., <part> ] )
   Create a new "Path::Abstract" object using <path> or by joining each
   <part> with "/"

   Returns the new "Path::Abstract" object

 $path->clone
   Returns an exact copy of $path

 $path->set( <path> )
 $path->set( <part>, [ <part>, ..., <part> ] )
   Set the path of $path to <path> or the concatenation of each <part>
   (separated by "/")

   Returns $path

 $path->is_nil
 $path->is_empty
   Returns true if $path is equal to ""

 $path->is_root
   Returns true if $path is equal to "/"

 $path->is_tree
   Returns true if $path begins with "/"

           path("/a/b")->is_tree # Returns true
           path("c/d")->is_tree # Returns false

 $path->is_branch
   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

 $path->to_tree
   Change $path by prefixing a "/" if it doesn't have one already

   Returns $path

 $path->to_branch
   Change $path by removing a leading "/" if it has one

   Returns $path

 $path->list
   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)

 $path->split
 $path->first
   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)

 $path->last
   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)

 $path->at( $index )
   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

 $path->beginning
   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->ending
   Returns the first part of path, including the leading slash, if any

       path("/a/b/c/")->ending # c/
       path("/a/b/c")->ending  # c

 $path->get
 $path->stringify
   Returns the path in string or scalar form

           path("c/d")->list # Returns "c/d"
           path("/a/b/")->last # Returns "/a/b"

 $path->push( <part>, [ <part>, ..., <part> ] )
 $path->down( <part>, [ <part>, ..., <part> ] )
   Modify $path by appending each <part> to the end of \$path, separated by
   "/"

   Returns $path

       path( "a/b/c" )->down( "d/e" ) # a/b/c/d/e

 $path->child( <part>, [ <part>, ..., <part> ] )
   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

 $path->append( $part1, [ $part2 ], ... )
   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"

 $path->extension
   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

 $path->extension( $extension )
   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

 $path->pop( <count> )
   Modify $path by removing <count> parts from the end of $path

   Returns the removed path as a "Path::Abstract" object

 $path->up( <count> )
   Modify $path by removing <count> parts from the end of $path

   Returns $path

 $path->parent( <count> )
   Make a copy of $path and pop <count> parts from the end of the new path

   Returns the new parent path

 $path->file
 $path->file( <part>, [ <part>, ..., <part> ] )
   Create a new "Path::Class::File" object using $path as a base, and
   optionally extending it by each <part>

   Returns the new file object

 $path->dir
 $path->dir( <part>, [ <part>, ..., <part> ] )
   Create a new "Path::Class::Dir" object using $path as a base, and
   optionally extending it by each <part>

   Returns the new dir object

SEE ALSO
   Path::Class

   File::Spec::Unix

   File::Spec

   Path::Resource

   Path::Abstract::Underload

   URI::PathAbstract

AUTHOR
   Robert Krimen, "<rkrimen at cpan.org>"

SOURCE
   You can contribute or fork this project via GitHub:

   <http://github.com/robertkrimen/path-abstract/tree/master>

       git clone git://github.com/robertkrimen/path-abstract.git Path-Abstract

BUGS
   Please report any bugs or feature requests to "bug-path-lite at
   rt.cpan.org", or through the web interface at
   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Path-Abstract>. I will
   be notified, and then you'll automatically be notified of progress on
   your bug as I make changes.

SUPPORT
   You can find documentation for this module with the perldoc command.

       perldoc Path::Abstract

   You can also look for information at:

   * AnnoCPAN: Annotated CPAN documentation
       <http://annocpan.org/dist/Path-Abstract>

   * CPAN Ratings
       <http://cpanratings.perl.org/d/Path-Abstract>

   * RT: CPAN's request tracker
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Path-Abstract>

   * Search CPAN
       <http://search.cpan.org/dist/Path-Abstract>

ACKNOWLEDGEMENTS
   Thanks to Joshua ben Jore, Max Kanat-Alexander, and Scott McWhirter for
   discovering the "use overload ..." slowdown issue.

COPYRIGHT & LICENSE
   Copyright 2007 Robert Krimen, all rights reserved.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.