Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Compare::PluginsUser Contributed Perl DocumentaData::Compare::Plugins(3)

NAME
       Data::Compare::Plugins -	how to extend Data::Compare

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.

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.

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

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.

perl v5.32.1			  2009-03-07	     Data::Compare::Plugins(3)

NAME | DESCRIPTION | FINDING PLUGINS | WRITING PLUGINS | DISTRIBUTION | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Compare::Plugins&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help