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