File::Next - phpMan

Che Dong
NAME
    File::Next - File-finding iterator

VERSION
    Version 1.18

SYNOPSIS
    File::Next is a lightweight, taint-safe file-finding module. It 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.

  from_file( [ \%options, ] $filename )
    Returns an iterator that iterates over each of the files specified in
    *$filename*. If *$filename* is "-", then the files are read from STDIN.

    The files are assumed to be in the file one filename per line. If
    *$nul_separated* is passed, then the files are assumed to be
    NUL-separated, as by "find -print0".

    If there are blank lines or empty filenames in the input stream, they
    are ignored.

    Each filename is checked to see that it is a regular file or a named
    pipe. If the file does not exists or is a directory, then a warning is
    thrown to *warning_handler*, and the file is skipped.

    The following options have no effect in "from_files": *descend_filter*,
    *sort_files*, *follow_symlinks*.

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 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. If
    the error is OS-related (ex. file not found, not permissions), the
    native error code is passed as a second argument. By default, this value
    is "CORE::die". This function must NOT return.

  warning_handler => \&warning_handler
    If *warning_handler* is set, then any errors will be sent through it. By
    default, this value is "CORE::warn". Unlike the *error_handler*, this
    function must return.

  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.

  nul_separated => [ 0 | 1 ]
    Used by the "from_file" iterator. Specifies that the files listed in the
    input file are separated by NUL characters, as from the "find" command
    with the "-print0" argument.

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, with each entry an
    arrayref of $dir, $file and $fullpath.

  _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.

DIAGNOSTICS
    "File::Next::files must not be invoked as File::Next->files"
    "File::Next::dirs must not be invoked as File::Next->dirs"
    "File::Next::everything must not be invoked as File::Next->everything"

    The interface functions do not allow for the method invocation syntax
    and throw errors with the messages above. You can work around this
    limitation with "can" in UNIVERSAL.

        for my $file_system_feature (qw(dirs files)) {
            my $iterator = File::Next->can($file_system_feature)->($options, $target_directory);
            while (defined(my $name = $iterator->())) {
                # ...
            }
        }

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>.

    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>

    *   CPAN Ratings

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

    *   Search CPAN

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

    *   Source code repository

        <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.

    Thanks to these fine contributors: Varadinsky, Paulo Custodio, Gerhard
    Poul, Brian Fraser, Todd Rinaldo, Bruce Woodward, Christopher J. Madsen,
    Bernhard Fisseni and Rob Hoelz.

COPYRIGHT & LICENSE
    Copyright 2005-2017 Andy Lester.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the Artistic License version 2.0.