| Number::Phone(3pm) | User Contributed Perl Documentation | Number::Phone(3pm) |
Number::Phone - base class for Number::Phone::* modules
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.
Early versions of this module allowed what are now object methods to also be called as class methods or even as functions. This was a bad design decision. Use of those calling conventions was deprecated in version 2.0, released in January 2012, and started to emit warnings. All code to support those calling conventions has now been removed.
Until 2017 we ued KOS for the country code for Kosovo, that has now changed to XK. See Number::Phone::Country.
From version 3.4000 to 3.4003 inclusive we accepted any old garbage after +383 as being valid, as the Kosovo numbering plan had not been published. Now that that has been published, we use libphonenumber data, and validate against it.
The prefix codes in 3.4003 and earlier were managed by hand and so got out of date. After that release they are mostly derived from libphonenumber. libphonenumber's data includes carrier selection codes when they are mandatory for dialling so those are now included. This sometimes means that some random carrier has been arbitrarily privileged over others.
As of version 3.6000 the "areaname" method is documented as taking an optional language code. As far as I can tell providing this new parameter to the method as provided by all the subclasses on the CPAN won't do any harm.
As of version 3.6000 the "areaname" method pays attention to your locale settings and so you might start getting locale-appropriate versions of areanames instead of what you used to get.
libphonenumber is a similar project for other languages, maintained by Google.
If you pass in a country code for which no supporting module is available, the constructor will try to use a 'stub' class under Number::Phone::StubCountry::* that uses data automatically extracted from Google's libphonenumber project. libphonenumber doesn't have enough data to support all the features of Number::Phone. If you want to disable this, then pass 'nostubs' when you use the module:
use Number::Phone qw(nostubs);
Alternatively, if you want to *always* use data derived from libphonenumber, you should use the Number::Phone::Lib module instead. This is a subclass of Number::Phone that will use the libphonenumber-derived stub classes even when extra data is available in, for example, Number::Phone::UK. You might want to do this for compatibility or performance. Number::Phone::UK is quite slow, because it uses a huge database for some of its features.
All Number::Phone classes can implement the following object methods.
The implementations in the parent class all return undef unless otherwise noted.
Those methods whose names begin "is_" should return the following values:
While the superclass does indeed implement this (returning undef) this is nonsense in just about all cases, so you should always implement this.
This may take an optional language code such as 'de' or 'en'. If you provide that then you will get back whatever the place name is in that language, if the data is available. If you don't provide it then it will first look at your locale settings and try to find a name in an appropriate language, and if nothing is found fall back to English.
The superclass implementation returns undef, which is a reasonable default.
While the superclass implementation returns undef, this is nonsense in just about all cases, so you should always implement this.
The superclass implementation returns undef, as this information is not easily available for most numbering plans.
The superclass implementation returns undef, indicating that you don't know whether the number has been ported.
The superclass implementation returns undef, which is nonsense, so you should always implement this.
For example, if you want to get "just the digits, ma'am", use the Raw formatter thus:
Number::Phone->new('+44 20 8771 2924')->format_using('Raw');
which will return:
2087712924
It is a fatal error to specify a non-existent formatter.
Exception: for the UK, return 'uk', not 'gb'.
Specifically, the superclass implementation looks at the class name and returns the last two-letter code it finds. eg ...
from Number::Phone::UK, it would return UK
from Number::Phone::UK::IM, it would return IM
from Number::Phone::NANP::US, it would return US
from Number::Phone::FR::Full, it would return FR
The superclass implementation returns undef.
Examples:
Call from +44 20 7210 3613
to +44 1932 341 111
You dial 01932341111
Call from +44 20 7210 3613
to +44 1932 341 111
You dial 01932341111
Call from +44 20 7210 3613
to +1 202 224 6361
You dial 0012022246361
Call from +1 202 224 6361
to +44 20 7210 3613
You dial 011442072103613
Call from +44 7979 866975
to +44 7979 866976
You dial 07979 866976
This method is implemented in the superclass, but you may have to define certain other methods to assist it. The algorithm is as follows:
If it dies, return undef.
If it returns anything other than undef, return that.
If it returns undef, append together the country's out-of-area calling prefix (usually 0 or 1), the destination area code and subscriber number.
If it dies, return undef.
If it returns anything other than undef, return that.
If it returns undef, return the destination subscriber number.
The superclass implementation is to die.
Note that the meaning of undef is a bit different for this method.
Why die by default? Some countries have weird arrangements for dialling some numbers domestically. In fact, both the countries I'm most familiar with do, so I assume that others do too.
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 an object based on Google's libphonenumber data if there's no complete country-specific module available.
It is generally assumed that numbers are complete and unambiguous - ie you can't pass just the local part to the constructor if the number has an area code. Any subclass's constructor which contravenes this should document it.
Sub-classes should implement methods as above, including a "new()" constructor. The constructor should take a single parameter, a phone number, and should validate that. If the number is valid (use your "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.
I release updates approximately every three months, including new data.
I will also do intercalary releases to fix *serious* bugs in the code and when *large* data updates (eg when a country's numbering scheme changes) are brought to my attention.
I will not normally do a release just because a country has added some new number range. If this irks you then I would welcome a discussion on how you can best write a patch, with tests, that will reliably incorporate updated data from libphonenumber. Much of the needed code already exists in the repository but it is not fit for end-user consumption.
Please report bugs by at <https://github.com/DrHyde/perl-modules-Number-Phone/issues>, including, if possible, a test case.
There is a mailing list for discussion and help. Please subscribe at <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/number-phone>.
Kindly hosted by Shadowcat <http://scsys.co.uk>.
<https://github.com/googlei18n/libphonenumber>, a similar project for Java, C++ and Javascript. Number::Phone imports its data.
<git://github.com/DrHyde/perl-modules-Number-Phone.git>
Copyright 2004 - 2015 David Cantrell <david@cantrell.org.uk>
This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.
Some files are under the Apache licence, a copy of which can be found in the file Apache-2.0.txt.
This module is also free-as-in-mason software.
| 2020-09-08 | perl v5.30.3 |