plucky (3) File::Find::Object::Rule.3pm.gz

Provided by: libfile-find-object-rule-perl_0.0313-1_all bug

NAME

       File::Find::Object::Rule - Alternative interface to File::Find::Object

VERSION

       version 0.0313

SYNOPSIS

         use File::Find::Object::Rule;
         # find all the subdirectories of a given directory
         my @subdirs = File::Find::Object::Rule->directory->in( $directory );

         # find all the .pm files in @INC
         my @files = File::Find::Object::Rule->file()
                                     ->name( '*.pm' )
                                     ->in( @INC );

         # as above, but without method chaining
         my $rule =  File::Find::Object::Rule->new;
         $rule->file;
         $rule->name( '*.pm' );
         my @files = $rule->in( @INC );

DESCRIPTION

       File::Find::Object::Rule is a friendlier interface to File::Find::Object .  It allows you to build rules
       which specify the desired files and directories.

       WARNING : This module is a fork of version 0.30 of File::Find::Rule (which has been unmaintained for
       several years as of February, 2009), and may still have some bugs due to its reliance on File::Find'isms.
       As such it is considered Alpha software. Please report any problems with File::Find::Object::Rule to its
       RT CPAN Queue.

METHODS

       "new"
           A constructor.  You need not invoke "new" manually unless you wish to, as each of the rule-making
           methods will auto-create a suitable object if called as class methods.

   finder
       The File::Find::Object finder instance itself.

   my @rules = @{$ffor->rules()};
       The rules to match against. For internal use only.

   Matching Rules
       "name( @patterns )"
           Specifies names that should match.  May be globs or regular expressions.

            $set->name( '*.mp3', '*.ogg' ); # mp3s or oggs
            $set->name( qr/\.(mp3|ogg)$/ ); # the same as a regex
            $set->name( 'foo.bar' );        # just things named foo.bar

       -X tests
           Synonyms are provided for each of the -X tests. See "-X" in perlfunc for details.  None of these
           methods take arguments.

             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
              -s  |  nonempty             -l  |  symlink
                  |                       -p  |  fifo
              -u  |  setuid               -S  |  socket
              -g  |  setgid               -b  |  block
              -k  |  sticky               -c  |  character
                  |                       -t  |  tty
              -M  |  modified                 |
              -A  |  accessed             -T  |  ascii
              -C  |  changed              -B  |  binary

           Though some tests are fairly meaningless as binary flags ("modified", "accessed", "changed"), they
           have been included for completeness.

            # find nonempty files
            $rule->file,
                 ->nonempty;

       stat tests
           The following "stat" based methods are provided: "dev", "ino", "mode", "nlink", "uid", "gid", "rdev",
           "size", "atime", "mtime", "ctime", "blksize", and "blocks".  See "stat" in perlfunc for details.

           Each of these can take a number of targets, which will follow Number::Compare semantics.

            $rule->size( 7 );         # exactly 7
            $rule->size( ">7Ki" );    # larger than 7 * 1024 * 1024 bytes
            $rule->size( ">=7" )
                 ->size( "<=90" );    # between 7 and 90, inclusive
            $rule->size( 7, 9, 42 );  # 7, 9 or 42

       "any( @rules )"
       "or( @rules )"
           Allows shortcircuiting boolean evaluation as an alternative to the default and-like nature of
           combined rules.  "any" and "or" are interchangeable.

            # find avis, movs, things over 200M and empty files
            $rule->any( File::Find::Object::Rule->name( '*.avi', '*.mov' ),
                        File::Find::Object::Rule->size( '>200M' ),
                        File::Find::Object::Rule->file->empty,
                      );

       "none( @rules )"
       "not( @rules )"
           Negates a rule.  (The inverse of "any".)  "none" and "not" are interchangeable.

             # files that aren't 8.3 safe
             $rule->file
                  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );

       "prune"
           Traverse no further.  This rule always matches.

       "discard"
           Don't keep this file.  This rule always matches.

       "exec( \&subroutine( $shortname, $path, $fullname ) )"
           Allows user-defined rules.  Your subroutine will be invoked with parameters of the name, the path
           you're in, and the full relative filename.  In addition, $_ is set to the current short name, but its
           use is discouraged since as opposed to File::Find::Rule, File::Find::Object::Rule does not cd to the
           containing directory.

           Return a true value if your rule matched.

            # get things with long names
            $rules->exec( sub { length > 20 } );

       ->grep( @specifiers );
           Opens a file and tests it each line at a time.

           For each line it evaluates each of the specifiers, stopping at the first successful match.  A
           specifier may be a regular expression or a subroutine.  The subroutine will be invoked with the same
           parameters as an ->exec subroutine.

           It is possible to provide a set of negative specifiers by enclosing them in anonymous arrays.  Should
           a negative specifier match the iteration is aborted and the clause is failed.  For example:

            $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );

           Is a passing clause if the first line of a file looks like a perl shebang line.

       "maxdepth( $level )"
           Descend at most $level (a non-negative integer) levels of directories below the starting point.

           May be invoked many times per rule, but only the most recent value is used.

       "mindepth( $level )"
           Do not apply any tests at levels less than $level (a non-negative integer).

       "extras( \%extras )"
           Specifies extra values to pass through to "File::File::find" as part of the options hash.

           For example this allows you to specify following of symlinks like so:

            my $rule = File::Find::Object::Rule->extras({ follow => 1 });

           May be invoked many times per rule, but only the most recent value is used.

       "relative"
           Trim the leading portion of any path found

       "not_*"
           Negated version of the rule.  An effective shortand related to ! in the procedural interface.

            $foo->not_name('*.pl');

            $foo->not( $foo->new->name('*.pl' ) );

   Query Methods
       "in( @directories )"
           Evaluates the rule, returns a list of paths to matching files and directories.

       "start( @directories )"
           Starts a find across the specified directories.  Matching items may then be queried using "match".
           This allows you to use a rule as an iterator.

            my $rule = File::Find::Object::Rule->file->name("*.jpeg")->start( "/web" );
            while ( my $image = $rule->match ) {
                ...
            }

       "match"
           Returns the next file which matches, false if there are no more.

   Extensions
       Extension modules are available from CPAN in the File::Find::Object::Rule namespace.  In order to use
       these extensions either use them directly:

        use File::Find::Object::Rule::ImageSize;
        use File::Find::Object::Rule::MMagic;

        # now your rules can use the clauses supplied by the ImageSize and
        # MMagic extension

       or, specify that File::Find::Object::Rule should load them for you:

        use File::Find::Object::Rule qw( :ImageSize :MMagic );

       For notes on implementing your own extensions, consult File::Find::Object::Rule::Extending

   Further examples
       Finding perl scripts
            my $finder = File::Find::Object::Rule->or
             (
              File::Find::Object::Rule->name( '*.pl' ),
              File::Find::Object::Rule->exec(
                                     sub {
                                         if (open my $fh, $_) {
                                             my $shebang = <$fh>;
                                             close $fh;
                                             return $shebang =~ /^#!.*\bperl/;
                                         }
                                         return 0;
                                     } ),
             );

           Based upon this message http://use.perl.org/comments.pl?sid=7052&cid=10842

       ignore CVS directories
            my $rule = File::Find::Object::Rule->new;
            $rule->or($rule->new
                           ->directory
                           ->name('CVS')
                           ->prune
                           ->discard,
                      $rule->new);

           Note here the use of a null rule.  Null rules match anything they see, so the effect is to match (and
           discard) directories called 'CVS' or to match anything.

