{ "mode": "perldoc", "parameter": "File::Next", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/File%3A%3ANext/json", "generated": "2026-06-14T00:47:51Z", "synopsis": "File::Next is a lightweight, taint-safe file-finding module. It has no non-core prerequisites.\nuse File::Next;\nmy $files = File::Next::files( '/tmp' );\nwhile ( defined ( my $file = $files->() ) ) {\n# do something...\n}", "sections": { "NAME": { "content": "File::Next - File-finding iterator\n", "subsections": [] }, "VERSION": { "content": "Version 1.18\n", "subsections": [] }, "SYNOPSIS": { "content": "File::Next is a lightweight, taint-safe file-finding module. It has no non-core prerequisites.\n\nuse File::Next;\n\nmy $files = File::Next::files( '/tmp' );\n\nwhile ( defined ( my $file = $files->() ) ) {\n# do something...\n}\n", "subsections": [] }, "OPERATIONAL THEORY": { "content": "The two major functions, *files()* and *dirs()*, return an iterator that will walk through a\ndirectory tree. The simplest use case is:\n\nuse File::Next;\n\nmy $iter = File::Next::files( '/tmp' );\n\nwhile ( defined ( my $file = $iter->() ) ) {\nprint $file, \"\\n\";\n}\n\n# Prints...\n/tmp/foo.txt\n/tmp/bar.pl\n/tmp/baz/1\n/tmp/baz/2.txt\n/tmp/baz/wango/tango/purple.txt\n\nNote that only files are returned by \"files()\"'s iterator. Directories are ignored.\n\nIn list context, the iterator returns a list containing *$dir*, *$file* and *$fullpath*, where\n*$fullpath* is what would get returned in scalar context.\n\nThe first parameter to any of the iterator factory functions may be a hashref of options.\n", "subsections": [] }, "ITERATORS": { "content": "For the three iterators, the \\%options are optional.\n\nfiles( [ \\%options, ] @startingpoints )\nReturns an iterator that walks directories starting with the items in *@startingpoints*. Each\ncall to the iterator returns another regular file.\n\ndirs( [ \\%options, ] @startingpoints )\nReturns an iterator that walks directories starting with the items in *@startingpoints*. Each\ncall to the iterator returns another directory.\n\neverything( [ \\%options, ] @startingpoints )\nReturns an iterator that walks directories starting with the items in *@startingpoints*. Each\ncall to the iterator returns another file, whether it's a regular file, directory, symlink,\nsocket, or whatever.\n\nfromfile( [ \\%options, ] $filename )\nReturns an iterator that iterates over each of the files specified in *$filename*. If\n*$filename* is \"-\", then the files are read from STDIN.\n\nThe files are assumed to be in the file one filename per line. If *$nulseparated* is passed,\nthen the files are assumed to be NUL-separated, as by \"find -print0\".\n\nIf there are blank lines or empty filenames in the input stream, they are ignored.\n\nEach filename is checked to see that it is a regular file or a named pipe. If the file does not\nexists or is a directory, then a warning is thrown to *warninghandler*, and the file is\nskipped.\n\nThe following options have no effect in \"fromfiles\": *descendfilter*, *sortfiles*,\n*followsymlinks*.\n", "subsections": [] }, "SUPPORT FUNCTIONS": { "content": "sortstandard( $a, $b )\nA sort function for passing as a \"sortfiles\" option:\n\nmy $iter = File::Next::files( {\nsortfiles => \\&File::Next::sortstandard,\n}, 't/swamp' );\n\nThis function is the default, so the code above is identical to:\n\nmy $iter = File::Next::files( {\nsortfiles => 1,\n}, 't/swamp' );\n\nsortreverse( $a, $b )\nSame as \"sortstandard\", but in reverse.\n\nreslash( $path )\nTakes a path with all forward slashes and rebuilds it with whatever is appropriate for the\nplatform. For example 'foo/bar/bat' will become 'foo\\bar\\bat' on Windows.\n\nThis is really just a convenience function. I'd make it private, but ack wants it, too.\n", "subsections": [] }, "CONSTRUCTOR PARAMETERS": { "content": "filefilter -> \\&filefilter\nThe filefilter lets you check to see if it's really a file you want to get back. If the\nfilefilter returns a true value, the file will be returned; if false, it will be skipped.\n\nThe filefilter function takes no arguments but rather does its work through a collection of\nvariables.\n\n* $ is the current filename within that directory\n\n* $File::Next::dir is the current directory name\n\n* $File::Next::name is the complete pathname to the file\n\nThese are analogous to the same variables in File::Find.\n\nmy $iter = File::Next::files( { filefilter => sub { /\\.txt$/ } }, '/tmp' );\n\nBy default, the *filefilter* is \"sub {1}\", or \"all files\".\n\nThis filter has no effect if your iterator is only returning directories.\n\ndescendfilter => \\&descendfilter\nThe descendfilter lets you check to see if the iterator should descend into a given directory.\nMaybe you want to skip CVS and .svn directories.\n\nmy $descendfilter = sub { $ ne \"CVS\" && $ ne \".svn\" }\n\nThe descendfilter function takes no arguments but rather does its work through a collection of\nvariables.\n\n* $ is the current filename of the directory\n\n* $File::Next::dir is the complete directory name\n\nThe descend filter is NOT applied to any directory names specified as *@startingpoints* in the\nconstructor. For example,\n\nmy $iter = File::Next::files( { descendfilter => sub{0} }, '/tmp' );\n\nalways descends into */tmp*, as you would expect.\n\nBy default, the *descendfilter* is \"sub {1}\", or \"always descend\".\n\nerrorhandler => \\&errorhandler\nIf *errorhandler* is set, then any errors will be sent through it. If the error is OS-related\n(ex. file not found, not permissions), the native error code is passed as a second argument. By\ndefault, this value is \"CORE::die\". This function must NOT return.\n\nwarninghandler => \\&warninghandler\nIf *warninghandler* is set, then any errors will be sent through it. By default, this value is\n\"CORE::warn\". Unlike the *errorhandler*, this function must return.\n\nsortfiles => [ 0 | 1 | \\&sortsub]\nIf you want files sorted, pass in some true value, as in \"sortfiles => 1\".\n\nIf you want a special sort order, pass in a sort function like \"sortfiles => sub { $a->[1] cmp\n$b->[1] }\". Note that the parms passed in to the sub are arrayrefs, where $a->[0] is the\ndirectory name, $a->[1] is the file name and $a->[2] is the full path. Typically you're going to\nbe sorting on $a->[2].\n\nfollowsymlinks => [ 0 | 1 ]\nIf set to false, the iterator will ignore any files and directories that are actually symlinks.\nThis has no effect on non-Unixy systems such as Windows. By default, this is true.\n\nNote that this filter does not apply to any of the *@startingpoints* passed in to the\nconstructor.\n\nYou should not set \"followsymlinks => 0\" unless you specifically need that behavior. Setting\n\"followsymlinks => 0\" can be a speed hit, because File::Next must check to see if the file or\ndirectory you're about to follow is actually a symlink.\n\nnulseparated => [ 0 | 1 ]\nUsed by the \"fromfile\" iterator. Specifies that the files listed in the input file are\nseparated by NUL characters, as from the \"find\" command with the \"-print0\" argument.\n", "subsections": [] }, "PRIVATE FUNCTIONS": { "content": "setup( $defaultparms, @whateverwaspassedtofiles() )\nHandles all the scut-work for setting up the parms passed in.\n\nReturns a hashref of operational options, combined between *$passedparms* and *$defaults*, plus\nthe queue.\n\nThe queue prep stuff takes the strings in *@startingpoints* and puts them in the format that\nqueue needs.\n\nThe @queue that gets passed around is an array, with each entry an arrayref of $dir, $file and\n$fullpath.\n\ncandidatefiles( $parms, $dir )\nPulls out the files/dirs that might be worth looking into in *$dir*. If *$dir* is the empty\nstring, then search the current directory.\n\n*$parms* is the hashref of parms passed into File::Next constructor.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "\"File::Next::files must not be invoked as File::Next->files\"\n\"File::Next::dirs must not be invoked as File::Next->dirs\"\n\"File::Next::everything must not be invoked as File::Next->everything\"\n\nThe interface functions do not allow for the method invocation syntax and throw errors with the\nmessages above. You can work around this limitation with \"can\" in UNIVERSAL.\n\nfor my $filesystemfeature (qw(dirs files)) {\nmy $iterator = File::Next->can($filesystemfeature)->($options, $targetdirectory);\nwhile (defined(my $name = $iterator->())) {\n# ...\n}\n}\n", "subsections": [] }, "SPEED TWEAKS": { "content": "* Don't set \"followsymlinks => 0\" unless you need it.\n", "subsections": [] }, "AUTHOR": { "content": "Andy Lester, \"\"\n", "subsections": [] }, "BUGS": { "content": "Please report any bugs or feature requests to .\n\nNote that File::Next does NOT use for bug tracking.\n", "subsections": [] }, "SUPPORT": { "content": "You can find documentation for this module with the perldoc command.\n\nperldoc File::Next\n\nYou can also look for information at:\n\n* File::Next's bug queue\n\n\n\n* CPAN Ratings\n\n\n\n* Search CPAN\n\n\n\n* Source code repository\n\n\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "All file-finding in this module is adapted from Mark Jason Dominus' marvelous *Higher Order\nPerl*, page 126.\n\nThanks to these fine contributors: Varadinsky, Paulo Custodio, Gerhard Poul, Brian Fraser, Todd\nRinaldo, Bruce Woodward, Christopher J. Madsen, Bernhard Fisseni and Rob Hoelz.\n\nCOPYRIGHT & LICENSE\nCopyright 2005-2017 Andy Lester.\n\nThis program is free software; you can redistribute it and/or modify it under the terms of the\nArtistic License version 2.0.\n", "subsections": [] } }, "summary": "File::Next - File-finding iterator", "flags": [], "examples": [], "see_also": [] }