local-lib5/man/man3/File::Find::Rule.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "File::Find::Rule 3"
 127 .TH File::Find::Rule 3 "2009-11-28" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 File::Find::Rule \- Alternative interface to File::Find
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  use File::Find::Rule;
 138 \&  # find all the subdirectories of a given directory
 139 \&  my @subdirs = File::Find::Rule\->directory\->in( $directory );
 140 \&
 141 \&  # find all the .pm files in @INC
 142 \&  my @files = File::Find::Rule\->file()
 143 \&                              \->name( \*(Aq*.pm\*(Aq )
 144 \&                              \->in( @INC );
 145 \&
 146 \&  # as above, but without method chaining
 147 \&  my $rule =  File::Find::Rule\->new;
 148 \&  $rule\->file;
 149 \&  $rule\->name( \*(Aq*.pm\*(Aq );
 150 \&  my @files = $rule\->in( @INC );
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 File::Find::Rule is a friendlier interface to File::Find.  It allows
 155 you to build rules which specify the desired files and directories.
 156 .SH "METHODS"
 157 .IX Header "METHODS"
 158 .ie n .IP """new""" 4
 159 .el .IP "\f(CWnew\fR" 4
 160 .IX Item "new"
 161 A constructor.  You need not invoke \f(CW\*(C`new\*(C'\fR manually unless you wish
 162 to, as each of the rule-making methods will auto-create a suitable
 163 object if called as class methods.
 164 .SS "Matching Rules"
 165 .IX Subsection "Matching Rules"
 166 .ie n .IP """name( @patterns )""" 4
 167 .el .IP "\f(CWname( @patterns )\fR" 4
 168 .IX Item "name( @patterns )"
 169 Specifies names that should match.  May be globs or regular
 170 expressions.
 171 .Sp
 172 .Vb 3
 173 \& $set\->name( \*(Aq*.mp3\*(Aq, \*(Aq*.ogg\*(Aq ); # mp3s or oggs
 174 \& $set\->name( qr/\e.(mp3|ogg)$/ ); # the same as a regex
 175 \& $set\->name( \*(Aqfoo.bar\*(Aq );        # just things named foo.bar
 176 .Ve
 177 .IP "\-X tests" 4
 178 .IX Item "-X tests"
 179 Synonyms are provided for each of the \-X tests. See \*(L"\-X\*(R" in perlfunc for
 180 details.  None of these methods take arguments.
 181 .Sp
 182 .Vb 10
 183 \&  Test | Method               Test |  Method
 184 \& \-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-        \-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 185 \&   \-r  |  readable             \-R  |  r_readable
 186 \&   \-w  |  writeable            \-W  |  r_writeable
 187 \&   \-w  |  writable             \-W  |  r_writable
 188 \&   \-x  |  executable           \-X  |  r_executable
 189 \&   \-o  |  owned                \-O  |  r_owned
 190 \&       |                           |
 191 \&   \-e  |  exists               \-f  |  file
 192 \&   \-z  |  empty                \-d  |  directory
 193 \&   \-s  |  nonempty             \-l  |  symlink
 194 \&       |                       \-p  |  fifo
 195 \&   \-u  |  setuid               \-S  |  socket
 196 \&   \-g  |  setgid               \-b  |  block
 197 \&   \-k  |  sticky               \-c  |  character
 198 \&       |                       \-t  |  tty
 199 \&   \-M  |  modified                 |
 200 \&   \-A  |  accessed             \-T  |  ascii
 201 \&   \-C  |  changed              \-B  |  binary
 202 .Ve
 203 .Sp
 204 Though some tests are fairly meaningless as binary flags (\f(CW\*(C`modified\*(C'\fR,
 205 \&\f(CW\*(C`accessed\*(C'\fR, \f(CW\*(C`changed\*(C'\fR), they have been included for completeness.
 206 .Sp
 207 .Vb 3
 208 \& # find nonempty files
 209 \& $rule\->file,
 210 \&      \->nonempty;
 211 .Ve
 212 .IP "stat tests" 4
 213 .IX Item "stat tests"
 214 The following \f(CW\*(C`stat\*(C'\fR based methods are provided: \f(CW\*(C`dev\*(C'\fR, \f(CW\*(C`ino\*(C'\fR,
 215 \&\f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`nlink\*(C'\fR, \f(CW\*(C`uid\*(C'\fR, \f(CW\*(C`gid\*(C'\fR, \f(CW\*(C`rdev\*(C'\fR, \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`atime\*(C'\fR,
 216 \&\f(CW\*(C`mtime\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`blksize\*(C'\fR, and \f(CW\*(C`blocks\*(C'\fR.  See \*(L"stat\*(R" in perlfunc
 217 for details.
 218 .Sp
 219 Each of these can take a number of targets, which will follow
 220 Number::Compare semantics.
 221 .Sp
 222 .Vb 5
 223 \& $rule\->size( 7 );         # exactly 7
 224 \& $rule\->size( ">7Ki" );    # larger than 7 * 1024 * 1024 bytes
 225 \& $rule\->size( ">=7" )
 226 \&      \->size( "<=90" );    # between 7 and 90, inclusive
 227 \& $rule\->size( 7, 9, 42 );  # 7, 9 or 42
 228 .Ve
 229 .ie n .IP """any( @rules )""" 4
 230 .el .IP "\f(CWany( @rules )\fR" 4
 231 .IX Item "any( @rules )"
 232 .PD 0
 233 .ie n .IP """or( @rules )""" 4
 234 .el .IP "\f(CWor( @rules )\fR" 4
 235 .IX Item "or( @rules )"
 236 .PD
 237 Allows shortcircuiting boolean evaluation as an alternative to the
 238 default and-like nature of combined rules.  \f(CW\*(C`any\*(C'\fR and \f(CW\*(C`or\*(C'\fR are
 239 interchangeable.
 240 .Sp
 241 .Vb 5
 242 \& # find avis, movs, things over 200M and empty files
 243 \& $rule\->any( File::Find::Rule\->name( \*(Aq*.avi\*(Aq, \*(Aq*.mov\*(Aq ),
 244 \&             File::Find::Rule\->size( \*(Aq>200M\*(Aq ),
 245 \&             File::Find::Rule\->file\->empty,
 246 \&           );
 247 .Ve
 248 .ie n .IP """none( @rules )""" 4
 249 .el .IP "\f(CWnone( @rules )\fR" 4
 250 .IX Item "none( @rules )"
 251 .PD 0
 252 .ie n .IP """not( @rules )""" 4
 253 .el .IP "\f(CWnot( @rules )\fR" 4
 254 .IX Item "not( @rules )"
 255 .PD
 256 Negates a rule.  (The inverse of \f(CW\*(C`any\*(C'\fR.)  \f(CW\*(C`none\*(C'\fR and \f(CW\*(C`not\*(C'\fR are
 257 interchangeable.
 258 .Sp
 259 .Vb 3
 260 \&  # files that aren\*(Aqt 8.3 safe
 261 \&  $rule\->file
 262 \&       \->not( $rule\->new\->name( qr/^[^.]{1,8}(\e.[^.]{0,3})?$/ ) );
 263 .Ve
 264 .ie n .IP """prune""" 4
 265 .el .IP "\f(CWprune\fR" 4
 266 .IX Item "prune"
 267 Traverse no further.  This rule always matches.
 268 .ie n .IP """discard""" 4
 269 .el .IP "\f(CWdiscard\fR" 4
 270 .IX Item "discard"
 271 Don't keep this file.  This rule always matches.
 272 .ie n .IP """exec( \e&subroutine( $shortname, $path, $fullname ) )""" 4
 273 .el .IP "\f(CWexec( \e&subroutine( $shortname, $path, $fullname ) )\fR" 4
 274 .IX Item "exec( &subroutine( $shortname, $path, $fullname ) )"
 275 Allows user-defined rules.  Your subroutine will be invoked with \f(CW$_\fR
 276 set to the current short name, and with parameters of the name, the
 277 path you're in, and the full relative filename.
 278 .Sp
 279 Return a true value if your rule matched.
 280 .Sp
 281 .Vb 2
 282 \& # get things with long names
 283 \& $rules\->exec( sub { length > 20 } );
 284 .Ve
 285 .ie n .IP """grep( @specifiers )""" 4
 286 .el .IP "\f(CWgrep( @specifiers )\fR" 4
 287 .IX Item "grep( @specifiers )"
 288 Opens a file and tests it each line at a time.
 289 .Sp
 290 For each line it evaluates each of the specifiers, stopping at the
 291 first successful match.  A specifier may be a regular expression or a
 292 subroutine.  The subroutine will be invoked with the same parameters
 293 as an \->exec subroutine.
 294 .Sp
 295 It is possible to provide a set of negative specifiers by enclosing
 296 them in anonymous arrays.  Should a negative specifier match the
 297 iteration is aborted and the clause is failed.  For example:
 298 .Sp
 299 .Vb 1
 300 \& $rule\->grep( qr/^#!.*\ebperl/, [ sub { 1 } ] );
 301 .Ve
 302 .Sp
 303 Is a passing clause if the first line of a file looks like a perl
 304 shebang line.
 305 .ie n .IP """maxdepth( $level )""" 4
 306 .el .IP "\f(CWmaxdepth( $level )\fR" 4
 307 .IX Item "maxdepth( $level )"
 308 Descend at most \f(CW$level\fR (a non-negative integer) levels of directories
 309 below the starting point.
 310 .Sp
 311 May be invoked many times per rule, but only the most recent value is
 312 used.
 313 .ie n .IP """mindepth( $level )""" 4
 314 .el .IP "\f(CWmindepth( $level )\fR" 4
 315 .IX Item "mindepth( $level )"
 316 Do not apply any tests at levels less than \f(CW$level\fR (a non-negative
 317 integer).
 318 .ie n .IP """extras( \e%extras )""" 4
 319 .el .IP "\f(CWextras( \e%extras )\fR" 4
 320 .IX Item "extras( %extras )"
 321 Specifies extra values to pass through to \f(CW\*(C`File::File::find\*(C'\fR as part
 322 of the options hash.
 323 .Sp
 324 For example this allows you to specify following of symlinks like so:
 325 .Sp
 326 .Vb 1
 327 \& my $rule = File::Find::Rule\->extras({ follow => 1 });
 328 .Ve
 329 .Sp
 330 May be invoked many times per rule, but only the most recent value is
 331 used.
 332 .ie n .IP """relative""" 4
 333 .el .IP "\f(CWrelative\fR" 4
 334 .IX Item "relative"
 335 Trim the leading portion of any path found
 336 .ie n .IP """not_*""" 4
 337 .el .IP "\f(CWnot_*\fR" 4
 338 .IX Item "not_*"
 339 Negated version of the rule.  An effective shortand related to ! in
 340 the procedural interface.
 341 .Sp
 342 .Vb 1
 343 \& $foo\->not_name(\*(Aq*.pl\*(Aq);
 344 \&
 345 \& $foo\->not( $foo\->new\->name(\*(Aq*.pl\*(Aq ) );
 346 .Ve
 347 .SS "Query Methods"
 348 .IX Subsection "Query Methods"
 349 .ie n .IP """in( @directories )""" 4
 350 .el .IP "\f(CWin( @directories )\fR" 4
 351 .IX Item "in( @directories )"
 352 Evaluates the rule, returns a list of paths to matching files and
 353 directories.
 354 .ie n .IP """start( @directories )""" 4
 355 .el .IP "\f(CWstart( @directories )\fR" 4
 356 .IX Item "start( @directories )"
 357 Starts a find across the specified directories.  Matching items may
 358 then be queried using \*(L"match\*(R".  This allows you to use a rule as an
 359 iterator.
 360 .Sp
 361 .Vb 4
 362 \& my $rule = File::Find::Rule\->file\->name("*.jpeg")\->start( "/web" );
 363 \& while ( defined ( my $image = $rule\->match ) ) {
 364 \&     ...
 365 \& }
 366 .Ve
 367 .ie n .IP """match""" 4
 368 .el .IP "\f(CWmatch\fR" 4
 369 .IX Item "match"
 370 Returns the next file which matches, false if there are no more.
 371 .SS "Extensions"
 372 .IX Subsection "Extensions"
 373 Extension modules are available from \s-1CPAN\s0 in the File::Find::Rule
 374 namespace.  In order to use these extensions either use them directly:
 375 .PP
 376 .Vb 2
 377 \& use File::Find::Rule::ImageSize;
 378 \& use File::Find::Rule::MMagic;
 379 \&
 380 \& # now your rules can use the clauses supplied by the ImageSize and
 381 \& # MMagic extension
 382 .Ve
 383 .PP
 384 or, specify that File::Find::Rule should load them for you:
 385 .PP
 386 .Vb 1
 387 \& use File::Find::Rule qw( :ImageSize :MMagic );
 388 .Ve
 389 .PP
 390 For notes on implementing your own extensions, consult
 391 File::Find::Rule::Extending
 392 .SS "Further examples"
 393 .IX Subsection "Further examples"
 394 .IP "Finding perl scripts" 4
 395 .IX Item "Finding perl scripts"
 396 .Vb 10
 397 \& my $finder = File::Find::Rule\->or
 398 \&  (
 399 \&   File::Find::Rule\->name( \*(Aq*.pl\*(Aq ),
 400 \&   File::Find::Rule\->exec(
 401 \&                          sub {
 402 \&                              if (open my $fh, $_) {
 403 \&                                  my $shebang = <$fh>;
 404 \&                                  close $fh;
 405 \&                                  return $shebang =~ /^#!.*\ebperl/;
 406 \&                              }
 407 \&                              return 0;
 408 \&                          } ),
 409 \&  );
 410 .Ve
 411 .Sp
 412 Based upon this message http://use.perl.org/comments.pl?sid=7052&cid=10842
 413 .IP "ignore \s-1CVS\s0 directories" 4
 414 .IX Item "ignore CVS directories"
 415 .Vb 7
 416 \& my $rule = File::Find::Rule\->new;
 417 \& $rule\->or($rule\->new
 418 \&                \->directory
 419 \&                \->name(\*(AqCVS\*(Aq)
 420 \&                \->prune
 421 \&                \->discard,
 422 \&           $rule\->new);
 423 .Ve
 424 .Sp
 425 Note here the use of a null rule.  Null rules match anything they see,
 426 so the effect is to match (and discard) directories called '\s-1CVS\s0' or to
 427 match anything.
 428 .SH "TWO FOR THE PRICE OF ONE"
 429 .IX Header "TWO FOR THE PRICE OF ONE"
 430 File::Find::Rule also gives you a procedural interface.  This is
 431 documented in File::Find::Rule::Procedural
 432 .SH "EXPORTS"
 433 .IX Header "EXPORTS"
 434 \&\*(L"find\*(R", \*(L"rule\*(R"
 435 .SH "TAINT MODE INTERACTION"
 436 .IX Header "TAINT MODE INTERACTION"
 437 As of 0.32 File::Find::Rule doesn't capture the current working directory in
 438 a taint-unsafe manner.  File::Find itself still does operations that the taint
 439 system will flag as insecure but you can use the \*(L"extras\*(R" feature to ask
 440 File::Find to internally \f(CW\*(C`untaint\*(C'\fR file paths with a regex like so:
 441 .PP
 442 .Vb 1
 443 \&    my $rule = File::Find::Rule\->extras({ untaint => 1 });
 444 .Ve
 445 .PP
 446 Please consult File::Find's documentation for \f(CW\*(C`untaint\*(C'\fR,
 447 \&\f(CW\*(C`untaint_pattern\*(C'\fR, and \f(CW\*(C`untaint_skip\*(C'\fR for more information.
 448 .SH "BUGS"
 449 .IX Header "BUGS"
 450 The code makes use of the \f(CW\*(C`our\*(C'\fR keyword and as such requires perl version
 451 5.6.0 or newer.
 452 .PP
 453 Currently it isn't possible to remove a clause from a rule object.  If
 454 this becomes a significant issue it will be addressed.
 455 .SH "AUTHOR"
 456 .IX Header "AUTHOR"
 457 Richard Clamp <richardc@unixbeard.net> with input gained from this
 458 use.perl discussion: http://use.perl.org/~richardc/journal/6467
 459 .PP
 460 Additional proofreading and input provided by Kake, Greg McCarroll,
 461 and Andy Lester andy@petdance.com.
 462 .SH "COPYRIGHT"
 463 .IX Header "COPYRIGHT"
 464 Copyright (C) 2002, 2003, 2004, 2006, 2009 Richard Clamp.  All Rights Reserved.
 465 .PP
 466 This module is free software; you can redistribute it and/or modify it
 467 under the same terms as Perl itself.
 468 .SH "SEE ALSO"
 469 .IX Header "SEE ALSO"
 470 File::Find, Text::Glob, Number::Compare, \fIfind\fR\|(1)
 471 .PP
 472 If you want to know about the procedural interface, see
 473 File::Find::Rule::Procedural, and if you have an idea for a neat
 474 extension File::Find::Rule::Extending