1Data::Compare::Plugins(U3s)er Contributed Perl DocumentatDiaotna::Compare::Plugins(3)
2
3
4

NAME

6       Data::Compare::Plugins - how to extend Data::Compare
7

DESCRIPTION

9       Data::Compare natively handles several built-in data types - scalars,
10       references to scalars, references to arrays, references to hashes,
11       references to subroutines, compiled regular expressions, and globs.
12       For objects, it tries to Do The Right Thing and compares the underlying
13       data type.  However, this is not always what you want.  This is
14       especially true if you have complex objects which overload
15       stringification and/or numification.
16
17       Hence we allow for plugins.
18

FINDING PLUGINS

20       Data::Compare will try to load any module installed on your system
21       under the various @INC/Data/Compare/Plugins/ directories.  If there is
22       a problem loading any of them, an appropriate warning will be issued.
23
24       Because of how we find plugins, no plugins are available when running
25       in "taint" mode.
26

WRITING PLUGINS

28       Internally, plugins are "require"d into Data::Compare.  This means that
29       they need to evaluate to true.  We make use of that true value.  Where
30       normally you just put:
31
32           1;
33
34       at the end of an included file, you should instead ensure that you
35       return a reference to an array.  This is treated as being true so
36       satisfies perl, and is a damned sight more useful.
37
38       Inside that array should be either a description of what this plugin is
39       to do, or references to several arrays containing such descriptions.  A
40       description consists of two or three items.  First a string telling us
41       what the first data-type handled by your plugin is.  Second, (and
42       optional, defaulting to the same as the first) the second data-type to
43       compare.  To handle comparisons to ordinary scalars, give the empty
44       string for the data-type, ie:
45
46           ['MyType', '', sub { ...}]
47
48       Third and last, we need a reference to the subroutine which does the
49       comparison.  That subroutine should expect to take two parameters,
50       which will be of the specified type.  It should return 1 if they
51       compare the same, or 0 if they compare different.
52
53       Be aware that while you might give a description like:
54
55           ['Type1', 'Type2', sub { ... }]
56
57       this will handle both comparing Type1 to Type2, and comparing Type2 to
58       Type1.  ie, comparison is commutative.
59
60       If you want to use Data::Compare's own comparison function from within
61       your handler (to, for example, compare a data structure that you have
62       stored somewhere in your object) then you will need to call it as
63       Data::Compare::Compare.  However, you must be careful to avoid infinite
64       recursion by calling D::C::Compare which in turn calls back to your
65       handler.
66
67       The name of your plugins does not matter, only that it lives in one of
68       those directories.  Of course, giving it a sensible name means that the
69       usual installation mechanisms will put it in the right place, and
70       meaningful names will make it easier to debug your code.
71
72       For an example, look at the plugin that handles Scalar::Properties
73       objects, which is distributed with Data::Compare.
74

DISTRIBUTION

76       Provided that the above rules are followed I see no reason for you to
77       not upload your plugin to the CPAN yourself.  You will need to make
78       Data::Compare a pre-requisite, so that the CPAN.pm installer does the
79       right thing.
80
81       Alternatively, if you would prefer me to roll your plugin in with the
82       Data::Compare distribution, I'd be happy to do so provided that the
83       code is clear and well-commented, and that you include tests and
84       documentation.
85

SEE ALSO

87       Data::Compare
88
89       Data::Compare::Plugins::Scalar::Properties
90

AUTHOR

92       Copyright (c) 2004 David Cantrell <david@cantrell.org.uk>.  All rights
93       reserved.  This program is free software; you can redistribute it
94       and/or modify it under the same terms as Perl itself.
95
96
97
98perl v5.36.0                      2023-03-15         Data::Compare::Plugins(3)
Impressum