Data::C...Plugins(3)

💖 NAME 💖

okay bestie, welcome to the Data::Compare::Plugins(3) page — this one is literally all about how to extend Data::Compare. No cap. 🫶

🌸 DESCRIPTION 🌸

So 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. But lowkey? That’s not always what you want — and it’s especially true if you have complex objects which overload stringification and/or numification. 😭

Hence we allow for plugins. periodt. 💅

🦋 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. wild, but that’s the rule. 🫠

🎀 WRITING PLUGINS 🎀

Internally, plugins are "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:

1. First, a string telling us what the first data-type handled by your plugin is. 💖
2. Second — and this one is optional, defaulting to the same as the first — the second data-type to compare. 🎀
3. Third and last, we need a reference to the subroutine which does the comparison. 🦋

To handle comparisons to ordinary scalars, give the empty string for the data-type, ie:

['MyType', '', sub { ...}]

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. 💫

⚠️ infinite recursion alert, bestie: 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. 🦋

🌈 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. 🌸

💜 SEE ALSO 💜

• Data::Compare
• Data::Compare::Plugins::Scalar::Properties

👑 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. 💅

---

mwah 💋 — this page is from perl v5.42.0, dated 2023-04-22. now go be a plugin main character, bestie 💅✨