.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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 .\" ======================================================================== .\" .IX Title "Next 3pm" .TH Next 3pm "2019-09-07" "perl v5.28.1" "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::Next \- File\-finding iterator .SH "VERSION" .IX Header "VERSION" Version 1.18 .SH "SYNOPSIS" .IX Header "SYNOPSIS" File::Next is a lightweight, taint-safe file-finding module. It has no non-core prerequisites. .PP .Vb 1 \& use File::Next; \& \& my $files = File::Next::files( \*(Aq/tmp\*(Aq ); \& \& while ( defined ( my $file = $files\->() ) ) { \& # do something... \& } .Ve .SH "OPERATIONAL THEORY" .IX Header "OPERATIONAL THEORY" The two major functions, \fI\f(BIfiles()\fI\fR and \fI\f(BIdirs()\fI\fR, return an iterator that will walk through a directory tree. The simplest use case is: .PP .Vb 1 \& use File::Next; \& \& my $iter = File::Next::files( \*(Aq/tmp\*(Aq ); \& \& while ( defined ( my $file = $iter\->() ) ) { \& print $file, "\en"; \& } \& \& # Prints... \& /tmp/foo.txt \& /tmp/bar.pl \& /tmp/baz/1 \& /tmp/baz/2.txt \& /tmp/baz/wango/tango/purple.txt .Ve .PP Note that only files are returned by \f(CW\*(C`files()\*(C'\fR's iterator. Directories are ignored. .PP In list context, the iterator returns a list containing \fI\f(CI$dir\fI\fR, \&\fI\f(CI$file\fI\fR and \fI\f(CI$fullpath\fI\fR, where \fI\f(CI$fullpath\fI\fR is what would get returned in scalar context. .PP The first parameter to any of the iterator factory functions may be a hashref of options. .SH "ITERATORS" .IX Header "ITERATORS" For the three iterators, the \e%options are optional. .ie n .SS "files( [ \e%options, ] @starting_points )" .el .SS "files( [ \e%options, ] \f(CW@starting_points\fP )" .IX Subsection "files( [ %options, ] @starting_points )" Returns an iterator that walks directories starting with the items in \fI\f(CI@starting_points\fI\fR. Each call to the iterator returns another regular file. .ie n .SS "dirs( [ \e%options, ] @starting_points )" .el .SS "dirs( [ \e%options, ] \f(CW@starting_points\fP )" .IX Subsection "dirs( [ %options, ] @starting_points )" Returns an iterator that walks directories starting with the items in \fI\f(CI@starting_points\fI\fR. Each call to the iterator returns another directory. .ie n .SS "everything( [ \e%options, ] @starting_points )" .el .SS "everything( [ \e%options, ] \f(CW@starting_points\fP )" .IX Subsection "everything( [ %options, ] @starting_points )" Returns an iterator that walks directories starting with the items in \fI\f(CI@starting_points\fI\fR. Each call to the iterator returns another file, whether it's a regular file, directory, symlink, socket, or whatever. .ie n .SS "from_file( [ \e%options, ] $filename )" .el .SS "from_file( [ \e%options, ] \f(CW$filename\fP )" .IX Subsection "from_file( [ %options, ] $filename )" Returns an iterator that iterates over each of the files specified in \fI\f(CI$filename\fI\fR. If \fI\f(CI$filename\fI\fR is \f(CW\*(C`\-\*(C'\fR, then the files are read from \s-1STDIN.\s0 .PP The files are assumed to be in the file one filename per line. If \&\fI\f(CI$nul_separated\fI\fR is passed, then the files are assumed to be NUL-separated, as by \f(CW\*(C`find \-print0\*(C'\fR. .PP If there are blank lines or empty filenames in the input stream, they are ignored. .PP 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 \fIwarning_handler\fR, and the file is skipped. .PP The following options have no effect in \f(CW\*(C`from_files\*(C'\fR: \fIdescend_filter\fR, \&\fIsort_files\fR, \fIfollow_symlinks\fR. .SH "SUPPORT FUNCTIONS" .IX Header "SUPPORT FUNCTIONS" .ie n .SS "sort_standard( $a, $b )" .el .SS "sort_standard( \f(CW$a\fP, \f(CW$b\fP )" .IX Subsection "sort_standard( $a, $b )" A sort function for passing as a \f(CW\*(C`sort_files\*(C'\fR option: .PP .Vb 3 \& my $iter = File::Next::files( { \& sort_files => \e&File::Next::sort_standard, \& }, \*(Aqt/swamp\*(Aq ); .Ve .PP This function is the default, so the code above is identical to: .PP .Vb 3 \& my $iter = File::Next::files( { \& sort_files => 1, \& }, \*(Aqt/swamp\*(Aq ); .Ve .ie n .SS "sort_reverse( $a, $b )" .el .SS "sort_reverse( \f(CW$a\fP, \f(CW$b\fP )" .IX Subsection "sort_reverse( $a, $b )" Same as \f(CW\*(C`sort_standard\*(C'\fR, but in reverse. .ie n .SS "reslash( $path )" .el .SS "reslash( \f(CW$path\fP )" .IX Subsection "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\ebar\ebat' on Windows. .PP This is really just a convenience function. I'd make it private, but \fIack\fR wants it, too. .SH "CONSTRUCTOR PARAMETERS" .IX Header "CONSTRUCTOR PARAMETERS" .SS "file_filter \-> \e&file_filter" .IX Subsection "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. .PP The file_filter function takes no arguments but rather does its work through a collection of variables. .IP "\(bu" 4 \&\f(CW$_\fR is the current filename within that directory .IP "\(bu" 4 \&\f(CW$File::Next::dir\fR is the current directory name .IP "\(bu" 4 \&\f(CW$File::Next::name\fR is the complete pathname to the file .PP These are analogous to the same variables in File::Find. .PP .Vb 1 \& my $iter = File::Next::files( { file_filter => sub { /\e.txt$/ } }, \*(Aq/tmp\*(Aq ); .Ve .PP By default, the \fIfile_filter\fR is \f(CW\*(C`sub {1}\*(C'\fR, or \*(L"all files\*(R". .PP This filter has no effect if your iterator is only returning directories. .SS "descend_filter => \e&descend_filter" .IX Subsection "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 \fI\s-1CVS\s0\fR and \&\fI.svn\fR directories. .PP .Vb 1 \& my $descend_filter = sub { $_ ne "CVS" && $_ ne ".svn" } .Ve .PP The descend_filter function takes no arguments but rather does its work through a collection of variables. .IP "\(bu" 4 \&\f(CW$_\fR is the current filename of the directory .IP "\(bu" 4 \&\f(CW$File::Next::dir\fR is the complete directory name .PP The descend filter is \s-1NOT\s0 applied to any directory names specified as \fI\f(CI@starting_points\fI\fR in the constructor. For example, .PP .Vb 1 \& my $iter = File::Next::files( { descend_filter => sub{0} }, \*(Aq/tmp\*(Aq ); .Ve .PP always descends into \fI/tmp\fR, as you would expect. .PP By default, the \fIdescend_filter\fR is \f(CW\*(C`sub {1}\*(C'\fR, or \*(L"always descend\*(R". .SS "error_handler => \e&error_handler" .IX Subsection "error_handler => &error_handler" If \fIerror_handler\fR 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 \&\f(CW\*(C`CORE::die\*(C'\fR. This function must \s-1NOT\s0 return. .SS "warning_handler => \e&warning_handler" .IX Subsection "warning_handler => &warning_handler" If \fIwarning_handler\fR is set, then any errors will be sent through it. By default, this value is \f(CW\*(C`CORE::warn\*(C'\fR. Unlike the \&\fIerror_handler\fR, this function must return. .SS "sort_files => [ 0 | 1 | \e&sort_sub]" .IX Subsection "sort_files => [ 0 | 1 | &sort_sub]" If you want files sorted, pass in some true value, as in \&\f(CW\*(C`sort_files => 1\*(C'\fR. .PP If you want a special sort order, pass in a sort function like \&\f(CW\*(C`sort_files => sub { $a\->[1] cmp $b\->[1] }\*(C'\fR. Note that the parms passed in to the sub are arrayrefs, where \f(CW$a\fR\->[0] is the directory name, \f(CW$a\fR\->[1] is the file name and \f(CW$a\fR\->[2] is the full path. Typically you're going to be sorting on \f(CW$a\fR\->[2]. .SS "follow_symlinks => [ 0 | 1 ]" .IX Subsection "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. .PP Note that this filter does not apply to any of the \fI\f(CI@starting_points\fI\fR passed in to the constructor. .PP You should not set \f(CW\*(C`follow_symlinks => 0\*(C'\fR unless you specifically need that behavior. Setting \f(CW\*(C`follow_symlinks => 0\*(C'\fR 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. .SS "nul_separated => [ 0 | 1 ]" .IX Subsection "nul_separated => [ 0 | 1 ]" Used by the \f(CW\*(C`from_file\*(C'\fR iterator. Specifies that the files listed in the input file are separated by \s-1NUL\s0 characters, as from the \f(CW\*(C`find\*(C'\fR command with the \f(CW\*(C`\-print0\*(C'\fR argument. .SH "PRIVATE FUNCTIONS" .IX Header "PRIVATE FUNCTIONS" .ie n .SS "_setup( $default_parms, @\fBwhatever_was_passed_to_files()\fP )" .el .SS "_setup( \f(CW$default_parms\fP, @\fBwhatever_was_passed_to_files()\fP )" .IX Subsection "_setup( $default_parms, @whatever_was_passed_to_files() )" Handles all the scut-work for setting up the parms passed in. .PP Returns a hashref of operational options, combined between \&\fI\f(CI$passed_parms\fI\fR and \fI\f(CI$defaults\fI\fR, plus the queue. .PP The queue prep stuff takes the strings in \fI\f(CI@starting_points\fI\fR and puts them in the format that queue needs. .PP The \f(CW@queue\fR that gets passed around is an array, with each entry an arrayref of \f(CW$dir\fR, \f(CW$file\fR and \f(CW$fullpath\fR. .ie n .SS "_candidate_files( $parms, $dir )" .el .SS "_candidate_files( \f(CW$parms\fP, \f(CW$dir\fP )" .IX Subsection "_candidate_files( $parms, $dir )" Pulls out the files/dirs that might be worth looking into in \fI\f(CI$dir\fI\fR. If \fI\f(CI$dir\fI\fR is the empty string, then search the current directory. .PP \&\fI\f(CI$parms\fI\fR is the hashref of parms passed into File::Next constructor. .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .ie n .IP """File::Next::files must not be invoked as File::Next\->files""" 4 .el .IP "\f(CWFile::Next::files must not be invoked as File::Next\->files\fR" 4 .IX Item "File::Next::files must not be invoked as File::Next->files" .PD 0 .ie n .IP """File::Next::dirs must not be invoked as File::Next\->dirs""" 4 .el .IP "\f(CWFile::Next::dirs must not be invoked as File::Next\->dirs\fR" 4 .IX Item "File::Next::dirs must not be invoked as File::Next->dirs" .ie n .IP """File::Next::everything must not be invoked as File::Next\->everything""" 4 .el .IP "\f(CWFile::Next::everything must not be invoked as File::Next\->everything\fR" 4 .IX Item "File::Next::everything must not be invoked as File::Next->everything" .PD .PP 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 \*(L"can\*(R" in \s-1UNIVERSAL\s0. .PP .Vb 6 \& for my $file_system_feature (qw(dirs files)) { \& my $iterator = File::Next\->can($file_system_feature)\->($options, $target_directory); \& while (defined(my $name = $iterator\->())) { \& # ... \& } \& } .Ve .SH "SPEED TWEAKS" .IX Header "SPEED TWEAKS" .IP "\(bu" 4 Don't set \f(CW\*(C`follow_symlinks => 0\*(C'\fR unless you need it. .SH "AUTHOR" .IX Header "AUTHOR" Andy Lester, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to . .PP Note that File::Next does \s-1NOT\s0 use for bug tracking. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc File::Next .Ve .PP You can also look for information at: .IP "\(bu" 4 File::Next's bug queue .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .IP "\(bu" 4 Source code repository .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" All file-finding in this module is adapted from Mark Jason Dominus' marvelous \fIHigher Order Perl\fR, page 126. .PP Thanks to these fine contributors: Varadinsky, Paulo Custodio, Gerhard Poul, Brian Fraser, Todd Rinaldo, Bruce Woodward, Christopher J. Madsen, Bernhard Fisseni and Rob Hoelz. .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2005\-2017 Andy Lester. .PP This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.