1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Path::Class 3"
132 .TH Path::Class 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
134 Path::Class \- Cross\-platform path specification manipulation
136 .IX Header "SYNOPSIS"
142 \& my $dir = dir('foo', 'bar'); # Path::Class::Dir object
143 \& my $file = file('bob', 'file.txt'); # Path::Class::File object
147 \& # Stringifies to 'foo/bar' on Unix, 'foo\ebar' on Windows, etc.
148 \& print "dir: $dir\en";
152 \& # Stringifies to 'bob/file.txt' on Unix, 'bob\efile.txt' on Windows
153 \& print "file: $file\en";
157 \& my $subdir = $dir\->subdir('baz'); # foo/bar/baz
158 \& my $parent = $subdir\->parent; # foo/bar
159 \& my $parent2 = $parent\->parent; # foo
163 \& my $dir2 = $file\->dir; # bob
167 \& # Work with foreign paths
168 \& use Path::Class qw(foreign_file foreign_dir);
169 \& my $file = foreign_file('Mac', ':foo:file.txt');
170 \& print $file\->dir; # :foo:
171 \& print $file\->as_foreign('Win32'); # foo\efile.txt
175 \& # Interact with the underlying filesystem:
179 \& # $dir_handle is an IO::Dir object
180 \& my $dir_handle = $dir\->open or die "Can't read $dir: $!";
184 \& # $file_handle is an IO::File object
185 \& my $file_handle = $file\->open($mode) or die "Can't read $file: $!";
188 .IX Header "DESCRIPTION"
189 \&\f(CW\*(C`Path::Class\*(C'\fR is a module for manipulation of file and directory
190 specifications (strings describing their locations, like
191 \&\f(CW'/home/ken/foo.txt'\fR or \f(CW'C:\eWindows\eFoo.txt'\fR) in a cross-platform
192 manner. It supports pretty much every platform Perl runs on,
193 including Unix, Windows, Mac, \s-1VMS\s0, Epoc, Cygwin, \s-1OS/2\s0, and NetWare.
195 The well-known module \f(CW\*(C`File::Spec\*(C'\fR also provides this service, but
196 it's sort of awkward to use well, so people sometimes avoid it, or use
197 it in a way that won't actually work properly on platforms
198 significantly different than the ones they've tested their code on.
200 In fact, \f(CW\*(C`Path::Class\*(C'\fR uses \f(CW\*(C`File::Spec\*(C'\fR internally, wrapping all
201 the unsightly details so you can concentrate on your application code.
202 Whereas \f(CW\*(C`File::Spec\*(C'\fR provides functions for some common path
203 manipulations, \f(CW\*(C`Path::Class\*(C'\fR provides an object-oriented model of the
204 world of path specifications and their underlying semantics.
205 \&\f(CW\*(C`File::Spec\*(C'\fR doesn't create any objects, and its classes represent
206 the different ways in which paths must be manipulated on various
207 platforms (not a very intuitive concept). \f(CW\*(C`Path::Class\*(C'\fR creates
208 objects representing files and directories, and provides methods that
209 relate them to each other. For instance, the following \f(CW\*(C`File::Spec\*(C'\fR
213 \& my $absolute = File::Spec\->file_name_is_absolute(
214 \& File::Spec\->catfile( @dirs, $file )
218 can be written using \f(CW\*(C`Path::Class\*(C'\fR as
221 \& my $absolute = Path::Class::File\->new( @dirs, $file )\->is_absolute;
227 \& my $absolute = file( @dirs, $file )\->is_absolute;
230 Similar readability improvements should happen all over the place when
231 using \f(CW\*(C`Path::Class\*(C'\fR.
233 Using \f(CW\*(C`Path::Class\*(C'\fR can help solve real problems in your code too \-
234 for instance, how many people actually take the \*(L"volume\*(R" (like \f(CW\*(C`C:\*(C'\fR
235 on Windows) into account when writing \f(CW\*(C`File::Spec\*(C'\fR\-using code? I
236 thought not. But if you use \f(CW\*(C`Path::Class\*(C'\fR, your file and directory objects
237 will know what volumes they refer to and do the right thing.
239 The guts of the \f(CW\*(C`Path::Class\*(C'\fR code live in the \f(CW\*(C`Path::Class::File\*(C'\fR
240 and \f(CW\*(C`Path::Class::Dir\*(C'\fR modules, so please see those
241 modules' documentation for more details about how to use them.
243 .IX Subsection "EXPORT"
244 The following functions are exported by default.
247 A synonym for \f(CW\*(C`Path::Class::File\->new\*(C'\fR.
250 A synonym for \f(CW\*(C`Path::Class::Dir\->new\*(C'\fR.
252 If you would like to prevent their export, you may explicitly pass an
253 empty list to perl's \f(CW\*(C`use\*(C'\fR, i.e. \f(CW\*(C`use Path::Class ()\*(C'\fR.
255 The following are exported only on demand.
257 .IX Item "foreign_file"
258 A synonym for \f(CW\*(C`Path::Class::File\->new_foreign\*(C'\fR.
260 .IX Item "foreign_dir"
261 A synonym for \f(CW\*(C`Path::Class::Dir\->new_foreign\*(C'\fR.
262 .SH "Notes on Cross-Platform Compatibility"
263 .IX Header "Notes on Cross-Platform Compatibility"
264 Although it is much easier to write cross-platform-friendly code with
265 this module than with \f(CW\*(C`File::Spec\*(C'\fR, there are still some issues to be
268 Some platforms, notably \s-1VMS\s0 and some older versions of \s-1DOS\s0 (I think),
269 all filenames must have an extension. Thus if you create a file
270 called \fIfoo/bar\fR and then ask for a list of files in the directory
271 \&\fIfoo\fR, you may find a file called \fIbar.\fR instead of the \fIbar\fR you
272 were expecting. Thus it might be a good idea to use an extension in
276 Ken Williams, KWILLIAMS@cpan.org
278 .IX Header "COPYRIGHT"
279 Copyright (c) Ken Williams. All rights reserved.
281 This library is free software; you can redistribute it and/or
282 modify it under the same terms as Perl itself.
284 .IX Header "SEE ALSO"
285 Path::Class::Dir, Path::Class::File, File::Spec