.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::Fu::Dir 3pm"
.TH File::Fu::Dir 3pm "2022-12-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::Fu::Dir \- a directoryname object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use File::Fu;
\&
\&  my $dir = File::Fu\->dir("path/to/dir");
\&  $dir\->e and warn "$dir exists";
\&
\&  $dir\->l and warn "$dir is a link to ", $dir\->readlink;
\&
\&  foreach my $entry ($dir\->list) {
\&    warn $entry . \*(Aq: \*(Aq . $entry\->stat\->size, "\en"
\&      if($entry\->f);
\&  }
.Ve
.SH "Constructor"
.IX Header "Constructor"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $dir = File::Fu::Dir\->new($path);
\&
\&  my $dir = File::Fu::Dir\->new(@path);
.Ve
.SH "Class Constants/Methods"
.IX Header "Class Constants/Methods"
.SS "file_class"
.IX Subsection "file_class"
Return the corresponding file class for this dir object.  Default:
File::Fu::File.
.PP
.Vb 1
\&  my $fc = $class\->file_class;
.Ve
.SS "is_dir"
.IX Subsection "is_dir"
Always true for a directory.
.SS "is_file"
.IX Subsection "is_file"
Always false for a directory.
.SS "temp_dir_class"
.IX Subsection "temp_dir_class"
Class for \*(L"temp_dir\*(R" objects.  Default: File::Fu::Dir::Temp.
.PP
.Vb 1
\&  my $class = File::Fu::Dir\->temp_dir_class;
.Ve
.SS "temp_file_class"
.IX Subsection "temp_file_class"
.Vb 1
\&  my $class = File::Fu::Dir\->temp_file_class;
.Ve
.SH "Methods"
.IX Header "Methods"
.SS "stringify"
.IX Subsection "stringify"
.Vb 1
\&  my $string = $dir\->stringify;
.Ve
.SS "bare"
.IX Subsection "bare"
Stringify without the trailing slash/assertion.
.PP
.Vb 1
\&  my $str = $self\->bare;
.Ve
.PP
The trailing slash causes trouble when trying to address a symlink to a
directory via a dir object.  Thus, \f(CW\*(C`\-l $dir\*(C'\fR doesn't work, but
\&\f(CW\*(C`$dir\->l\*(C'\fR does the same thing as \f(CW\*(C`\-l $dir\->bare\*(C'\fR.
.SS "file"
.IX Subsection "file"
Create a filename object with \f(CW$dir\fR as its parent.
.PP
.Vb 1
\&  my $file = $dir\->file($filename);
\&
\&  my $file = $dir + $filename;
.Ve
.SS "append"
.IX Subsection "append"
Append a string only to the last directory part.
.PP
.Vb 1
\&  $dir\->append(\*(Aq.tmp\*(Aq);
\&
\&  $dir %= "something";
.Ve
.SS "subdir"
.IX Subsection "subdir"
.Vb 1
\&  $newdir = $dir\->subdir(\*(Aqfoo\*(Aq);
\&
\&  $newdir = $dir / \*(Aqfoo\*(Aq;
.Ve
.SS "part"
.IX Subsection "part"
Returns the \f(CW$i\fR'th part of the directory list.
.PP
.Vb 1
\&  my $part = $dir\->part($i);
.Ve
.PP
\&\f(CW$dir\fR\->part(\-1) is like \f(CW$dir\fR\->basename, but not an object and not quite
like \fBFile::Basename::basename()\fR when it comes to the / directory.
.SS "end"
.IX Subsection "end"
Shorthand for part(\-1);
.SS "parts"
.IX Subsection "parts"
Retrieve the inner list of the directory's parts.
.PP
.Vb 1
\&  my @parts = $dir\->parts;
\&
\&  my @parts = $dir\->parts(0..2);
.Ve
.PP
The returned parts will be contiguous, but the request can be a
two-element list (and can also start or end at negative indices.)
.PP
.Vb 1
\&  my @parts = $dir\->parts(3, 7);
\&
\&  my @parts = $dir\->parts(3, \-1);
\&
\&  my @parts = $dir\->parts(\-5, \-1);
.Ve
.SS "slice"
.IX Subsection "slice"
Returns a new dir object as the return of \fBparts()\fR.
.PP
.Vb 1
\&  my $slice = $dir\->slice(0);
\&
\&  my $slice = $dir\->slice(0,3);
.Ve
.SS "map"
.IX Subsection "map"
Execute a callback on each part of \f(CW$dir\fR.  The sub should modify \f(CW$_\fR (yes,
this is slightly unlike the \fBmap()\fR builtin.)
.PP
If \f(CW$parts\fR is defined as an integer or array reference of integers, it
will be treated as a slice on the directory parts to which the map
should be applied.
.PP
.Vb 1
\&  $dir\->map(sub {...}, [@parts]);
\&
\&  $dir &= sub {s/foo$/bar/};
.Ve
.PP
So, to modify only the first directory part:
.PP
.Vb 1
\&  $dir\->map(sub {s/foo$/bar/}, 0);
.Ve
.SH "Properties"
.IX Header "Properties"
.SS "is_cwd"
.IX Subsection "is_cwd"
True if the \f(CW$dir\fR represents a relative (e.g. '.') directory.
.PP
.Vb 1
\&  my $bool = $dir\->is_cwd;
.Ve
.SS "basename"
.IX Subsection "basename"
Returns the last part of the path as a Dir object.
.PP
.Vb 1
\&  my $bit = $dir\->basename;
.Ve
.SS "dirname"
.IX Subsection "dirname"
Returns the parent parts of the path as a Dir object.
.PP
.Vb 1
\&  my $parent = $dir\->dirname;
.Ve
.SS "absolute"
.IX Subsection "absolute"
Get an absolute name (without checking the filesystem.)
.PP
.Vb 1
\&  my $abs = $dir\->absolute;
.Ve
.SS "absolutely"
.IX Subsection "absolutely"
Get an absolute path (resolved on filesystem, so it must exist.)
.PP
.Vb 1
\&  my $abs = $dir\->absolutely;
.Ve
.SH "Doing stuff"
.IX Header "Doing stuff"
.SS "open"
.IX Subsection "open"
Calls \fBopendir()\fR, but throws an error if it fails.
.PP
.Vb 1
\&  my $dh = $dir\->open;
.Ve
.PP
Returns a directory handle, for e.g. \fBreaddir()\fR.
.PP
.Vb 1
\&  my @files = map({$dir + $_} grep({$_ !~ m/^\e./} readdir($dh)));
.Ve
.SS "touch"
.IX Subsection "touch"
Update the timestamp of a directory (croak if it doesn't exist.)
.PP
.Vb 1
\&  $dir\->touch;
.Ve
.SS "list"
.IX Subsection "list"
.Vb 1
\&  my @paths = $dir\->list(all => 1);
.Ve
.SS "lister"
.IX Subsection "lister"
.Vb 1
\&  my $subref = $dir\->lister(all => 1);
.Ve
.SS "contents"
.IX Subsection "contents"
Equivalent to readdir.  With the 'all' option true, returns hidden names
too (but not the '.' and '..' entries.)
.PP
The return values are strings, not File::Fu objects.
.PP
.Vb 1
\&  my @names = $dir\->contents(all => 1);
.Ve
.SS "iterate_contents"
.IX Subsection "iterate_contents"
Returns a subref which will iterate over the directory's contents.
.PP
.Vb 1
\&  my $subref = $dir\->iterate_contents(all => 1);
.Ve
.SS "find"
.IX Subsection "find"
Recursively search a directory's contents for items where the supplied
coderef (matcher) returns true.  The matcher will be invoked with the
topic (\f(CW$_\fR) set to the current path (which is either a Dir or File
object.) The return values will be File::Fu::File or File::Fu::Dir
objects.
.PP
If your matcher returns true, the topic will be added to the return
values.
.PP
.Vb 1
\&  my @paths = $dir\->find(sub {m/foo/});
.Ve
.PP
There is a knob for controlling recursion, which is the first argument
to your matcher.
.PP
.Vb 5
\&  my @pm_files = $dir\->find(sub {
\&    return shift\->prune
\&      if($_\->is_dir and $_\->part(\-1) =~ m/^\e.svn$/);
\&    $_\->is_file and m/\e.pm$/;
\&  });
.Ve
.IP "Differences from \fBFile::Find::find()\fR" 4
.IX Item "Differences from File::Find::find()"
The invocant (\f(CW$dir\fR aka '.') is not examined (because this is an
object method, there is always only one starting path.)
.Sp
The topic is always absolute in the same sense as the invocant.  That
is, if \f(CW$dir\fR is relative to your current directory, then so are the
topics and return values.  If \f(CW$dir\fR is absolute, so are the topics and
return values.
.SS "finder"
.IX Subsection "finder"
Returns an iterator for finding files.  This iterator does everything
that \fBfind()\fR does, but returns one path at a time.  Returns undef when
exhausted and zero when it is just taking a break.
.PP
.Vb 1
\&  my $subref = $dir\->finder(sub {$_\->is_file and $_\->file =~ m/foo/});
.Ve
.PP
This allows a non-blocking find.
.PP
.Vb 4
\&  while(defined(my $path = $subref\->())) {
\&    $path or next; # 0 means \*(Aqnot done yet\*(Aq
\&    # do something with $path (a file or dir object)
\&  }
.Ve
.PP
The \fBfind()\fR method is implemented in terms of \fBfinder()\fR by simply using a
\&\fBwhile()\fR loop and accumulating the return values.
.SS "The FindKnob object"
.IX Subsection "The FindKnob object"
The FindKnob object allows you to control the next steps of \fBfind()\fR.
Methods called on it will typically return a value which also makes
sense as a return value of your matcher sub.  Thus the idiom:
.PP
.Vb 1
\&  $dir\->find(sub {return shift\->prune if(condition); ...})
.Ve
.IP "prune" 4
.IX Item "prune"
Do not recurse into the topic directory.  Returns false.
.SS "mkdir"
.IX Subsection "mkdir"
Create the directory or croak with an error.
.PP
.Vb 1
\&  $dir\->mkdir;
\&
\&  $dir\->mkdir(0700);
.Ve
.SS "create"
.IX Subsection "create"
Create the directory, with parents if needed.
.PP
.Vb 1
\&  $dir\->create;
.Ve
.SS "rmdir"
.IX Subsection "rmdir"
Remove the directory or croak with an error.
.PP
.Vb 1
\&  $dir\->rmdir;
.Ve
.SS "remove"
.IX Subsection "remove"
Remove the directory and all of its children.
.PP
.Vb 1
\&  $dir\->remove;
.Ve
.SS "unlink"
.IX Subsection "unlink"
.Vb 1
\&  $link\->unlink;
.Ve
.SS "symlink"
.IX Subsection "symlink"
Create a symlink which points to \f(CW$dir\fR.
.PP
.Vb 1
\&  my $link = $dir\->symlink($linkname);
.Ve
.PP
Note that symlinks are relative to where they live, so if \f(CW$dir\fR is a
relative path, it must be relative to \f(CW$linkname\fR.
.SS "readlink"
.IX Subsection "readlink"
.Vb 1
\&  my $to = $file\->readlink;
.Ve
.SH "Changing Directories"
.IX Header "Changing Directories"
.SS "chdir"
.IX Subsection "chdir"
Change to the directory in self, returning a new '.' directory object.
.PP
.Vb 1
\&  $dir = $dir\->chdir;
.Ve
.SS "chdir_for"
.IX Subsection "chdir_for"
Change to \f(CW$dir\fR and run the given subroutine.  The sub will be passed a
\&'./' directory object.
.PP
.Vb 1
\&  $dir\->chdir_for(sub {...});
.Ve
.SS "chdir_local"
.IX Subsection "chdir_local"
Change to \f(CW$dir\fR, but return to the current cwd when \f(CW$token\fR goes out of
scope.
.PP
.Vb 1
\&  my $token = $self\->chdir_local;
.Ve
.SH "Temporary Directories and Files"
.IX Header "Temporary Directories and Files"
These methods use the \f(CW$dir\fR object as a parent location for the temp
path.  To use your system's global temp space (e.g. '/tmp/'), just
replace \f(CW$dir\fR with 'File::Fu'.
.PP
.Vb 3
\&  File::Fu\->temp_dir;              # \*(Aq/tmp/\*(Aq
\&  File::Fu\->dir\->temp_dir;         # \*(Aq./\*(Aq
\&  File::Fu\->dir("foo")\->temp_dir;  # \*(Aqfoo/\*(Aq
\&
\&  File::Fu\->temp_file;             # \*(Aq/tmp/\*(Aq
\&  File::Fu\->dir\->temp_file;        # \*(Aq./\*(Aq
\&  File::Fu\->dir("foo")\->temp_file; # \*(Aqfoo/\*(Aq
.Ve
.SS "temp_dir"
.IX Subsection "temp_dir"
Return a temporary directory in \f(CW$dir\fR.
.PP
.Vb 1
\&  my $dir = $dir\->temp_dir;
.Ve
.SS "temp_file"
.IX Subsection "temp_file"
Return a filehandle to a temporary file in \f(CW$dir\fR.
.PP
.Vb 1
\&  my $handle = $dir\->temp_file;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Eric Wilhelm @ <ewilhelm at cpan dot org>
.PP
http://scratchcomputing.com/
.SH "BUGS"
.IX Header "BUGS"
If you found this module on \s-1CPAN,\s0 please report any bugs or feature
requests through the web interface at <http://rt.cpan.org>.  I will be
notified, and then you'll automatically be notified of progress on your
bug as I make changes.
.PP
If you pulled this development version from my /svn/, please contact me
directly.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2008 Eric L. Wilhelm, All Rights Reserved.
.SH "NO WARRANTY"
.IX Header "NO WARRANTY"
Absolutely, positively \s-1NO WARRANTY,\s0 neither express or implied, is
offered with this software.  You use this software at your own risk.  In
case of loss, no person or entity owes you anything whatsoever.  You
have been warned.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.