Path-Iterator-Rule-1.009/000755 000765 000024 00000000000 12577662462 015366 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/Changes000644 000765 000024 00000010032 12577662462 016655 0ustar00davidstaff000000 000000 Revision history for Path-Iterator-Rule 1.009 2015-09-20 22:02:20-04:00 America/New_York [FIXED] - Regular expressions flags were being lost. Now name(qr/foo/i) works like iname(qr/foo/) 1.008 2014-02-04 17:40:45-05:00 America/New_York [ADDED] - Added VCS rules for DARCS (Gian Piero Carrubba) 1.007 2014-01-25 14:39:09-05:00 America/New_York [DOCS] - Document the behavior of ->all in scalar context 1.006 2013-10-09 11:14:28 America/New_York [PREREQS] - Removed dependencies on Data::Clone, namespace::clean and autodie [DOCS] - Typo fixes 1.005 2013-04-02 09:33:44 America/New_York [FIXED] - Fixed broken t/content.t on Windows 1.004 2013-03-27 23:14:01 America/New_York [ADDED] - contents_match and line_match rules 1.003 2013-03-09 23:16:30 America/New_York [FIXED] - Fixed Windows test failure 1.002 2013-03-08 22:35:51 America/New_York [FIXED] - Returning relative results now works with subclasses 1.001 2013-03-02 08:50:25 America/New_York [FIXED] - A test unintentionally required 5.12; this has been fixed and 5.10 is the minimum Perl once again 1.000 2013-02-27 15:25:47 America/New_York [INCOMPATIBLE CHANGES] - Custom rule logic has changed. The previous "0 but true" hack will throw an exception. Custom rules should return \1 or \0 to signal that a directory should be pruned but returned or pruned and skipped, respectively [ADDED] - Added 'skip_subdirs' method (Issue #7) [DOCUMENTED] - Clarified max/min depth rules 0.014 2013-02-16 09:57:39 America/New_York [CHANGED] - Refactored some internals to allow more flexible subclassing 0.013 2013-02-15 10:51:59 America/New_York [ADDED] - Added 'relative' option to iterator 0.012 2013-02-13 20:40:55 America/New_York [ADDED] - Includes PIR.pm as an empty subclass of Path::Iterator::Rule for less typing for one-liners 0.011 2013-02-06 16:24:16 America/New_York [FIXED] - Really fixed tests on Windows this time, I hope. 0.010 2013-01-31 15:56:17 America/New_York [ADDED] - Added a "visitor" option to pass results to a code reference during iteration [CHANGED] - Calling all() in void context will iterate but not store results [FIXED] - Another attempt at fixing tests on Windows. Damn those backslashes! 0.009 2013-01-25 21:52:41 America/New_York [FIXED] - Fixed tests on Windows 0.008 2013-01-24 09:05:01 America/New_York [DOCUMENTED] - Fixed typos that still talked about Path::Class objects - Fixed documentation of test() - Added Path::Class::Rule and IO::All::Rule to the list of alternates 0.007 2013-01-23 22:35:47 America/New_York [DOCUMENTED] - Fixed typo relating to Number::Compare. "1M" is legal, "1MB" is not 0.006 2013-01-23 21:54:31 America/New_York [CHANGED] - Even more internal optimization 0.005 2013-01-23 19:55:57 America/New_York [FIXED] - Fixed broken t/fast.t on some systems 0.004 2013-01-23 19:37:47 America/New_York [ADDED] - Added 'iter_fast' and 'all_fast' methods that switch default options from safe to fast 0.003 2013-01-23 18:32:31 America/New_York [DOCUMENTED] - Added PERFORMANCE section with tips [CHANGED] - Additional internal optimization 0.002 2013-01-23 14:38:24 America/New_York [INCOMPATIBLE CHANGES] - Test subroutines now get path, basename and stash instead of just path and stash; this saves substantial overhead on name checks. [ADDED] - Add 'sorted' option that defaults to true; disabling this can improve speed for directories with many files [CHANGED] - Setting 'error_handler' to undef disables error checks for speed - Various other optimizations for improved performance 0.001 2013-01-22 06:22:44 America/New_York - First release, based on Path::Class::Rule 0.015 Path-Iterator-Rule-1.009/CONTRIBUTING.mkdn000644 000765 000024 00000006604 12577662462 020156 0ustar00davidstaff000000 000000 ## HOW TO CONTRIBUTE Thank you for considering contributing to this distribution. This file contains instructions that will help you work with the source code. The distribution is managed with Dist::Zilla. This means that many of the usual files you might expect are not in the repository, but are generated at release time, as is much of the documentation. Some generated files are kept in the repository as a convenience (e.g. Makefile.PL or cpanfile). Generally, **you do not need Dist::Zilla to contribute patches**. You do need Dist::Zilla to create a tarball. See below for guidance. ### Getting dependencies If you have App::cpanminus 1.6 or later installed, you can use `cpanm` to satisfy dependencies like this: $ cpanm --installdeps . Otherwise, look for either a `Makefile.PL` or `cpanfile` file for a list of dependencies to satisfy. ### Running tests You can run tests directly using the `prove` tool: $ prove -l $ prove -lv t/some_test_file.t For most of my distributions, `prove` is entirely sufficient for you to test any patches you have. I use `prove` for 99% of my testing during development. ### Code style and tidying Please try to match any existing coding style. If there is a `.perltidyrc` file, please install Perl::Tidy and use perltidy before submitting patches. If there is a `tidyall.ini` file, you can also install Code::TidyAll and run `tidyall` on a file or `tidyall -a` to tidy all files. ### Patching documentation Much of the documentation Pod is generated at release time. Some is generated boilerplate; other documentation is built from pseudo-POD directives in the source like C<=method> or C<=func>. If you would like to submit a documentation edit, please limit yourself to the documentation you see. If you see typos or documentation issues in the generated docs, please email or open a bug ticket instead of patching. ### Where to send patches and pull requests If you found this distribution on Github, sending a pull-request is the best way to contribute. If a pull-request isn't possible, a bug ticket with a patch file is the next best option. As a last resort, an email to the author(s) is acceptable. ## Installing and using Dist::Zilla Dist::Zilla is not required for contributing, but if you'd like to learn more, this section will get you up to speed. Dist::Zilla is a very powerful authoring tool, optimized for maintaining a large number of distributions with a high degree of automation, but it has a large dependency chain, a bit of a learning curve and requires a number of author-specific plugins. To install it from CPAN, I recommend one of the following approaches for the quickest installation: # using CPAN.pm, but bypassing non-functional pod tests $ cpan TAP::Harness::Restricted $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla # using cpanm, bypassing *all* tests $ cpanm -n Dist::Zilla In either case, it's probably going to take about 10 minutes. Go for a walk, go get a cup of your favorite beverage, take a bathroom break, or whatever. When you get back, Dist::Zilla should be ready for you. Then you need to install any plugins specific to this distribution: $ cpan `dzil authordeps` $ dzil authordeps | cpanm Once installed, here are some dzil commands you might try: $ dzil build $ dzil test $ dzil xtest You can learn more about Dist::Zilla at http://dzil.org/ Path-Iterator-Rule-1.009/cpanfile000644 000765 000024 00000003042 12577662462 017071 0ustar00davidstaff000000 000000 requires "Carp" => "0"; requires "File::Basename" => "0"; requires "File::Spec" => "0"; requires "List::Util" => "0"; requires "Number::Compare" => "0.02"; requires "Scalar::Util" => "0"; requires "Text::Glob" => "0"; requires "Try::Tiny" => "0"; requires "perl" => "5.010"; requires "re" => "0"; requires "strict" => "0"; requires "warnings" => "0"; requires "warnings::register" => "0"; on 'test' => sub { requires "Exporter" => "0"; requires "ExtUtils::MakeMaker" => "0"; requires "File::Spec" => "0"; requires "File::Temp" => "0"; requires "File::pushd" => "0"; requires "Path::Tiny" => "0"; requires "Test::Deep" => "0"; requires "Test::Filename" => "0.03"; requires "Test::More" => "0.92"; requires "lib" => "0"; requires "perl" => "5.010"; }; on 'test' => sub { recommends "CPAN::Meta" => "2.120900"; }; on 'configure' => sub { requires "ExtUtils::MakeMaker" => "6.17"; requires "perl" => "5.010"; }; on 'develop' => sub { requires "Dist::Zilla" => "5"; requires "Dist::Zilla::Plugin::AppendExternalData" => "0"; requires "Dist::Zilla::PluginBundle::DAGOLDEN" => "0.072"; requires "English" => "0"; requires "File::Spec" => "0"; requires "File::Temp" => "0"; requires "IO::Handle" => "0"; requires "IPC::Open3" => "0"; requires "Pod::Wordlist" => "0"; requires "Software::License::Apache_2_0" => "0"; requires "Test::CPAN::Meta" => "0"; requires "Test::More" => "0"; requires "Test::Pod" => "1.41"; requires "Test::Spelling" => "0.12"; requires "Test::Version" => "1"; requires "blib" => "1.01"; }; Path-Iterator-Rule-1.009/dist.ini000644 000765 000024 00000000545 12577662462 017036 0ustar00davidstaff000000 000000 name = Path-Iterator-Rule author = David Golden license = Apache_2_0 copyright_holder = David Golden copyright_year = 2013 [AppendExternalData] source_dir = pod [@DAGOLDEN] :version = 0.072 no_coverage = 1 stopwords = postorder stopwords = rjbs stopwords = Signes stopwords = subclasses stopwords = timestamps stopwords = tuples Path-Iterator-Rule-1.009/examples/000755 000765 000024 00000000000 12577662462 017204 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/lib/000755 000765 000024 00000000000 12577662462 016134 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/LICENSE000644 000765 000024 00000026354 12577662462 016405 0ustar00davidstaff000000 000000 This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Path-Iterator-Rule-1.009/Makefile.PL000644 000765 000024 00000003642 12577662462 017345 0ustar00davidstaff000000 000000 # This file was automatically generated by Dist::Zilla::Plugin::MakeMaker v5.039. use strict; use warnings; use 5.010; use ExtUtils::MakeMaker 6.17; my %WriteMakefileArgs = ( "ABSTRACT" => "Iterative, recursive file finder", "AUTHOR" => "David Golden ", "CONFIGURE_REQUIRES" => { "ExtUtils::MakeMaker" => "6.17" }, "DISTNAME" => "Path-Iterator-Rule", "LICENSE" => "apache", "MIN_PERL_VERSION" => "5.010", "NAME" => "Path::Iterator::Rule", "PREREQ_PM" => { "Carp" => 0, "File::Basename" => 0, "File::Spec" => 0, "List::Util" => 0, "Number::Compare" => "0.02", "Scalar::Util" => 0, "Text::Glob" => 0, "Try::Tiny" => 0, "re" => 0, "strict" => 0, "warnings" => 0, "warnings::register" => 0 }, "TEST_REQUIRES" => { "Exporter" => 0, "ExtUtils::MakeMaker" => 0, "File::Spec" => 0, "File::Temp" => 0, "File::pushd" => 0, "Path::Tiny" => 0, "Test::Deep" => 0, "Test::Filename" => "0.03", "Test::More" => "0.92", "lib" => 0 }, "VERSION" => "1.009", "test" => { "TESTS" => "t/*.t" } ); my %FallbackPrereqs = ( "Carp" => 0, "Exporter" => 0, "ExtUtils::MakeMaker" => 0, "File::Basename" => 0, "File::Spec" => 0, "File::Temp" => 0, "File::pushd" => 0, "List::Util" => 0, "Number::Compare" => "0.02", "Path::Tiny" => 0, "Scalar::Util" => 0, "Test::Deep" => 0, "Test::Filename" => "0.03", "Test::More" => "0.92", "Text::Glob" => 0, "Try::Tiny" => 0, "lib" => 0, "re" => 0, "strict" => 0, "warnings" => 0, "warnings::register" => 0 ); unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) { delete $WriteMakefileArgs{TEST_REQUIRES}; delete $WriteMakefileArgs{BUILD_REQUIRES}; $WriteMakefileArgs{PREREQ_PM} = \%FallbackPrereqs; } delete $WriteMakefileArgs{CONFIGURE_REQUIRES} unless eval { ExtUtils::MakeMaker->VERSION(6.52) }; WriteMakefile(%WriteMakefileArgs); Path-Iterator-Rule-1.009/MANIFEST000644 000765 000024 00000001445 12577662462 016523 0ustar00davidstaff000000 000000 # This file was automatically generated by Dist::Zilla::Plugin::Manifest v5.039. CONTRIBUTING.mkdn Changes LICENSE MANIFEST META.json META.yml Makefile.PL README cpanfile dist.ini examples/modules-in-inc.pl lib/PIR.pm lib/Path/Iterator/Rule.pm perlcritic.rc t/00-report-prereqs.dd t/00-report-prereqs.t t/basic.t t/breadth-depth-files.t t/breadth-depth.t t/clone.t t/content.t t/error_handler.t t/fast.t t/helpers.t t/lib/PCNTest.pm t/lib/PIRTiny.pm t/logic.t t/min-max-depth.t t/names.t t/perl.t t/pir.t t/relative.t t/stat_tests.t t/stringify.t t/symlink.t t/unsorted.t t/vcs.t t/visitor.t t/x_tests.t tidyall.ini xt/author/00-compile.t xt/author/critic.t xt/author/pod-spell.t xt/author/test-version.t xt/release/distmeta.t xt/release/minimum-version.t xt/release/pod-syntax.t xt/release/portability.t Path-Iterator-Rule-1.009/META.json000644 000765 000024 00000006442 12577662462 017015 0ustar00davidstaff000000 000000 { "abstract" : "Iterative, recursive file finder", "author" : [ "David Golden " ], "dynamic_config" : 0, "generated_by" : "Dist::Zilla version 5.039, CPAN::Meta::Converter version 2.150005", "license" : [ "apache_2_0" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "Path-Iterator-Rule", "no_index" : { "directory" : [ "t", "xt", "examples", "corpus" ], "package" : [ "DB" ] }, "prereqs" : { "configure" : { "requires" : { "ExtUtils::MakeMaker" : "6.17", "perl" : "5.010" } }, "develop" : { "requires" : { "Dist::Zilla" : "5", "Dist::Zilla::Plugin::AppendExternalData" : "0", "Dist::Zilla::PluginBundle::DAGOLDEN" : "0.072", "English" : "0", "File::Spec" : "0", "File::Temp" : "0", "IO::Handle" : "0", "IPC::Open3" : "0", "Pod::Wordlist" : "0", "Software::License::Apache_2_0" : "0", "Test::CPAN::Meta" : "0", "Test::More" : "0", "Test::Pod" : "1.41", "Test::Spelling" : "0.12", "Test::Version" : "1", "blib" : "1.01" } }, "runtime" : { "requires" : { "Carp" : "0", "File::Basename" : "0", "File::Spec" : "0", "List::Util" : "0", "Number::Compare" : "0.02", "Scalar::Util" : "0", "Text::Glob" : "0", "Try::Tiny" : "0", "perl" : "5.010", "re" : "0", "strict" : "0", "warnings" : "0", "warnings::register" : "0" } }, "test" : { "recommends" : { "CPAN::Meta" : "2.120900" }, "requires" : { "Exporter" : "0", "ExtUtils::MakeMaker" : "0", "File::Spec" : "0", "File::Temp" : "0", "File::pushd" : "0", "Path::Tiny" : "0", "Test::Deep" : "0", "Test::Filename" : "0.03", "Test::More" : "0.92", "lib" : "0", "perl" : "5.010" } } }, "provides" : { "PIR" : { "file" : "lib/PIR.pm", "version" : "1.009" }, "Path::Iterator::Rule" : { "file" : "lib/Path/Iterator/Rule.pm", "version" : "1.009" } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://github.com/dagolden/Path-Iterator-Rule/issues" }, "homepage" : "https://github.com/dagolden/Path-Iterator-Rule", "repository" : { "type" : "git", "url" : "https://github.com/dagolden/Path-Iterator-Rule.git", "web" : "https://github.com/dagolden/Path-Iterator-Rule" } }, "version" : "1.009", "x_authority" : "cpan:DAGOLDEN", "x_contributors" : [ "David Steinbrunner ", "Gian Piero Carrubba ", "Graham Knop ", "Ricardo Signes ", "Toby Inkster " ] } Path-Iterator-Rule-1.009/META.yml000644 000765 000024 00000003042 12577662462 016636 0ustar00davidstaff000000 000000 --- abstract: 'Iterative, recursive file finder' author: - 'David Golden ' build_requires: Exporter: '0' ExtUtils::MakeMaker: '0' File::Spec: '0' File::Temp: '0' File::pushd: '0' Path::Tiny: '0' Test::Deep: '0' Test::Filename: '0.03' Test::More: '0.92' lib: '0' perl: '5.010' configure_requires: ExtUtils::MakeMaker: '6.17' perl: '5.010' dynamic_config: 0 generated_by: 'Dist::Zilla version 5.039, CPAN::Meta::Converter version 2.150005' license: apache meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Path-Iterator-Rule no_index: directory: - t - xt - examples - corpus package: - DB provides: PIR: file: lib/PIR.pm version: '1.009' Path::Iterator::Rule: file: lib/Path/Iterator/Rule.pm version: '1.009' requires: Carp: '0' File::Basename: '0' File::Spec: '0' List::Util: '0' Number::Compare: '0.02' Scalar::Util: '0' Text::Glob: '0' Try::Tiny: '0' perl: '5.010' re: '0' strict: '0' warnings: '0' warnings::register: '0' resources: bugtracker: https://github.com/dagolden/Path-Iterator-Rule/issues homepage: https://github.com/dagolden/Path-Iterator-Rule repository: https://github.com/dagolden/Path-Iterator-Rule.git version: '1.009' x_authority: cpan:DAGOLDEN x_contributors: - 'David Steinbrunner ' - 'Gian Piero Carrubba ' - 'Graham Knop ' - 'Ricardo Signes ' - 'Toby Inkster ' Path-Iterator-Rule-1.009/perlcritic.rc000644 000765 000024 00000001166 12577662462 020060 0ustar00davidstaff000000 000000 severity = 5 verbose = 8 [Variables::ProhibitPunctuationVars] allow = $@ $! [TestingAndDebugging::ProhibitNoStrict] allow = refs [Variables::ProhibitEvilVariables] variables = $DB::single # Turn these off [-BuiltinFunctions::ProhibitStringyEval] [-ControlStructures::ProhibitPostfixControls] [-ControlStructures::ProhibitUnlessBlocks] [-Documentation::RequirePodSections] [-InputOutput::ProhibitInteractiveTest] [-References::ProhibitDoubleSigils] [-RegularExpressions::RequireExtendedFormatting] [-InputOutput::ProhibitTwoArgOpen] [-Modules::ProhibitEvilModules] # Turn this on [Lax::ProhibitStringyEval::ExceptForRequire] Path-Iterator-Rule-1.009/README000644 000765 000024 00000065473 12577662462 016265 0ustar00davidstaff000000 000000 NAME Path::Iterator::Rule - Iterative, recursive file finder VERSION version 1.009 SYNOPSIS use Path::Iterator::Rule; my $rule = Path::Iterator::Rule->new; # match anything $rule->file->size(">10k"); # add/chain rules # iterator interface my $next = $rule->iter( @dirs ); while ( defined( my $file = $next->() ) ) { ... } # list interface for my $file ( $rule->all( @dirs ) ) { ... } DESCRIPTION This module iterates over files and directories to identify ones matching a user-defined set of rules. The API is based heavily on File::Find::Rule, but with more explicit distinction between matching rules and options that influence how directories are searched. A "Path::Iterator::Rule" object is a collection of rules (match criteria) with methods to add additional criteria. Options that control directory traversal are given as arguments to the method that generates an iterator. Here is a summary of features for comparison to other file finding modules: * provides many "helper" methods for specifying rules * offers (lazy) iterator and flattened list interfaces * custom rules implemented with callbacks * breadth-first (default) or pre- or post-order depth-first searching * follows symlinks (by default, but can be disabled) * directories visited only once (no infinite loop; can be disabled) * doesn't chdir during operation * provides an API for extensions As a convenience, the PIR module is an empty subclass of this one that is less arduous to type for one-liners. USAGE Constructors "new" my $rule = Path::Iterator::Rule->new; Creates a new rule object that matches any file or directory. It takes no arguments. For convenience, it may also be called on an object, in which case it still returns a new object that matches any file or directory. "clone" my $common = Path::Iterator::Rule->new->file->not_empty; my $big_files = $common->clone->size(">1M"); my $small_files = $common->clone->size("<10K"); Creates a copy of a rule object. Useful for customizing different rule objects against a common base. Matching and iteration "iter" my $next = $rule->iter( @dirs, \%options); while ( defined( my $file = $next->() ) ) { ... } Creates a subroutine reference iterator that returns a single result when dereferenced. This iterator is "lazy" -- results are not pre-computed. It takes as arguments a list of directories to search and an optional hash reference of control options. If no search directories are provided, the current directory is used ("."). Valid options include: * "depthfirst" -- Controls order of results. Valid values are "1" (post-order, depth-first search), "0" (breadth-first search) or "-1" (pre-order, depth-first search). Default is 0. * "error_handler" -- Catches errors during execution of rule tests. Default handler dies with the filename and error. If set to undef, error handling is disabled. * "follow_symlinks" -- Follow directory symlinks when true. Default is 1. * "loop_safe" -- Prevents visiting the same directory more than once when true. Default is 1. * "relative" -- Return matching items relative to the search directory. Default is 0. * "sorted" -- Whether entries in a directory are sorted before processing. Default is 1. * "visitor" -- An optional coderef that will be called on items matching all rules. Filesystem loops might exist from either hard or soft links. The "loop_safe" option prevents infinite loops, but adds some overhead by making "stat" calls. Because directories are visited only once when "loop_safe" is true, matches could come from a symlinked directory before the real directory depending on the search order. To get only the real files, turn off "follow_symlinks". Turning "loop_safe" off and leaving "follow_symlinks" on avoids "stat" calls and will be fastest, but with the risk of an infinite loop and repeated files. The default is slow, but safe. The "error_handler" parameter must be a subroutine reference. It will be called when a rule test throws an exception. The first argument will be the file name being inspected and the second argument will be the exception. The optional "visitor" parameter must be a subroutine reference. If set, it will be called for any result that matches. It is called the same way a custom rule would be (see "EXTENDING") but its return value is ignored. It is called when an item is first inspected -- "postorder" is not respected. The paths inspected and returned will be relative to the search directories provided. If these are absolute, then the paths returned will have absolute paths. If these are relative, then the paths returned will have relative paths. If the search directories are absolute and the "relative" option is true, files returned will be relative to the search directory. Note that if the search directories are not mutually exclusive (whether containing subdirectories like @INC or symbolic links), files found could be returned relative to different initial search directories based on "depthfirst", "follow_symlinks" or "loop_safe". When the iterator is exhausted, it will return undef. "iter_fast" This works just like "iter", except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See "PERFORMANCE" for details. "all" my @matches = $rule->all( @dir, \%options ); Returns a list of paths that match the rule. It takes the same arguments and has the same behaviors as the "iter" method. The "all" method uses "iter" internally to fetch all results. In scalar context, it will return the count of matched paths. In void context, it is optimized to iterate over everything, but not store results. This is most useful with the "visitor" option: $rule->all( $path, { visitor => \&callback } ); "all_fast" This works just like "all", except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See "PERFORMANCE" for details. "test" if ( $rule->test( $path, $basename, $stash ) ) { ... } Test a file path against a rule. Used internally, but provided should someone want to create their own, custom iteration algorithm. Logic operations "Path::Iterator::Rule" provides three logic operations for adding rules to the object. Rules may be either a subroutine reference with specific semantics (described below in "EXTENDING") or another "Path::Iterator::Rule" object. "and" $rule->and( sub { -r -w -x $_ } ); # stacked filetest example $rule->and( @more_rules ); Adds one or more constraints to the current rule. E.g. "old rule AND new1 AND new2 AND ...". Returns the object to allow method chaining. "or" $rule->or( $rule->new->name("foo*"), $rule->new->name("bar*"), sub { -r -w -x $_ }, ); Takes one or more alternatives and adds them as a constraint to the current rule. E.g. "old rule AND ( new1 OR new2 OR ... )". Returns the object to allow method chaining. "not" $rule->not( sub { -r -w -x $_ } ); Takes one or more alternatives and adds them as a negative constraint to the current rule. E.g. "old rule AND NOT ( new1 AND new2 AND ...)". Returns the object to allow method chaining. "skip" $rule->skip( $rule->new->dir->not_writeable, $rule->new->dir->name("foo"), ); Takes one or more alternatives and will prune a directory if any of the criteria match or if any of the rules already indicate the directory should be pruned. Pruning means the directory will not be returned by the iterator and will not be searched. For files, it is equivalent to "$rule->not($rule->or(@rules))". Returns the object to allow method chaining. This method should be called as early as possible in the rule chain. See "skip_dirs" below for further explanation and an example. RULE METHODS Rule methods are helpers that add constraints. Internally, they generate a closure to accomplish the desired logic and add it to the rule object with the "and" method. Rule methods return the object to allow for method chaining. File name rules "name" $rule->name( "foo.txt" ); $rule->name( qr/foo/, "bar.*"); The "name" method takes one or more patterns and creates a rule that is true if any of the patterns match the basename of the file or directory path. Patterns may be regular expressions or glob expressions (or literal names). "iname" $rule->iname( "foo.txt" ); $rule->iname( qr/foo/, "bar.*"); The "iname" method is just like the "name" method, but matches case-insensitively. "skip_dirs" $rule->skip_dirs( @patterns ); The "skip_dirs" method skips directories that match one or more patterns. Patterns may be regular expressions or globs (just like "name"). Directories that match will not be returned from the iterator and will be excluded from further search. This includes the starting directories. If that isn't what you want, see "skip_subdirs" instead. Note: this rule should be specified early so that it has a chance to operate before a logical shortcut. E.g. $rule->skip_dirs(".git")->file; # OK $rule->file->skip_dirs(".git"); # Won't work In the latter case, when a ".git" directory is seen, the "file" rule shortcuts the rule before the "skip_dirs" rule has a chance to act. "skip_subdirs" $rule->skip_subdirs( @patterns ); This works just like "skip_dirs", except that the starting directories (depth 0) are not skipped and may be returned from the iterator unless excluded by other rules. File test rules Most of the "-X" style filetest are available as boolean rules. The table below maps the filetest to its corresponding method name. Test | Method Test | Method ------|------------- ------|---------------- -r | readable -R | r_readable -w | writeable -W | r_writeable -w | writable -W | r_writable -x | executable -X | r_executable -o | owned -O | r_owned | | -e | exists -f | file -z | empty -d | directory, dir -s | nonempty -l | symlink | -p | fifo -u | setuid -S | socket -g | setgid -b | block -k | sticky -c | character | -t | tty -T | ascii -B | binary For example: $rule->file->nonempty; # -f -s $file The -X operators for timestamps take a single argument in a form that Number::Compare can interpret. Test | Method ------|------------- -A | accessed -M | modified -C | changed For example: $rule->modified(">1"); # -M $file > 1 Stat test rules All of the "stat" elements have a method that takes a single argument in a form understood by Number::Compare. stat() | Method -------------------- 0 | dev 1 | ino 2 | mode 3 | nlink 4 | uid 5 | gid 6 | rdev 7 | size 8 | atime 9 | mtime 10 | ctime 11 | blksize 12 | blocks For example: $rule->size(">10K") Depth rules $rule->min_depth(3); $rule->max_depth(5); The "min_depth" and "max_depth" rule methods take a single argument and limit the paths returned to a minimum or maximum depth (respectively) from the starting search directory. A depth of 0 means the starting directory itself. A depth of 1 means its children. (This is similar to the Unix "find" utility.) Perl file rules # All perl rules $rule->perl_file; # Individual perl file rules $rule->perl_module; # .pm files $rule->perl_pod; # .pod files $rule->perl_test; # .t files $rule->perl_installer; # Makefile.PL or Build.PL $rule->perl_script; # .pl or 'perl' in the shebang These rule methods match file names (or a shebang line) that are typical of Perl distribution files. Version control file rules # Skip all known VCS files $rule->skip_vcs; # Skip individual VCS files $rule->skip_cvs; $rule->skip_rcs; $rule->skip_svn; $rule->skip_git; $rule->skip_bzr; $rule->skip_hg; $rule->skip_darcs; Skips files and/or prunes directories related to a version control system. Just like "skip_dirs", these rules should be specified early to get the correct behavior. File content rules "contents_match" $rule->contents_match(qr/BEGIN .* END/xs); The "contents_match" rule takes a list of regular expressions and returns files that match one of the expressions. The expressions are applied to the file's contents as a single string. For large files, this is likely to take significant time and memory. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument: $rule->contents_match(":encoding(iso-8859-1)", qr/BEGIN .* END/xs); See perlio for further details. "line_match" $rule->line_match(qr/^new/i, qr/^Addition/); The "line_match" rule takes a list of regular expressions and returns files with at least one line that matches one of the expressions. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument. "shebang" $rule->shebang(qr/#!.*\bperl\b/); The "shebang" rule takes a list of regular expressions or glob patterns and checks them against the first line of a file. Other rules "dangling" $rule->symlink->dangling; $rule->not_dangling; The "dangling" rule method matches dangling symlinks. Use it or its inverse to control how dangling symlinks should be treated. Negated rules Most rule methods have a negated form preceded by "not_". $rule->not_name("foo.*") Because this happens automatically, it includes somewhat silly ones like "not_nonempty" (which is thus a less efficient way of saying "empty"). Rules that skip directories or version control files do not have a negated version. EXTENDING Custom rule subroutines Rules are implemented as (usually anonymous) subroutine callbacks that return a value indicating whether or not the rule matches. These callbacks are called with three arguments. The first argument is a path, which is also locally aliased as the $_ global variable for convenience in simple tests. $rule->and( sub { -r -w -x $_ } ); # tests $_ The second argument is the basename of the path, which is useful for certain types of name checks: $rule->and( sub { $_[1] =~ /foo|bar/ } ); "foo" or "bar" in basename; The third argument is a hash reference that can be used to maintain state. Keys beginning with an underscore are reserved for "Path::Iterator::Rule" to provide additional data about the search in progress. For example, the "_depth" key is used to support minimum and maximum depth checks. The custom rule subroutine must return one of four values: * A true value -- indicates the constraint is satisfied * A false value -- indicates the constraint is not satisfied * "\1" -- indicate the constraint is satisfied, and prune if it's a directory * "\0" -- indicate the constraint is not satisfied, and prune if it's a directory A reference is a special flag that signals that a directory should not be searched recursively, regardless of whether the directory should be returned by the iterator or not. The legacy "0 but true" value used previously for pruning is no longer valid and will throw an exception if it is detected. Here is an example. This is equivalent to the "max_depth" rule method with a depth of 3: $rule->and( sub { my ($path, $basename, $stash) = @_; return 1 if $stash->{_depth} < 3; return \1 if $stash->{_depth} == 3; return \0; # should never get here } ); Files and directories and directories up to depth 3 will be returned and directories will be searched. Files of depth 3 will be returned. Directories of depth 3 will be returned, but their contents will not be added to the search. Returning a reference is "sticky" -- they will propagate through "and" and "or" logic. 0 && \0 = \0 \0 && 0 = \0 0 || \0 = \0 \0 || 0 = \0 0 && \1 = \0 \0 && 1 = \0 0 || \1 = \1 \0 || 1 = \1 1 && \0 = \0 \1 && 0 = \0 1 || \0 = \1 \1 || 0 = \1 1 && \1 = \1 \1 && 1 = \1 1 || \1 = \1 \1 || 1 = \1 Once a directory is flagged to be pruned, it will be pruned regardless of subsequent rules. $rule->max_depth(3)->name(qr/foo/); This will return files or directories with "foo" in the name, but all directories at depth 3 will be pruned, regardless of whether they match the name rule. Generally, if you want to do directory pruning, you are encouraged to use the "skip" method instead of writing your own logic using "\0" and "\1". Extension modules and custom rule methods One of the strengths of File::Find::Rule is the many CPAN modules that extend it. "Path::Iterator::Rule" provides the "add_helper" method to provide a similar mechanism for extensions. The "add_helper" class method takes three arguments, a "name" for the rule method, a closure-generating callback, and a flag for not generating a negated form of the rule. Unless the flag is true, an inverted "not_*" method is generated automatically. Extension classes should call this as a class method to install new rule methods. For example, this adds a "foo" method that checks if the filename is "foo": package Path::Iterator::Rule::Foo; use Path::Iterator::Rule; Path::Iterator::Rule->add_helper( foo => sub { my @args = @_; # do this to customize closure with arguments return sub { my ($item, $basename) = @_; return if -d "$item"; return $basename =~ /^foo$/; } } ); 1; This allows the following rule methods: $rule->foo; $fule->not_foo; The "add_helper" method will warn and ignore a helper with the same name as an existing method. Subclassing Instead of processing and returning strings, this module may be subclassed to operate on objects that represent files. Such objects must stringify to a file path. The following private implementation methods must be overridden: * _objectify -- given a path, return an object * _children -- given a directory, return an (unsorted) list of [ basename, full path ] entries within it, excluding "." and ".." Note that "_children" should return a *list* of *tuples*, where the tuples are array references containing basename and full path. See Path::Class::Rule source for an example. LEXICAL WARNINGS If you run with lexical warnings enabled, "Path::Iterator::Rule" will issue warnings in certain circumstances (such as an unreadable directory that must be skipped). To disable these categories, put the following statement at the correct scope: no warnings 'Path::Iterator::Rule'; PERFORMANCE By default, "Path::Iterator::Rule" iterator options are "slow but safe". They ensure uniqueness, return files in sorted order, and throw nice error messages if something goes wrong. If you want speed over safety, set these options: %options = ( loop_safe => 0, sorted => 0, depthfirst => -1, error_handler => undef ); Alternatively, use the "iter_fast" and "all_fast" methods instead, which set these options for you. $iter = $rule->iter( @dirs, \%options ); $iter = $rule->iter_fast( @dirs ); # same thing Depending on the file structure being searched, "depthfirst => -1" may or may not be a good choice. If you have lots of nested directories and all the files at the bottom, a depth first search might do less work or use less memory, particularly if the search will be halted early (e.g. finding the first N matches.) Rules will shortcut on failure, so be sure to put rules likely to fail early in a rule chain. Consider: $r1 = Path::Iterator::Rule->new->name(qr/foo/)->file; $r2 = Path::Iterator::Rule->new->file->name(qr/foo/); If there are lots of files, but only a few containing "foo", then $r1 above will be faster. Rules are implemented as code references, so long chains have some overhead. Consider testing with a custom coderef that combines several tests into one. Consider: $r3 = Path::Iterator::Rule->new->and( sub { -x -w -r $_ } ); $r4 = Path::Iterator::Rule->new->executable->writeable->readable; Rule $r3 above will be much faster, not only because it stacks the file tests, but because it requires only a single code reference. CAVEATS Some features are still unimplemented: * Untainting options * Some File::Find::Rule helpers (e.g. "grep") * Extension class loading via "import()" Filetest operators and stat rules are subject to the usual portability considerations. See perlport for details. SEE ALSO There are many other file finding modules out there. They all have various features/deficiencies, depending on your preferences and needs. Here is an (incomplete) list of alternatives, with some comparison commentary. Path::Class::Rule and IO::All::Rule are subclasses of "Path::Iterator::Rule" and operate on Path::Class and IO::All objects, respectively. Because of this, they are substantially slower on large directory trees than just using this module directly. File::Find is part of the Perl core. It requires the user to write a callback function to process each node of the search. Callbacks must use global variables to determine the current node. It only supports depth-first search (both pre- and post-order). It supports pre- and post-processing callbacks; the former is required for sorting files to process in a directory. File::Find::Closures can be used to help create a callback for File::Find. File::Find::Rule is an object-oriented wrapper around File::Find. It provides a number of helper functions and there are many more "File::Find::Rule::*" modules on CPAN with additional helpers. It provides an iterator interface, but precomputes all the results. File::Next provides iterators for file, directories or "everything". It takes two callbacks, one to match files and one to decide which directories to descend. It does not allow control over breadth/depth order, though it does provide means to sort files for processing within a directory. Like File::Find, it requires callbacks to use global variables. Path::Class::Iterator walks a directory structure with an iterator. It is implemented as Path::Class subclasses, which adds a degree of extra complexity. It takes a single callback to define "interesting" paths to return. The callback gets a Path::Class::Iterator::File or Path::Class::Iterator::Dir object for evaluation. File::Find::Object and companion File::Find::Object::Rule are like File::Find and File::Find::Rule, but without File::Find inside. They use an iterator that does not precompute results. They can return File::Find::Object::Result objects, which give a subset of the utility of Path::Class objects. File::Find::Object::Rule appears to be a literal translation of File::Find::Rule, including oddities like making "-M" into a boolean. File::chdir::WalkDir recursively descends a tree, calling a callback on each file. No iterator. Supports exclusion patterns. Depth-first post-order by default, but offers pre-order option. Does not process symlinks. File::Find::Iterator is based on iterator patterns in Higher Order Perl. It allows a filtering callback. Symlinks are followed automatically without infinite loop protection. No control over order. It offers a "state file" option for resuming interrupted work. File::Find::Declare has declarative helper rules, no iterator, is Moose-based and offers no control over ordering or following symlinks. File::Find::Node has no iterator, does matching via callback and offers no control over ordering. File::Set builds up a set of files to operate on from a list of directories to include or exclude, with control over recursion. A callback is applied to each file (or directory) in the set. There is no iterator. There is no control over ordering. Symlinks are not followed. It has several extra features for checksumming the set and creating tarballs with /bin/tar. THANKS Thank you to Ricardo Signes (rjbs) for inspiring me to write yet another file finder module, for writing file finder optimization benchmarks, and tirelessly running my code over and over to see if it got faster. * See the speed of Perl file finders SUPPORT Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. git clone https://github.com/dagolden/Path-Iterator-Rule.git AUTHOR David Golden CONTRIBUTORS * David Steinbrunner * Gian Piero Carrubba * Graham Knop * Ricardo Signes * Toby Inkster COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 Path-Iterator-Rule-1.009/t/000755 000765 000024 00000000000 12577662462 015631 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/tidyall.ini000644 000765 000024 00000000240 12577662462 017525 0ustar00davidstaff000000 000000 ; Install Code::TidyAll ; run "tidyall -a" to tidy all files ; run "tidyall -g" to tidy only files modified from git [PerlTidy] select = {lib,t}/**/*.{pl,pm,t} Path-Iterator-Rule-1.009/xt/000755 000765 000024 00000000000 12577662462 016021 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/xt/author/000755 000765 000024 00000000000 12577662462 017323 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/xt/release/000755 000765 000024 00000000000 12577662462 017441 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/xt/release/distmeta.t000644 000765 000024 00000000172 12577662462 021440 0ustar00davidstaff000000 000000 #!perl # This file was automatically generated by Dist::Zilla::Plugin::MetaTests. use Test::CPAN::Meta; meta_yaml_ok(); Path-Iterator-Rule-1.009/xt/release/minimum-version.t000644 000765 000024 00000000266 12577662462 022770 0ustar00davidstaff000000 000000 #!perl use Test::More; eval "use Test::MinimumVersion"; plan skip_all => "Test::MinimumVersion required for testing minimum versions" if $@; all_minimum_version_ok( qq{5.010} ); Path-Iterator-Rule-1.009/xt/release/pod-syntax.t000644 000765 000024 00000000220 12577662462 021726 0ustar00davidstaff000000 000000 #!perl # This file was automatically generated by Dist::Zilla::Plugin::PodSyntaxTests. use Test::More; use Test::Pod 1.41; all_pod_files_ok(); Path-Iterator-Rule-1.009/xt/release/portability.t000644 000765 000024 00000000332 12577662462 022166 0ustar00davidstaff000000 000000 #!perl use strict; use warnings; use Test::More; eval 'use Test::Portability::Files'; plan skip_all => 'Test::Portability::Files required for testing portability' if $@; options(test_one_dot => 0); run_tests(); Path-Iterator-Rule-1.009/xt/author/00-compile.t000644 000765 000024 00000002401 12577662462 021352 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; # this test was generated with Dist::Zilla::Plugin::Test::Compile 2.054 use Test::More; plan tests => 3; my @module_files = ( 'PIR.pm', 'Path/Iterator/Rule.pm' ); # fake home for cpan-testers use File::Temp; local $ENV{HOME} = File::Temp::tempdir( CLEANUP => 1 ); my $inc_switch = -d 'blib' ? '-Mblib' : '-Ilib'; use File::Spec; use IPC::Open3; use IO::Handle; open my $stdin, '<', File::Spec->devnull or die "can't open devnull: $!"; my @warnings; for my $lib (@module_files) { # see L my $stderr = IO::Handle->new; my $pid = open3($stdin, '>&STDERR', $stderr, $^X, $inc_switch, '-e', "require q[$lib]"); binmode $stderr, ':crlf' if $^O eq 'MSWin32'; my @_warnings = <$stderr>; waitpid($pid, 0); is($?, 0, "$lib loaded ok"); shift @_warnings if @_warnings and $_warnings[0] =~ /^Using .*\bblib/ and not eval { require blib; blib->VERSION('1.01') }; if (@_warnings) { warn @_warnings; push @warnings, @_warnings; } } is(scalar(@warnings), 0, 'no warnings found') or diag 'got warnings: ', ( Test::More->can('explain') ? Test::More::explain(\@warnings) : join("\n", '', @warnings) ); Path-Iterator-Rule-1.009/xt/author/critic.t000644 000765 000024 00000000435 12577662462 020767 0ustar00davidstaff000000 000000 #!perl use strict; use warnings; use Test::More; use English qw(-no_match_vars); eval "use Test::Perl::Critic"; plan skip_all => 'Test::Perl::Critic required to criticise code' if $@; Test::Perl::Critic->import( -profile => "perlcritic.rc" ) if -e "perlcritic.rc"; all_critic_ok(); Path-Iterator-Rule-1.009/xt/author/pod-spell.t000644 000765 000024 00000000656 12577662462 021416 0ustar00davidstaff000000 000000 use strict; use warnings; use Test::More; # generated by Dist::Zilla::Plugin::Test::PodSpelling 2.006009 use Test::Spelling 0.12; use Pod::Wordlist; add_stopwords(); all_pod_files_spelling_ok( qw( bin lib ) ); __DATA__ postorder rjbs Signes subclasses timestamps tuples David Golden dagolden Steinbrunner dsteinbrunner Gian Piero Carrubba gpiero Graham Knop haarg Ricardo Toby Inkster tobyink lib PIR Path Iterator Rule Path-Iterator-Rule-1.009/xt/author/test-version.t000644 000765 000024 00000000640 12577662462 022152 0ustar00davidstaff000000 000000 use strict; use warnings; use Test::More; # generated by Dist::Zilla::Plugin::Test::Version 1.05 use Test::Version; my @imports = qw( version_all_ok ); my $params = { is_strict => 0, has_version => 1, multiple => 0, }; push @imports, $params if version->parse( $Test::Version::VERSION ) >= version->parse('1.002'); Test::Version->import(@imports); version_all_ok; done_testing; Path-Iterator-Rule-1.009/t/00-report-prereqs.dd000644 000765 000024 00000006205 12577662462 021354 0ustar00davidstaff000000 000000 do { my $x = { 'configure' => { 'requires' => { 'ExtUtils::MakeMaker' => '6.17', 'perl' => '5.010' } }, 'develop' => { 'requires' => { 'Dist::Zilla' => '5', 'Dist::Zilla::Plugin::AppendExternalData' => '0', 'Dist::Zilla::PluginBundle::DAGOLDEN' => '0.072', 'English' => '0', 'File::Spec' => '0', 'File::Temp' => '0', 'IO::Handle' => '0', 'IPC::Open3' => '0', 'Pod::Wordlist' => '0', 'Software::License::Apache_2_0' => '0', 'Test::CPAN::Meta' => '0', 'Test::More' => '0', 'Test::Pod' => '1.41', 'Test::Spelling' => '0.12', 'Test::Version' => '1', 'blib' => '1.01' } }, 'runtime' => { 'requires' => { 'Carp' => '0', 'File::Basename' => '0', 'File::Spec' => '0', 'List::Util' => '0', 'Number::Compare' => '0.02', 'Scalar::Util' => '0', 'Text::Glob' => '0', 'Try::Tiny' => '0', 'perl' => '5.010', 're' => '0', 'strict' => '0', 'warnings' => '0', 'warnings::register' => '0' } }, 'test' => { 'recommends' => { 'CPAN::Meta' => '2.120900' }, 'requires' => { 'Exporter' => '0', 'ExtUtils::MakeMaker' => '0', 'File::Spec' => '0', 'File::Temp' => '0', 'File::pushd' => '0', 'Path::Tiny' => '0', 'Test::Deep' => '0', 'Test::Filename' => '0.03', 'Test::More' => '0.92', 'lib' => '0', 'perl' => '5.010' } } }; $x; }Path-Iterator-Rule-1.009/t/00-report-prereqs.t000644 000765 000024 00000012731 12577662462 021231 0ustar00davidstaff000000 000000 #!perl use strict; use warnings; # This test was generated by Dist::Zilla::Plugin::Test::ReportPrereqs 0.021 use Test::More tests => 1; use ExtUtils::MakeMaker; use File::Spec; # from $version::LAX my $lax_version_re = qr/(?: undef | (?: (?:[0-9]+) (?: \. | (?:\.[0-9]+) (?:_[0-9]+)? )? | (?:\.[0-9]+) (?:_[0-9]+)? ) | (?: v (?:[0-9]+) (?: (?:\.[0-9]+)+ (?:_[0-9]+)? )? | (?:[0-9]+)? (?:\.[0-9]+){2,} (?:_[0-9]+)? ) )/x; # hide optional CPAN::Meta modules from prereq scanner # and check if they are available my $cpan_meta = "CPAN::Meta"; my $cpan_meta_pre = "CPAN::Meta::Prereqs"; my $HAS_CPAN_META = eval "require $cpan_meta; $cpan_meta->VERSION('2.120900')" && eval "require $cpan_meta_pre"; ## no critic # Verify requirements? my $DO_VERIFY_PREREQS = 1; sub _max { my $max = shift; $max = ( $_ > $max ) ? $_ : $max for @_; return $max; } sub _merge_prereqs { my ($collector, $prereqs) = @_; # CPAN::Meta::Prereqs object if (ref $collector eq $cpan_meta_pre) { return $collector->with_merged_prereqs( CPAN::Meta::Prereqs->new( $prereqs ) ); } # Raw hashrefs for my $phase ( keys %$prereqs ) { for my $type ( keys %{ $prereqs->{$phase} } ) { for my $module ( keys %{ $prereqs->{$phase}{$type} } ) { $collector->{$phase}{$type}{$module} = $prereqs->{$phase}{$type}{$module}; } } } return $collector; } my @include = qw( ); my @exclude = qw( ); # Add static prereqs to the included modules list my $static_prereqs = do 't/00-report-prereqs.dd'; # Merge all prereqs (either with ::Prereqs or a hashref) my $full_prereqs = _merge_prereqs( ( $HAS_CPAN_META ? $cpan_meta_pre->new : {} ), $static_prereqs ); # Add dynamic prereqs to the included modules list (if we can) my ($source) = grep { -f } 'MYMETA.json', 'MYMETA.yml'; if ( $source && $HAS_CPAN_META ) { if ( my $meta = eval { CPAN::Meta->load_file($source) } ) { $full_prereqs = _merge_prereqs($full_prereqs, $meta->prereqs); } } else { $source = 'static metadata'; } my @full_reports; my @dep_errors; my $req_hash = $HAS_CPAN_META ? $full_prereqs->as_string_hash : $full_prereqs; # Add static includes into a fake section for my $mod (@include) { $req_hash->{other}{modules}{$mod} = 0; } for my $phase ( qw(configure build test runtime develop other) ) { next unless $req_hash->{$phase}; next if ($phase eq 'develop' and not $ENV{AUTHOR_TESTING}); for my $type ( qw(requires recommends suggests conflicts modules) ) { next unless $req_hash->{$phase}{$type}; my $title = ucfirst($phase).' '.ucfirst($type); my @reports = [qw/Module Want Have/]; for my $mod ( sort keys %{ $req_hash->{$phase}{$type} } ) { next if $mod eq 'perl'; next if grep { $_ eq $mod } @exclude; my $file = $mod; $file =~ s{::}{/}g; $file .= ".pm"; my ($prefix) = grep { -e File::Spec->catfile($_, $file) } @INC; my $want = $req_hash->{$phase}{$type}{$mod}; $want = "undef" unless defined $want; $want = "any" if !$want && $want == 0; my $req_string = $want eq 'any' ? 'any version required' : "version '$want' required"; if ($prefix) { my $have = MM->parse_version( File::Spec->catfile($prefix, $file) ); $have = "undef" unless defined $have; push @reports, [$mod, $want, $have]; if ( $DO_VERIFY_PREREQS && $HAS_CPAN_META && $type eq 'requires' ) { if ( $have !~ /\A$lax_version_re\z/ ) { push @dep_errors, "$mod version '$have' cannot be parsed ($req_string)"; } elsif ( ! $full_prereqs->requirements_for( $phase, $type )->accepts_module( $mod => $have ) ) { push @dep_errors, "$mod version '$have' is not in required range '$want'"; } } } else { push @reports, [$mod, $want, "missing"]; if ( $DO_VERIFY_PREREQS && $type eq 'requires' ) { push @dep_errors, "$mod is not installed ($req_string)"; } } } if ( @reports ) { push @full_reports, "=== $title ===\n\n"; my $ml = _max( map { length $_->[0] } @reports ); my $wl = _max( map { length $_->[1] } @reports ); my $hl = _max( map { length $_->[2] } @reports ); if ($type eq 'modules') { splice @reports, 1, 0, ["-" x $ml, "", "-" x $hl]; push @full_reports, map { sprintf(" %*s %*s\n", -$ml, $_->[0], $hl, $_->[2]) } @reports; } else { splice @reports, 1, 0, ["-" x $ml, "-" x $wl, "-" x $hl]; push @full_reports, map { sprintf(" %*s %*s %*s\n", -$ml, $_->[0], $wl, $_->[1], $hl, $_->[2]) } @reports; } push @full_reports, "\n"; } } } if ( @full_reports ) { diag "\nVersions for all modules listed in $source (including optional ones):\n\n", @full_reports; } if ( @dep_errors ) { diag join("\n", "\n*** WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING ***\n", "The following REQUIRED prerequisites were not satisfied:\n", @dep_errors, "\n" ); } pass; # vim: ts=4 sts=4 sw=4 et: Path-Iterator-Rule-1.009/t/basic.t000644 000765 000024 00000004103 12577662462 017075 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; require_ok('Path::Iterator::Rule'); #--------------------------------------------------------------------------# { my $td = make_tree( qw( atroot.txt empty/ data/file1.txt more/file2.txt ) ); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new; # or via object $rule = $rule->new->file; $iter = $rule->iter($td); @files = (); while ( my $f = $iter->() ) { push @files, $f; } is( scalar @files, 3, "Iterator files" ) or diag explain \@files; is( ref $files[0], '', "Iterator returns string, not object" ); @files = (); @files = $rule->all($td); my $count = $rule->all($td); is( scalar @files, 3, "All files" ) or diag explain \@files; is( $count, 3, "All files (scalar context)" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->dir; @files = (); @files = map { "$_" } $rule->all($td); is( scalar @files, 4, "All files and dirs" ) or diag explain \@files; my $wd = pushd($td); @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 4, "All files and dirs w/ cwd" ) or diag explain \@files; $rule->skip_dirs(qw/data/); @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 3, "All w/ prune dir" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->skip_dirs(qr/./)->file; @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 0, "All w/ prune top directory" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->skip_subdirs(qr/./)->file; @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 1, "All w/ prune subdirs" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/breadth-depth-files.t000644 000765 000024 00000002452 12577662462 021634 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @depth_pre = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @depth_post = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my $td = make_tree(@tree); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new->file; @files = map { unixify( $_, $td ) } $rule->all( { depthfirst => -1 }, $td ); cmp_deeply( \@files, \@depth_pre, "Depth first iteration (pre)" ) or diag explain \@files; @files = map { unixify( $_, $td ) } $rule->all( { depthfirst => 1 }, $td ); cmp_deeply( \@files, \@depth_post, "Depth first iteration (post)" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/breadth-depth.t000644 000765 000024 00000003265 12577662462 020537 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @breadth = qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt cccc/eeee cccc/eeee/ffff.txt ); my @depth_pre = qw( . aaaa.txt bbbb.txt cccc cccc/dddd.txt cccc/eeee cccc/eeee/ffff.txt gggg.txt ); my @depth_post = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt cccc/eeee cccc gggg.txt . ); my $td = make_tree(@tree); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new; @files = map { unixify( $_, $td ) } $rule->all( { depthfirst => 0 }, $td ); cmp_deeply( \@files, \@breadth, "Breadth first iteration" ) or diag explain \@files; @files = map { unixify( $_, $td ) } $rule->all( { depthfirst => -1 }, $td ); cmp_deeply( \@files, \@depth_pre, "Depth first iteration (pre)" ) or diag explain \@files; @files = map { unixify( $_, $td ) } $rule->all( { depthfirst => 1 }, $td ); cmp_deeply( \@files, \@depth_post, "Depth first iteration (post)" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/clone.t000644 000765 000024 00000002225 12577662462 017117 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( aaaa.txt bbbb.txt aaaabbbb.txt ); my $td = make_tree(@tree); sub test { my ( $name, $rule, $expected ) = @_; my @got = sort map { unixify( $_, $td ) } $rule->all($td); local $Test::Builder::Level = $Test::Builder::Level + 1; cmp_deeply( \@got, $expected, $name ) or diag explain { got => \@got, expected => $expected }; } # end test { my $ruleA = Path::Iterator::Rule->new->file; my $ruleB = $ruleA->new->name("*bb*"); $ruleA->name("*aa*"); test( 'new *aa*', $ruleA => [qw/aaaa.txt aaaabbbb.txt/] ); test( 'new *bb*', $ruleB => [qw/aaaabbbb.txt bbbb.txt/] ); } { my $ruleA = Path::Iterator::Rule->new->file; my $ruleB = $ruleA->clone->name("*bb*"); $ruleA->name("*aa*"); test( 'cloned *aa*', $ruleA => [qw/aaaa.txt aaaabbbb.txt/] ); test( 'cloned *bb*', $ruleB => [qw/aaaabbbb.txt bbbb.txt/] ); } done_testing; Path-Iterator-Rule-1.009/t/content.t000644 000765 000024 00000004405 12577662462 017473 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Test::Filename 0.03; use Path::Tiny; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my ( $rule, @files ); my $td = make_tree(qw(file1.txt)); path( $td, 'file2.txt' )->spew( map "$_\n", qw( foo bar baz ) ); path( $td, 'file3.txt' )->spew(qw( foo bar baz )); path( $td, 'file4.txt' )->spew_utf8("\x{2603}"); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->line_match(qr{foo.*baz}s)->all($td) ], ['file3.txt'], ); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->not_line_match( ":encoding(iso-8859-1)", qr{foo.*baz}s )->all($td) ], [qw/file1.txt file2.txt file4.txt/], ); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->contents_match(qr{foo.*baz}s)->all($td) ], [qw/file2.txt file3.txt/], ); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->not_contents_match(qr{foo.*baz}s)->all($td) ], [qw/file1.txt file4.txt/], ); # encoding stuff is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->contents_match(qr{\x{2603}}s)->all($td) ], ['file4.txt'] ); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->contents_match( ":encoding(iso-8859-1)", qr{\x{2603}}s )->all($td) ], [] ); is_deeply( [ map { unixify( $_, $td ) } Path::Iterator::Rule->new->file->contents_match( ":encoding(iso-8859-1)", qr{\x{E2}\x{98}\x{83}}s )->all($td) ], ['file4.txt'] ); } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # # vim: ts=4 sts=4 sw=4 et: Path-Iterator-Rule-1.009/t/error_handler.t000644 000765 000024 00000002232 12577662462 020643 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( aaaa.txt bbbb.txt ); my $td = make_tree(@tree); { my $rule = Path::Iterator::Rule->new->and( sub { die "Evil here" } ); eval { $rule->all($td) }; like( $@, qr/^\Q$td\E: Evil here/, "default error handler dies" ); } { my @msg; my $handler = sub { push @msg, [@_]; }; my $rule = Path::Iterator::Rule->new->and( sub { die "Evil here" } ); eval { $rule->all( $td, { error_handler => $handler } ) }; is( $@, '', "error handler catches fatalities" ); is( scalar @msg, 3, "saw correct number of errors" ); my ( $file, $text ) = @{ $msg[0] }; is( $file, $td, "object has file path of error" ); like( $text, qr/^Evil here/, "handler gets message" ); } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/fast.t000644 000765 000024 00000002202 12577662462 016747 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt gggg.txt cccc.txt dddd.txt bbbb.txt eeee.txt ); my $td = make_tree(@tree); opendir( my $dh, "$td" ); my @expected = ( grep { $_ ne "." && $_ ne ".." } readdir $dh ); closedir $dh; my ( $iter, @files ); my $rule = Path::Iterator::Rule->new->file; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, [ sort @expected ], "all() gives sorted order" ) or diag explain \@files; @files = map { unixify( $_, $td ) } $rule->all_fast($td); cmp_deeply( \@files, \@expected, "all_fast() gives disk order" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/helpers.t000644 000765 000024 00000002303 12577662462 017456 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Test::Filename 0.03; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Tiny; use Path::Iterator::Rule; #--------------------------------------------------------------------------# Path::Iterator::Rule->add_helper( txt => sub { return sub { return /\.txt$/ } } ); can_ok( 'Path::Iterator::Rule', 'txt' ); # check we can do this via object, too my $rule = Path::Iterator::Rule->new; eval { $rule->add_helper( txt => sub { 1 } ); }; like( $@, qr/Can't add rule 'txt'/, "exception if helper exists" ); { my $td = make_tree( qw( atroot empty/ data/file1.txt ) ); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new->file->txt; @files = $rule->all( $td, { relative => 1 } ); is( scalar @files, 1, "All: one file" ) or diag explain \@files; filename_is( $files[0], "data/file1.txt", "got expected file" ) } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/lib/000755 000765 000024 00000000000 12577662462 016377 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/t/logic.t000644 000765 000024 00000010337 12577662462 017117 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use PIR; #--------------------------------------------------------------------------# my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my $td = make_tree(@tree); { my $rule = PIR->new; eval { $rule->and( bless {}, "Dummy" ) }; like( $@, qr/rules must be/i, "catch invalid rules" ); } { my $rule = PIR->new->and( sub { return "0 but true" } ); eval { $rule->all($td) }; like( $@, qr/0 but true/i, "catch 0 but true" ); } { my @files; my $rule = PIR->new->file->not_name("gggg.txt"); my $expected = [ qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "not() test" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new->file; $rule->or( $rule->new->name("gggg.txt"), $rule->new->name("bbbb.txt"), ); my $expected = [qw/bbbb.txt gggg.txt/]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "or() test" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->skip( $rule->new->name("gggg.txt"), $rule->new->name("cccc"), ); $rule->file; my $expected = [ qw( aaaa.txt bbbb.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "skip() test" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->skip( sub { return \1 if /eeee$/ } ); my $expected = [ qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "skip() with custom rule" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->skip( sub { return \0 if /eeee$/ } ); my $expected = [ qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "skip() with crazy custom rule" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->skip( PIR->new->skip_dirs("eeee")->name("gggg*") ); my $expected = [ qw( . aaaa.txt bbbb.txt cccc cccc/dddd.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "skip() with skip" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->and( PIR->new->not( PIR->new->or( PIR->new->name("lldskfkad"), sub { return \1 if /eeee$/ }, ) ) ); my $expected = [ qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "nested not and or with references" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = PIR->new; $rule->and( PIR->new->or( sub { return \0 if /eeee/; return 0 }, sub { return 1 }, ), PIR->new->and( sub { /eeee/ } ), ); my $expected = [ qw( cccc/eeee ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "nested and + or with prunning" ) or diag explain { got => \@files, expected => $expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/min-max-depth.t000644 000765 000024 00000003436 12577662462 020474 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt hhhh/iiii/jjjj/kkkk/llll/mmmm.txt ); my $td = make_tree(@tree); { my @files; my $rule = Path::Iterator::Rule->new->file->min_depth(3); my $expected = [ qw( cccc/eeee/ffff.txt hhhh/iiii/jjjj/kkkk/llll/mmmm.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "min_depth(3) test" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = Path::Iterator::Rule->new->max_depth(2)->file; my $expected = [ qw( aaaa.txt bbbb.txt gggg.txt cccc/dddd.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "max_depth(2) test" ) or diag explain { got => \@files, expected => $expected }; } { my @files; my $rule = Path::Iterator::Rule->new->file->min_depth(2)->max_depth(3); my $expected = [ qw( cccc/dddd.txt cccc/eeee/ffff.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "min_depth(2)->max_depth(3) test" ) or diag explain { got => \@files, expected => $expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/names.t000644 000765 000024 00000007036 12577662462 017127 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( lib/Foo.pm lib/Foo.pod t/test.t ); my $td = make_tree(@tree); { my $rule = Path::Iterator::Rule->new->name('Foo'); my $expected = []; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name('Foo') empty match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->name('Foo.*'); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name('Foo.*') match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->name(qr/Foo/); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name(qr/Foo/) match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->name(qr/foo/i); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name(qr/Foo/) match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->name(qr/ foo /ix); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name(qr/Foo/) match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->name( "*.pod", "*.pm" ); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "name('*.pod', '*.pm') match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->iname(qr/foo/); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "iname(qr/foo/) match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->iname(qr/ foo /x); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "iname(qr/foo/) match" ) or diag explain { got => \@files, expected => $expected }; } { my $rule = Path::Iterator::Rule->new->iname('foo.*'); my $expected = [ qw( lib/Foo.pm lib/Foo.pod ) ]; my @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "iname('foo.*') match" ) or diag explain { got => \@files, expected => $expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/perl.t000644 000765 000024 00000002331 12577662462 016757 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Path::Tiny; use File::Temp; use Test::Deep qw/cmp_deeply/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( lib/Foo.pm lib/Foo.pod t/test.t ); my @bin = qw( bin/foo.pl bin/foo bin/bar ); my $td = make_tree( @tree, @bin ); for my $f ( map { path( $td, $_ ) } @bin ) { next if $f =~ /foo\.pl/; my $fh = $f->openw; print {$fh} ( $f =~ 'bin/bar' ? "#!/usr/bin/env perl\n" : "#!/usr/bin/perl\n" ); $fh->close; } { my @files; my $rule = Path::Iterator::Rule->new->perl_file; my $expected = [ qw( bin/bar bin/foo bin/foo.pl lib/Foo.pm lib/Foo.pod t/test.t ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "all perl files" ) or diag explain { got => \@files, expected => $expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/pir.t000644 000765 000024 00000002677 12577662462 016624 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use PIR; #--------------------------------------------------------------------------# { my $td = make_tree( qw( empty/ data/file1.txt ) ); my ( $iter, @files ); my $rule = PIR->new->file; $iter = $rule->iter($td); @files = (); while ( my $f = $iter->() ) { push @files, $f; } is( scalar @files, 1, "Iterator: one file" ) or diag explain \@files; is( ref $files[0], '', "Iterator: returns string, not object" ); @files = (); @files = $rule->all($td); is( scalar @files, 1, "All: one file" ) or diag explain \@files; $rule = PIR->new->dir; @files = (); @files = map { "$_" } $rule->all($td); is( scalar @files, 3, "All: 3 directories" ) or diag explain \@files; my $wd = pushd($td); @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 3, "All w/ cwd: 3 directories" ) or diag explain \@files; $rule->skip_dirs(qw/data/); @files = (); @files = map { "$_" } $rule->all(); is( scalar @files, 2, "All w/ prune: 2 directories" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/relative.t000644 000765 000024 00000002646 12577662462 017641 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Path::Tiny; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @depth_pre = qw( . aaaa.txt bbbb.txt cccc cccc/dddd.txt cccc/eeee cccc/eeee/ffff.txt gggg.txt ); my @depth_post = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt cccc/eeee cccc gggg.txt . ); my $td = make_tree(@tree); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new; @files = map { path($_)->stringify } $rule->all( { depthfirst => -1, relative => 1 }, $td ); cmp_deeply( \@files, \@depth_pre, "Depth first iteration (pre)" ) or diag explain \@files; @files = map { path($_)->stringify } $rule->all( { depthfirst => 1, relative => 1 }, $td ); cmp_deeply( \@files, \@depth_post, "Depth first iteration (post)" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/stat_tests.t000644 000765 000024 00000002012 12577662462 020206 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Test::Filename 0.03; use Path::Tiny; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my ( $rule, @files ); my $td = make_tree( qw( data/file1.txt ) ); my $changes = path( $td, 'data', 'Changes' ); path('Changes')->copy($changes); $rule = Path::Iterator::Rule->new->file; @files = (); @files = $rule->all($td); is( scalar @files, 2, "Any file" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->file->size(">0k"); @files = (); @files = $rule->all($td); filename_is( $files[0], $changes, "size > 0" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/stringify.t000644 000765 000024 00000002224 12577662462 020034 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use PIRTiny; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @breadth = qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt cccc/eeee cccc/eeee/ffff.txt ); my $td = make_tree(@tree); my ( $iter, @files ); my $rule = PIRTiny->new; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@breadth, "Object-based subclass (all)" ) or diag explain \@files; @files = map { unixify( $_, $td ) } $rule->all_fast($td); cmp_deeply( [ sort @files ], [ sort @breadth ], "Object-based subclass (all_fast)" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/symlink.t000644 000765 000024 00000007611 12577662462 017511 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Path::Tiny; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use Config; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# plan skip_all => "No symlink support" unless $Config{d_symlink}; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @follow = qw( . aaaa.txt bbbb.txt cccc gggg.txt pppp qqqq.txt cccc/dddd.txt cccc/eeee pppp/ffff.txt ); my @not_loop_safe = qw( . aaaa.txt bbbb.txt cccc gggg.txt pppp qqqq.txt cccc/dddd.txt cccc/eeee pppp/ffff.txt cccc/eeee/ffff.txt ); my @nofollow = qw( . aaaa.txt bbbb.txt cccc gggg.txt cccc/dddd.txt cccc/eeee cccc/eeee/ffff.txt ); my $td = make_tree(@tree); symlink path( $td, 'cccc', 'eeee' ), path( $td, 'pppp' ); symlink path( $td, 'aaaa.txt' ), path( $td, 'qqqq.txt' ); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@follow, "Follow symlinks" ) or diag explain { got => \@files, expected => \@follow }; @files = map { unixify( $_, $td ) } $rule->all( $td, { loop_safe => 0 } ); cmp_deeply( \@files, \@not_loop_safe, "Follow symlinks, but loop_safe = 0" ) or diag explain { got => \@files, expected => \@not_loop_safe }; @files = map { unixify( $_, $td ) } $rule->all( { follow_symlinks => 0 }, $td ); cmp_deeply( \@files, \@nofollow, "Don't follow symlinks" ) or diag explain { got => \@files, expected => \@nofollow }; } { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt ); my $td = make_tree(@tree); symlink path( $td, 'zzzz' ), path( $td, 'pppp' ); # dangling symlink symlink path( $td, 'cccc', 'dddd.txt' ), path( $td, 'qqqq.txt' ); # regular symlink my @dangling = qw( pppp ); my @not_dangling = qw( . aaaa.txt bbbb.txt cccc qqqq.txt cccc/dddd.txt ); my @valid_symlinks = qw( qqqq.txt ); my ( $rule, @files ); $rule = Path::Iterator::Rule->new->dangling; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@dangling, "Dangling symlinks" ) or diag explain { got => \@files, expected => \@dangling }; $rule = Path::Iterator::Rule->new->not_dangling; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@not_dangling, "No dangling symlinks" ) or diag explain { got => \@files, expected => \@not_dangling }; $rule = Path::Iterator::Rule->new->symlink->not_dangling; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@valid_symlinks, "Only non-dangling symlinks" ) or diag explain { got => \@files, expected => \@valid_symlinks }; } { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt ); my $td = make_tree(@tree); symlink path( $td, 'cccc' ), path( $td, 'cccc', 'eeee' ); # symlink loop my @expected = qw( . aaaa.txt bbbb.txt cccc cccc/dddd.txt cccc/eeee ); my ( $rule, @files ); $rule = Path::Iterator::Rule->new; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, \@expected, "Symlink loop" ) or diag explain { got => \@files, expected => \@expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/unsorted.t000644 000765 000024 00000001753 12577662462 017667 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt gggg.txt cccc.txt dddd.txt bbbb.txt eeee.txt ); my $td = make_tree(@tree); opendir( my $dh, "$td" ); my @expected = ( grep { $_ ne "." && $_ ne ".." } readdir $dh ); closedir $dh; my ( $iter, @files ); my $rule = Path::Iterator::Rule->new->file; @files = map { unixify( $_, $td ) } $rule->all( { sorted => 0 }, $td ); cmp_deeply( \@files, \@expected, "unsorted gives disk order" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/vcs.t000644 000765 000024 00000002041 12577662462 016606 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# my @tree = qw( aaaa.txt bbbb.txt cccc/.svn/foo cccc/.bzr/foo cccc/.git/foo cccc/.hg/foo cccc/_darcs/foo cccc/CVS/foo cccc/RCS/foo ); push @tree, 'eeee/foo,v', 'dddd/foo.#'; # avoids warning about stuff in qw my $td = make_tree(@tree); { my @files; my $rule = Path::Iterator::Rule->new->skip_vcs->file; my $expected = [ qw( aaaa.txt bbbb.txt ) ]; @files = map { unixify( $_, $td ) } $rule->all($td); cmp_deeply( \@files, $expected, "not_vcs test" ) or diag explain { got => \@files, expected => $expected }; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/visitor.t000644 000765 000024 00000002541 12577662462 017517 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use File::Temp; use Test::Deep qw/cmp_deeply/; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my @tree = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @depth_pre = qw( aaaa.txt bbbb.txt cccc/dddd.txt cccc/eeee/ffff.txt gggg.txt ); my @breadth = qw( aaaa.txt bbbb.txt gggg.txt cccc/dddd.txt cccc/eeee/ffff.txt ); my $td = make_tree(@tree); my ( $iter, @files ); my $rule = Path::Iterator::Rule->new->file; $rule->all( $td, { visitor => sub { push @files, unixify( $_, $td ) }, depthfirst => -1 } ); cmp_deeply( \@files, \@depth_pre, "Visitor (depth)" ) or diag explain \@files; @files = (); $rule->all( $td, { visitor => sub { push @files, unixify( $_, $td ) } } ); cmp_deeply( \@files, \@breadth, "Visitor (breadth)" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/x_tests.t000644 000765 000024 00000002225 12577662462 017510 0ustar00davidstaff000000 000000 use 5.006; use strict; use warnings; use Test::More 0.92; use Path::Tiny; use File::Temp; use File::pushd qw/pushd/; use lib 't/lib'; use PCNTest; use Path::Iterator::Rule; #--------------------------------------------------------------------------# { my ( $rule, @files ); my $td = make_tree( qw( data/file1.txt ) ); my $file = path( $td, 'data', 'file1.txt' ); # chmod a-rwx chmod 0777, $file; $rule = Path::Iterator::Rule->new->file; @files = (); @files = $rule->all($td); is( scalar @files, 1, "Any file" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->file->readable; @files = (); @files = $rule->all($td); is( scalar @files, 1, "readable" ) or diag explain \@files; $rule = Path::Iterator::Rule->new->file->not_readable; @files = (); @files = $rule->all($td); is( scalar @files, 0, "not_readable" ) or diag explain \@files; } done_testing; # # This file is part of Path-Iterator-Rule # # This software is Copyright (c) 2013 by David Golden. # # This is free software, licensed under: # # The Apache License, Version 2.0, January 2004 # Path-Iterator-Rule-1.009/t/lib/PCNTest.pm000644 000765 000024 00000001053 12577662462 020214 0ustar00davidstaff000000 000000 use strict; use warnings; package PCNTest; use Path::Tiny; use File::Temp; use Exporter; our @ISA = qw/Exporter/; our @EXPORT = qw/make_tree unixify/; sub make_tree { my $td = File::Temp->newdir; for (@_) { if (/\/$/) { path( $td, $_ )->mkpath; } else { my $item = path( $td, $_ ); $item->parent->mkpath; $item->touch; } } return $td; } sub unixify { my ( $arg, $td ) = @_; my $pc = path($arg); return $pc->relative($td)->stringify; } 1; Path-Iterator-Rule-1.009/t/lib/PIRTiny.pm000644 000765 000024 00000001042 12577662462 020230 0ustar00davidstaff000000 000000 use strict; use warnings; package PIRTiny; # ABSTRACT: PIR with Path::Tiny # Dependencies use Path::Iterator::Rule; our @ISA = qw/Path::Iterator::Rule/; use Path::Tiny (); sub _objectify { my ( $self, $path ) = @_; return Path::Tiny::path($path); } sub _children { my $self = shift; my $path = shift; return map { [ $_->basename, $_ ] } $path->children; } sub _defaults { return ( $_[0]->SUPER::_defaults, _stringify => 0, ); } sub _fast_defaults { return ( $_[0]->SUPER::_fast_defaults, _stringify => 0, ); } Path-Iterator-Rule-1.009/lib/Path/000755 000765 000024 00000000000 12577662462 017030 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/lib/PIR.pm000644 000765 000024 00000060476 12577662462 017141 0ustar00davidstaff000000 000000 use 5.010; # re::regexp_pattern use strict; use warnings; package PIR; # ABSTRACT: Short alias for Path::Iterator::Rule our $VERSION = '1.009'; # Dependencies use Path::Iterator::Rule; our @ISA = qw/Path::Iterator::Rule/; 1; # vim: ts=4 sts=4 sw=4 et: __END__ =pod =encoding UTF-8 =head1 NAME PIR - Short alias for Path::Iterator::Rule =head1 VERSION version 1.009 =head1 SYNOPSIS use PIR; my $rule = PIR->new; # match anything $rule->file->size(">10k"); # add/chain rules # iterator interface my $next = $rule->iter( @dirs ); while ( defined( my $file = $next->() ) ) { ... } # list interface for my $file ( $rule->all( @dirs ) ) { ... } =head1 DESCRIPTION This is an empty subclass of L. It saves you from having to type the full name repeatedly, which is particularly handy for one-liners: $ perl -MPIR -wE 'say for PIR->new->skip_dirs(".")->perl_module->all(@INC)' =head1 USAGE =head2 Constructors =head3 C my $rule = Path::Iterator::Rule->new; Creates a new rule object that matches any file or directory. It takes no arguments. For convenience, it may also be called on an object, in which case it still returns a new object that matches any file or directory. =head3 C my $common = Path::Iterator::Rule->new->file->not_empty; my $big_files = $common->clone->size(">1M"); my $small_files = $common->clone->size("<10K"); Creates a copy of a rule object. Useful for customizing different rule objects against a common base. =head2 Matching and iteration =head3 C my $next = $rule->iter( @dirs, \%options); while ( defined( my $file = $next->() ) ) { ... } Creates a subroutine reference iterator that returns a single result when dereferenced. This iterator is "lazy" -- results are not pre-computed. It takes as arguments a list of directories to search and an optional hash reference of control options. If no search directories are provided, the current directory is used (C<".">). Valid options include: =over 4 =item * C -- Controls order of results. Valid values are "1" (post-order, depth-first search), "0" (breadth-first search) or "-1" (pre-order, depth-first search). Default is 0. =item * C -- Catches errors during execution of rule tests. Default handler dies with the filename and error. If set to undef, error handling is disabled. =item * C -- Follow directory symlinks when true. Default is 1. =item * C -- Prevents visiting the same directory more than once when true. Default is 1. =item * C -- Return matching items relative to the search directory. Default is 0. =item * C -- Whether entries in a directory are sorted before processing. Default is 1. =item * C -- An optional coderef that will be called on items matching all rules. =back Filesystem loops might exist from either hard or soft links. The C option prevents infinite loops, but adds some overhead by making C calls. Because directories are visited only once when C is true, matches could come from a symlinked directory before the real directory depending on the search order. To get only the real files, turn off C. Turning C off and leaving C on avoids C calls and will be fastest, but with the risk of an infinite loop and repeated files. The default is slow, but safe. The C parameter must be a subroutine reference. It will be called when a rule test throws an exception. The first argument will be the file name being inspected and the second argument will be the exception. The optional C parameter must be a subroutine reference. If set, it will be called for any result that matches. It is called the same way a custom rule would be (see L) but its return value is ignored. It is called when an item is first inspected -- "postorder" is not respected. The paths inspected and returned will be relative to the search directories provided. If these are absolute, then the paths returned will have absolute paths. If these are relative, then the paths returned will have relative paths. If the search directories are absolute and the C option is true, files returned will be relative to the search directory. Note that if the search directories are not mutually exclusive (whether containing subdirectories like C<@INC> or symbolic links), files found could be returned relative to different initial search directories based on C, C or C. When the iterator is exhausted, it will return undef. =head3 C This works just like C, except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See L for details. =head3 C my @matches = $rule->all( @dir, \%options ); Returns a list of paths that match the rule. It takes the same arguments and has the same behaviors as the C method. The C method uses C internally to fetch all results. In scalar context, it will return the count of matched paths. In void context, it is optimized to iterate over everything, but not store results. This is most useful with the C option: $rule->all( $path, { visitor => \&callback } ); =head3 C This works just like C, except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See L for details. =head3 C if ( $rule->test( $path, $basename, $stash ) ) { ... } Test a file path against a rule. Used internally, but provided should someone want to create their own, custom iteration algorithm. =head2 Logic operations C provides three logic operations for adding rules to the object. Rules may be either a subroutine reference with specific semantics (described below in L) or another C object. =head3 C $rule->and( sub { -r -w -x $_ } ); # stacked filetest example $rule->and( @more_rules ); Adds one or more constraints to the current rule. E.g. "old rule AND new1 AND new2 AND ...". Returns the object to allow method chaining. =head3 C $rule->or( $rule->new->name("foo*"), $rule->new->name("bar*"), sub { -r -w -x $_ }, ); Takes one or more alternatives and adds them as a constraint to the current rule. E.g. "old rule AND ( new1 OR new2 OR ... )". Returns the object to allow method chaining. =head3 C $rule->not( sub { -r -w -x $_ } ); Takes one or more alternatives and adds them as a negative constraint to the current rule. E.g. "old rule AND NOT ( new1 AND new2 AND ...)". Returns the object to allow method chaining. =head3 C $rule->skip( $rule->new->dir->not_writeable, $rule->new->dir->name("foo"), ); Takes one or more alternatives and will prune a directory if any of the criteria match or if any of the rules already indicate the directory should be pruned. Pruning means the directory will not be returned by the iterator and will not be searched. For files, it is equivalent to C<< $rule->not($rule->or(@rules)) >>. Returns the object to allow method chaining. This method should be called as early as possible in the rule chain. See L below for further explanation and an example. =for Pod::Coverage method_names_here =head1 RULE METHODS Rule methods are helpers that add constraints. Internally, they generate a closure to accomplish the desired logic and add it to the rule object with the C method. Rule methods return the object to allow for method chaining. =head2 File name rules =head3 C $rule->name( "foo.txt" ); $rule->name( qr/foo/, "bar.*"); The C method takes one or more patterns and creates a rule that is true if any of the patterns match the B of the file or directory path. Patterns may be regular expressions or glob expressions (or literal names). =head3 C $rule->iname( "foo.txt" ); $rule->iname( qr/foo/, "bar.*"); The C method is just like the C method, but matches case-insensitively. =head3 C $rule->skip_dirs( @patterns ); The C method skips directories that match one or more patterns. Patterns may be regular expressions or globs (just like C). Directories that match will not be returned from the iterator and will be excluded from further search. B If that isn't what you want, see L instead. B this rule should be specified early so that it has a chance to operate before a logical shortcut. E.g. $rule->skip_dirs(".git")->file; # OK $rule->file->skip_dirs(".git"); # Won't work In the latter case, when a ".git" directory is seen, the C rule shortcuts the rule before the C rule has a chance to act. =head3 C $rule->skip_subdirs( @patterns ); This works just like C, except that the starting directories (depth 0) are not skipped and may be returned from the iterator unless excluded by other rules. =head2 File test rules Most of the C<-X> style filetest are available as boolean rules. The table below maps the filetest to its corresponding method name. Test | Method Test | Method ------|------------- ------|---------------- -r | readable -R | r_readable -w | writeable -W | r_writeable -w | writable -W | r_writable -x | executable -X | r_executable -o | owned -O | r_owned | | -e | exists -f | file -z | empty -d | directory, dir -s | nonempty -l | symlink | -p | fifo -u | setuid -S | socket -g | setgid -b | block -k | sticky -c | character | -t | tty -T | ascii -B | binary For example: $rule->file->nonempty; # -f -s $file The -X operators for timestamps take a single argument in a form that L can interpret. Test | Method ------|------------- -A | accessed -M | modified -C | changed For example: $rule->modified(">1"); # -M $file > 1 =head2 Stat test rules All of the C elements have a method that takes a single argument in a form understood by L. stat() | Method -------------------- 0 | dev 1 | ino 2 | mode 3 | nlink 4 | uid 5 | gid 6 | rdev 7 | size 8 | atime 9 | mtime 10 | ctime 11 | blksize 12 | blocks For example: $rule->size(">10K") =head2 Depth rules $rule->min_depth(3); $rule->max_depth(5); The C and C rule methods take a single argument and limit the paths returned to a minimum or maximum depth (respectively) from the starting search directory. A depth of 0 means the starting directory itself. A depth of 1 means its children. (This is similar to the Unix C utility.) =head2 Perl file rules # All perl rules $rule->perl_file; # Individual perl file rules $rule->perl_module; # .pm files $rule->perl_pod; # .pod files $rule->perl_test; # .t files $rule->perl_installer; # Makefile.PL or Build.PL $rule->perl_script; # .pl or 'perl' in the shebang These rule methods match file names (or a shebang line) that are typical of Perl distribution files. =head2 Version control file rules # Skip all known VCS files $rule->skip_vcs; # Skip individual VCS files $rule->skip_cvs; $rule->skip_rcs; $rule->skip_svn; $rule->skip_git; $rule->skip_bzr; $rule->skip_hg; $rule->skip_darcs; Skips files and/or prunes directories related to a version control system. Just like C, these rules should be specified early to get the correct behavior. =head2 File content rules =head3 C $rule->contents_match(qr/BEGIN .* END/xs); The C rule takes a list of regular expressions and returns files that match one of the expressions. The expressions are applied to the file's contents as a single string. For large files, this is likely to take significant time and memory. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument: $rule->contents_match(":encoding(iso-8859-1)", qr/BEGIN .* END/xs); See L for further details. =head3 C $rule->line_match(qr/^new/i, qr/^Addition/); The C rule takes a list of regular expressions and returns files with at least one line that matches one of the expressions. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument. =head3 C $rule->shebang(qr/#!.*\bperl\b/); The C rule takes a list of regular expressions or glob patterns and checks them against the first line of a file. =head2 Other rules =head3 C $rule->symlink->dangling; $rule->not_dangling; The C rule method matches dangling symlinks. Use it or its inverse to control how dangling symlinks should be treated. =head2 Negated rules Most rule methods have a negated form preceded by "not_". $rule->not_name("foo.*") Because this happens automatically, it includes somewhat silly ones like C (which is thus a less efficient way of saying C). Rules that skip directories or version control files do not have a negated version. =head1 EXTENDING =head2 Custom rule subroutines Rules are implemented as (usually anonymous) subroutine callbacks that return a value indicating whether or not the rule matches. These callbacks are called with three arguments. The first argument is a path, which is also locally aliased as the C<$_> global variable for convenience in simple tests. $rule->and( sub { -r -w -x $_ } ); # tests $_ The second argument is the basename of the path, which is useful for certain types of name checks: $rule->and( sub { $_[1] =~ /foo|bar/ } ); "foo" or "bar" in basename; The third argument is a hash reference that can be used to maintain state. Keys beginning with an underscore are B for C to provide additional data about the search in progress. For example, the C<_depth> key is used to support minimum and maximum depth checks. The custom rule subroutine must return one of four values: =over 4 =item * A true value -- indicates the constraint is satisfied =item * A false value -- indicates the constraint is not satisfied =item * C<\1> -- indicate the constraint is satisfied, and prune if it's a directory =item * C<\0> -- indicate the constraint is not satisfied, and prune if it's a directory =back A reference is a special flag that signals that a directory should not be searched recursively, regardless of whether the directory should be returned by the iterator or not. The legacy "0 but true" value used previously for pruning is no longer valid and will throw an exception if it is detected. Here is an example. This is equivalent to the "max_depth" rule method with a depth of 3: $rule->and( sub { my ($path, $basename, $stash) = @_; return 1 if $stash->{_depth} < 3; return \1 if $stash->{_depth} == 3; return \0; # should never get here } ); Files and directories and directories up to depth 3 will be returned and directories will be searched. Files of depth 3 will be returned. Directories of depth 3 will be returned, but their contents will not be added to the search. Returning a reference is "sticky" -- they will propagate through "and" and "or" logic. 0 && \0 = \0 \0 && 0 = \0 0 || \0 = \0 \0 || 0 = \0 0 && \1 = \0 \0 && 1 = \0 0 || \1 = \1 \0 || 1 = \1 1 && \0 = \0 \1 && 0 = \0 1 || \0 = \1 \1 || 0 = \1 1 && \1 = \1 \1 && 1 = \1 1 || \1 = \1 \1 || 1 = \1 Once a directory is flagged to be pruned, it will be pruned regardless of subsequent rules. $rule->max_depth(3)->name(qr/foo/); This will return files or directories with "foo" in the name, but all directories at depth 3 will be pruned, regardless of whether they match the name rule. Generally, if you want to do directory pruning, you are encouraged to use the L method instead of writing your own logic using C<\0> and C<\1>. =head2 Extension modules and custom rule methods One of the strengths of L is the many CPAN modules that extend it. C provides the C method to provide a similar mechanism for extensions. The C class method takes three arguments, a C for the rule method, a closure-generating callback, and a flag for not generating a negated form of the rule. Unless the flag is true, an inverted "not_*" method is generated automatically. Extension classes should call this as a class method to install new rule methods. For example, this adds a "foo" method that checks if the filename is "foo": package Path::Iterator::Rule::Foo; use Path::Iterator::Rule; Path::Iterator::Rule->add_helper( foo => sub { my @args = @_; # do this to customize closure with arguments return sub { my ($item, $basename) = @_; return if -d "$item"; return $basename =~ /^foo$/; } } ); 1; This allows the following rule methods: $rule->foo; $fule->not_foo; The C method will warn and ignore a helper with the same name as an existing method. =head2 Subclassing Instead of processing and returning strings, this module may be subclassed to operate on objects that represent files. Such objects B stringify to a file path. The following private implementation methods must be overridden: =over 4 =item * _objectify -- given a path, return an object =item * _children -- given a directory, return an (unsorted) list of [ basename, full path ] entries within it, excluding "." and ".." =back Note that C<_children> should return a I of I, where the tuples are array references containing basename and full path. See L source for an example. =head1 LEXICAL WARNINGS If you run with lexical warnings enabled, C will issue warnings in certain circumstances (such as an unreadable directory that must be skipped). To disable these categories, put the following statement at the correct scope: no warnings 'Path::Iterator::Rule'; =head1 PERFORMANCE By default, C iterator options are "slow but safe". They ensure uniqueness, return files in sorted order, and throw nice error messages if something goes wrong. If you want speed over safety, set these options: %options = ( loop_safe => 0, sorted => 0, depthfirst => -1, error_handler => undef ); Alternatively, use the C and C methods instead, which set these options for you. $iter = $rule->iter( @dirs, \%options ); $iter = $rule->iter_fast( @dirs ); # same thing Depending on the file structure being searched, C<< depthfirst => -1 >> may or may not be a good choice. If you have lots of nested directories and all the files at the bottom, a depth first search might do less work or use less memory, particularly if the search will be halted early (e.g. finding the first N matches.) Rules will shortcut on failure, so be sure to put rules likely to fail early in a rule chain. Consider: $r1 = Path::Iterator::Rule->new->name(qr/foo/)->file; $r2 = Path::Iterator::Rule->new->file->name(qr/foo/); If there are lots of files, but only a few containing "foo", then C<$r1> above will be faster. Rules are implemented as code references, so long chains have some overhead. Consider testing with a custom coderef that combines several tests into one. Consider: $r3 = Path::Iterator::Rule->new->and( sub { -x -w -r $_ } ); $r4 = Path::Iterator::Rule->new->executable->writeable->readable; Rule C<$r3> above will be much faster, not only because it stacks the file tests, but because it requires only a single code reference. =head1 CAVEATS Some features are still unimplemented: =over 4 =item * Untainting options =item * Some L helpers (e.g. C) =item * Extension class loading via C =back Filetest operators and stat rules are subject to the usual portability considerations. See L for details. =head1 SEE ALSO There are many other file finding modules out there. They all have various features/deficiencies, depending on your preferences and needs. Here is an (incomplete) list of alternatives, with some comparison commentary. L and L are subclasses of C and operate on L and L objects, respectively. Because of this, they are substantially slower on large directory trees than just using this module directly. L is part of the Perl core. It requires the user to write a callback function to process each node of the search. Callbacks must use global variables to determine the current node. It only supports depth-first search (both pre- and post-order). It supports pre- and post-processing callbacks; the former is required for sorting files to process in a directory. L can be used to help create a callback for L. L is an object-oriented wrapper around L. It provides a number of helper functions and there are many more C modules on CPAN with additional helpers. It provides an iterator interface, but precomputes all the results. L provides iterators for file, directories or "everything". It takes two callbacks, one to match files and one to decide which directories to descend. It does not allow control over breadth/depth order, though it does provide means to sort files for processing within a directory. Like L, it requires callbacks to use global variables. L walks a directory structure with an iterator. It is implemented as L subclasses, which adds a degree of extra complexity. It takes a single callback to define "interesting" paths to return. The callback gets a L or L object for evaluation. L and companion L are like File::Find and File::Find::Rule, but without File::Find inside. They use an iterator that does not precompute results. They can return L objects, which give a subset of the utility of Path::Class objects. L appears to be a literal translation of L, including oddities like making C<-M> into a boolean. L recursively descends a tree, calling a callback on each file. No iterator. Supports exclusion patterns. Depth-first post-order by default, but offers pre-order option. Does not process symlinks. L is based on iterator patterns in Higher Order Perl. It allows a filtering callback. Symlinks are followed automatically without infinite loop protection. No control over order. It offers a "state file" option for resuming interrupted work. L has declarative helper rules, no iterator, is Moose-based and offers no control over ordering or following symlinks. L has no iterator, does matching via callback and offers no control over ordering. L builds up a set of files to operate on from a list of directories to include or exclude, with control over recursion. A callback is applied to each file (or directory) in the set. There is no iterator. There is no control over ordering. Symlinks are not followed. It has several extra features for checksumming the set and creating tarballs with F. =head1 THANKS Thank you to Ricardo Signes (rjbs) for inspiring me to write yet another file finder module, for writing file finder optimization benchmarks, and tirelessly running my code over and over to see if it got faster. =over 4 =item * See L =back =head1 AUTHOR David Golden =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 =cut Path-Iterator-Rule-1.009/lib/Path/Iterator/000755 000765 000024 00000000000 12577662462 020621 5ustar00davidstaff000000 000000 Path-Iterator-Rule-1.009/lib/Path/Iterator/Rule.pm000644 000765 000024 00000140310 12577662462 022065 0ustar00davidstaff000000 000000 use 5.010; # re::regexp_pattern use strict; use warnings; package Path::Iterator::Rule; # ABSTRACT: Iterative, recursive file finder our $VERSION = '1.009'; # Register warnings category use warnings::register; # Dependencies use re 'regexp_pattern'; use Carp (); use File::Basename (); use File::Spec (); use List::Util (); use Number::Compare 0.02; use Scalar::Util (); use Text::Glob (); use Try::Tiny; #--------------------------------------------------------------------------# # constructors and meta methods #--------------------------------------------------------------------------# sub new { my $class = shift; $class = ref $class if ref $class; return bless { rules => [] }, $class; } sub clone { my $self = shift; return bless _my_clone( {%$self} ), ref $self; } # avoid XS/buggy dependencies for a simple recursive clone; we clone # fully instead of just 'rules' in case we get subclassed and they # add attributes sub _my_clone { my $d = shift; if ( ref $d eq 'HASH' ) { return { map { ; my $v = $d->{$_}; $_ => ( ref($v) ? _my_clone($v) : $v ) } keys %$d }; } elsif ( ref $d eq 'ARRAY' ) { return [ map { ref($_) ? _my_clone($_) : $_ } @$d ]; } else { return $d; } } sub add_helper { my ( $class, $name, $coderef, $skip_negation ) = @_; $class = ref $class if ref $class; if ( !$class->can($name) ) { no strict 'refs'; ## no critic *$name = sub { my $self = shift; my $rule = $coderef->(@_); $self->and($rule); }; if ( !$skip_negation ) { *{"not_$name"} = sub { my $self = shift; my $rule = $coderef->(@_); $self->not($rule); }; } } else { Carp::croak("Can't add rule '$name' because it conflicts with an existing method"); } } #--------------------------------------------------------------------------# # Implementation-specific method; these may be overridden by subclasses # to test/return results of file wrappers like Path::Class or IO::All # or to provide custom error handler, visitors or other features #--------------------------------------------------------------------------# sub _objectify { my ( $self, $path ) = @_; return "$path"; } ## We inline this below, but a subclass equivalent would be this: ##sub _children { ## my $self = shift; ## my $path = "" . shift; # stringify objects ## opendir( my $dh, $path ); ## return map { [ $_, "$path/$_" ] } grep { $_ ne "." && $_ ne ".." } readdir $dh; ##} # The _stringify option controls whether the string form of an object is cached # for iteration control. This is generally a good idea to avoid extra overhead, # but subclasses can override this if necessary sub _defaults { return ( _stringify => 1, follow_symlinks => 1, depthfirst => 0, sorted => 1, loop_safe => ( $^O eq 'MSWin32' ? 0 : 1 ), # No inode #'s on Windows error_handler => sub { die sprintf( "%s: %s", @_ ) }, visitor => undef, ); } sub _fast_defaults { return ( _stringify => 1, follow_symlinks => 1, depthfirst => -1, sorted => 0, loop_safe => 0, error_handler => undef, visitor => undef, ); } #--------------------------------------------------------------------------# # iteration methods #--------------------------------------------------------------------------# sub iter { my $self = shift; $self->_iter( { $self->_defaults }, @_ ); } sub iter_fast { my $self = shift; $self->_iter( { $self->_fast_defaults }, @_ ); } sub _iter { my $self = shift; my $defaults = shift; my $args = ref( $_[0] ) && !Scalar::Util::blessed( $_[0] ) ? shift : ref( $_[-1] ) && !Scalar::Util::blessed( $_[-1] ) ? pop : {}; my %opts = ( %$defaults, %$args ); # unroll these for efficiency my $opt_stringify = $opts{_stringify}; my $opt_depthfirst = $opts{depthfirst}; my $opt_follow_symlinks = $opts{follow_symlinks}; my $opt_sorted = $opts{sorted}; my $opt_loop_safe = $opts{loop_safe}; my $opt_error_handler = $opts{error_handler}; my $opt_relative = $opts{relative}; my $opt_visitor = $opts{visitor}; my $has_rules = @{ $self->{rules} }; my $stash = {}; # if not subclassed, we want to inline my $can_children = $self->can("_children"); # queue structure: flat list in tuples of 4: (object, basename, depth, origin) # if object is arrayref, then that's a special case signal that it # was already of interest and can finally be returned for postorder searches my @queue = map { my $i = $self->_objectify($_); ( $i, File::Basename::basename("$_"), 0, $i ) } @_ ? @_ : '.'; return sub { LOOP: { my ( $item, $base, $depth, $origin ) = splice( @queue, 0, 4 ); return unless $item; return $item->[0] if ref $item eq 'ARRAY'; # deferred for postorder my $string_item = $opt_stringify ? "$item" : $item; if ( !$opt_follow_symlinks ) { redo LOOP if -l $string_item; } # by default, we're interested in everything and prune nothing my ( $interest, $prune ) = ( 1, 0 ); if ($has_rules) { local $_ = $item; $stash->{_depth} = $depth; if ($opt_error_handler) { $interest = try { $self->test( $item, $base, $stash ) } catch { $opt_error_handler->( $item, $_ ) }; } else { $interest = $self->test( $item, $base, $stash ); } # New way to signal prune is returning a reference to a scalar. # Value of the scalar indicates if it should be returned by the # iterator or not if ( ref $interest eq 'SCALAR' ) { $prune = 1; $interest = $$interest; } } # if we have a visitor, we call it like a custom rule if ( $opt_visitor && $interest ) { local $_ = $item; $stash->{_depth} = $depth; $opt_visitor->( $item, $base, $stash ); } # if it's a directory, maybe add children to the queue if ( ( -d $string_item ) && ( !$prune ) && ( !$opt_loop_safe || $self->_is_unique( $string_item, $stash ) ) ) { if ( !-r $string_item ) { warnings::warnif("Directory '$string_item' is not readable. Skipping it"); } else { my @next; my $depth_p1 = $depth + 1; if ($can_children) { my @paths = $can_children->( $self, $item ); if ($opt_sorted) { @paths = sort { "$a->[0]" cmp "$b->[0]" } @paths; } @next = map { ( $_->[1], $_->[0], $depth_p1, $origin ) } @paths; } else { opendir( my $dh, $string_item ); if ($opt_sorted) { @next = map { ( "$string_item/$_", $_, $depth_p1, $origin ) } sort { $a cmp $b } grep { $_ ne "." && $_ ne ".." } readdir $dh; } else { @next = map { ( "$string_item/$_", $_, $depth_p1, $origin ) } grep { $_ ne "." && $_ ne ".." } readdir $dh; } } if ($opt_depthfirst) { # for postorder, requeue as reference to signal it can be returned # without being retested push @next, [ ( $opt_relative ? $self->_objectify( File::Spec->abs2rel( $string_item, $origin ) ) : $item ) ], $base, $depth, $origin if $interest && $opt_depthfirst > 0; unshift @queue, @next; redo LOOP if $opt_depthfirst > 0; } else { push @queue, @next; } } } return ( $opt_relative ? $self->_objectify( File::Spec->abs2rel( $string_item, $origin ) ) : $item ) if $interest; redo LOOP; } }; } sub all { my $self = shift; return $self->_all( $self->iter(@_) ); } sub all_fast { my $self = shift; return $self->_all( $self->iter_fast(@_) ); } sub _all { my $self = shift; my $iter = shift; if (wantarray) { my @results; while ( defined( my $item = $iter->() ) ) { push @results, $item; } return @results; } elsif ( defined wantarray ) { my $count = 0; $count++ while defined $iter->(); return $count; } else { 1 while defined $iter->(); } } #--------------------------------------------------------------------------# # logic methods #--------------------------------------------------------------------------# sub and { my $self = shift; push @{ $self->{rules} }, $self->_rulify(@_); return $self; } sub or { my $self = shift; my @rules = $self->_rulify(@_); my $coderef = sub { my ( $result, $prune ); for my $rule (@rules) { $result = $rule->(@_); # once any rule says to prune, we remember that $prune ||= ref($result) eq 'SCALAR'; # extract whether constraint was met $result = $$result if ref($result) eq 'SCALAR'; # shortcut if met, propagating prune state return ( $prune ? \1 : 1 ) if $result; } return ( $prune ? \$result : $result ) ; # may or may not be met, but propagate prune state }; return $self->and($coderef); } sub not { my $self = shift; my $obj = $self->new->and(@_); my $coderef = sub { my $result = $obj->test(@_); return ref($result) ? \!$$result : !$result; # invert, but preserve prune }; return $self->and($coderef); } sub skip { my $self = shift; my @rules = @_; my $obj = $self->new->or(@rules); my $coderef = sub { my $result = $obj->test(@_); my ( $prune, $interest ); if ( ref($result) eq 'SCALAR' ) { # test told us to prune, so make that sticky # and also skip it $prune = 1; $interest = 0; } else { # prune if test was true $prune = $result; # negate test result $interest = !$result; } return $prune ? \$interest : $interest; }; return $self->and($coderef); } sub test { my ( $self, $item, $base, $stash ) = @_; my ( $result, $prune ); for my $rule ( @{ $self->{rules} } ) { $result = $rule->( $item, $base, $stash ) || 0; if ( !ref($result) && $result eq '0 but true' ) { Carp::croak("0 but true no longer supported by custom rules"); } # once any rule says to prune, we remember that $prune ||= ref($result) eq 'SCALAR'; # extract whether constraint was met $result = $$result if ref($result) eq 'SCALAR'; # shortcut if not met, propagating prune state return ( $prune ? \0 : 0 ) if !$result; } return ( $prune ? \1 : 1 ); # all constraints met, but propagate prune state } #--------------------------------------------------------------------------# # private methods #--------------------------------------------------------------------------# sub _rulify { my ( $self, @args ) = @_; my @rules; for my $arg (@args) { my $rule; if ( Scalar::Util::blessed($arg) && $arg->isa("Path::Iterator::Rule") ) { $rule = sub { $arg->test(@_) }; } elsif ( ref($arg) eq 'CODE' ) { $rule = $arg; } else { Carp::croak("Rules must be coderef or Path::Iterator::Rule"); } push @rules, $rule; } return @rules; } sub _is_unique { my ( $self, $string_item, $stash ) = @_; my $unique_id; my @st = eval { stat $string_item }; @st = eval { lstat $string_item } unless @st; if (@st) { $unique_id = join( ",", $st[0], $st[1] ); } else { my $type = -d $string_item ? 'directory' : 'file'; warnings::warnif("Could not stat $type '$string_item'"); $unique_id = $string_item; } return !$stash->{_seen}{$unique_id}++; } #--------------------------------------------------------------------------# # built-in helpers #--------------------------------------------------------------------------# sub _regexify { my ( $re, $add ) = @_; $add ||= ''; my $new = ref($re) eq 'Regexp' ? $re : Text::Glob::glob_to_regex($re); return $new unless $add; my ( $pattern, $flags ) = regexp_pattern($new); my $new_flags = $add ? _reflag( $flags, $add ) : ""; return qr/$new_flags$pattern/; } sub _reflag { my ( $orig, $add ) = @_; $orig ||= ""; if ( $] >= 5.014 ) { return "(?^$orig$add)"; } else { my ( $pos, $neg ) = split /-/, $orig; $pos ||= ""; $neg ||= ""; $neg =~ s/i//; $neg = "-$neg" if length $neg; return "(?$add$pos$neg)"; } } # "simple" helpers take no arguments my %simple_helpers = ( directory => sub { -d $_ }, # see also -d => dir below dangling => sub { -l $_ && !stat $_ }, ); while ( my ( $k, $v ) = each %simple_helpers ) { __PACKAGE__->add_helper( $k, sub { return $v } ); } sub _generate_name_matcher { my (@patterns) = @_; if ( @patterns > 1 ) { return sub { my $name = "$_[1]"; return ( List::Util::first { $name =~ $_ } @patterns ) ? 1 : 0; } } else { my $pattern = $patterns[0]; return sub { my $name = "$_[1]"; return $name =~ $pattern ? 1 : 0; } } } # "complex" helpers take arguments my %complex_helpers = ( name => sub { Carp::croak("No patterns provided to 'name'") unless @_; _generate_name_matcher( map { _regexify($_) } @_ ); }, iname => sub { Carp::croak("No patterns provided to 'iname'") unless @_; _generate_name_matcher( map { _regexify( $_, "i" ) } @_ ); }, min_depth => sub { Carp::croak("No depth argument given to 'min_depth'") unless @_; my $min_depth = 0+ shift; # if this warns, do here and not on every file return sub { my ( $f, $b, $stash ) = @_; return $stash->{_depth} >= $min_depth; } }, max_depth => sub { Carp::croak("No depth argument given to 'max_depth'") unless @_; my $max_depth = 0+ shift; # if this warns, do here and not on every file return sub { my ( $f, $b, $stash ) = @_; return 1 if $stash->{_depth} < $max_depth; return \1 if $stash->{_depth} == $max_depth; return \0; } }, shebang => sub { Carp::croak("No patterns provided to 'shebang'") unless @_; my @patterns = map { _regexify($_) } @_; return sub { my $f = shift; return unless !-d $f; open my $fh, "<", $f; my $shebang = <$fh>; return unless defined $shebang; return ( List::Util::first { $shebang =~ $_ } @patterns ) ? 1 : 0; }; }, contents_match => sub { my @regexp = @_; my $filter = ':encoding(UTF-8)'; $filter = shift @regexp unless ref $regexp[0]; return sub { my $f = shift; return unless !-d $f; my $contents = do { local $/ = undef; open my $fh, "<$filter", $f; <$fh>; }; for my $re (@regexp) { return 1 if $contents =~ $re; } return 0; }; }, line_match => sub { my @regexp = @_; my $filter = ':encoding(UTF-8)'; $filter = shift @regexp unless ref $regexp[0]; return sub { my $f = shift; return unless !-d $f; open my $fh, "<$filter", $f; while ( my $line = <$fh> ) { for my $re (@regexp) { return 1 if $line =~ $re; } } return 0; }; }, ); while ( my ( $k, $v ) = each %complex_helpers ) { __PACKAGE__->add_helper( $k, $v ); } # skip_dirs __PACKAGE__->add_helper( skip_dirs => sub { Carp::croak("No patterns provided to 'skip_dirs'") unless @_; my $name_check = Path::Iterator::Rule->new->name(@_); return sub { return \0 if -d $_[0] && $name_check->test(@_); return 1; # otherwise, like a null rule } } => 1 # don't create not_skip_dirs ); __PACKAGE__->add_helper( skip_subdirs => sub { Carp::croak("No patterns provided to 'skip_subdirs'") unless @_; my $name_check = Path::Iterator::Rule->new->name(@_); return sub { my ( $f, $b, $stash ) = @_; return \0 if -d $f && $stash->{_depth} && $name_check->test(@_); return 1; # otherwise, like a null rule } } => 1 # don't create not_skip_dirs ); # X_tests adapted from File::Find::Rule #<<< do not perltidy this my %X_tests = ( -r => readable => -R => r_readable => -w => writeable => -W => r_writeable => -w => writable => -W => r_writable => -x => executable => -X => r_executable => -o => owned => -O => r_owned => -e => exists => -f => file => -z => empty => -d => dir => -s => nonempty => -l => symlink => => -p => fifo => -u => setuid => -S => socket => -g => setgid => -b => block => -k => sticky => -c => character => => -t => tty => -T => ascii => -B => binary => ); #>>> while ( my ( $op, $name ) = each %X_tests ) { my $coderef = eval "sub { $op \$_ }"; ## no critic __PACKAGE__->add_helper( $name, sub { return $coderef } ); } my %time_tests = ( -A => accessed => -M => modified => -C => changed => ); while ( my ( $op, $name ) = each %time_tests ) { my $filetest = eval "sub { $op \$_ }"; ## no critic my $coderef = sub { Carp::croak("The '$name' test requires a single argument") unless @_ == 1; my $comparator = Number::Compare->new(shift); return sub { return $comparator->( $filetest->() ) }; }; __PACKAGE__->add_helper( $name, $coderef ); } # stat tests adapted from File::Find::Rule my @stat_tests = qw( dev ino mode nlink uid gid rdev size atime mtime ctime blksize blocks ); for my $i ( 0 .. $#stat_tests ) { my $name = $stat_tests[$i]; my $coderef = sub { Carp::croak("The '$name' test requires a single argument") unless @_ == 1; my $comparator = Number::Compare->new(shift); return sub { return $comparator->( ( stat($_) )[$i] ) }; }; __PACKAGE__->add_helper( $name, $coderef ); } # VCS rules adapted from File::Find::Rule::VCS my %vcs_rules = ( skip_cvs => sub { return Path::Iterator::Rule->new->skip_dirs('CVS')->not_name(qr/\.\#$/); }, skip_rcs => sub { return Path::Iterator::Rule->new->skip_dirs('RCS')->not_name(qr/,v$/); }, skip_git => sub { return Path::Iterator::Rule->new->skip_dirs('.git'); }, skip_svn => sub { return Path::Iterator::Rule->new->skip_dirs( ( $^O eq 'MSWin32' ) ? ( '.svn', '_svn' ) : ('.svn') ); }, skip_bzr => sub { return Path::Iterator::Rule->new->skip_dirs('.bzr'); }, skip_hg => sub { return Path::Iterator::Rule->new->skip_dirs('.hg'); }, skip_darcs => sub { return Path::Iterator::Rule->new->skip_dirs('_darcs'); }, skip_vcs => sub { return Path::Iterator::Rule->new->skip_dirs(qw/.git .bzr .hg _darcs CVS RCS/) ->skip_svn->not_name( qr/\.\#$/, qr/,v$/ ); }, ); while ( my ( $name, $coderef ) = each %vcs_rules ) { __PACKAGE__->add_helper( $name, $coderef, 1 ); # don't create not_* } # perl rules adapted from File::Find::Rule::Perl my %perl_rules = ( perl_module => sub { return Path::Iterator::Rule->new->file->name('*.pm') }, perl_pod => sub { return Path::Iterator::Rule->new->file->name('*.pod') }, perl_test => sub { return Path::Iterator::Rule->new->file->name('*.t') }, perl_installer => sub { return Path::Iterator::Rule->new->file->name( 'Makefile.PL', 'Build.PL' ); }, perl_script => sub { return Path::Iterator::Rule->new->file->or( Path::Iterator::Rule->new->name('*.pl'), Path::Iterator::Rule->new->shebang(qr/#!.*\bperl\b/), ); }, perl_file => sub { return Path::Iterator::Rule->new->or( Path::Iterator::Rule->new->perl_module, Path::Iterator::Rule->new->perl_pod, Path::Iterator::Rule->new->perl_test, Path::Iterator::Rule->new->perl_installer, Path::Iterator::Rule->new->perl_script, ); }, ); while ( my ( $name, $coderef ) = each %perl_rules ) { __PACKAGE__->add_helper( $name, $coderef ); } 1; # vim: ts=4 sts=4 sw=4 et: __END__ =pod =encoding UTF-8 =head1 NAME Path::Iterator::Rule - Iterative, recursive file finder =head1 VERSION version 1.009 =head1 SYNOPSIS use Path::Iterator::Rule; my $rule = Path::Iterator::Rule->new; # match anything $rule->file->size(">10k"); # add/chain rules # iterator interface my $next = $rule->iter( @dirs ); while ( defined( my $file = $next->() ) ) { ... } # list interface for my $file ( $rule->all( @dirs ) ) { ... } =head1 DESCRIPTION This module iterates over files and directories to identify ones matching a user-defined set of rules. The API is based heavily on L, but with more explicit distinction between matching rules and options that influence how directories are searched. A C object is a collection of rules (match criteria) with methods to add additional criteria. Options that control directory traversal are given as arguments to the method that generates an iterator. Here is a summary of features for comparison to other file finding modules: =over 4 =item * provides many "helper" methods for specifying rules =item * offers (lazy) iterator and flattened list interfaces =item * custom rules implemented with callbacks =item * breadth-first (default) or pre- or post-order depth-first searching =item * follows symlinks (by default, but can be disabled) =item * directories visited only once (no infinite loop; can be disabled) =item * doesn't chdir during operation =item * provides an API for extensions =back As a convenience, the L module is an empty subclass of this one that is less arduous to type for one-liners. =head1 USAGE =head2 Constructors =head3 C my $rule = Path::Iterator::Rule->new; Creates a new rule object that matches any file or directory. It takes no arguments. For convenience, it may also be called on an object, in which case it still returns a new object that matches any file or directory. =head3 C my $common = Path::Iterator::Rule->new->file->not_empty; my $big_files = $common->clone->size(">1M"); my $small_files = $common->clone->size("<10K"); Creates a copy of a rule object. Useful for customizing different rule objects against a common base. =head2 Matching and iteration =head3 C my $next = $rule->iter( @dirs, \%options); while ( defined( my $file = $next->() ) ) { ... } Creates a subroutine reference iterator that returns a single result when dereferenced. This iterator is "lazy" -- results are not pre-computed. It takes as arguments a list of directories to search and an optional hash reference of control options. If no search directories are provided, the current directory is used (C<".">). Valid options include: =over 4 =item * C -- Controls order of results. Valid values are "1" (post-order, depth-first search), "0" (breadth-first search) or "-1" (pre-order, depth-first search). Default is 0. =item * C -- Catches errors during execution of rule tests. Default handler dies with the filename and error. If set to undef, error handling is disabled. =item * C -- Follow directory symlinks when true. Default is 1. =item * C -- Prevents visiting the same directory more than once when true. Default is 1. =item * C -- Return matching items relative to the search directory. Default is 0. =item * C -- Whether entries in a directory are sorted before processing. Default is 1. =item * C -- An optional coderef that will be called on items matching all rules. =back Filesystem loops might exist from either hard or soft links. The C option prevents infinite loops, but adds some overhead by making C calls. Because directories are visited only once when C is true, matches could come from a symlinked directory before the real directory depending on the search order. To get only the real files, turn off C. Turning C off and leaving C on avoids C calls and will be fastest, but with the risk of an infinite loop and repeated files. The default is slow, but safe. The C parameter must be a subroutine reference. It will be called when a rule test throws an exception. The first argument will be the file name being inspected and the second argument will be the exception. The optional C parameter must be a subroutine reference. If set, it will be called for any result that matches. It is called the same way a custom rule would be (see L) but its return value is ignored. It is called when an item is first inspected -- "postorder" is not respected. The paths inspected and returned will be relative to the search directories provided. If these are absolute, then the paths returned will have absolute paths. If these are relative, then the paths returned will have relative paths. If the search directories are absolute and the C option is true, files returned will be relative to the search directory. Note that if the search directories are not mutually exclusive (whether containing subdirectories like C<@INC> or symbolic links), files found could be returned relative to different initial search directories based on C, C or C. When the iterator is exhausted, it will return undef. =head3 C This works just like C, except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See L for details. =head3 C my @matches = $rule->all( @dir, \%options ); Returns a list of paths that match the rule. It takes the same arguments and has the same behaviors as the C method. The C method uses C internally to fetch all results. In scalar context, it will return the count of matched paths. In void context, it is optimized to iterate over everything, but not store results. This is most useful with the C option: $rule->all( $path, { visitor => \&callback } ); =head3 C This works just like C, except that it optimizes for speed over safety. Don't do this unless you're sure you need it and accept the consequences. See L for details. =head3 C if ( $rule->test( $path, $basename, $stash ) ) { ... } Test a file path against a rule. Used internally, but provided should someone want to create their own, custom iteration algorithm. =head2 Logic operations C provides three logic operations for adding rules to the object. Rules may be either a subroutine reference with specific semantics (described below in L) or another C object. =head3 C $rule->and( sub { -r -w -x $_ } ); # stacked filetest example $rule->and( @more_rules ); Adds one or more constraints to the current rule. E.g. "old rule AND new1 AND new2 AND ...". Returns the object to allow method chaining. =head3 C $rule->or( $rule->new->name("foo*"), $rule->new->name("bar*"), sub { -r -w -x $_ }, ); Takes one or more alternatives and adds them as a constraint to the current rule. E.g. "old rule AND ( new1 OR new2 OR ... )". Returns the object to allow method chaining. =head3 C $rule->not( sub { -r -w -x $_ } ); Takes one or more alternatives and adds them as a negative constraint to the current rule. E.g. "old rule AND NOT ( new1 AND new2 AND ...)". Returns the object to allow method chaining. =head3 C $rule->skip( $rule->new->dir->not_writeable, $rule->new->dir->name("foo"), ); Takes one or more alternatives and will prune a directory if any of the criteria match or if any of the rules already indicate the directory should be pruned. Pruning means the directory will not be returned by the iterator and will not be searched. For files, it is equivalent to C<< $rule->not($rule->or(@rules)) >>. Returns the object to allow method chaining. This method should be called as early as possible in the rule chain. See L below for further explanation and an example. =head1 RULE METHODS Rule methods are helpers that add constraints. Internally, they generate a closure to accomplish the desired logic and add it to the rule object with the C method. Rule methods return the object to allow for method chaining. =head2 File name rules =head3 C $rule->name( "foo.txt" ); $rule->name( qr/foo/, "bar.*"); The C method takes one or more patterns and creates a rule that is true if any of the patterns match the B of the file or directory path. Patterns may be regular expressions or glob expressions (or literal names). =head3 C $rule->iname( "foo.txt" ); $rule->iname( qr/foo/, "bar.*"); The C method is just like the C method, but matches case-insensitively. =head3 C $rule->skip_dirs( @patterns ); The C method skips directories that match one or more patterns. Patterns may be regular expressions or globs (just like C). Directories that match will not be returned from the iterator and will be excluded from further search. B If that isn't what you want, see L instead. B this rule should be specified early so that it has a chance to operate before a logical shortcut. E.g. $rule->skip_dirs(".git")->file; # OK $rule->file->skip_dirs(".git"); # Won't work In the latter case, when a ".git" directory is seen, the C rule shortcuts the rule before the C rule has a chance to act. =head3 C $rule->skip_subdirs( @patterns ); This works just like C, except that the starting directories (depth 0) are not skipped and may be returned from the iterator unless excluded by other rules. =head2 File test rules Most of the C<-X> style filetest are available as boolean rules. The table below maps the filetest to its corresponding method name. Test | Method Test | Method ------|------------- ------|---------------- -r | readable -R | r_readable -w | writeable -W | r_writeable -w | writable -W | r_writable -x | executable -X | r_executable -o | owned -O | r_owned | | -e | exists -f | file -z | empty -d | directory, dir -s | nonempty -l | symlink | -p | fifo -u | setuid -S | socket -g | setgid -b | block -k | sticky -c | character | -t | tty -T | ascii -B | binary For example: $rule->file->nonempty; # -f -s $file The -X operators for timestamps take a single argument in a form that L can interpret. Test | Method ------|------------- -A | accessed -M | modified -C | changed For example: $rule->modified(">1"); # -M $file > 1 =head2 Stat test rules All of the C elements have a method that takes a single argument in a form understood by L. stat() | Method -------------------- 0 | dev 1 | ino 2 | mode 3 | nlink 4 | uid 5 | gid 6 | rdev 7 | size 8 | atime 9 | mtime 10 | ctime 11 | blksize 12 | blocks For example: $rule->size(">10K") =head2 Depth rules $rule->min_depth(3); $rule->max_depth(5); The C and C rule methods take a single argument and limit the paths returned to a minimum or maximum depth (respectively) from the starting search directory. A depth of 0 means the starting directory itself. A depth of 1 means its children. (This is similar to the Unix C utility.) =head2 Perl file rules # All perl rules $rule->perl_file; # Individual perl file rules $rule->perl_module; # .pm files $rule->perl_pod; # .pod files $rule->perl_test; # .t files $rule->perl_installer; # Makefile.PL or Build.PL $rule->perl_script; # .pl or 'perl' in the shebang These rule methods match file names (or a shebang line) that are typical of Perl distribution files. =head2 Version control file rules # Skip all known VCS files $rule->skip_vcs; # Skip individual VCS files $rule->skip_cvs; $rule->skip_rcs; $rule->skip_svn; $rule->skip_git; $rule->skip_bzr; $rule->skip_hg; $rule->skip_darcs; Skips files and/or prunes directories related to a version control system. Just like C, these rules should be specified early to get the correct behavior. =head2 File content rules =head3 C $rule->contents_match(qr/BEGIN .* END/xs); The C rule takes a list of regular expressions and returns files that match one of the expressions. The expressions are applied to the file's contents as a single string. For large files, this is likely to take significant time and memory. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument: $rule->contents_match(":encoding(iso-8859-1)", qr/BEGIN .* END/xs); See L for further details. =head3 C $rule->line_match(qr/^new/i, qr/^Addition/); The C rule takes a list of regular expressions and returns files with at least one line that matches one of the expressions. Files are assumed to be encoded in UTF-8, but alternative Perl IO layers can be passed as the first argument. =head3 C $rule->shebang(qr/#!.*\bperl\b/); The C rule takes a list of regular expressions or glob patterns and checks them against the first line of a file. =head2 Other rules =head3 C $rule->symlink->dangling; $rule->not_dangling; The C rule method matches dangling symlinks. Use it or its inverse to control how dangling symlinks should be treated. =head2 Negated rules Most rule methods have a negated form preceded by "not_". $rule->not_name("foo.*") Because this happens automatically, it includes somewhat silly ones like C (which is thus a less efficient way of saying C). Rules that skip directories or version control files do not have a negated version. =head1 EXTENDING =head2 Custom rule subroutines Rules are implemented as (usually anonymous) subroutine callbacks that return a value indicating whether or not the rule matches. These callbacks are called with three arguments. The first argument is a path, which is also locally aliased as the C<$_> global variable for convenience in simple tests. $rule->and( sub { -r -w -x $_ } ); # tests $_ The second argument is the basename of the path, which is useful for certain types of name checks: $rule->and( sub { $_[1] =~ /foo|bar/ } ); "foo" or "bar" in basename; The third argument is a hash reference that can be used to maintain state. Keys beginning with an underscore are B for C to provide additional data about the search in progress. For example, the C<_depth> key is used to support minimum and maximum depth checks. The custom rule subroutine must return one of four values: =over 4 =item * A true value -- indicates the constraint is satisfied =item * A false value -- indicates the constraint is not satisfied =item * C<\1> -- indicate the constraint is satisfied, and prune if it's a directory =item * C<\0> -- indicate the constraint is not satisfied, and prune if it's a directory =back A reference is a special flag that signals that a directory should not be searched recursively, regardless of whether the directory should be returned by the iterator or not. The legacy "0 but true" value used previously for pruning is no longer valid and will throw an exception if it is detected. Here is an example. This is equivalent to the "max_depth" rule method with a depth of 3: $rule->and( sub { my ($path, $basename, $stash) = @_; return 1 if $stash->{_depth} < 3; return \1 if $stash->{_depth} == 3; return \0; # should never get here } ); Files and directories and directories up to depth 3 will be returned and directories will be searched. Files of depth 3 will be returned. Directories of depth 3 will be returned, but their contents will not be added to the search. Returning a reference is "sticky" -- they will propagate through "and" and "or" logic. 0 && \0 = \0 \0 && 0 = \0 0 || \0 = \0 \0 || 0 = \0 0 && \1 = \0 \0 && 1 = \0 0 || \1 = \1 \0 || 1 = \1 1 && \0 = \0 \1 && 0 = \0 1 || \0 = \1 \1 || 0 = \1 1 && \1 = \1 \1 && 1 = \1 1 || \1 = \1 \1 || 1 = \1 Once a directory is flagged to be pruned, it will be pruned regardless of subsequent rules. $rule->max_depth(3)->name(qr/foo/); This will return files or directories with "foo" in the name, but all directories at depth 3 will be pruned, regardless of whether they match the name rule. Generally, if you want to do directory pruning, you are encouraged to use the L method instead of writing your own logic using C<\0> and C<\1>. =head2 Extension modules and custom rule methods One of the strengths of L is the many CPAN modules that extend it. C provides the C method to provide a similar mechanism for extensions. The C class method takes three arguments, a C for the rule method, a closure-generating callback, and a flag for not generating a negated form of the rule. Unless the flag is true, an inverted "not_*" method is generated automatically. Extension classes should call this as a class method to install new rule methods. For example, this adds a "foo" method that checks if the filename is "foo": package Path::Iterator::Rule::Foo; use Path::Iterator::Rule; Path::Iterator::Rule->add_helper( foo => sub { my @args = @_; # do this to customize closure with arguments return sub { my ($item, $basename) = @_; return if -d "$item"; return $basename =~ /^foo$/; } } ); 1; This allows the following rule methods: $rule->foo; $fule->not_foo; The C method will warn and ignore a helper with the same name as an existing method. =head2 Subclassing Instead of processing and returning strings, this module may be subclassed to operate on objects that represent files. Such objects B stringify to a file path. The following private implementation methods must be overridden: =over 4 =item * _objectify -- given a path, return an object =item * _children -- given a directory, return an (unsorted) list of [ basename, full path ] entries within it, excluding "." and ".." =back Note that C<_children> should return a I of I, where the tuples are array references containing basename and full path. See L source for an example. =head1 LEXICAL WARNINGS If you run with lexical warnings enabled, C will issue warnings in certain circumstances (such as an unreadable directory that must be skipped). To disable these categories, put the following statement at the correct scope: no warnings 'Path::Iterator::Rule'; =head1 PERFORMANCE By default, C iterator options are "slow but safe". They ensure uniqueness, return files in sorted order, and throw nice error messages if something goes wrong. If you want speed over safety, set these options: %options = ( loop_safe => 0, sorted => 0, depthfirst => -1, error_handler => undef ); Alternatively, use the C and C methods instead, which set these options for you. $iter = $rule->iter( @dirs, \%options ); $iter = $rule->iter_fast( @dirs ); # same thing Depending on the file structure being searched, C<< depthfirst => -1 >> may or may not be a good choice. If you have lots of nested directories and all the files at the bottom, a depth first search might do less work or use less memory, particularly if the search will be halted early (e.g. finding the first N matches.) Rules will shortcut on failure, so be sure to put rules likely to fail early in a rule chain. Consider: $r1 = Path::Iterator::Rule->new->name(qr/foo/)->file; $r2 = Path::Iterator::Rule->new->file->name(qr/foo/); If there are lots of files, but only a few containing "foo", then C<$r1> above will be faster. Rules are implemented as code references, so long chains have some overhead. Consider testing with a custom coderef that combines several tests into one. Consider: $r3 = Path::Iterator::Rule->new->and( sub { -x -w -r $_ } ); $r4 = Path::Iterator::Rule->new->executable->writeable->readable; Rule C<$r3> above will be much faster, not only because it stacks the file tests, but because it requires only a single code reference. =head1 CAVEATS Some features are still unimplemented: =over 4 =item * Untainting options =item * Some L helpers (e.g. C) =item * Extension class loading via C =back Filetest operators and stat rules are subject to the usual portability considerations. See L for details. =head1 SEE ALSO There are many other file finding modules out there. They all have various features/deficiencies, depending on your preferences and needs. Here is an (incomplete) list of alternatives, with some comparison commentary. L and L are subclasses of C and operate on L and L objects, respectively. Because of this, they are substantially slower on large directory trees than just using this module directly. L is part of the Perl core. It requires the user to write a callback function to process each node of the search. Callbacks must use global variables to determine the current node. It only supports depth-first search (both pre- and post-order). It supports pre- and post-processing callbacks; the former is required for sorting files to process in a directory. L can be used to help create a callback for L. L is an object-oriented wrapper around L. It provides a number of helper functions and there are many more C modules on CPAN with additional helpers. It provides an iterator interface, but precomputes all the results. L provides iterators for file, directories or "everything". It takes two callbacks, one to match files and one to decide which directories to descend. It does not allow control over breadth/depth order, though it does provide means to sort files for processing within a directory. Like L, it requires callbacks to use global variables. L walks a directory structure with an iterator. It is implemented as L subclasses, which adds a degree of extra complexity. It takes a single callback to define "interesting" paths to return. The callback gets a L or L object for evaluation. L and companion L are like File::Find and File::Find::Rule, but without File::Find inside. They use an iterator that does not precompute results. They can return L objects, which give a subset of the utility of Path::Class objects. L appears to be a literal translation of L, including oddities like making C<-M> into a boolean. L recursively descends a tree, calling a callback on each file. No iterator. Supports exclusion patterns. Depth-first post-order by default, but offers pre-order option. Does not process symlinks. L is based on iterator patterns in Higher Order Perl. It allows a filtering callback. Symlinks are followed automatically without infinite loop protection. No control over order. It offers a "state file" option for resuming interrupted work. L has declarative helper rules, no iterator, is Moose-based and offers no control over ordering or following symlinks. L has no iterator, does matching via callback and offers no control over ordering. L builds up a set of files to operate on from a list of directories to include or exclude, with control over recursion. A callback is applied to each file (or directory) in the set. There is no iterator. There is no control over ordering. Symlinks are not followed. It has several extra features for checksumming the set and creating tarballs with F. =head1 THANKS Thank you to Ricardo Signes (rjbs) for inspiring me to write yet another file finder module, for writing file finder optimization benchmarks, and tirelessly running my code over and over to see if it got faster. =over 4 =item * See L =back =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan =head1 SUPPORT =head2 Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at L. You will be notified automatically of any progress on your issue. =head2 Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. L git clone https://github.com/dagolden/Path-Iterator-Rule.git =head1 AUTHOR David Golden =head1 CONTRIBUTORS =for stopwords David Steinbrunner Gian Piero Carrubba Graham Knop Ricardo Signes Toby Inkster =over 4 =item * David Steinbrunner =item * Gian Piero Carrubba =item * Graham Knop =item * Ricardo Signes =item * Toby Inkster =back =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by David Golden. This is free software, licensed under: The Apache License, Version 2.0, January 2004 =cut Path-Iterator-Rule-1.009/examples/modules-in-inc.pl000644 000765 000024 00000000367 12577662462 022372 0ustar00davidstaff000000 000000 #!/usr/bin/env perl use v5.10; use strict; use warnings; use autodie; use PIR; my $rule = PIR->new->skip_dirs('.')->perl_module; for ( $rule->all( { relative => 1 }, grep { /site_perl/ } @INC ) ) { s{[/\\]}{::}g; s{\.pm$}{}; say; }