forked from DrHyde/perl-modules-Number-Phone
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Phone.pm
424 lines (297 loc) · 12.1 KB
/
Phone.pm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
package Number::Phone;
use strict;
use Scalar::Util 'blessed';
use Number::Phone::Country qw(noexport uk);
use Number::Phone::StubCountry;
our $VERSION = 1.8002;
my @is_methods = qw(
is_valid is_allocated is_in_use
is_geographic is_fixed_line is_mobile is_pager
is_tollfree is_specialrate is_adult is_network_service is_personal
is_corporate is_government is_international
is_ipphone is_isdn
);
foreach my $method (
@is_methods, qw(
country_code regulator areacode areaname
subscriber operator translates_to
format location
)
) {
no strict 'refs';
*{__PACKAGE__."::$method"} = sub {
my $self = shift;
return undef if(blessed($self) && $self->isa(__PACKAGE__));
my $pkg = __PACKAGE__;
$self = shift if(
$self eq __PACKAGE__ ||
substr($self, 0, 2 + length(__PACKAGE__)) eq __PACKAGE__.'::'
);
$self = __PACKAGE__->new($self)
unless(blessed($self) && $self->isa(__PACKAGE__));
return $self->$method() if($self);
undef;
}
}
sub type {
my $parm = shift;
my $class = __PACKAGE__;
no strict 'refs';
unless(blessed($parm) && $parm->isa(__PACKAGE__)) {
if(
$parm eq __PACKAGE__ ||
substr($parm, 0, 2 + length(__PACKAGE__)) eq __PACKAGE__.'::'
) {
$class = $parm;
$parm = shift;
}
$parm = $class->new($parm);
}
my $rval = $parm ?
[grep { $parm->$_() } @is_methods] :
undef;
wantarray() ? @{$rval} : $rval;
}
sub country {
my $self = shift;
return undef if(!blessed($self));
(my $country = blessed($self)) =~ s/.*:://;
return undef unless(length($country) == 2);
return $country;
}
1;
=head1 NAME
Number::Phone - base class for Number::Phone::* modules
=head1 SYNOPSIS
In a sub-class ...
package Number::Phone::UK;
use base 'Number::Phone';
and to magically use the right subclass ...
use Number::Phone;
$daves_phone = Number::Phone->new('+442087712924');
$daves_other_phone = Number::Phone->new('+44 7979 866 975');
# alternatively Number::Phone->new('+44', '7979 866 975');
# or Number::Phone->new('UK', '07979 866 975');
if($daves_phone->is_mobile()) {
send_rude_SMS();
}
in the example, the +44 is recognised as the country code for the UK,
so the appropriate country-specific module is loaded if available.
If you pass in a bogus country code not recognised by
Number::Phone::Country, the constructor will return undef.
If you pass in a country code for which
no supporting module is available, the constructor will return a
minimal object that knows its country code and how to format a phone
number, but nothing else. Note that this is an incompatible change:
previously it would return undef.
=cut
sub new {
my $class = shift;
my($country, $number) = @_;
if(!defined($number)) {
$number = $country;
} elsif($country =~ /[a-z]/i) { # eg 'UK', '12345'
$number = '+'.
Number::Phone::Country::country_code($country).
$number
unless(index($number, '+'.Number::Phone::Country::country_code($country)) == 0);
} else {
$number = join('', grep { defined } ($country, $number));
}
die("Need to specify a number for ".__PACKAGE__."->new()\n")
unless($number);
die("Number::Phone->new(): too many params\n")
if(exists($_[2]));
$number =~ s/[^+0-9]//g;
$number = "+$number" unless($number =~ /^\+/);
$country = Number::Phone::Country::phone2country($number);
return undef unless($country);
$country = "NANP" if($number =~ /^\+1/);
eval "use Number::Phone::$country";
return $class->_make_stub_object($number) if($@);
return "Number::Phone::$country"->new($number);
}
sub _make_stub_object {
my $class = shift;
my $number = shift;
my $self = {
country => 'STUBFORCOUNTRYWITHNOMODULE',
country_idd_code => ''.Number::Phone::Country::country_code(Number::Phone::Country::phone2country($number)),
country_code => ''.Number::Phone::Country::phone2country($number),
number => $number
};
# use Data::Dumper; local $Data::Dumper::Indent = 1;
# print Dumper($self);
bless($self, 'Number::Phone::StubCountry');
}
=head1 METHODS
All Number::Phone classes should implement the following methods, both
as object methods and as class methods. Used as class methods they should
take a scalar parameter which they should attempt to parse as a phone
number. Used as object methods, they should perform their duties on the
phone number that was supplied to the constructor.
Those methods whose names begin C<is_> should return the following
values:
=over 4
=item undef
The truth or falsehood can not be determined;
=item 0 (zero)
False - eg, is_personal() might return 0 for a number that is assigned to
a government department.
=item 1 (one)
True
=back
The C<is_*> methods are:
=over 4
=item is_valid
The number is valid within the national numbering scheme. It may or may
not yet be allocated, or it may be reserved. Any number which returns
true for any of the following methods will also be valid.
=item is_allocated
The number has been allocated to a telco for use. It may or may not yet
be in use or may be reserved.
=item is_in_use
The number has been assigned to a customer or is in use by the telco for
its own purposes.
=item is_geographic
The number refers to a geographic area.
=item is_fixed_line
The number, when in use, can only refer to a fixed line.
=item is_mobile
The number, when in use, can only refer to a mobile phone.
=item is_pager
The number, when in use, can only refer to a pager.
=item is_ipphone
The number, when in use, can only refer to a VoIP service.
=item is_isdn
The number, when in use, can only refer to an ISDN service.
=item is_tollfree
Callers will not be charged for calls to this number under normal circumstances.
=item is_specialrate
The number, when in use, attracts special rates. For instance, national
dialling at local rates, or premium rates for services.
=item is_adult
The number, when in use, goes to a service of an adult nature, such as porn.
=item is_personal
The number, when in use, goes to an individual person.
=item is_corporate
The number, when in use, goes to a business.
=item is_government
The number, when in use, goes to a government department. Note that the
emergency services are considered to be a network service so should *not*
return true for this method.
=item is_international
The number is charged like a domestic number (including toll-free or special
rate), but actually terminates in a different country. This covers the
special dialling arrangements between Spain and Gibraltar, and between the
Republic of Ireland and Northern Ireland, as well as services such as the
various "Country Direct"-a-likes. See also the C<country()> method.
=item is_network_service
The number is some kind of network service such as the operator, directory
enquiries, emergency services etc
=back
Other methods are as follows. Some of them may return undef if the result
is unknown or not applicable:
=over 4
=item country_code
The numeric code for this country. eg, 44 for the UK. Note that there is
*no* + sign.
=item regulator
Returns some text in an appropriate character set saying who the telecoms
regulator is, with optional details such as their web site or phone number.
=item areacode
Return the area code - if applicable - for the number. If not applicable,
returns undef.
=item areaname
Return the name for the area code - if applicable. If not applicable,
returns undef. For instance, for a number beginning +44 20 it would return
'London'. Note that this may return data in non-ASCII character sets.
=item location
This returns an approximate geographic location for the number if possible.
Obviously this only applies to fixed lines! The data returned is, if defined,
a reference to an array containing two elements, latitude and longitude,
in degrees.
North of the equator and East of Greenwich are positive.
You may optionally return a third element indicating how confident you are
of the location. Specify this as a number in kilometers indicating the radius
of the error circle.
=item subscriber
Return the subscriber part of the number
=item operator
Return the name of the telco operating this number, in an appropriate
character set and with optional details such as their web site or phone
number.
=item type
Return a listref of all the is_... methods above which are true. Note that
this method should only be implemented in the super-class. eg, for the
number +44 20 87712924 this might return
C<[qw(valid allocated geographic fixed_line)]>.
=item format
Return a sanely formatted version of the number, complete with IDD code, eg
for the UK number (0208) 771-2924 it would return +44 20 87712924.
=item country
The two letter ISO country code for the country in which the call will
terminate. This is implemented in the superclass and you will only have
to implement your own version for countries where part of the number
range is overlayed with another country.
Exception: for the UK, return 'uk', not 'gb'.
=item translates_to
If the number forwards to another number (such as a special rate number
forwarding to a geographic number), or is part of a chunk of number-space
mapped onto another chunk of number-space (such as where a country has a
shortcut to (part of) another country's number-space, like how Gibraltar
appears as an area code in Spain's numbering plan as well as having its
own country code), then this method may return an object representing the
target number. Otherwise it returns undef.
=back
Finally, there is a constructor:
=over 4
=item new
Can be called with either one or two parameters. The *first* is an optional
country code (see the C<country()> method). The other is a phone number.
If a country code is specified, and a subclass for that country is available,
the phone number is passed to its constructor unchanged.
If only one parameter is passed, then we try to figure out which is the right
country subclass to use by pre-pending a + sign to the number if
there isn't one, and looking the country up using
Number::Phone::Country. That gives us a two letter country code that
is used to try to load the right module.
The constructor returns undef if it can not figure out what country
you're talking about, or a minimal object if there's no country-specific
module available. Note that in the case of there being no country-specific
module available this is an incompatible change: previously it would
return undef.
=back
=head1 SUBCLASSING
Sub-classes should implement methods as above, including a C<new()> constructor.
The constructor should take a single parameter, a phone number, and should
validate that. If the number is valid (use your C<is_valid()> method!) then
you can return a blessed object. Otherwise you should return undef.
The constructor *must* be capable of accepting a number with the
+ sign and the country's numeric code attached, but should also accept
numbers in the preferred local format (eg 01234 567890 in the UK, which
is the same number as +44 1234 567890) so that users can go straight
to your class without going through Number::Phone's magic country
detector.
Subclasses' names should be Number::Phone::XX, where XX is the two letter
ISO code for the country, in upper case. So, for example, France would be
FR and Ireland would be IE. As usual, the UK is an exception, using UK
instead of the ISO-mandated GB. NANP countries are also an exception,
going like Number::Phone::NANP::XX.
Note that subclasses no longer need to register themselves with
Number::Phone. In fact, registration is now *ignored* as the magic
country detector now works properly.
=head1 WARNING
There is an incompatible change in version 1.8. See the SYNOPSIS and
the documentation for the C<new> method above.
=head1 BUGS/FEEDBACK
Please report bugs by email or using http://rt.cpan.org, including,
if possible, a test case.
I welcome feedback from users.
=head1 LICENCE
You may use, modify and distribute this software under the same terms as
perl itself.
=head1 AUTHOR
David Cantrell E<lt>david@cantrell.org.ukE<gt>
Copyright 2004 - 2011
=cut