Business/FO/Postalcode.pm

filter: Statementstmt 100% 32 / 32 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 12 / 12 Podpod 100% 7 / 7 totaltotal 100% 51 / 51 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary Class/Business/FO/Postalcode.pm »
1 package Business::FO::Postalcode;
2  
3 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 ▶use Class::Business::FO::Postalcode;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 4 ▶use 5.010; #5.10.0
Subroutine BEGIN: called CC=1 SCAR=0.0
7 4 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 4 require Exporter;
10 4 our @ISA = qw(Exporter);
11 4 our @EXPORT_OK = qw(get_all_data get_all_postalcodes get_all_cities get_postalcode_from_city get_city_from_postalcode validate_postalcode validate);
12  
13 4 our $VERSION = '0.04'; # VERSION: generated by DZP::OurPkgVersion
14  
15 2 ▶sub get_all_data {
Subroutine get_all_data: called CC=1 SCAR=0.0
Pod documented
16 2 my $validator = Class::Business::FO::Postalcode->new();
17  
18 2 return $validator->postal_data();
19 }
20  
21 2 ▶sub get_all_postalcodes {
Subroutine get_all_postalcodes: called CC=1 SCAR=0.0
Pod documented
22 2 my $validator = Class::Business::FO::Postalcode->new();
23  
24 2 return $validator->get_all_postalcodes();
25 }
26  
27 1 ▶sub get_all_cities {
Subroutine get_all_cities: called CC=1 SCAR=0.0
Pod documented
28 1 my $validator = Class::Business::FO::Postalcode->new();
29  
30 1 return $validator->get_all_cities();
31 }
32  
33 1 ▶sub get_city_from_postalcode {
Subroutine get_city_from_postalcode: called CC=1 SCAR=0.0
Pod documented
34 1 my $validator = Class::Business::FO::Postalcode->new();
35  
36 1 return $validator->get_city_from_postalcode( $_[0] );
37 }
38  
39 1 ▶sub get_postalcode_from_city {
Subroutine get_postalcode_from_city: called CC=1 SCAR=0.0
Pod documented
40 1 my $validator = Class::Business::FO::Postalcode->new();
41  
42 1 return $validator->get_postalcode_from_city( $_[0] );
43 }
44  
45 1000 ▶sub validate {
Subroutine validate: called CC=1 SCAR=0.0
Pod documented
46 1000 return validate_postalcode( $_[0] );
47 }
48  
49 2000 ▶sub validate_postalcode {
Subroutine validate_postalcode: called CC=1 SCAR=0.0
Pod documented
50 2000 my $validator = Class::Business::FO::Postalcode->new();
51  
52 2000 return $validator->validate( $_[0] );
53 }
54  
55 4 1;
56  
57 =pod
58  
59 =encoding UTF-8
60  
61 =begin markdown
62  
63 [![CPAN version](https://badge.fury.io/pl/Business-FO-Postalcode.svg)](http://badge.fury.io/pl/Business-FO-Postalcode)
64 [![Build Status](https://travis-ci.org/jonasbn/perl-Business-FO-Postalcode.svg?branch=master)](https://travis-ci.org/jonasbn/perl-Business-FO-Postalcode.svg)
65 [![Coverage Status](https://coveralls.io/repos/jonasbn/perl-Business-FO-Postalcode/badge.png)](https://coveralls.io/r/jonasbn/perl-Business-FO-Postalcode)
66  
67 =end markdown
68  
69 =head1 NAME
70  
71 Class::Business::FO::Postalcode - Faroe Islands postal code validator and container
72  
73 =head1 VERSION
74  
75 This documentation describes version 0.03
76  
77 =head1 SYNOPSIS
78  
79 # basic validation of string
80 use Business::FO::Postalcode qw(validate);
81  
82 if (validate($postalcode)) {
83 print "We have a valid Faroe Islands postal code\n";
84 } else {
85 warn "Not a valid Faroe Islands code\n";
86 }
87  
88  
89 # basic validation of string, using less intrusive subroutine
90 use Business::FO::Postalcode qw(validate_postalcode);
91  
92 if (validate_postalcode($postalcode)) {
93 print "We have a valid Faroe Islands postal code\n";
94 } else {
95 warn "Not a valid Faroe Islands postal code\n";
96 }
97  
98  
99 # using the untainted return value
100 use Business::FO::Postalcode qw(validate_postalcode);
101  
102 if (my $untainted = validate_postalcode($postalcode)) {
103 print "We have a valid Faroe Islands postal code: $untainted\n";
104 } else {
105 warn "Not a valid Faroe Islands postal code\n";
106 }
107  
108  
109 # All postal codes for use outside this module
110 use Business::FO::Postalcode qw(get_all_postalcodes);
111  
112 my @postalcodes = @{get_all_postalcodes()};
113  
114  
115 # All postal codes and data for use outside this module
116 use Business::FO::Postalcode qw(get_all_data);
117  
118 my $postalcodes = get_all_data();
119  
120 foreach (@{postalcodes}) {
121 printf
122 'postal code: %s city: %s street/desc: %s company: %s province: %d country: %d', split /;/, $_, 6;
123 }
124  
125 =head1 FEATURES
126  
127 =over
128  
129 =item * Providing list of Faroe Islands postal codes and related area names
130  
131 =item * Look up methods for Faroe Islands postal codes for web applications and the like
132  
133 =back
134  
135 =head1 DESCRIPTION
136  
137 This distribution is not the original resource for the included data, but simply
138 acts as a simple distribution for Perl use. The central source is monitored so this
139 distribution can contain the newest data. The monitor script (F<postdanmark.pl>) is
140 included in the distribution: L<https://metacpan.org/pod/Business::DK::Postalcode>.
141  
142 The data are converted for inclusion in this module. You can use different extraction
143 subroutines depending on your needs:
144  
145 =over
146  
147 =item * L</get_all_data>, to retrieve all data, data description below in L</Data>.
148  
149 =item * L</get_all_postalcodes>, to retrieve all postal codes
150  
151 =item * L</get_all_cities>, to retieve all cities
152  
153 =item * L</get_postalcode_from_city>, to retrieve one or more postal codes from a city name
154  
155 =item * L</get_city_from_postalcode>, to retieve a city name from a postal code
156  
157 =back
158  
159 =head2 Data
160  
161 Here follows a description of the included data, based on the description from
162 the original source and the authors interpretation of the data, including
163 details on the distribution of the data.
164  
165 =head3 city name
166  
167 A non-unique, case-sensitive representation of a city name in Faroese.
168  
169 =head3 street/description
170  
171 This field is unused for this dataset.
172  
173 =head3 company name
174  
175 This field is unused for this dataset.
176  
177 =head3 province
178  
179 This field is a bit special and it's use is expected to be related to distribution
180 all entries are marked as 'False'. The data are included since they are a part of
181 the original data.
182  
183 =head3 country
184  
185 Since the original source contains data on 3 different countries:
186  
187 =over
188  
189 =item * Denmark (1)
190  
191 =item * Greenland (2)
192  
193 =item * Faroe Islands (3)
194  
195 =back
196  
197 Only the data representing Greenland has been included in this distribution, so this
198 field is always containing a '3'.
199  
200 For access to the data on Denmark or Greenland please refer to: L<Business::DK::Postalcode>
201 and L<Business::GL::Postalcode> respectfully.
202  
203 =head2 Encoding
204  
205 The data distributed are in Faroese and Danish for descriptions and names and these are encoded in UTF-8.
206  
207 This distribution is not the original resource for the included data, but simply
208 acts as a simple distribution for Perl use. The central source is monitored so this
209 distribution can contain the newest data. The monitor script (F<postdanmark.pl>) is
210 included in the distribution: L<https://metacpan.org/pod/Business::DK::Postalcode>.
211  
212 The data are converted for inclusion in this module. You can use different extraction
213 subroutines depending on your needs:
214  
215 =over
216  
217 =item * L</get_all_data>, to retrieve all data, data description below in L</Data>.
218  
219 =item * L</get_all_postalcodes>, to retrieve all postal codes
220  
221 =item * L</get_all_cities>, to retieve all cities
222  
223 =item * L</get_postalcode_from_city>, to retrieve one or more postal codes from a city name
224  
225 =item * L</get_city_from_postalcode>, to retieve a city name from a postal code
226  
227 =back
228  
229 =head2 Data
230  
231 Here follows a description of the included data, based on the description from
232 the original source and the authors interpretation of the data, including
233 details on the distribution of the data.
234  
235 =head3 city name
236  
237 A non-unique, case-sensitive representation of a city name in Greenlandic or Danish.
238  
239 =head3 street/description
240  
241 This field is unused for this dataset.
242  
243 =head3 company name
244  
245 This field is unused for this dataset.
246  
247 =head3 province
248  
249 This field is a bit special and it's use is expected to be related to distribution
250 all entries are marked as 'False'. The data are included since they are a part of
251 the original data.
252  
253 =head3 country
254  
255 Since the original source contains data on 3 different countries:
256  
257 =over
258  
259 =item * Denmark (1)
260  
261 =item * Greenland (2)
262  
263 =item * Faroe Islands (3)
264  
265 =back
266  
267 Only the data representing Greenland has been included in this distribution, so this
268 field is always containing a '2'.
269  
270 For access to the data on Denmark or Faroe Islands please refer to: L<Business::DK::Postalcode>
271 and L<Business::FO::Postalcode> respectfully.
272  
273 =head2 Encoding
274  
275 The data distributed are in Greenlandic and Danish for descriptions and names and these are encoded in UTF-8.
276  
277 =head1 SUBROUTINES AND METHODS
278  
279 =head2 validate
280  
281 A simple validator for Faroese postal codes.
282  
283 Takes a string representing a possible Faroese postal code and returns either
284 B<1> or B<0> indicating either validity or invalidity.
285  
286 my $rv = validate(100);
287  
288 if ($rv == 1) {
289 print "We have a valid Faroese postal code\n";
290 } ($rv == 0) {
291 print "Not a valid Faroese postal code\n";
292 }
293  
294 =head2 validate_postalcode
295  
296 A less intrusive subroutine for import. Acts as a wrapper of L</validate>.
297  
298 my $rv = validate_postalcode(100);
299  
300 if ($rv) {
301 print "We have a valid Faroese postal code\n";
302 } else {
303 print "Not a valid Faroese postal code\n";
304 }
305  
306 =head2 get_all_data
307  
308 Returns a reference to a a list of strings, separated by tab characters. See
309 L</Data> for a description of the fields.
310  
311 use Business::FO::Postalcode qw(get_all_data);
312  
313 my $postalcodes = get_all_data();
314  
315 foreach (@{postalcodes}) {
316 printf
317 'postalcode: %s city: %s street/desc: %s company: %s province: %d country: %d', split /\t/, $_, 6;
318 }
319  
320 =head2 get_all_postalcodes
321  
322 Takes no parameters.
323  
324 Returns a reference to an array containing all valid Danish postal codes
325  
326 use Business::FO::Postalcode qw(get_all_postalcodes);
327  
328 my $postalcodes = get_all_postalcodes;
329  
330 foreach my $postalcode (@{$postalcodes}) { ... }
331  
332 =head2 get_all_cities
333  
334 Takes no parameters.
335  
336 Returns a reference to an array containing all Danish city names having a postal code.
337  
338 use Business::FO::Postalcode qw(get_all_cities);
339  
340 my $cities = get_all_cities;
341  
342 foreach my $city (@{$cities}) { ... }
343  
344 Please note that this data source used in this distribution by no means is authorative
345 when it comes to cities located in Denmark, it might have all cities listed, but
346 unfortunately also other post distribution data.
347  
348 =head2 get_city_from_postalcode
349  
350 Takes a string representing a Danish postal code.
351  
352 Returns a single string representing the related city name or an empty string indicating nothing was found.
353  
354 use Business::FO::Postalcode qw(get_city_from_postalcode);
355  
356 my $zipcode = '100';
357  
358 my $city = get_city_from_postalcode($zipcode);
359  
360 if ($city) {
361 print "We found a city for $zipcode\n";
362 } else {
363 warn "No city found for $zipcode";
364 }
365  
366 =head2 get_postalcode_from_city
367  
368 Takes a string representing a Faroese city name.
369  
370 Returns a reference to an array containing zero or more postal codes related to that city name. Zero indicates nothing was found.
371  
372 Please note that city names are not unique, hence the possibility of a list of postal codes.
373  
374 use Business::FO::Postalcode qw(get_postalcode_from_city);
375  
376 my $city = 'Tórshavn';
377  
378 my $postalcodes = get_postalcode_from_city($city);
379  
380 if (scalar @{$postalcodes} == 1) {
381 print "$city is unique\n";
382 } elsif (scalar @{$postalcodes} > 1) {
383 warn "$city is NOT unique\n";
384 } else {
385 die "$city not found\n";
386 }
387  
388 =head1 DIAGNOSTICS
389  
390 There are not special diagnostics apart from the ones related to the different
391 subroutines.
392  
393 =head1 CONFIGURATION AND ENVIRONMENT
394  
395 This distribution requires no special configuration or environment.
396  
397 =head1 DEPENDENCIES
398  
399 =over
400  
401 =item * L<https://metacpan.org/pod/Carp> (core)
402  
403 =item * L<https://metacpan.org/pod/Exporter> (core)
404  
405 =item * L<https://metacpan.org/pod/Data::Handle>
406  
407 =item * L<https://metacpan.org/pod/List::Util>
408  
409 =item * L<https://metacpan.org/pod/Params::Validate>
410  
411 =item * L<https://metacpan.org/pod/Business::GL::Postalcode>
412  
413 =back
414  
415 =head2 TEST
416  
417 Please note that the above list does not reflect requirements for:
418  
419 =over
420  
421 =item * Additional components in this distribution, see F<lib/>. Additional
422 components list own requirements
423  
424 =item * Test and build system, please see: F<Build.PL> for details
425  
426 =back
427  
428 =head1 BUGS AND LIMITATIONS
429  
430 There are no known bugs at this time.
431  
432 The data source used in this distribution by no means is authorative when it
433 comes to cities located in Faroe Islands, it might have all cities listed, but
434 unfortunately also other post distribution data.
435  
436 =head1 BUG REPORTING
437  
438 Please report issues via CPAN RT:
439  
440 =over
441  
442 =item * Web (RT): L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-FO-Postalcode>
443  
444 =item * Web (Github): L<https://github.com/jonasbn/perl-Business-FO-Postalcode/issues>
445  
446 =item * Email (RT): L<bug-Business-FO-Postalcode@rt.cpan.org>
447  
448 =back
449  
450 =head1 SEE ALSO
451  
452 =over
453  
454 =item L<Business::DK::Postalcode>
455  
456 =item L<Business::GL::Postalcode>
457  
458 =back
459  
460 =head1 MOTIVATION
461  
462 Postdanmark the largest danish postal and formerly stateowned postal service, maintain the
463 postalcode mapping for Greenland and the Faroe Islands. Since I am using this resource to
464 maintain the danish postalcodes I decided to release distributions of these two other countries.
465  
466 =head1 AUTHOR
467  
468 Jonas B., (jonasbn) - C<< <jonasbn@cpan.org> >>
469  
470 =head1 COPYRIGHT
471  
472 Business-FO-Postalcode is (C) by Jonas B., (jonasbn) 2014-2019
473  
474 Business-FO-Postalcode is released under the Artistic License 2.0
475  
476 =cut
↑ Summary Class/Business/FO/Postalcode.pm »