1Algorithm::CheckDigits(U3s)er Contributed Perl DocumentatAilognorithm::CheckDigits(3)
2
3
4

NAME

6       Algorithm::CheckDigits - Perl extension to generate and test check
7       digits
8

SYNOPSIS

10         perl -MAlgorithm::CheckDigits -e Algorithm::CheckDigits::print_methods
11
12       or
13
14         use Algorithm::CheckDigits;
15
16         @ml = Algorithm::CheckDigits->method_list();
17         %md = Algorithm::CheckDigits->method_descriptions();
18
19         $isbn = CheckDigits('ISBN');
20
21         if ($isbn->is_valid('3-930673-48-7')) {
22               # do something
23         }
24
25         $cn = $isbn->complete('3-930673-48');     # $cn = '3-930673-48-7'
26
27         $cd = $isbn->checkdigit('3-930673-48-7'); # $cd = '7'
28
29         $bn = $isbn->basenumber('3-930673-48-7'); # $bn = '3-930673-48'
30

ABSTRACT

32       This module provides a number of methods to test and generate check
33       digits. For more information have a look at the web site
34       www.pruefziffernberechnung.de (german).
35

SUBROUTINES/METHODS

37   CheckDigits($method)
38       Returns an object of an appropriate Algorithm::CheckDigits class for
39       the given algorithm.
40
41       Dies with an error message if called with an unknown algorithm.
42
43       See below for the available algorithms. Every object understands the
44       following methods:
45
46       is_valid($number)
47           Returns true or false if $number contains/contains no valid check
48           digit.
49
50       complete($number)
51           Returns a string representation of $number completed with the
52           appropriate check digit.
53
54       checkdigit($number)
55           Extracts the check digit from $number if $number contains a valid
56           check digit.
57
58       basenumber($number)
59           Extracts the basenumber from $number if $number contains a valid
60           check digit.
61
62   Algorithm::CheckDigits::plug_in($module, $description, $prefkey)
63       Register a module that provides the same four methods as above. This
64       function returns a handle with which the registered module can be
65       instantiated.
66
67       The first argument $module is the module to be used for this plugin.
68       This argument is mandatory. Do not register 'Algorithm::CheckDigits'.
69
70       The second argument is a short description of the algorithm. If it is
71       omitted, the string "algorithm of module $module" will be taken.
72
73       The third argument is the preferred key for this algorithm. The
74       "plug_in()" function does not guarantee to register the algorithm with
75       this key. Instead it returns the key under which the algorithm is
76       registered.
77
78       See "REGISTERING PLUGINS" for more information on registering plugins.
79
80   Algorithm::CheckDigits::method_list()
81       Returns a list of known methods for check digit computation.
82
83   Algorithm::CheckDigits::method_descriptions()
84       Returns a hash of descriptions for the known methods for check digit
85       computations. The keys of the hash are the values returned by
86       "method_list()".
87
88   Algorithm::CheckDigits::print_methods()
89       Returns a list of known methods for check digit computation.
90
91       You may use the following to find out which methods your version of
92       Algorithm::CheckDigits provides and where to look for further
93       information.
94
95        perl -MAlgorithm::CheckDigits -e Algorithm::CheckDigits::print_methods
96
97   CHECK SUM METHODS
98       At the moment these methods to compute check digits are provided:
99       (vatrn - VAT Return Number, in german ustid UmsatzSTeuer-ID)
100
101       euronote
102           European bank notes, see Algorithm::CheckDigits::M09_001.
103
104       amex, bahncard, diners, discover, enroute, eurocard, happydigits, isin,
105       jcb, klubkarstadt, mastercard, miles&more, visa, imei, imeisv
106           See Algorithm::CheckDigits::M10_001.
107
108       siren, siret
109           See Algorithm::CheckDigits::M10_002.
110
111       ismn
112           See Algorithm::CheckDigits::M10_003.
113
114       ean, iln, isbn13, nve, 2aus5
115           See Algorithm::CheckDigits::M10_004.
116
117       identcode_dp, leitcode_dp
118           See Algorithm::CheckDigits::M10_005.
119
120       rentenversicherung
121           See Algorithm::CheckDigits::M10_006.
122
123       sedol
124           See Algorithm::CheckDigits::M10_008.
125
126       betriebsnummer
127           See Algorithm::CheckDigits::M10_009.
128
129       postscheckkonti
130           See Algorithm::CheckDigits::M10_010.
131
132       ups See Algorithm::CheckDigits::M10_011.
133
134       hkid, isbn, issn, nhs_gb, ustid_pt, vat_sl, wagonnr_br
135           See Algorithm::CheckDigits::M11_001.
136
137       pzn See Algorithm::CheckDigits::M11_002.
138
139       pkz See Algorithm::CheckDigits::M11_003.
140
141       cpf, titulo_eleitor
142           See Algorithm::CheckDigits::M11_004.
143
144       ccc_es
145           See Algorithm::CheckDigits::M11_006.
146
147       ustid_fi, vatrn_fi
148           See Algorithm::CheckDigits::M11_007.
149
150       ustid_dk, vatrn_dk
151           See Algorithm::CheckDigits::M11_008.
152
153       nric_sg
154           See Algorithm::CheckDigits::M11_009.
155
156       ahv_ch
157           See Algorithm::CheckDigits::M11_010.
158
159       ustid_nl, vatrn_nl
160           See Algorithm::CheckDigits::M11_011.
161
162       bwpk_de
163           See Algorithm::CheckDigits::M11_012.
164
165       ustid_gr, vatrn_gr
166           See Algorithm::CheckDigits::M11_013.
167
168       esr5_ch
169           See Algorithm::CheckDigits::M11_015.
170
171       ustid_pl, vatrn_pl
172           See Algorithm::CheckDigits::M11_016.
173
174       ecno, ec-no, einecs, elincs
175           See Algorithm::CheckDigits::M11_017.
176
177       isan
178           See Algorithm::CheckDigits::M16_001.
179
180       dni_es
181           See Algorithm::CheckDigits::M23_001.
182
183       ustid_ie, vatrn_ie
184           See Algorithm::CheckDigits::M23_002.
185
186       code_39
187           See Algorithm::CheckDigits::M43_001.
188
189       ustid_lu, vatrn_lu
190           See Algorithm::CheckDigits::M89_001.
191
192       ustid_be, vatrn_be
193           See Algorithm::CheckDigits::M97_001.
194
195       iban
196           See Algorithm::CheckDigits::M97_002.
197
198       upc See Algorithm::CheckDigits::MBase_001.
199
200       blutbeutel, bzue_de, ustid_de, vatrn_de
201           See Algorithm::CheckDigits::MBase_002.
202
203       sici
204           See Algorithm::CheckDigits::MBase_003.
205
206       pa_de
207           See Algorithm::CheckDigits::MXX_001.
208
209       cas See Algorithm::CheckDigits::MXX_002.
210
211       dem Old german bank notes (DEM), see Algorithm::CheckDigits::MXX_003.
212
213       ustid_at, vatrn_at
214           See Algorithm::CheckDigits::MXX_004.
215
216       esr9_ch
217           See Algorithm::CheckDigits::MXX_005.
218
219       verhoeff
220           Verhoeff scheme, see Algorithm::CheckDigits::MXX_006 or
221           Algorithm::Verhoeff
222
223   EXPORT
224       This module exports the Function "CheckDigits()" that is used to create
225       an instance of a checker with the given algorithm.
226

