NAME
Path::Class::Dir - Objects representing directories
SYNOPSIS
use Path::Class qw(dir); # Export a short constructor
my $dir = dir('foo', 'bar'); # Path::Class::Dir object
my $dir = Path::Class::Dir->new('foo', 'bar'); # Same thing
# Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
print "dir: $dir\n";
if ($dir->is_absolute) { ... }
my $v = $dir->volume; # Could be 'C:' on Windows, empty string
# on Unix, 'Macintosh HD:' on Mac OS
$dir->cleanup; # Perform logical cleanup of pathname
my $file = $dir->file('file.txt'); # A file in this directory
my $subdir = $dir->subdir('george'); # A subdirectory
my $parent = $dir->parent; # The parent directory, 'foo'
my $abs = $dir->absolute; # Transform to absolute path
my $rel = $abs->relative; # Transform to relative path
my $rel = $abs->relative('/foo'); # Relative to /foo
print $dir->as_foreign('MacOS'); # :foo:bar:
print $dir->as_foreign('Win32'); # foo\bar
DESCRIPTION
The Path::Class::Dir
class contains functionality for manipulating directory names in a cross-platform way.
METHODS
- $dir = Path::Class::Dir->new( <dir1>, <dir2>, ... )
- $dir = dir( <dir1>, <dir2>, ... )
-
Creates a new
Path::Class::Dir
object and returns it. The arguments specify names of directories which will be joined to create a single directory object. A volume may also be specified as the first argument, or as part of the first argument. You can use platform-neutral syntax:my $dir = dir( 'foo', 'bar', 'baz' );
or platform-native syntax:
my $dir = dir( 'foo/bar/baz' );
or a mixture of the two:
my $dir = dir( 'foo/bar', 'baz' );
All three of the above examples create relative paths. To create an absolute path, either use the platform native syntax for doing so:
my $dir = dir( '/var/tmp' );
or use an empty string as the first argument:
my $dir = dir( '', 'var', 'tmp' );
If the second form seems awkward, that's somewhat intentional - paths like
/var/tmp
or\Windows
aren't cross-platform concepts in the first place, so they probably shouldn't appear in your code if you're trying to be cross-platform. The first form is perfectly natural, because paths like this may come from config files, user input, or whatever.As a special case, since it doesn't otherwise mean anything useful and it's convenient to define this way,
Path::Class::Dir->new()
(ordir()
) refers to the current directory (File::Spec->curdir
). To get the current directory as an absolute path, dodir()->absolute
. - $dir->stringify
-
This method is called internally when a
Path::Class::Dir
object is used in a string context, so the following are equivalent:$string = $dir->stringify; $string = "$dir";
- $dir->volume
-
Returns the volume (e.g.
C:
on Windows,Macintosh HD:
on Mac OS, etc.) of the directory object, if any. Otherwise, returns the empty string. - $dir->is_absolute
-
Returns true or false depending on whether the directory refers to an absolute path specifier (like
/usr/local
or\Windows
). - $dir->cleanup
-
Performs a logical cleanup of the file path. For instance:
my $dir = dir('/foo//baz/./foo')->cleanup; # $dir now represents '/foo/baz/foo';
- $file = $dir->file( <dir1>, <dir2>, ..., <file> )
-
Returns a
Path::Class::File
object representing an entry in$dir
or one of its subdirectories. Internally, this just callsPath::Class::File->new( @_ )
. - $subdir = $dir->subdir( <dir1>, <dir2>, ... )
-
Returns a new
Path::Class::Dir
object representing a subdirectory of$dir
. - $parent = $dir->parent
-
Returns the parent directory of
$dir
. Note that this is the logical parent, not necessarily the physical parent. It really means we just chop off entries from the end of the directory list until we cain't chop no more. If the directory is relative, we start using the relative forms of parent directories.The following code demonstrates the behavior on absolute and relative directories:
$dir = dir('/foo/bar'); for (1..6) { print "Absolute: $dir\n"; $dir = $dir->parent; } $dir = dir('foo/bar'); for (1..6) { print "Relative: $dir\n"; $dir = $dir->parent; } ########### Output on Unix ################ Absolute: /foo/bar Absolute: /foo Absolute: / Absolute: / Absolute: / Absolute: / Relative: foo/bar Relative: foo Relative: . Relative: .. Relative: ../.. Relative: ../../..
- $abs = $dir->absolute
-
Returns a
Path::Class::Dir
object representing$dir
as an absolute path. An optional argument, given as either a string or aPath::Class::Dir
object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used. - $rel = $dir->relative
-
Returns a
Path::Class::Dir
object representing$dir
as a relative path. An optional argument, given as either a string or aPath::Class::Dir
object, specifies the directory to use as the base of relativity - otherwise the current working directory will be used. - $foreign = $dir->as_foreign($type)
-
Returns a
Path::Class::Dir
object representing$dir
as it would be specified on a system of type$type
. Known types includeUnix
,Win32
,Mac
,VMS
, andOS2
, i.e. anything for which there is a subclass ofFile::Spec
.Any generated objects (subdirectories, files, parents, etc.) will also retain this type.
- $foreign = Path::Class::Dir->new_foreign($type, @args)
-
Returns a
Path::Class::Dir
object representing$dir
as it would be specified on a system of type$type
. Known types includeUnix
,Win32
,Mac
,VMS
, andOS2
, i.e. anything for which there is a subclass ofFile::Spec
.The arguments in
@args
are the same as they would be specified innew()
.
AUTHOR
Ken Williams, ken@mathforum.org
SEE ALSO
Path::Class, Path::Class::File, File::Spec