1 files changed, 91 insertions, 0 deletions
diff --git a/lib/File/Find/Rule/Extending.pod b/lib/File/Find/Rule/Extending.pod
new file mode 100644
index 0000000..7137859
--- /dev/null
+++ b/lib/File/Find/Rule/Extending.pod
@@ -0,0 +1,91 @@
+=head1 NAME
+
+File::Find::Rule::Extending - the mini-guide to extending File::Find::Rule
+
+=head1 SYNOPSIS
+
+ package File::Find::Rule::Random;
+ use strict;
+ 
+ # take useful things from File::Find::Rule
+ use base 'File::Find::Rule';
+
+ # and force our crack into the main namespace
+ sub File::Find::Rule::random () {
+     my $self = shift()->_force_object;
+     $self->exec( sub { rand > 0.5 } );
+ }
+ 
+ 1;
+
+=head1 DESCRIPTION
+
+File::Find::Rule went down so well with the buying public that
+everyone wanted to add extra features.  With the 0.07 release this
+became a possibility, using the following conventions.
+
+=head2 Declare your package
+
+ package File::Find::Rule::Random;
+ use strict;
+
+=head2 Inherit methods from File::Find::Rule
+
+ # take useful things from File::Find::Rule
+ use base 'File::Find::Rule';
+ 
+=head3 Force your madness into the main package
+
+ # and force our crack into the main namespace
+ sub File::Find::Rule::random () {
+     my $self = shift()->_force_object;
+     $self->exec( sub { rand > 0.5 } );
+ }
+ 
+
+Yes, we're being very cavalier here and defining things into the main
+File::Find::Rule namespace.  This is due to lack of imaginiation on my
+part - I simply can't find a way for the functional and oo interface
+to work without doing this or some kind of inheritance, and
+inheritance stops you using two File::Find::Rule::Foo modules
+together.
+
+For this reason try and pick distinct names for your extensions.  If
+this becomes a problem then I may institute a semi-official registry
+of taken names.
+
+=head2 Taking no arguments.
+
+Note the null prototype on random.  This is a cheat for the procedural
+interface to know that your sub takes no arguments, and so allows this
+to happen:
+
+ find( random => in => '.' );
+
+If you hadn't declared C<random> with a null prototype it would have
+consumed C<in> as a parameter to it, then got all confused as it
+doesn't know about a C<'.'> rule.
+
+=head1 AUTHOR
+
+Richard Clamp <richardc@unixbeard.net>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002 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.
+
+=head1 SEE ALSO
+
+L<File::Find::Rule>
+
+L<File::Find::Rule::MMagic> was the first extension module, so maybe
+check that out.
+
+=cut
+
+
+
+