/usr/share/perl5/Data/Compare/Plugins.pod is in libdata-compare-perl 1.25-0.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | =head1 NAME
Data::Compare::Plugins - how to extend Data::Compare
=head1 DESCRIPTION
Data::Compare natively handles several built-in data types - scalars,
references to scalars,
references to arrays, references to hashes, references to
subroutines, compiled regular expressions, and globs. For objects,
it tries to Do The Right Thing and compares the underlying data type.
However, this is not always what you want. This is especially true if
you have complex objects which overload stringification and/or
numification.
Hence we allow for plugins.
=head1 FINDING PLUGINS
Data::Compare will try to load any module installed on your system under
the various @INC/Data/Compare/Plugins/ directories. If there is a problem
loading any of them, an appropriate warning will be issued.
Because of how we find plugins, no plugins are available when running in
"taint" mode.
=head1 WRITING PLUGINS
Internally, plugins are C<require>d into Data::Compare. This means that
they need to evaluate to true. We make use of that true value. Where
normally you just put:
1;
at the end of an included file, you should instead ensure that you return
a reference to an array. This is treated as being true so satisfies perl,
and is a damned sight more useful.
Inside that array should be either a description of what this plugin is to
do, or references to several arrays containing such descriptions. A
description consists of two or three items. First a string telling
us what the first data-type handled by your plugin is. Second, (and
optional, defaulting to the same as the first) the second data-type
to compare. To handle comparisons to ordinary scalars, give the empty string
for the data-type, ie:
['MyType', '', sub { ...}]
Third and last, we need a reference to the
subroutine which does the comparison.
That subroutine should expect to take two parameters, which will be of
the specified type. It should return 1 if they compare
the same, or 0 if they compare different.
Be aware that while you might give a description like:
['Type1', 'Type2', sub { ... }]
this will handle both comparing Type1 to Type2, and comparing Type2 to
Type1. ie, comparison is commutative.
If you want to use Data::Compare's own comparison function from within
your handler (to, for example, compare a data structure that you have
stored somewhere in your object) then you will need to call it as
Data::Compare::Compare. However, you must be careful to avoid infinite
recursion by calling D::C::Compare which in turn calls back to your
handler.
The name of
your plugins does not matter, only that it lives in one of those directories.
Of course, giving it a sensible name means that the usual installation
mechanisms will put it in the right place, and meaningful names will make
it easier to debug your code.
For an example, look at the plugin that handles Scalar::Properties
objects, which is distributed with Data::Compare.
=head1 DISTRIBUTION
Provided that the above rules are followed I see no reason for you to not
upload your plugin to the CPAN yourself. You will need to make Data::Compare
a pre-requisite, so that the CPAN.pm installer does the right thing.
Alternatively, if you would prefer me to roll your plugin in with the
Data::Compare distribution, I'd be happy to do so provided that the code
is clear and well-commented, and that you include tests and documentation.
=head1 SEE ALSO
L<Data::Compare>
L<Data::Compare::Plugins::Scalar::Properties>
=head1 AUTHOR
Copyright (c) 2004 David Cantrell <david@cantrell.org.uk>.
All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=cut
|