NAME

Path::Class - Cross-platform path specification manipulation

SYNOPSIS

  use Path::Class qw(file dir);  # Export a couple of short constructors
  
  my $dir  = dir('foo', 'bar');       # Path::Class::Dir object
  my $file = file('bob', 'file.txt'); # Path::Class::File object
  
  # Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
  print "file: $file\n";
  
  # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows
  print "dir: $dir\n";
  
  my $subdir  = $dir->subdir('baz');  # foo/bar/baz
  my $parent  = $subdir->parent;      # foo/bar
  my $parent2 = $parent->parent;      # foo
  
  my $dir2 = $file->dir;              # bob

  # Work with foreign paths
  use Path::Class qw(foreign_file foreign_dir);
  my $file = foreign_file('Mac', ':foo:file.txt');
  print $file->dir;                   # :foo:
  print $file->as_foreign('Win32');   # foo\file.txt

DESCRIPTION

The well-known module File::Spec allows Perl programmers to manipulate file and directory specifications (strings describing their locations, like '/home/ken/foo.txt' or 'C:\Windows\Foo.txt') in a cross-platform manner, but it's sort of awkward to use well, so people sometimes avoid it.

Path::Class provides a nicer interface (nicer in my opinion, anyway) to the File::Spec functionality. File::Spec has an object-oriented interface, but the OO-ness doesn't actually buy you anything. All it does is give you a really long name for some things that are essentially function calls (not very helpful), and lets you avoid polluting your namespace with function names (somewhat helpful).

Path::Class actually gets some mileage out of its class hierarchy. It has a class for files and a class for directories, and methods that relate them to each other. For instance, the following File::Spec code:

 my $absolute = File::Spec->file_name_is_absolute(
                  File::Spec->catfile( @dirs, $file )
                );

can be written using Path::Class as

 my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute;

or even as

 my $absolute = file( @dirs, $file )->is_absolute;

if you're willing to export the file function into your namespace. Similar readability improvements happen all over the place when using Path::Class.

Using Path::Class can help solve real problems in your code too - for instance, how many people actually take the "volume" (like C: on Windows) into account when writing File::Spec-using code? I thought not. But if you use Path::Class, your directory objects will know what volumes they refer to and do the right thing.

The guts of the Path::Class code live in the Path::Class::File and Path::Class::Dir modules, so please see those modules' documentation for more details about how to use them.

EXPORT

The following functions can be exported upon request:

file

A synonym for Path::Class::File->new.

dir

A synonym for Path::Class::Dir->new.

foreign_file

A synonym for Path::Class::File->new_foreign.

foreign_dir

A synonym for Path::Class::Dir->new_foreign.

AUTHOR

Ken Williams, ken@mathforum.org

SEE ALSO

Path::Class::Dir, Path::Class::File, File::Spec