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

VERSION
    version 0.096

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

USAGE
  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

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

AUTHOR
      Robert Krimen <robertkrimen@gmail.com>

COPYRIGHT AND LICENSE
    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.

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 247:
        =back without =over