GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Path::Abstract(3) User Contributed Perl Documentation Path::Abstract(3)

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

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

The old behavior:

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

The new behavior:

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

Create a new "Path::Abstract" object using <path> or by joining each <part> with "/"

Returns the new "Path::Abstract" object

Create a new "Path::Abstract" object using <path> or by joining each <part> with "/"

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

Returns $path

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

Returns $path

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

Returns the first part of path, including the leading slash, if any

    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 "/"

Returns $path

    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

Modify $path by removing <count> parts from the end of $path

Returns $path

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>

Returns the new file object

Create a new "Path::Class::Dir" object using $path as a base, and optionally extending it by each <part>

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.

Hey! The above document had some coding errors, which are explained below:
Around line 247:
=back without =over
2010-05-13 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.