local-lib5/lib/perl5/File/Find/Rule/Extending.pod

   1 =head1 NAME
   2
   3 File::Find::Rule::Extending - the mini-guide to extending File::Find::Rule
   4
   5 =head1 SYNOPSIS
   6
   7  package File::Find::Rule::Random;
   8  use strict;
   9
  10  # take useful things from File::Find::Rule
  11  use base 'File::Find::Rule';
  12
  13  # and force our crack into the main namespace
  14  sub File::Find::Rule::random () {
  15      my $self = shift()->_force_object;
  16      $self->exec( sub { rand > 0.5 } );
  17  }
  18
  19  1;
  20
  21 =head1 DESCRIPTION
  22
  23 File::Find::Rule went down so well with the buying public that
  24 everyone wanted to add extra features.  With the 0.07 release this
  25 became a possibility, using the following conventions.
  26
  27 =head2 Declare your package
  28
  29  package File::Find::Rule::Random;
  30  use strict;
  31
  32 =head2 Inherit methods from File::Find::Rule
  33
  34  # take useful things from File::Find::Rule
  35  use base 'File::Find::Rule';
  36
  37 =head3 Force your madness into the main package
  38
  39  # and force our crack into the main namespace
  40  sub File::Find::Rule::random () {
  41      my $self = shift()->_force_object;
  42      $self->exec( sub { rand > 0.5 } );
  43  }
  44
  45
  46 Yes, we're being very cavalier here and defining things into the main
  47 File::Find::Rule namespace.  This is due to lack of imaginiation on my
  48 part - I simply can't find a way for the functional and oo interface
  49 to work without doing this or some kind of inheritance, and
  50 inheritance stops you using two File::Find::Rule::Foo modules
  51 together.
  52
  53 For this reason try and pick distinct names for your extensions.  If
  54 this becomes a problem then I may institute a semi-official registry
  55 of taken names.
  56
  57 =head2 Taking no arguments.
  58
  59 Note the null prototype on random.  This is a cheat for the procedural
  60 interface to know that your sub takes no arguments, and so allows this
  61 to happen:
  62
  63  find( random => in => '.' );
  64
  65 If you hadn't declared C<random> with a null prototype it would have
  66 consumed C<in> as a parameter to it, then got all confused as it
  67 doesn't know about a C<'.'> rule.
  68
  69 =head1 AUTHOR
  70
  71 Richard Clamp <richardc@unixbeard.net>
  72
  73 =head1 COPYRIGHT
  74
  75 Copyright (C) 2002 Richard Clamp.  All Rights Reserved.
  76
  77 This module is free software; you can redistribute it and/or modify it
  78 under the same terms as Perl itself.
  79
  80 =head1 SEE ALSO
  81
  82 L<File::Find::Rule>
  83
  84 L<File::Find::Rule::MMagic> was the first extension module, so maybe
  85 check that out.
  86
  87 =cut
  88
  89
  90
  91