TWO FOR THE PRICE OF ONE

       File::Find::Object::Rule also gives you a procedural interface.  This is documented in
       File::Find::Object::Rule::Procedural

EXPORTS

   find
   rule

Tests

   accessed
       Corresponds to "-A".

   ascii
       Corresponds to "-T".

   atime
       See "stat tests".

   binary
       Corresponds to "-b".

   blksize
       See "stat tests".

   block
       Corresponds to "-b".

   blocks
       See "stat tests".

   changed
       Corresponds to "-C".

   character
       Corresponds to "-c".

   ctime
       See "stat tests".

   dev
       See "stat tests".

   directory
       Corresponds to "-d".

   empty
       Corresponds to "-z".

   executable
       Corresponds to "-x".

   exists
       Corresponds to "-e".

   fifo
       Corresponds to "-p".

   file
       Corresponds to "-f".

   gid
       See "stat tests".

   ino
       See "stat tests".

   mode
       See "stat tests".

   modified
       Corresponds to "-M".

   mtime
       See "stat tests".

   nlink
       See "stat tests".

   r_executable
       Corresponds to "-X".

   r_owned
       Corresponds to "-O".

   nonempty
       A predicate that determines if the file is empty. Uses "-s".

   owned
       Corresponds to "-o".

   r_readable
       Corresponds to "-R".

   r_writeable
   r_writable
       Corresponds to "-W".

   rdev
       See "stat tests".

   readable
       Corresponds to "-r".

   setgid
       Corresponds to "-g".

   setuid
       Corresponds to "-u".

   size
       See stat tests.

   socket
       Corresponds to "-S".

   sticky
       Corresponds to "-k".

   symlink
       Corresponds to "-l".

   uid
       See "stat tests".

   tty
       Corresponds to "-t".

   writable()
       Corresponds to "-w".

