view release on metacpan or  search on metacpan

lib/File/Util/Manual.pod  view on Meta::CPAN

                                           'f.conf' => '/tmp/hJMOsoGuEb/f.conf',
                                           'g.bin' => '/tmp/hJMOsoGuEb/g.bin',
                                           'h.rc' => '/tmp/hJMOsoGuEb/h.rc',
                                         }
                       }
            }
   }


When using this option, the hashref you get back will have certain metadata
entries at each level of the hierarchy, namely there will be two special
keys: "_DIR_SELF", and "_DIR_PARENT_".  Their values will be the name of
the directory itself, and the name of its parent, respectively.

That metadata can be extremely helpful when iterating over and parsing the
hashref later on, but if you don't want the metadata, include the
C<dirmeta> option and set it to a zero (false) value as shown below:

   my $tree = $ftl->list_dir(
      '/some/dir' => {
         as_tree  => 1,
         recurse  => 1,
         dirmeta  => 0,
      }
   );

**Remember: the C<as_tree> doesn't recurse into subdirectories unless you tell
it to with C<< recurse => 1 >>

=back

=item B<Filtering and Matching with C<list_dir()>>

C<list_dir()> can use Perl L<Regular Expressions|perlre> to match against
and thereby filter the results it returns.  It can match based on file name,
directory name, the path preceding results, and the parent directory of
results.  The matching arguments you use must be real regular expression
references as shown (i.e.- NOT strings).

Regular expressions can be provided as a single argument value, or a
specifically crafted hashref designating a list of patterns to match against
in either an "or" manner, or an "and"ed cumulative manner.

Some short examples of proper syntax will be provided after the list of
matching options below.

I<**If you experience a big slowdown in directory listings while>
I<using regular expressions, check to make sure your regular expressions are>
I<properly written and optimized.  In general, directory listings should>
I<not be slow or resource-intensive.  Badly-written regular expressions will>
I<result in considerable slowdowns and bottlenecks in any application.>

=over

=item C<< files_match => qr/regexp/ >>

=item I<OR:> C<< files_match => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only file names matching the regex(es).  Preceding directories are
included in the results; for technical reasons they are not excluded (if they
were excluded, C<list_dir()> would not be able to "cascade" or recurse into
subdirectories in search of matching files.

Use the C<files_only> option in combination with this matching parameter to
exclude the preceding directory names.

=item C<< dirs_match => qr/regexp/ >>

=item I<OR:> C<< dirs_match => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names in directories that match the
regex(es) you specify.  B<BE CAREFUL> with this one!!  It doesn't "cascade"
the way you might expect; for technical reasons, it won't descend into
directories that don't match the regex(es) you provide.  For example, if you
want to match a directory name that is three levels deep against a given
pattern, but don't know (or don't care about) the names of the intermediate
directories-- THIS IS NOT THE OPTION YOU ARE LOOKING FOR.  Use the
C<path_matches> option instead.

B<*NOTE:> Bear in mind that just because you tell C<list_dir()> to match each
directory against the regex(es) you specify here, that doesn't mean you are
telling it to only show directories in its results.  You will get file names
in matching directories included in the results as well, unless you combine
this with the C<dirs_only> option.

=item C<< path_matches => qr/regexp/ >>

=item I<OR:> C<< path_matches => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names with preceding paths that match the
regex(es) you specify.

=item C<< parent_matches => qr/regexp reference/ >>

=item I<OR:> C<< parent_matches => { and/or => [ qr/listref of/, qr/regexps/ ] } >>

Return only files and subdirectory names whose parent directory matches the
regex(es) you specify.

=back

=item Examples of matching and filtering results in C<listdir()>

Single-argument matching examples

   my @files = $f->list_dir(
      '../notes' => { files_match => qr/\.txt$/i, files_only => 1 }
   );

   my @dirs = $f->list_dir(
      '/var' => {
         dirs_match => qr/log|spool/i,
         recurse => 1,
         dirs_only => 1,
      }
   );

   my @dirs = $f->list_dir(
      '/home' => {
         path_matches => qr/Desktop/,
         recurse => 1,
         dirs_only => 1,
      }
   );

   my @files = $f->list_dir(
      '/home/tommy/projects' => {
         parent_matches => qr/^\.git$/,
         recurse => 1,
      }
   );