1package Path::Class; 2 3$VERSION = '0.18'; 4@ISA = qw(Exporter); 5@EXPORT = qw(file dir); 6@EXPORT_OK = qw(file dir foreign_file foreign_dir); 7 8use strict; 9use Exporter; 10use Path::Class::File; 11use Path::Class::Dir; 12 13sub file { Path::Class::File->new(@_) } 14sub dir { Path::Class::Dir ->new(@_) } 15sub foreign_file { Path::Class::File->new_foreign(@_) } 16sub foreign_dir { Path::Class::Dir ->new_foreign(@_) } 17 18 191; 20__END__ 21 22=head1 NAME 23 24Path::Class - Cross-platform path specification manipulation 25 26=head1 SYNOPSIS 27 28 use Path::Class; 29 30 my $dir = dir('foo', 'bar'); # Path::Class::Dir object 31 my $file = file('bob', 'file.txt'); # Path::Class::File object 32 33 # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc. 34 print "dir: $dir\n"; 35 36 # Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows 37 print "file: $file\n"; 38 39 my $subdir = $dir->subdir('baz'); # foo/bar/baz 40 my $parent = $subdir->parent; # foo/bar 41 my $parent2 = $parent->parent; # foo 42 43 my $dir2 = $file->dir; # bob 44 45 # Work with foreign paths 46 use Path::Class qw(foreign_file foreign_dir); 47 my $file = foreign_file('Mac', ':foo:file.txt'); 48 print $file->dir; # :foo: 49 print $file->as_foreign('Win32'); # foo\file.txt 50 51 # Interact with the underlying filesystem: 52 53 # $dir_handle is an IO::Dir object 54 my $dir_handle = $dir->open or die "Can't read $dir: $!"; 55 56 # $file_handle is an IO::File object 57 my $file_handle = $file->open($mode) or die "Can't read $file: $!"; 58 59=head1 DESCRIPTION 60 61C<Path::Class> is a module for manipulation of file and directory 62specifications (strings describing their locations, like 63C<'/home/ken/foo.txt'> or C<'C:\Windows\Foo.txt'>) in a cross-platform 64manner. It supports pretty much every platform Perl runs on, 65including Unix, Windows, Mac, VMS, Epoc, Cygwin, OS/2, and NetWare. 66 67The well-known module C<File::Spec> also provides this service, but 68it's sort of awkward to use well, so people sometimes avoid it, or use 69it in a way that won't actually work properly on platforms 70significantly different than the ones they've tested their code on. 71 72In fact, C<Path::Class> uses C<File::Spec> internally, wrapping all 73the unsightly details so you can concentrate on your application code. 74Whereas C<File::Spec> provides functions for some common path 75manipulations, C<Path::Class> provides an object-oriented model of the 76world of path specifications and their underlying semantics. 77C<File::Spec> doesn't create any objects, and its classes represent 78the different ways in which paths must be manipulated on various 79platforms (not a very intuitive concept). C<Path::Class> creates 80objects representing files and directories, and provides methods that 81relate them to each other. For instance, the following C<File::Spec> 82code: 83 84 my $absolute = File::Spec->file_name_is_absolute( 85 File::Spec->catfile( @dirs, $file ) 86 ); 87 88can be written using C<Path::Class> as 89 90 my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute; 91 92or even as 93 94 my $absolute = file( @dirs, $file )->is_absolute; 95 96Similar readability improvements should happen all over the place when 97using C<Path::Class>. 98 99Using C<Path::Class> can help solve real problems in your code too - 100for instance, how many people actually take the "volume" (like C<C:> 101on Windows) into account when writing C<File::Spec>-using code? I 102thought not. But if you use C<Path::Class>, your file and directory objects 103will know what volumes they refer to and do the right thing. 104 105The guts of the C<Path::Class> code live in the C<Path::Class::File> 106and C<Path::Class::Dir> modules, so please see those 107modules' documentation for more details about how to use them. 108 109=head2 EXPORT 110 111The following functions are exported by default. 112 113=over 4 114 115=item file 116 117A synonym for C<< Path::Class::File->new >>. 118 119=item dir 120 121A synonym for C<< Path::Class::Dir->new >>. 122 123=back 124 125If you would like to prevent their export, you may explicitly pass an 126empty list to perl's C<use>, i.e. C<use Path::Class ()>. 127 128The following are exported only on demand. 129 130=over 4 131 132=item foreign_file 133 134A synonym for C<< Path::Class::File->new_foreign >>. 135 136=item foreign_dir 137 138A synonym for C<< Path::Class::Dir->new_foreign >>. 139 140=back 141 142=head1 Notes on Cross-Platform Compatibility 143 144Although it is much easier to write cross-platform-friendly code with 145this module than with C<File::Spec>, there are still some issues to be 146aware of. 147 148=over 4 149 150=item * 151 152Some platforms, notably VMS and some older versions of DOS (I think), 153all filenames must have an extension. Thus if you create a file 154called F<foo/bar> and then ask for a list of files in the directory 155F<foo>, you may find a file called F<bar.> instead of the F<bar> you 156were expecting. Thus it might be a good idea to use an extension in 157the first place. 158 159=back 160 161=head1 AUTHOR 162 163Ken Williams, KWILLIAMS@cpan.org 164 165=head1 COPYRIGHT 166 167Copyright (c) Ken Williams. All rights reserved. 168 169This library is free software; you can redistribute it and/or 170modify it under the same terms as Perl itself. 171 172 173=head1 SEE ALSO 174 175Path::Class::Dir, Path::Class::File, File::Spec 176 177=cut 178