BUGS

       The code relies on qr// compiled regexes, therefore this module requires perl version 5.005_03 or newer.

       Currently it isn't possible to remove a clause from a rule object.  If this becomes a significant issue
       it will be addressed.

AUTHOR

       Richard Clamp <richardc@unixbeard.net> with input gained from this use.perl discussion:
       http://use.perl.org/~richardc/journal/6467

       Additional proofreading and input provided by Kake, Greg McCarroll, and Andy Lester andy@petdance.com.

       Ported to use File::Find::Object as File::Find::Object::Rule by Shlomi Fish.

       Copyright (C) 2002, 2003, 2004, 2006 Richard Clamp.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.

SEE ALSO

       File::Find::Object, Text::Glob, Number::Compare, find(1)

       If you want to know about the procedural interface, see File::Find::Object::Rule::Procedural, and if you
       have an idea for a neat extension, see  File::Find::Object::Rule::Extending .

       Path::Class::Rule Xs SEE ALSO contains a review of many directory traversal modules on CPAN, including
       File::Find::Object::Rule and File::Find::Rule (on which this module is based).

KNOWN BUGS

       The tests don't run successfully when directly inside an old Subversion checkout, due to the presence of
       ".svn" directories. "./Build disttest" or "./Build distruntest" run fine.

SUPPORT

   Websites
       The following websites have more information about this module, and may be of help to you. As always, in
       addition to those websites please use your favorite search engine to discover more resources.

       •   MetaCPAN

           A modern, open-source CPAN search engine, useful to view POD in HTML format.

           <https://metacpan.org/release/File-Find-Object-Rule>

       •   RT: CPAN's Bug Tracker

           The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

           <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Find-Object-Rule>

       •   CPANTS

           The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

           <http://cpants.cpanauthors.org/dist/File-Find-Object-Rule>

       •   CPAN Testers

           The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN
           distributions.

           <http://www.cpantesters.org/distro/F/File-Find-Object-Rule>

       •   CPAN Testers Matrix

           The CPAN Testers Matrix is a website that provides a visual overview of the test results for a
           distribution on various Perls/platforms.

           <http://matrix.cpantesters.org/?dist=File-Find-Object-Rule>

       •   CPAN Testers Dependencies

           The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies
           for a distribution.

           <http://deps.cpantesters.org/?module=File::Find::Object::Rule>

   Bugs / Feature Requests
       Please report any bugs or feature requests by email to "bug-file-find-object-rule at rt.cpan.org", or
       through the web interface at <https://rt.cpan.org/Public/Bug/Report.html?Queue=File-Find-Object-Rule>.
       You will be automatically notified of any progress on the request by the system.

   Source Code
       The code is open to the world, and available for you to hack on. Please feel free to browse it and play
       with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from
       your repository :)

       <https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule>

         git clone git://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule.git

AUTHORS

       •   Richard Clamp <richardc@unixbeard.net>

       •   Andy Lester andy@petdance.com.

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule/issues>

       When submitting a bug or request, please include a test-file or a patch to an existing test-file that
       illustrates the bug or desired feature.

       This software is copyright (c) 2021 by Richard Clamp.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
       programming language system itself.