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


Manual Reference Pages  -  PATH::ABSTRACT (3)

.ds Aq ’

NAME

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

CONTENTS

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:

CW$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



CW$path->split

See the above note on $path->list

CW$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

CW$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

CW$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

CW$path->clone

Returns an exact copy of $path

CW$path->set( <path> )

CW$path->set( <part>, [ <part>, ..., <part> ] )

Set the path of $path to <path> or the concatenation of each <part> (separated by /)

Returns $path

CW$path->is_nil

CW$path->is_empty

Returns true if $path is equal to ""

CW$path->is_root

Returns true if $path is equal to /

CW$path->is_tree

Returns true if $path begins with /



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



CW$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



CW$path->to_tree

Change $path by prefixing a / if it doesn’t have one already

Returns $path

CW$path->to_branch

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

Returns $path

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

CW$path->split

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

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

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



CW$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



CW$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



CW$path->get

CW$path->stringify

Returns the path in string or scalar form



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



CW$path->push( <part>, [ <part>, ..., <part> ] )

CW$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



CW$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



CW$path->append( CW$part1, [ CW$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"



CW$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



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

CW$path->pop( <count> )

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

Returns the removed path as a Path::Abstract object

CW$path->up( <count> )

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

Returns $path

CW$path->parent( <count> )

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

Returns the new parent path

CW$path->file

CW$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

CW$path->dir

CW$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! <B>The above document had some coding errors, which are explained below:B>
Around line 247: =back without =over
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PATH::ABSTRACT (3) 2010-05-13

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