/ 
Number-Phone-1.7
River stage two • 14 direct dependents • 19 total dependents
/ Number::Phone

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');

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 or one for a country for which no supporting module is available, the constructor will return undef.

IMPORTANT NOTE WHAT YOU SHOULD READ

All previous versions had a dependency on the excellent DBM::Deep module. Unfortunately its file format changed when it hit version 1.0. Therefore this release has an old version of DBM::Deep bundled with it, which you may use in parallel with the new version.

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 or not applicable:

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.

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.

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.

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

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'.

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.

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 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 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.

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.

BUGS/FEEDBACK

Please report bugs by email or using http://rt.cpan.org, 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 - 2008