.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Algorithm::CheckDigits 3pm"
.TH Algorithm::CheckDigits 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Algorithm::CheckDigits \- Perl extension to generate and test check digits
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  perl \-MAlgorithm::CheckDigits \-e Algorithm::CheckDigits::print_methods
.Ve
.PP
or
.PP
.Vb 1
\&  use Algorithm::CheckDigits;
\&  
\&  @ml = Algorithm::CheckDigits\->method_list();
\&  %md = Algorithm::CheckDigits\->method_descriptions();
\&
\&  $isbn = CheckDigits(\*(AqISBN\*(Aq);
\&
\&  if ($isbn\->is_valid(\*(Aq3\-930673\-48\-7\*(Aq)) {
\&        # do something
\&  }
\&
\&  $cn = $isbn\->complete(\*(Aq3\-930673\-48\*(Aq);     # $cn = \*(Aq3\-930673\-48\-7\*(Aq
\&
\&  $cd = $isbn\->checkdigit(\*(Aq3\-930673\-48\-7\*(Aq); # $cd = \*(Aq7\*(Aq
\&
\&  $bn = $isbn\->basenumber(\*(Aq3\-930673\-48\-7\*(Aq); # $bn = \*(Aq3\-930673\-48\*(Aq
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
This module provides a number of methods to test and generate check
digits. For more information have a look at the web site
\&\fIwww.pruefziffernberechnung.de\fR (german).
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "CheckDigits($method)"
.IX Subsection "CheckDigits($method)"
Returns an object of an appropriate Algorithm::CheckDigits class for the
given algorithm.
.PP
Dies with an error message if called with an unknown algorithm.
.PP
See below for the available algorithms. Every object understands the following
methods:
.IP "is_valid($number)" 4
.IX Item "is_valid($number)"
Returns true or false if \f(CW$number\fR contains/contains no valid check digit.
.IP "complete($number)" 4
.IX Item "complete($number)"
Returns a string representation of \f(CW$number\fR completed with the appropriate
check digit.
.IP "checkdigit($number)" 4
.IX Item "checkdigit($number)"
Extracts the check digit from \f(CW$number\fR if \f(CW$number\fR contains a valid check
digit.
.IP "basenumber($number)" 4
.IX Item "basenumber($number)"
Extracts the basenumber from \f(CW$number\fR if \f(CW$number\fR contains a valid check
digit.
.ie n .SS "Algorithm::CheckDigits::plug_in($module, $description, $prefkey)"
.el .SS "Algorithm::CheckDigits::plug_in($module, \f(CW$description\fP, \f(CW$prefkey\fP)"
.IX Subsection "Algorithm::CheckDigits::plug_in($module, $description, $prefkey)"
Register a module that provides the same four methods as above. This function
returns a handle with which the registered module can be instantiated.
.PP
The first argument \f(CW$module\fR is the module to be used for this plugin. This
argument is mandatory. Do not register 'Algorithm::CheckDigits'.
.PP
The second argument is a short description of the algorithm. If it is omitted,
the string \f(CW\*(C`algorithm of module $module\*(C'\fR will be taken.
.PP
The third argument is the preferred key for this algorithm. The \f(CW\*(C`plug_in()\*(C'\fR
function does not guarantee to register the algorithm with this key. Instead
it returns the key under which the algorithm is registered.
.PP
See \*(L"\s-1REGISTERING PLUGINS\*(R"\s0 for more information on registering plugins.
.SS "\fBAlgorithm::CheckDigits::method_list()\fP"
.IX Subsection "Algorithm::CheckDigits::method_list()"
Returns a list of known methods for check digit computation.
.SS "\fBAlgorithm::CheckDigits::method_descriptions()\fP"
.IX Subsection "Algorithm::CheckDigits::method_descriptions()"
Returns a hash of descriptions for the known methods for check digit
computations. The keys of the hash are the values returned by
\&\f(CW\*(C`method_list()\*(C'\fR.
.SS "\fBAlgorithm::CheckDigits::print_methods()\fP"
.IX Subsection "Algorithm::CheckDigits::print_methods()"
Returns a list of known methods for check digit computation.
.PP
You may use the following to find out which methods your version of
Algorithm::CheckDigits provides and where to look for further
information.
.PP
.Vb 1
\& perl \-MAlgorithm::CheckDigits \-e Algorithm::CheckDigits::print_methods
.Ve
.SS "\s-1CHECK SUM METHODS\s0"
.IX Subsection "CHECK SUM METHODS"
At the moment these methods to compute check digits are provided:
(vatrn \- \s-1VAT\s0 Return Number, in german ustid UmsatzSTeuer-ID)
.IP "euronote" 4
.IX Item "euronote"
European bank notes, see Algorithm::CheckDigits::M09_001.
.IP "amex, bahncard, diners, discover, enroute, eurocard, happydigits, isin, jcb, klubkarstadt, mastercard, miles&more, visa, imei, imeisv" 4
.IX Item "amex, bahncard, diners, discover, enroute, eurocard, happydigits, isin, jcb, klubkarstadt, mastercard, miles&more, visa, imei, imeisv"
See Algorithm::CheckDigits::M10_001.
.IP "siren, siret" 4
.IX Item "siren, siret"
See Algorithm::CheckDigits::M10_002.
.IP "ismn" 4
.IX Item "ismn"
See Algorithm::CheckDigits::M10_003.
.IP "ean, iln, isbn13, nve, 2aus5" 4
.IX Item "ean, iln, isbn13, nve, 2aus5"
See Algorithm::CheckDigits::M10_004.
.IP "identcode_dp, leitcode_dp" 4
.IX Item "identcode_dp, leitcode_dp"
See Algorithm::CheckDigits::M10_005.
.IP "rentenversicherung" 4
.IX Item "rentenversicherung"
See Algorithm::CheckDigits::M10_006.
.IP "sedol" 4
.IX Item "sedol"
See Algorithm::CheckDigits::M10_008.
.IP "betriebsnummer" 4
.IX Item "betriebsnummer"
See Algorithm::CheckDigits::M10_009.
.IP "postscheckkonti" 4
.IX Item "postscheckkonti"
See Algorithm::CheckDigits::M10_010.
.IP "ups" 4
.IX Item "ups"
See Algorithm::CheckDigits::M10_011.
.IP "hkid, isbn, issn, nhs_gb, ustid_pt, vat_sl, wagonnr_br" 4
.IX Item "hkid, isbn, issn, nhs_gb, ustid_pt, vat_sl, wagonnr_br"
See Algorithm::CheckDigits::M11_001.
.IP "pzn" 4
.IX Item "pzn"
See Algorithm::CheckDigits::M11_002.
.IP "pkz" 4
.IX Item "pkz"
See Algorithm::CheckDigits::M11_003.
.IP "cpf, titulo_eleitor" 4
.IX Item "cpf, titulo_eleitor"
See Algorithm::CheckDigits::M11_004.
.IP "ccc_es" 4
.IX Item "ccc_es"
See Algorithm::CheckDigits::M11_006.
.IP "ustid_fi, vatrn_fi" 4
.IX Item "ustid_fi, vatrn_fi"
See Algorithm::CheckDigits::M11_007.
.IP "ustid_dk, vatrn_dk" 4
.IX Item "ustid_dk, vatrn_dk"
See Algorithm::CheckDigits::M11_008.
.IP "nric_sg" 4
.IX Item "nric_sg"
See Algorithm::CheckDigits::M11_009.
.IP "ahv_ch" 4
.IX Item "ahv_ch"
See Algorithm::CheckDigits::M11_010.
.IP "ustid_nl, vatrn_nl" 4
.IX Item "ustid_nl, vatrn_nl"
See Algorithm::CheckDigits::M11_011.
.IP "bwpk_de" 4
.IX Item "bwpk_de"
See Algorithm::CheckDigits::M11_012.
.IP "ustid_gr, vatrn_gr" 4
.IX Item "ustid_gr, vatrn_gr"
See Algorithm::CheckDigits::M11_013.
.IP "esr5_ch" 4
.IX Item "esr5_ch"
See Algorithm::CheckDigits::M11_015.
.IP "ustid_pl, vatrn_pl" 4
.IX Item "ustid_pl, vatrn_pl"
See Algorithm::CheckDigits::M11_016.
.IP "ecno, ec-no, einecs, elincs" 4
.IX Item "ecno, ec-no, einecs, elincs"
See Algorithm::CheckDigits::M11_017.
.IP "isan" 4
.IX Item "isan"
See Algorithm::CheckDigits::M16_001.
.IP "dni_es" 4
.IX Item "dni_es"
See Algorithm::CheckDigits::M23_001.
.IP "ustid_ie, vatrn_ie" 4
.IX Item "ustid_ie, vatrn_ie"
See Algorithm::CheckDigits::M23_002.
.IP "code_39" 4
.IX Item "code_39"
See Algorithm::CheckDigits::M43_001.
.IP "ustid_lu, vatrn_lu" 4
.IX Item "ustid_lu, vatrn_lu"
See Algorithm::CheckDigits::M89_001.
.IP "ustid_be, vatrn_be" 4
.IX Item "ustid_be, vatrn_be"
See Algorithm::CheckDigits::M97_001.
.IP "iban" 4
.IX Item "iban"
See Algorithm::CheckDigits::M97_002.
.IP "upc" 4
.IX Item "upc"
See Algorithm::CheckDigits::MBase_001.
.IP "blutbeutel, bzue_de, ustid_de, vatrn_de" 4
.IX Item "blutbeutel, bzue_de, ustid_de, vatrn_de"
See Algorithm::CheckDigits::MBase_002.
.IP "sici" 4
.IX Item "sici"
See Algorithm::CheckDigits::MBase_003.
.IP "pa_de" 4
.IX Item "pa_de"
See Algorithm::CheckDigits::MXX_001.
.IP "cas" 4
.IX Item "cas"
See Algorithm::CheckDigits::MXX_002.
.IP "dem" 4
.IX Item "dem"
Old german bank notes (\s-1DEM\s0), see Algorithm::CheckDigits::MXX_003.
.IP "ustid_at, vatrn_at" 4
.IX Item "ustid_at, vatrn_at"
See Algorithm::CheckDigits::MXX_004.
.IP "esr9_ch" 4
.IX Item "esr9_ch"
See Algorithm::CheckDigits::MXX_005.
.IP "verhoeff" 4
.IX Item "verhoeff"
Verhoeff scheme, see Algorithm::CheckDigits::MXX_006 or
Algorithm::Verhoeff
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
This module exports the Function \f(CW\*(C`CheckDigits()\*(C'\fR that is used to create an
instance of a checker with the given algorithm.
.SH "REGISTERING PLUGINS"
.IX Header "REGISTERING PLUGINS"
Brian T. Wightman was the first, asking me to add a plugin registry to
Algorithm::CheckDigits and so I added the function \f(CW\*(C`plug_in()\*(C'\fR that does just
this, registering plug in modules to be used just like the modules in the
distribution of this module.
.PP
Providing some means to add additional algorithms without the need to change
the module has the benefit that the user of those additional algorithms may
easily use them with the same interface as the other algorithms without having
to wait for a new version, that may or may not include the wanted algorithm.
.PP
But there is a problem: the user must be able to select the new algorithms
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 \f(CW\*(C`plug_in()\*(C'\fR 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 \f(CW\*(C`plug_in()\*(C'\fR function.
.PP
This could go like this in the module:
.PP
.Vb 1
\& package Algorithm::XyZ;
\&
\& use Algorithm::CheckDigits;
\&
\& our $xyz = Algorithm::CheckDigits::plug_in(\*(AqAlgorithm::XyZ\*(Aq,
\&                                            \*(AqXyZ check digits\*(Aq,
\&                                            \*(Aqxyz\*(Aq);
.Ve
.PP
And the user of this algorithm would write something like this:
.PP
.Vb 2
\& use Algorithm::CheckDigits;
\& use Algorithm::XyZ;
\&
\& my $cd = CheckDigits($Algorithm::XyZ::xyz);
\&
\& if ($cd\->is_valid($some_number)) {
\&     # do something
\& }
.Ve
.PP
Please have a look at the plugin tests in the test directory (\fIt/plugin*.t\fR)
and the accompanying modules (\fIt/PluginLib*.pm\fR) for example usage. You may
also try to load an additional module with the scripts in \fIbin\fR and
\&\fIcgi-bin\fR and look for the additional algorithms in the output:
.PP
.Vb 1
\& perl \-Ilib \-It \-MPluginLibA bin/checkdigits.pl list
\&
\& perl \-Ilib \-It \-MPluginLibA cgi\-bin/checkdigits.cgi
.Ve
.SS "Namespace"
.IX Subsection "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl,
\&\fIwww.pruefziffernberechnung.de\fR.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
The function \f(CW\*(C`plug_in()\*(C'\fR dies if you try to register the module
\&'Algorithm::CheckDigits'.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-algorithm\-checkdigits@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mathias Weidner, \f(CW\*(C`mamawe@cpan.org\*(C'\fR
.SH "THANKS"
.IX Header "THANKS"
Petri Oksanen made me aware that CheckDigits('\s-1IMEI\s0') would invoke no test at
all since there was no entry for this in the methods hash.
.PP
Brian T. Wightman made me think about and implement the plugin interface.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2004\-2020 by Mathias Weidner
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself. See perlartistic.