local-lib5/man/man3/Path::Class::File.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  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<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  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
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  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.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  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
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  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'
 101 .\}
 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 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Path::Class::File 3"
 132 .TH Path::Class::File 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Path::Class::File \- Objects representing files
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use Path::Class qw(file);  # Export a short constructor
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&  my $file = file('foo', 'bar.txt');  # Path::Class::File object
 143 \&  my $file = Path::Class::File\->new('foo', 'bar.txt'); # Same thing
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  # Stringifies to 'foo/bar.txt' on Unix, 'foo\ebar.txt' on Windows, etc.
 148 \&  print "file: $file\en";
 149 .Ve
 150 .PP
 151 .Vb 2
 152 \&  if ($file\->is_absolute) { ... }
 153 \&  if ($file\->is_relative) { ... }
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&  my $v = $file\->volume; # Could be 'C:' on Windows, empty string
 158 \&                         # on Unix, 'Macintosh HD:' on Mac OS
 159 .Ve
 160 .PP
 161 .Vb 2
 162 \&  $file\->cleanup; # Perform logical cleanup of pathname
 163 \&  $file\->resolve; # Perform physical cleanup of pathname
 164 .Ve
 165 .PP
 166 .Vb 1
 167 \&  my $dir = $file\->dir;  # A Path::Class::Dir object
 168 .Ve
 169 .PP
 170 .Vb 2
 171 \&  my $abs = $file\->absolute; # Transform to absolute path
 172 \&  my $rel = $file\->relative; # Transform to relative path
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 The \f(CW\*(C`Path::Class::File\*(C'\fR class contains functionality for manipulating
 177 file names in a cross-platform way.
 178 .SH "METHODS"
 179 .IX Header "METHODS"
 180 .IP "$file = Path::Class::File\->new( <dir1>, <dir2>, ..., <file> )" 4
 181 .IX Item "$file = Path::Class::File->new( <dir1>, <dir2>, ..., <file> )"
 182 .PD 0
 183 .IP "$file = file( <dir1>, <dir2>, ..., <file> )" 4
 184 .IX Item "$file = file( <dir1>, <dir2>, ..., <file> )"
 185 .PD
 186 Creates a new \f(CW\*(C`Path::Class::File\*(C'\fR object and returns it.  The
 187 arguments specify the path to the file.  Any volume may also be
 188 specified as the first argument, or as part of the first argument.
 189 You can use platform-neutral syntax:
 190 .Sp
 191 .Vb 1
 192 \&  my $dir = file( 'foo', 'bar', 'baz.txt' );
 193 .Ve
 194 .Sp
 195 or platform-native syntax:
 196 .Sp
 197 .Vb 1
 198 \&  my $dir = dir( 'foo/bar/baz.txt' );
 199 .Ve
 200 .Sp
 201 or a mixture of the two:
 202 .Sp
 203 .Vb 1
 204 \&  my $dir = dir( 'foo/bar', 'baz.txt' );
 205 .Ve
 206 .Sp
 207 All three of the above examples create relative paths.  To create an
 208 absolute path, either use the platform native syntax for doing so:
 209 .Sp
 210 .Vb 1
 211 \&  my $dir = dir( '/var/tmp/foo.txt' );
 212 .Ve
 213 .Sp
 214 or use an empty string as the first argument:
 215 .Sp
 216 .Vb 1
 217 \&  my $dir = dir( '', 'var', 'tmp', 'foo.txt' );
 218 .Ve
 219 .Sp
 220 If the second form seems awkward, that's somewhat intentional \- paths
 221 like \f(CW\*(C`/var/tmp\*(C'\fR or \f(CW\*(C`\eWindows\*(C'\fR aren't cross-platform concepts in the
 222 first place, so they probably shouldn't appear in your code if you're
 223 trying to be cross\-platform.  The first form is perfectly fine,
 224 because paths like this may come from config files, user input, or
 225 whatever.
 226 .IP "$file\->stringify" 4
 227 .IX Item "$file->stringify"
 228 This method is called internally when a \f(CW\*(C`Path::Class::File\*(C'\fR object is
 229 used in a string context, so the following are equivalent:
 230 .Sp
 231 .Vb 2
 232 \&  $string = $file\->stringify;
 233 \&  $string = "$file";
 234 .Ve
 235 .IP "$file\->volume" 4
 236 .IX Item "$file->volume"
 237 Returns the volume (e.g. \f(CW\*(C`C:\*(C'\fR on Windows, \f(CW\*(C`Macintosh HD:\*(C'\fR on Mac \s-1OS\s0,
 238 etc.) of the object, if any.  Otherwise, returns the empty string.
 239 .IP "$file\->basename" 4
 240 .IX Item "$file->basename"
 241 Returns the name of the file as a string, without the directory
 242 portion (if any).
 243 .IP "$file\->is_dir" 4
 244 .IX Item "$file->is_dir"
 245 Returns a boolean value indicating whether this object represents a
 246 directory.  Not surprisingly, \f(CW\*(C`Path::Class::File\*(C'\fR objects always
 247 return false, and \f(CW\*(C`Path::Class::Dir\*(C'\fR objects always return true.
 248 .IP "$file\->is_absolute" 4
 249 .IX Item "$file->is_absolute"
 250 Returns true or false depending on whether the file refers to an
 251 absolute path specifier (like \f(CW\*(C`/usr/local/foo.txt\*(C'\fR or \f(CW\*(C`\eWindows\eFoo.txt\*(C'\fR).
 252 .IP "$file\->is_absolute" 4
 253 .IX Item "$file->is_absolute"
 254 Returns true or false depending on whether the file refers to a
 255 relative path specifier (like \f(CW\*(C`lib/foo.txt\*(C'\fR or \f(CW\*(C`.\eFoo.txt\*(C'\fR).
 256 .IP "$file\->cleanup" 4
 257 .IX Item "$file->cleanup"
 258 Performs a logical cleanup of the file path.  For instance:
 259 .Sp
 260 .Vb 2
 261 \&  my $file = file('/foo//baz/./foo.txt')\->cleanup;
 262 \&  # $file now represents '/foo/baz/foo.txt';
 263 .Ve
 264 .IP "$dir\->resolve" 4
 265 .IX Item "$dir->resolve"
 266 Performs a physical cleanup of the file path.  For instance:
 267 .Sp
 268 .Vb 2
 269 \&  my $dir = dir('/foo/baz/../foo.txt')\->resolve;
 270 \&  # $dir now represents '/foo/foo.txt', assuming no symlinks
 271 .Ve
 272 .Sp
 273 This actually consults the filesystem to verify the validity of the
 274 path.
 275 .ie n .IP "$dir = $file\->dir" 4
 276 .el .IP "$dir = \f(CW$file\fR\->dir" 4
 277 .IX Item "$dir = $file->dir"
 278 Returns a \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing the directory
 279 containing this file.
 280 .ie n .IP "$dir = $file\->parent" 4
 281 .el .IP "$dir = \f(CW$file\fR\->parent" 4
 282 .IX Item "$dir = $file->parent"
 283 A synonym for the \f(CW\*(C`dir()\*(C'\fR method.
 284 .ie n .IP "$abs = $file\->absolute" 4
 285 .el .IP "$abs = \f(CW$file\fR\->absolute" 4
 286 .IX Item "$abs = $file->absolute"
 287 Returns a \f(CW\*(C`Path::Class::File\*(C'\fR object representing \f(CW$file\fR as an
 288 absolute path.  An optional argument, given as either a string or a
 289 \&\f(CW\*(C`Path::Class::Dir\*(C'\fR object, specifies the directory to use as the base
 290 of relativity \- otherwise the current working directory will be used.
 291 .ie n .IP "$rel = $file\->relative" 4
 292 .el .IP "$rel = \f(CW$file\fR\->relative" 4
 293 .IX Item "$rel = $file->relative"
 294 Returns a \f(CW\*(C`Path::Class::File\*(C'\fR object representing \f(CW$file\fR as a
 295 relative path.  An optional argument, given as either a string or a
 296 \&\f(CW\*(C`Path::Class::Dir\*(C'\fR object, specifies the directory to use as the base
 297 of relativity \- otherwise the current working directory will be used.
 298 .ie n .IP "$foreign = $file\->as_foreign($type)" 4
 299 .el .IP "$foreign = \f(CW$file\fR\->as_foreign($type)" 4
 300 .IX Item "$foreign = $file->as_foreign($type)"
 301 Returns a \f(CW\*(C`Path::Class::File\*(C'\fR object representing \f(CW$file\fR as it would
 302 be specified on a system of type \f(CW$type\fR.  Known types include
 303 \&\f(CW\*(C`Unix\*(C'\fR, \f(CW\*(C`Win32\*(C'\fR, \f(CW\*(C`Mac\*(C'\fR, \f(CW\*(C`VMS\*(C'\fR, and \f(CW\*(C`OS2\*(C'\fR, i.e. anything for which
 304 there is a subclass of \f(CW\*(C`File::Spec\*(C'\fR.
 305 .Sp
 306 Any generated objects (subdirectories, files, parents, etc.) will also
 307 retain this type.
 308 .ie n .IP "$foreign = Path::Class::File\->new_foreign($type, @args)" 4
 309 .el .IP "$foreign = Path::Class::File\->new_foreign($type, \f(CW@args\fR)" 4
 310 .IX Item "$foreign = Path::Class::File->new_foreign($type, @args)"
 311 Returns a \f(CW\*(C`Path::Class::File\*(C'\fR object representing a file as it would
 312 be specified on a system of type \f(CW$type\fR.  Known types include
 313 \&\f(CW\*(C`Unix\*(C'\fR, \f(CW\*(C`Win32\*(C'\fR, \f(CW\*(C`Mac\*(C'\fR, \f(CW\*(C`VMS\*(C'\fR, and \f(CW\*(C`OS2\*(C'\fR, i.e. anything for which
 314 there is a subclass of \f(CW\*(C`File::Spec\*(C'\fR.
 315 .Sp
 316 The arguments in \f(CW@args\fR are the same as they would be specified in
 317 \&\f(CW\*(C`new()\*(C'\fR.
 318 .ie n .IP "$fh = $file\fR\->open($mode, \f(CW$permissions)" 4
 319 .el .IP "$fh = \f(CW$file\fR\->open($mode, \f(CW$permissions\fR)" 4
 320 .IX Item "$fh = $file->open($mode, $permissions)"
 321 Passes the given arguments, including \f(CW$file\fR, to \f(CW\*(C`IO::File\->new\*(C'\fR
 322 (which in turn calls \f(CW\*(C`IO::File\->open\*(C'\fR and returns the result
 323 as an \f(CW\*(C`IO::File\*(C'\fR object.  If the opening
 324 fails, \f(CW\*(C`undef\*(C'\fR is returned and \f(CW$!\fR is set.
 325 .ie n .IP "$fh = $file\fR\->\fIopenr()" 4
 326 .el .IP "$fh = \f(CW$file\fR\->\fIopenr()\fR" 4
 327 .IX Item "$fh = $file->openr()"
 328 A shortcut for
 329 .Sp
 330 .Vb 1
 331 \& $fh = $file\->open('r') or die "Can't read $file: $!";
 332 .Ve
 333 .ie n .IP "$fh = $file\fR\->\fIopenw()" 4
 334 .el .IP "$fh = \f(CW$file\fR\->\fIopenw()\fR" 4
 335 .IX Item "$fh = $file->openw()"
 336 A shortcut for
 337 .Sp
 338 .Vb 1
 339 \& $fh = $file\->open('w') or die "Can't write $file: $!";
 340 .Ve
 341 .IP "$file\->touch" 4
 342 .IX Item "$file->touch"
 343 Sets the modification and access time of the given file to right now,
 344 if the file exists.  If it doesn't exist, \f(CW\*(C`touch()\*(C'\fR will \fImake\fR it
 345 exist, and \- \s-1YES\s0! \- set its modification and access time to now.
 346 .IP "$file\->\fIslurp()\fR" 4
 347 .IX Item "$file->slurp()"
 348 In a scalar context, returns the contents of \f(CW$file\fR in a string.  In
 349 a list context, returns the lines of \f(CW$file\fR (according to how \f(CW$/\fR
 350 is set) as a list.  If the file can't be read, this method will throw
 351 an exception.
 352 .Sp
 353 If you want \f(CW\*(C`chomp()\*(C'\fR run on each line of the file, pass a true value
 354 for the \f(CW\*(C`chomp\*(C'\fR or \f(CW\*(C`chomped\*(C'\fR parameters:
 355 .Sp
 356 .Vb 1
 357 \&  my @lines = $file\->slurp(chomp => 1);
 358 .Ve
 359 .IP "$file\->\fIremove()\fR" 4
 360 .IX Item "$file->remove()"
 361 This method will remove the file in a way that works well on all
 362 platforms, and returns a boolean value indicating whether or not the
 363 file was successfully removed.
 364 .Sp
 365 \&\f(CW\*(C`remove()\*(C'\fR is better than simply calling Perl's \f(CW\*(C`unlink()\*(C'\fR function,
 366 because on some platforms (notably \s-1VMS\s0) you actually may need to call
 367 \&\f(CW\*(C`unlink()\*(C'\fR several times before all versions of the file are gone \-
 368 the \f(CW\*(C`remove()\*(C'\fR method handles this process for you.
 369 .ie n .IP "$st = $file\fR\->\fIstat()" 4
 370 .el .IP "$st = \f(CW$file\fR\->\fIstat()\fR" 4
 371 .IX Item "$st = $file->stat()"
 372 Invokes \f(CW\*(C`File::stat::stat()\*(C'\fR on this file and returns a
 373 \&\f(CW\*(C`File::stat\*(C'\fR object representing the result.
 374 .ie n .IP "$st = $file\fR\->\fIlstat()" 4
 375 .el .IP "$st = \f(CW$file\fR\->\fIlstat()\fR" 4
 376 .IX Item "$st = $file->lstat()"
 377 Same as \f(CW\*(C`stat()\*(C'\fR, but if \f(CW$file\fR is a symbolic link, \f(CW\*(C`lstat()\*(C'\fR
 378 stats the link instead of the file the link points to.
 379 .SH "AUTHOR"
 380 .IX Header "AUTHOR"
 381 Ken Williams, ken@mathforum.org
 382 .SH "SEE ALSO"
 383 .IX Header "SEE ALSO"
 384 Path::Class, Path::Class::Dir, File::Spec