NAME¶
Number::Phone - base class for Number::Phone::* modules
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.
COMPATIBILTY WITH libphonenumber¶
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, and this is an experimental feature. 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.
METHODS¶
All Number::Phone classes can implement the following methods, as object
methods. Note that in previous versions these were also required to work as
class methods and could also work as subroutines. That was a bad design
decision and is deprecated. Number::Phone will spit warnings if you try that
now, and support will be removed in the future.
The implementations in the parent class all return undef unless otherwise noted.
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
IS_* methods¶
- 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
- country_code
- The numeric code for this country. eg, 44 for the UK. Note that there is
*no* + sign.
While the superclass does indeed implement this (returning undef) this is
nonsense in just about all cases, so you should always implement
this.
- 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,
the superclass implementation returns undef.
- areaname
- Return the name for the area code - if applicable. If not applicable, the
superclass definition 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.
- 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.
The superclass implementation returns undef, which is a reasonable
default.
- subscriber
- Return the subscriber part of the number.
While the superclass implementation returns undef, this is nonsense in just
about all cases, so you should always implement this.
- operator
- Return the name of the telco assigned this number, in an appropriate
character set and with optional details such as their web site or phone
number. Note that this should not take into account number portability.
The superclass implementation returns undef, as this information is not
easily available for most numbering plans.
- operator_ported
- Return the name of the telco to whom this number has been ported. If it is
known to have not been ported, then return the same as
"operator()" above.
The superclass implementation returns undef, indicating that you don't know
whether the number has been ported.
- 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)]".
- 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 8771 2924.
The superclass implementation returns undef, which is nonsense, so you
should always implement this.
- 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'.
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
- 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
used to appear 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.
The superclass implementation returns undef.
HOW TO DIAL FROM ONE NUMBER TO ANOTHER¶
- dial_to
- EXPERIMENTAL METHOD
Takes another Number::Phone object as its only argument and returns a string
showing how to dial from the number represented by the invocant to that
represented by the argument.
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:
- international call
- Append together the source country's international dialling prefix
(usually 00), then the destination country's code code, area code, and
subscriber number.
- domestic call, different area code
- Call the object's "intra_country_dial_to()" method.
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.
- domestic call, same area code
- Call the object's "intra_country_dial_to()" method.
If it dies, return undef.
If it returns anything other than undef, return that.
If it returns undef, return the destination subscriber number.
- intra_country_dial_to
- Takes an object (which should be in the same country as the invocant) and
returns either undef (meaning "use the default behaviour") or a
dialling string. If it dies this means "I don't know how to dial this
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.
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 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.
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.
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.
BUGS/FEEDBACK¶
Please report bugs by at
<
https://github.com/DrHyde/perl-modules-Number-Phone/issues>, including,
if possible, a test case.
I welcome feedback from users.
SEE ALSO¶
<
http://code.google.com/p/libphonenumber/>, a similar project for Java,
C++ and Javascript
SOURCE CODE REPOSITORY¶
<
git://github.com/DrHyde/perl-modules-Number-Phone.git>
AUTHOR, COPYRIGHT and LICENCE¶
Copyright 2004 - 2012 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.
CONSPIRACY¶
This module is also free-as-in-mason software.