REGISTERING PLUGINS

228       Brian T. Wightman was the first, asking me to add a plugin registry to
229       Algorithm::CheckDigits and so I added the function "plug_in()" that
230       does just this, registering plug in modules to be used just like the
231       modules in the distribution of this module.
232
233       Providing some means to add additional algorithms without the need to
234       change the module has the benefit that the user of those additional
235       algorithms may easily use them with the same interface as the other
236       algorithms without having to wait for a new version, that may or may
237       not include the wanted algorithm.
238
239       But there is a problem: the user must be able to select the new
240       algorithms like he did with the other ones. And the catch is: since
241       these new algorithms are developed independently there is no guarantee
242       that no more than one module applies for the same handle. I could have
243       implemented some simple strategies like last one wins (the module that
244       registers last for a given handle is the one that is choosen) or first
245       one wins (the first registered module is choosen). Instead I went for
246       something more complex to assure that every module that wants to get
247       registered will be registered and that every registered module will be
248       accessible by the same handle as long as the program runs. To make this
249       work "plug_in()" sees the third argument only as a hint how the handle
250       should look like, when a module is registered. It returns the real
251       handle with which the algorithm can be instantiated. That means a
252       developer of a plugin module cannot make the handle immediately
253       available like I did for the modules in the distribution. Instead there
254       should be something like a public variable or function that returns the
255       handle as it came back from the "plug_in()" function.
256
257       This could go like this in the module:
258
259        package Algorithm::XyZ;
260
261        use Algorithm::CheckDigits;
262
263        our $xyz = Algorithm::CheckDigits::plug_in('Algorithm::XyZ',
264                                                   'XyZ check digits',
265                                                   'xyz');
266
267       And the user of this algorithm would write something like this:
268
269        use Algorithm::CheckDigits;
270        use Algorithm::XyZ;
271
272        my $cd = CheckDigits($Algorithm::XyZ::xyz);
273
274        if ($cd->is_valid($some_number)) {
275            # do something
276        }
277
278       Please have a look at the plugin tests in the test directory
279       (t/plugin*.t) and the accompanying modules (t/PluginLib*.pm) for
280       example usage. You may also try to load an additional module with the
281       scripts in bin and cgi-bin and look for the additional algorithms in
282       the output:
283
284        perl -Ilib -It -MPluginLibA bin/checkdigits.pl list
285
286        perl -Ilib -It -MPluginLibA cgi-bin/checkdigits.cgi
287
288   Namespace
289       I would like to ask you to use any namespace below or outside but not
290       direct Algorithm::CheckDigits. That means for instance for the XyZ
291       algorithm, Algorithm::XyZ would be fine,
292       Algorithm::CheckDigits::Plugin::XyZ or Algorithm::CheckDigits::X::XyZ
293       would be fine too. But Algorithm::CheckDigits::XyZ could collide with
294       some future version of the Algorithm::CheckDigits distribution, so
295       please avoid this namespace.
296

SEE ALSO

298       perl, www.pruefziffernberechnung.de.
299

BUGS AND LIMITATIONS

301       The function "plug_in()" dies if you try to register the module
302       'Algorithm::CheckDigits'.
303
304       Please report any bugs or feature requests to
305       "bug-algorithm-checkdigits@rt.cpan.org", or through the web interface
306       at <http://rt.cpan.org>.
307

AUTHOR

309       Mathias Weidner, "mamawe@cpan.org"
310

THANKS

312       Petri Oksanen made me aware that CheckDigits('IMEI') would invoke no
313       test at all since there was no entry for this in the methods hash.
314
315       Brian T. Wightman made me think about and implement the plugin
316       interface.
317

COPYRIGHT AND LICENSE

319       Copyright 2004-2020 by Mathias Weidner
320
321       This library is free software; you can redistribute it and/or modify it
322       under the same terms as Perl itself. See perlartistic.
323
324
325
326perl v5.34.0                      2022-01-20         Algorithm::CheckDigits(3)