local-lib5/man/man3/Path::Class::Dir.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::Dir 3"
 132 .TH Path::Class::Dir 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Path::Class::Dir \- Objects representing directories
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use Path::Class qw(dir);  # Export a short constructor
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&  my $dir = dir('foo', 'bar');       # Path::Class::Dir object
 143 \&  my $dir = Path::Class::Dir\->new('foo', 'bar');  # Same thing
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  # Stringifies to 'foo/bar' on Unix, 'foo\ebar' on Windows, etc.
 148 \&  print "dir: $dir\en";
 149 .Ve
 150 .PP
 151 .Vb 2
 152 \&  if ($dir\->is_absolute) { ... }
 153 \&  if ($dir\->is_relative) { ... }
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&  my $v = $dir\->volume; # Could be 'C:' on Windows, empty string
 158 \&                        # on Unix, 'Macintosh HD:' on Mac OS
 159 .Ve
 160 .PP
 161 .Vb 2
 162 \&  $dir\->cleanup; # Perform logical cleanup of pathname
 163 \&  $dir\->resolve; # Perform physical cleanup of pathname
 164 .Ve
 165 .PP
 166 .Vb 3
 167 \&  my $file = $dir\->file('file.txt'); # A file in this directory
 168 \&  my $subdir = $dir\->subdir('george'); # A subdirectory
 169 \&  my $parent = $dir\->parent; # The parent directory, 'foo'
 170 .Ve
 171 .PP
 172 .Vb 3
 173 \&  my $abs = $dir\->absolute; # Transform to absolute path
 174 \&  my $rel = $abs\->relative; # Transform to relative path
 175 \&  my $rel = $abs\->relative('/foo'); # Relative to /foo
 176 .Ve
 177 .PP
 178 .Vb 2
 179 \&  print $dir\->as_foreign('Mac');   # :foo:bar:
 180 \&  print $dir\->as_foreign('Win32'); #  foo\ebar
 181 .Ve
 182 .PP
 183 .Vb 6
 184 \&  # Iterate with IO::Dir methods:
 185 \&  my $handle = $dir\->open;
 186 \&  while (my $file = $handle\->read) {
 187 \&    $file = $dir\->file($file);  # Turn into Path::Class::File object
 188 \&    ...
 189 \&  }
 190 .Ve
 191 .PP
 192 .Vb 5
 193 \&  # Iterate with Path::Class methods:
 194 \&  while (my $file = $dir\->next) {
 195 \&    # $file is a Path::Class::File or Path::Class::Dir object
 196 \&    ...
 197 \&  }
 198 .Ve
 199 .SH "DESCRIPTION"
 200 .IX Header "DESCRIPTION"
 201 The \f(CW\*(C`Path::Class::Dir\*(C'\fR class contains functionality for manipulating
 202 directory names in a cross-platform way.
 203 .SH "METHODS"
 204 .IX Header "METHODS"
 205 .IP "$dir = Path::Class::Dir\->new( <dir1>, <dir2>, ... )" 4
 206 .IX Item "$dir = Path::Class::Dir->new( <dir1>, <dir2>, ... )"
 207 .PD 0
 208 .IP "$dir = dir( <dir1>, <dir2>, ... )" 4
 209 .IX Item "$dir = dir( <dir1>, <dir2>, ... )"
 210 .PD
 211 Creates a new \f(CW\*(C`Path::Class::Dir\*(C'\fR object and returns it.  The
 212 arguments specify names of directories which will be joined to create
 213 a single directory object.  A volume may also be specified as the
 214 first argument, or as part of the first argument.  You can use
 215 platform-neutral syntax:
 216 .Sp
 217 .Vb 1
 218 \&  my $dir = dir( 'foo', 'bar', 'baz' );
 219 .Ve
 220 .Sp
 221 or platform-native syntax:
 222 .Sp
 223 .Vb 1
 224 \&  my $dir = dir( 'foo/bar/baz' );
 225 .Ve
 226 .Sp
 227 or a mixture of the two:
 228 .Sp
 229 .Vb 1
 230 \&  my $dir = dir( 'foo/bar', 'baz' );
 231 .Ve
 232 .Sp
 233 All three of the above examples create relative paths.  To create an
 234 absolute path, either use the platform native syntax for doing so:
 235 .Sp
 236 .Vb 1
 237 \&  my $dir = dir( '/var/tmp' );
 238 .Ve
 239 .Sp
 240 or use an empty string as the first argument:
 241 .Sp
 242 .Vb 1
 243 \&  my $dir = dir( '', 'var', 'tmp' );
 244 .Ve
 245 .Sp
 246 If the second form seems awkward, that's somewhat intentional \- paths
 247 like \f(CW\*(C`/var/tmp\*(C'\fR or \f(CW\*(C`\eWindows\*(C'\fR aren't cross-platform concepts in the
 248 first place (many non-Unix platforms don't have a notion of a \*(L"root
 249 directory\*(R"), so they probably shouldn't appear in your code if you're
 250 trying to be cross\-platform.  The first form is perfectly natural,
 251 because paths like this may come from config files, user input, or
 252 whatever.
 253 .Sp
 254 As a special case, since it doesn't otherwise mean anything useful and
 255 it's convenient to define this way, \f(CW\*(C`Path::Class::Dir\->new()\*(C'\fR (or
 256 \&\f(CW\*(C`dir()\*(C'\fR) refers to the current directory (\f(CW\*(C`File::Spec\->curdir\*(C'\fR).
 257 To get the current directory as an absolute path, do \f(CW\*(C`dir()\->absolute\*(C'\fR.
 258 .Sp
 259 Finally, as another special case \f(CW\*(C`dir(undef)\*(C'\fR will return undef,
 260 since that's usually an accident on the part of the caller, and
 261 returning the root directory would be a nasty surprise just asking for
 262 trouble a few lines later.
 263 .IP "$dir\->stringify" 4
 264 .IX Item "$dir->stringify"
 265 This method is called internally when a \f(CW\*(C`Path::Class::Dir\*(C'\fR object is
 266 used in a string context, so the following are equivalent:
 267 .Sp
 268 .Vb 2
 269 \&  $string = $dir\->stringify;
 270 \&  $string = "$dir";
 271 .Ve
 272 .IP "$dir\->volume" 4
 273 .IX Item "$dir->volume"
 274 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,
 275 etc.) of the directory object, if any.  Otherwise, returns the empty
 276 string.
 277 .IP "$dir\->is_dir" 4
 278 .IX Item "$dir->is_dir"
 279 Returns a boolean value indicating whether this object represents a
 280 directory.  Not surprisingly, \f(CW\*(C`Path::Class::File\*(C'\fR objects always
 281 return false, and \f(CW\*(C`Path::Class::Dir\*(C'\fR objects always return true.
 282 .IP "$dir\->is_absolute" 4
 283 .IX Item "$dir->is_absolute"
 284 Returns true or false depending on whether the directory refers to an
 285 absolute path specifier (like \f(CW\*(C`/usr/local\*(C'\fR or \f(CW\*(C`\eWindows\*(C'\fR).
 286 .IP "$dir\->is_relative" 4
 287 .IX Item "$dir->is_relative"
 288 Returns true or false depending on whether the directory refers to a
 289 relative path specifier (like \f(CW\*(C`lib/foo\*(C'\fR or \f(CW\*(C`./dir\*(C'\fR).
 290 .IP "$dir\->cleanup" 4
 291 .IX Item "$dir->cleanup"
 292 Performs a logical cleanup of the file path.  For instance:
 293 .Sp
 294 .Vb 2
 295 \&  my $dir = dir('/foo//baz/./foo')\->cleanup;
 296 \&  # $dir now represents '/foo/baz/foo';
 297 .Ve
 298 .IP "$dir\->resolve" 4
 299 .IX Item "$dir->resolve"
 300 Performs a physical cleanup of the file path.  For instance:
 301 .Sp
 302 .Vb 2
 303 \&  my $dir = dir('/foo//baz/../foo')\->resolve;
 304 \&  # $dir now represents '/foo/foo', assuming no symlinks
 305 .Ve
 306 .Sp
 307 This actually consults the filesystem to verify the validity of the
 308 path.
 309 .ie n .IP "$file = $dir\->file( <dir1>, <dir2>, ..., <file> )" 4
 310 .el .IP "$file = \f(CW$dir\fR\->file( <dir1>, <dir2>, ..., <file> )" 4
 311 .IX Item "$file = $dir->file( <dir1>, <dir2>, ..., <file> )"
 312 Returns a \f(CW\*(C`Path::Class::File\*(C'\fR object representing an entry in \f(CW$dir\fR
 313 or one of its subdirectories.  Internally, this just calls \f(CW\*(C`Path::Class::File\->new( @_ )\*(C'\fR.
 314 .ie n .IP "$subdir = $dir\->subdir( <dir1>, <dir2>, ... )" 4
 315 .el .IP "$subdir = \f(CW$dir\fR\->subdir( <dir1>, <dir2>, ... )" 4
 316 .IX Item "$subdir = $dir->subdir( <dir1>, <dir2>, ... )"
 317 Returns a new \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing a subdirectory
 318 of \f(CW$dir\fR.
 319 .ie n .IP "$parent = $dir\->parent" 4
 320 .el .IP "$parent = \f(CW$dir\fR\->parent" 4
 321 .IX Item "$parent = $dir->parent"
 322 Returns the parent directory of \f(CW$dir\fR.  Note that this is the
 323 \&\fIlogical\fR parent, not necessarily the physical parent.  It really
 324 means we just chop off entries from the end of the directory list
 325 until we cain't chop no more.  If the directory is relative, we start
 326 using the relative forms of parent directories.
 327 .Sp
 328 The following code demonstrates the behavior on absolute and relative
 329 directories:
 330 .Sp
 331 .Vb 5
 332 \&  $dir = dir('/foo/bar');
 333 \&  for (1..6) {
 334 \&    print "Absolute: $dir\en";
 335 \&    $dir = $dir\->parent;
 336 \&  }
 337 .Ve
 338 .Sp
 339 .Vb 5
 340 \&  $dir = dir('foo/bar');
 341 \&  for (1..6) {
 342 \&    print "Relative: $dir\en";
 343 \&    $dir = $dir\->parent;
 344 \&  }
 345 .Ve
 346 .Sp
 347 .Vb 13
 348 \&  ########### Output on Unix ################
 349 \&  Absolute: /foo/bar
 350 \&  Absolute: /foo
 351 \&  Absolute: /
 352 \&  Absolute: /
 353 \&  Absolute: /
 354 \&  Absolute: /
 355 \&  Relative: foo/bar
 356 \&  Relative: foo
 357 \&  Relative: .
 358 \&  Relative: ..
 359 \&  Relative: ../..
 360 \&  Relative: ../../..
 361 .Ve
 362 .ie n .IP "@list = $dir\->children" 4
 363 .el .IP "@list = \f(CW$dir\fR\->children" 4
 364 .IX Item "@list = $dir->children"
 365 Returns a list of \f(CW\*(C`Path::Class::File\*(C'\fR and/or \f(CW\*(C`Path::Class::Dir\*(C'\fR
 366 objects listed in this directory, or in scalar context the number of
 367 such objects.  Obviously, it is necessary for \f(CW$dir\fR to
 368 exist and be readable in order to find its children.
 369 .Sp
 370 Note that the children are returned as subdirectories of \f(CW$dir\fR,
 371 i.e. the children of \fIfoo\fR will be \fIfoo/bar\fR and \fIfoo/baz\fR, not
 372 \&\fIbar\fR and \fIbaz\fR.
 373 .Sp
 374 Ordinarily \f(CW\*(C`children()\*(C'\fR will not include the \fIself\fR and \fIparent\fR
 375 entries \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`..\*(C'\fR (or their equivalents on non-Unix systems),
 376 because that's like I'm\-my\-own\-grandpa business.  If you do want all
 377 directory entries including these special ones, pass a true value for
 378 the \f(CW\*(C`all\*(C'\fR parameter:
 379 .Sp
 380 .Vb 2
 381 \&  @c = $dir\->children(); # Just the children
 382 \&  @c = $dir\->children(all => 1); # All entries
 383 .Ve
 384 .ie n .IP "$abs = $dir\->absolute" 4
 385 .el .IP "$abs = \f(CW$dir\fR\->absolute" 4
 386 .IX Item "$abs = $dir->absolute"
 387 Returns a \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing \f(CW$dir\fR as an
 388 absolute path.  An optional argument, given as either a string or a
 389 \&\f(CW\*(C`Path::Class::Dir\*(C'\fR object, specifies the directory to use as the base
 390 of relativity \- otherwise the current working directory will be used.
 391 .ie n .IP "$rel = $dir\->relative" 4
 392 .el .IP "$rel = \f(CW$dir\fR\->relative" 4
 393 .IX Item "$rel = $dir->relative"
 394 Returns a \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing \f(CW$dir\fR as a
 395 relative path.  An optional argument, given as either a string or a
 396 \&\f(CW\*(C`Path::Class::Dir\*(C'\fR object, specifies the directory to use as the base
 397 of relativity \- otherwise the current working directory will be used.
 398 .ie n .IP "$boolean = $dir\->subsumes($other)" 4
 399 .el .IP "$boolean = \f(CW$dir\fR\->subsumes($other)" 4
 400 .IX Item "$boolean = $dir->subsumes($other)"
 401 Returns true if this directory spec subsumes the other spec, and false
 402 otherwise.  Think of \*(L"subsumes\*(R" as \*(L"contains\*(R", but we only look at the
 403 \&\fIspecs\fR, not whether \f(CW$dir\fR actually contains \f(CW$other\fR on the
 404 filesystem.
 405 .Sp
 406 The \f(CW$other\fR argument may be a \f(CW\*(C`Path::Class::Dir\*(C'\fR object, a
 407 \&\f(CW\*(C`Path::Class::File\*(C'\fR object, or a string.  In the latter case, we
 408 assume it's a directory.
 409 .Sp
 410 .Vb 5
 411 \&  # Examples:
 412 \&  dir('foo/bar' )\->subsumes(dir('foo/bar/baz'))  # True
 413 \&  dir('/foo/bar')\->subsumes(dir('/foo/bar/baz')) # True
 414 \&  dir('foo/bar' )\->subsumes(dir('bar/baz'))      # False
 415 \&  dir('/foo/bar')\->subsumes(dir('foo/bar'))      # False
 416 .Ve
 417 .ie n .IP "$boolean = $dir\->contains($other)" 4
 418 .el .IP "$boolean = \f(CW$dir\fR\->contains($other)" 4
 419 .IX Item "$boolean = $dir->contains($other)"
 420 Returns true if this directory actually contains \f(CW$other\fR on the
 421 filesystem.  \f(CW$other\fR doesn't have to be a direct child of \f(CW$dir\fR,
 422 it just has to be subsumed.
 423 .ie n .IP "$foreign = $dir\->as_foreign($type)" 4
 424 .el .IP "$foreign = \f(CW$dir\fR\->as_foreign($type)" 4
 425 .IX Item "$foreign = $dir->as_foreign($type)"
 426 Returns a \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing \f(CW$dir\fR as it would
 427 be specified on a system of type \f(CW$type\fR.  Known types include
 428 \&\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
 429 there is a subclass of \f(CW\*(C`File::Spec\*(C'\fR.
 430 .Sp
 431 Any generated objects (subdirectories, files, parents, etc.) will also
 432 retain this type.
 433 .ie n .IP "$foreign = Path::Class::Dir\->new_foreign($type, @args)" 4
 434 .el .IP "$foreign = Path::Class::Dir\->new_foreign($type, \f(CW@args\fR)" 4
 435 .IX Item "$foreign = Path::Class::Dir->new_foreign($type, @args)"
 436 Returns a \f(CW\*(C`Path::Class::Dir\*(C'\fR object representing \f(CW$dir\fR as it would
 437 be specified on a system of type \f(CW$type\fR.  Known types include
 438 \&\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
 439 there is a subclass of \f(CW\*(C`File::Spec\*(C'\fR.
 440 .Sp
 441 The arguments in \f(CW@args\fR are the same as they would be specified in
 442 \&\f(CW\*(C`new()\*(C'\fR.
 443 .ie n .IP "@list = $dir\->dir_list([\s-1OFFSET\s0, [\s-1LENGTH\s0]])" 4
 444 .el .IP "@list = \f(CW$dir\fR\->dir_list([\s-1OFFSET\s0, [\s-1LENGTH\s0]])" 4
 445 .IX Item "@list = $dir->dir_list([OFFSET, [LENGTH]])"
 446 Returns the list of strings internally representing this directory
 447 structure.  Each successive member of the list is understood to be an
 448 entry in its predecessor's directory list.  By contract, \f(CW\*(C`Path::Class\->new( $dir\->dir_list )\*(C'\fR should be equivalent to \f(CW$dir\fR.
 449 .Sp
 450 The semantics of this method are similar to Perl's \f(CW\*(C`splice\*(C'\fR or
 451 \&\f(CW\*(C`substr\*(C'\fR functions; they return \f(CW\*(C`LENGTH\*(C'\fR elements starting at
 452 \&\f(CW\*(C`OFFSET\*(C'\fR.  If \f(CW\*(C`LENGTH\*(C'\fR is omitted, returns all the elements starting
 453 at \f(CW\*(C`OFFSET\*(C'\fR up to the end of the list.  If \f(CW\*(C`LENGTH\*(C'\fR is negative,
 454 returns the elements from \f(CW\*(C`OFFSET\*(C'\fR onward except for \f(CW\*(C`\-LENGTH\*(C'\fR
 455 elements at the end.  If \f(CW\*(C`OFFSET\*(C'\fR is negative, it counts backward
 456 \&\f(CW\*(C`OFFSET\*(C'\fR elements from the end of the list.  If \f(CW\*(C`OFFSET\*(C'\fR and
 457 \&\f(CW\*(C`LENGTH\*(C'\fR are both omitted, the entire list is returned.
 458 .Sp
 459 In a scalar context, \f(CW\*(C`dir_list()\*(C'\fR with no arguments returns the
 460 number of entries in the directory list; \f(CW\*(C`dir_list(OFFSET)\*(C'\fR returns
 461 the single element at that offset; \f(CW\*(C`dir_list(OFFSET, LENGTH)\*(C'\fR returns
 462 the final element that would have been returned in a list context.
 463 .ie n .IP "$fh = $dir\fR\->\fIopen()" 4
 464 .el .IP "$fh = \f(CW$dir\fR\->\fIopen()\fR" 4
 465 .IX Item "$fh = $dir->open()"
 466 Passes \f(CW$dir\fR to \f(CW\*(C`IO::Dir\->open\*(C'\fR and returns the result as an
 467 \&\f(CW\*(C`IO::Dir\*(C'\fR object.  If the opening fails, \f(CW\*(C`undef\*(C'\fR is returned and
 468 \&\f(CW$!\fR is set.
 469 .ie n .IP "$dir\->mkpath($verbose, $mode)" 4
 470 .el .IP "$dir\->mkpath($verbose, \f(CW$mode\fR)" 4
 471 .IX Item "$dir->mkpath($verbose, $mode)"
 472 Passes all arguments, including \f(CW$dir\fR, to \f(CW\*(C`File::Path::mkpath()\*(C'\fR and returns the result (a list of all directories created).
 473 .ie n .IP "$dir\->rmtree($verbose, $cautious)" 4
 474 .el .IP "$dir\->rmtree($verbose, \f(CW$cautious\fR)" 4
 475 .IX Item "$dir->rmtree($verbose, $cautious)"
 476 Passes all arguments, including \f(CW$dir\fR, to \f(CW\*(C`File::Path::rmtree()\*(C'\fR and returns the result (the number of files successfully deleted).
 477 .IP "$dir\->\fIremove()\fR" 4
 478 .IX Item "$dir->remove()"
 479 Removes the directory, which must be empty.  Returns a boolean value
 480 indicating whether or not the directory was successfully removed.
 481 This method is mainly provided for consistency with
 482 \&\f(CW\*(C`Path::Class::File\*(C'\fR's \f(CW\*(C`remove()\*(C'\fR method.
 483 .ie n .IP "$dir_or_file = $dir\fR\->\fInext()" 4
 484 .el .IP "$dir_or_file = \f(CW$dir\fR\->\fInext()\fR" 4
 485 .IX Item "$dir_or_file = $dir->next()"
 486 A convenient way to iterate through directory contents.  The first
 487 time \f(CW\*(C`next()\*(C'\fR is called, it will \f(CW\*(C`open()\*(C'\fR the directory and read the
 488 first item from it, returning the result as a \f(CW\*(C`Path::Class::Dir\*(C'\fR or
 489 \&\f(CW\*(C`Path::Class::File\*(C'\fR object (depending, of course, on its actual
 490 type).  Each subsequent call to \f(CW\*(C`next()\*(C'\fR will simply iterate over the
 491 directory's contents, until there are no more items in the directory,
 492 and then the undefined value is returned.  For example, to iterate
 493 over all the regular files in a directory:
 494 .Sp
 495 .Vb 5
 496 \&  while (my $file = $dir\->next) {
 497 \&    next unless \-f $file;
 498 \&    my $fh = $file\->open('r') or die "Can't read $file: $!";
 499 \&    ...
 500 \&  }
 501 .Ve
 502 .Sp
 503 If an error occurs when opening the directory (for instance, it
 504 doesn't exist or isn't readable), \f(CW\*(C`next()\*(C'\fR will throw an exception
 505 with the value of \f(CW$!\fR.
 506 .IP "$dir\->recurse( callback => sub {...} )" 4
 507 .IX Item "$dir->recurse( callback => sub {...} )"
 508 Iterates through this directory and all of its children, and all of
 509 its children's children, etc., calling the \f(CW\*(C`callback\*(C'\fR subroutine for
 510 each entry.  This is a lot like what the \f(CW\*(C`File::Find\*(C'\fR module does,
 511 and of course \f(CW\*(C`File::Find\*(C'\fR will work fine on \f(CW\*(C`Path::Class\*(C'\fR objects,
 512 but the advantage of the \f(CW\*(C`recurse()\*(C'\fR method is that it will also feed
 513 your callback routine \f(CW\*(C`Path::Class\*(C'\fR objects rather than just pathname
 514 strings.
 515 .Sp
 516 The \f(CW\*(C`recurse()\*(C'\fR method requires a \f(CW\*(C`callback\*(C'\fR parameter specifying
 517 the subroutine to invoke for each entry.  It will be passed the
 518 \&\f(CW\*(C`Path::Class\*(C'\fR object as its first argument.
 519 .Sp
 520 \&\f(CW\*(C`recurse()\*(C'\fR also accepts two boolean parameters, \f(CW\*(C`depthfirst\*(C'\fR and
 521 \&\f(CW\*(C`preorder\*(C'\fR that control the order of recursion.  The default is a
 522 preorder, breadth-first search, i.e. \f(CW\*(C`depthfirst => 0, preorder => 1\*(C'\fR.
 523 At the time of this writing, all combinations of these two parameters
 524 are supported \fIexcept\fR \f(CW\*(C`depthfirst => 0, preorder => 0\*(C'\fR.
 525 .ie n .IP "$st = $file\fR\->\fIstat()" 4
 526 .el .IP "$st = \f(CW$file\fR\->\fIstat()\fR" 4
 527 .IX Item "$st = $file->stat()"
 528 Invokes \f(CW\*(C`File::stat::stat()\*(C'\fR on this directory and returns a
 529 \&\f(CW\*(C`File::stat\*(C'\fR object representing the result.
 530 .ie n .IP "$st = $file\fR\->\fIlstat()" 4
 531 .el .IP "$st = \f(CW$file\fR\->\fIlstat()\fR" 4
 532 .IX Item "$st = $file->lstat()"
 533 Same as \f(CW\*(C`stat()\*(C'\fR, but if \f(CW$file\fR is a symbolic link, \f(CW\*(C`lstat()\*(C'\fR
 534 stats the link instead of the directory the link points to.
 535 .SH "AUTHOR"
 536 .IX Header "AUTHOR"
 537 Ken Williams, ken@mathforum.org
 538 .SH "SEE ALSO"
 539 .IX Header "SEE ALSO"
 540 Path::Class, Path::Class::File, File::Spec