NAME
Number::Phone - base class for Number::Phone::* modules
SYNOPSIS
In a sub-class ...
package Number::Phone::UK;
use base 'Number::Phone';
$Number::Phone::subclasses{country_code()} = __PACKAGE__;and to magically use the right subclass ...
$daves_phone = Number::Phone->new('+442087712924');
$daves_other_phone = Number::Phone->new(UK => '07979 866 975');
if($daves_phone->is_mobile()) {
send_rude_SMS();
}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 is_ should return the following values:
- undef
-
The truth or falsehood can not be determined;
- 0 (zero)
-
False - eg, is_personal() might return 0 for a number that is assigned to a government department.
- 1 (one)
-
True
The is_* methods are:
- 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.
- 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.
- is_in_use
-
The number has been assigned to a customer or is in use by the telco for its own purposes.
- is_geographic
-
The number refers to a geographic area.
- is_fixed_line
-
The number, when in use, can only refer to a fixed line.
- is_mobile
-
The number, when in use, can only refer to a mobile phone.
- is_pager
-
The number, when in use, can only refer to a pager.
- is_ipphone
-
The number, when in use, can only refer to a VoIP service.
- is_isdn
-
The number, when in use, can only refer to an ISDN service.
- is_tollfree
-
Callers will not be charged for calls to this number under normal circumstances.
- is_specialrate
-
The number, when in use, attracts special rates. For instance, national dialling at local rates, or premium rates for services.
- is_adult
-
The number, when in use, goes to a service of an adult nature, such as porn.
- is_personal
-
The number, when in use, goes to an individual person.
- is_corporate
-
The number, when in use, goes to a business.
- 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.
- 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
country()method. - is_network_service
-
The number is some kind of network service such as the operator, directory enquiries, emergency services etc
Other methods are as follows. Some of them may return undef if the result is unknown:
- country_code
-
The numeric code for this country. eg, 44 for the UK. Note that there is *no* + sign.
- 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.
- areacode
-
Return the area code - if applicable - for the number. If not applicable, returns undef.
- subscriber
-
Return the subscriber part of the number
- 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.
- 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
[qw(valid allocated geographic fixed_line)]. - 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.
- country
-
If the number is_international, return the two-letter ISO country code. Exception: for the UK, return 'uk', not 'gb'.
Finally, there is a constructor:
- new
-
Can be called with either one or two parameters. The *first* is an optional country code (see the
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 thus:
If the phone number begins with a + sign we take the following few digits as a country code, look up the country that code is assigned to, and if the module exists, call its constructor with the supplied phone number.
Otherwise, we try the constructors for all registered subclasses. If one of them returns an object, we return that. However, if none of them succeed, or if 2 or more succeed, this is a failure.
The constructor returns undef if it can not figure out which subclass to use.
SUBCLASSING
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.
To register your subclass so that Number::Phone can automagically use it when appropriate, do thus:
$Number::Phone::subclasses{country_code()} = __PACKAGE__;as in the SYNOPSIS above.
Note that the NANP countries may potentially be treated as a special case, as they all share +1. For the small Carribean countries, it may be appropriate to use a "country" code of (eg, for Jamaica) 1876. For the US and Canada, you should probably register lots of codes, 1NXX, for each NXX area code assigned to your country. I also recommend that code common to all NANP countries, such as the is_valid() method, should use something like Number::Phone::NANP for those (which would inherit from Number::Phone) and then have their national variations inherit from Number::Phone::NANP.
BUGS/FEEDBACK
Please report bugs by email, including, if possible, a test case.
I welcome feedback from users.
LICENCE
You may use, modify and distribute this software under the same terms as perl itself.
AUTHOR
David Cantrell <david@cantrell.org.uk>
Copyright 2004