Linux Certif

Toute la documentation sur la certification Linux LPI

File::Next.3pm

NAME

File::Next - File-finding iterator

VERSION

Version 1.06

SYNOPSIS

File::Next is a lightweight, taint-safe file-finding module. It's lightweight and has no non-core prerequisites.

     use File::Next;
 
     my $files = File::Next::files( '/tmp' );
 
     while ( defined ( my $file = $files->() ) ) {
         # do something...
     }
 
 

OPERATIONAL THEORY

The two major functions, files() and dirs(), return an iterator that will walk through a directory tree. The simplest use case is:

     use File::Next;
 
     my $iter = File::Next::files( '/tmp' );
 
     while ( defined ( my $file = $iter->() ) ) {
         print $file, "\n";
     }
 
     # Prints...
     /tmp/foo.txt
     /tmp/bar.pl
     /tmp/baz/1
     /tmp/baz/2.txt
     /tmp/baz/wango/tango/purple.txt
 
 

Note that only files are returned by "files()"'s iterator. Directories are ignored.

In list context, the iterator returns a list containing $dir, $file and $fullpath, where $fullpath is what would get returned in scalar context.

The first parameter to any of the iterator factory functions may be a hashref of options.

ITERATORS

For the three iterators, the \%options are optional.

files( [ \%options, ] @starting_points )

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another regular file.

dirs( [ \%options, ] @starting_points )

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another directory.

everything( [ \%options, ] @starting_points )

Returns an iterator that walks directories starting with the items in @starting_points. Each call to the iterator returns another file, whether it's a regular file, directory, symlink, socket, or whatever.

SUPPORT FUNCTIONS

sort_standard( $a, $b )

A sort function for passing as a "sort_files" option:

     my $iter = File::Next::files( {
         sort_files => \&File::Next::sort_standard,
     }, 't/swamp' );
 
 

This function is the default, so the code above is identical to:

     my $iter = File::Next::files( {
         sort_files => 1,
     }, 't/swamp' );
 
 

sort_reverse( $a, $b )

Same as "sort_standard", but in reverse.

reslash( $path )

Takes a path with all forward slashes and rebuilds it with whatever is appropriate for the platform. For example 'foo/bar/bat' will become 'foo\bar\bat' on Windows.

This is really just a convenience function. I'd make it private, but ack wants it, too.

CONSTRUCTOR PARAMETERS

file_filter -> \&file_filter

The file_filter lets you check to see if it's really a file you want to get back. If the file_filter returns a true value, the file will be returned; if false, it will be skipped.

The file_filter function takes no arguments but rather does its work through a collection of variables.

*

$_ is the current filename within that directory

*

$File::Next::dir is the current directory name

*

$File::Next::name is the complete pathname to the file

These are analogous to the same variables in File::Find.

     my $iter = File::Next::files( { file_filter => sub { /\.txt$/ } }, '/tmp' );
 
 

By default, the file_filter is "sub {1}", or ``all files''.

This filter has no effect if your iterator is only returning directories.

descend_filter => \&descend_filter

The descend_filter lets you check to see if the iterator should descend into a given directory. Maybe you want to skip CVS and .svn directories.

     my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" }
 
 

The descend_filter function takes no arguments but rather does its work through a collection of variables.

*

$_ is the current filename of the directory

*

$File::Next::dir is the complete directory name

The descend filter is NOT applied to any directory names specified in as @starting_points in the constructor. For example,

     my $iter = File::Next::files( { descend_filter => sub{0} }, '/tmp' );
 
 

always descends into /tmp, as you would expect.

By default, the descend_filter is "sub {1}", or ``always descend''.

error_handler => \&error_handler

If error_handler is set, then any errors will be sent through it. By default, this value is "CORE::die".

sort_files => [ 0 | 1 | \&sort_sub]

If you want files sorted, pass in some true value, as in "sort_files => 1".

If you want a special sort order, pass in a sort function like "sort_files => sub { $a->[1] cmp $b->[1] }". Note that the parms passed in to the sub are arrayrefs, where $a->[0] is the directory name, $a->[1] is the file name and $a->[2] is the full path. Typically you're going to be sorting on $a->[2].

follow_symlinks => [ 0 | 1 ]

If set to false, the iterator will ignore any files and directories that are actually symlinks. This has no effect on non-Unixy systems such as Windows. By default, this is true.

Note that this filter does not apply to any of the @starting_points passed in to the constructor.

You should not set "follow_symlinks => 0" unless you specifically need that behavior. Setting "follow_symlinks => 0" can be a speed hit, because File::Next must check to see if the file or directory you're about to follow is actually a symlink.

PRIVATE FUNCTIONS

_setup( $default_parms, @whatever_was_passed_to_files() )

Handles all the scut-work for setting up the parms passed in.

Returns a hashref of operational options, combined between $passed_parms and $defaults, plus the queue.

The queue prep stuff takes the strings in @starting_points and puts them in the format that queue needs.

The @queue that gets passed around is an array that has three elements for each of the entries in the queue: $dir, $file and $fullpath. Items must be pushed and popped off the queue three at a time (spliced, really).

_candidate_files( $parms, $dir )

Pulls out the files/dirs that might be worth looking into in $dir. If $dir is the empty string, then search the current directory.

$parms is the hashref of parms passed into File::Next constructor.

SPEED TWEAKS

*

Don't set "follow_symlinks => 0" unless you need it.

AUTHOR

Andy Lester, "<andy at petdance.com>"

BUGS

Please report any bugs or feature requests to http://github.com/petdance/file-next/issues <http://github.com/petdance/file-next/issues>.

Note that File::Next does NOT use <http://rt.cpan.org> for bug tracking.

SUPPORT

You can find documentation for this module with the perldoc command.

     perldoc File::Next
 
 

You can also look for information at:

*

File::Next's bug queue

http://github.com/petdance/file-next/issues <http://github.com/petdance/file-next/issues>

*

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/File-Next <http://annocpan.org/dist/File-Next>

*

CPAN Ratings

http://cpanratings.perl.org/d/File-Next <http://cpanratings.perl.org/d/File-Next>

*

Search CPAN

http://search.cpan.org/dist/File-Next <http://search.cpan.org/dist/File-Next>

*

Source code repository

http://github.com/petdance/file-next/tree/master <http://github.com/petdance/file-next/tree/master>

ACKNOWLEDGEMENTS

All file-finding in this module is adapted from Mark Jason Dominus' marvelous Higher Order Perl, page 126.

COPYRIGHT & LICENSE

Copyright 2005-2009 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of either:

*

the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

*

the Artistic License version 2.0.