view release on metacpan or  search on metacpan

lib/Algorithm/CheckDigits.pm  view on Meta::CPAN

like he did with the other ones. And the catch is: since these new algorithms
are developed independently there is no guarantee that no more than one
module applies for the same handle. I could have implemented some simple
strategies like last one wins (the module that registers last for a given
handle is the one that is choosen) or first one wins (the first registered
module is choosen). Instead I went for something more complex to assure that
every module that wants to get registered will be registered and that every
registered module will be accessible by the same handle as long as the program
runs. To make this work C<plug_in()> sees the third argument only as a hint
how the handle should look like, when a module is registered. It returns the
real handle with which the algorithm can be instantiated. That means a
developer of a plugin module cannot make the handle immediately available like
I did for the modules in the distribution. Instead there should be something
like a public variable or function that returns the handle as it came back
from the C<plug_in()> function.

This could go like this in the module:

 package Algorithm::XyZ;

 use Algorithm::CheckDigits;

 our $xyz = Algorithm::CheckDigits::plug_in('Algorithm::XyZ',
                                            'XyZ check digits',
                                            'xyz');

And the user of this algorithm would write something like this:

 use Algorithm::CheckDigits;
 use Algorithm::XyZ;

 my $cd = CheckDigits($Algorithm::XyZ::xyz);

 if ($cd->is_valid($some_number)) {
     # do something
 }

Please have a look at the plugin tests in the test directory (I<t/plugin*.t>)
and the accompanying modules (I<t/PluginLib*.pm>) for example usage. You may
also try to load an additional module with the scripts in I<bin> and
I<cgi-bin> and look for the additional algorithms in the output:

 perl -Ilib -It -MPluginLibA bin/checkdigits.pl list

 perl -Ilib -It -MPluginLibA cgi-bin/checkdigits.cgi

=head2 Namespace

I would like to ask you to use any namespace below or outside but not direct
Algorithm::CheckDigits. That means for instance for the XyZ algorithm,
Algorithm::XyZ would be fine, Algorithm::CheckDigits::Plugin::XyZ or
Algorithm::CheckDigits::X::XyZ would be fine too. But
Algorithm::CheckDigits::XyZ could collide with some future version of the
Algorithm::CheckDigits distribution, so please avoid this namespace.

=head1 SEE ALSO

L<perl>,
F<www.pruefziffernberechnung.de>.

=head1 BUGS AND LIMITATIONS

The function C<plug_in()> dies if you try to register the module
'Algorithm::CheckDigits'.

Please report any bugs or feature requests to
C<bug-algorithm-checkdigits@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org>.

=head1 AUTHOR

Mathias Weidner, C<< mamawe@cpan.org >>

=head1 THANKS

Petri Oksanen made me aware that CheckDigits('IMEI') would invoke no test at
all since there was no entry for this in the methods hash.

Brian T. Wightman made me think about and implement the plugin interface.

=head1 COPYRIGHT AND LICENSE

Copyright 2004-2020 by Mathias Weidner

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. See L<perlartistic>.

=cut