NAME
    URI::tel - Implementation of rfc3966 for tel URI

SYNOPSIS
        my $tel = URI::tel->new( 'tel:+1-418-656-9254;ext=102' );
        ## or
        my $tel = URI::tel->new( 'tel:5678-1234;phone-context=+81-3' );
        ## or
        my $tel = URI::tel->new( '03-5678-1234' );
        $tel->context( '+81' );
        $tel->ext( 42 );
        print( $tel->canonical->as_string, "\n" );
        my $tel2 = $tel->canonical;
        print( "$tel2\n" );
        ## or
        my $tel = URI::tel->new( '+1-800-LAWYERS' );
        my $actualPhone = $tel->aton;
        ## would produce +1-800-5299377

        ## Comparing 2 telephones
        ## https://tools.ietf.org/search/rfc3966#section-4
        if( $tel == $tel2 )
        {
            ## then do something
        }

DESCRIPTION
    "URI::tel" is a package to implement the tel URI as defined in rfc3966
    <https://tools.ietf.org/search/rfc3966>.

    tel URI is structured as follows:

    tel:*telephone-subscriber*

    *telephone-subscriber* is either a *global-number* or a *local-number*

    *global-number* can be composed of the following characters:

    +[0-9\-\.\(\)]*[0-9][0-9\-\.\(\)]* then followed with one or zero
    parameter, extension, isdn-subaddress

    *local-number* can be composed of the following characters:

    [0-9A-F\*\#\-\.\(\)]* ([0-9A-F\*\#])[0-9A-F\*\#\-\.\(\)]* followed by
    one or zero of parameter, extension, isdn-subaddress, then at least one
    context then followed by one or zero of parameter, extension,
    isdn-subaddress.

    *parameter* is something that looks like
    ;[a-zA-Z0-9\-]+=[\[\]\/\:\&\+\$0-9a-zA-Z\-\_\.\!\~\*\'\(\)]+

    *extension* is something that looks like ;ext=[0-9\-\.\(\)]+

    *isdn-subaddress* is something that looks like
    ;isub=[\;\/\?\:\@\&\=\+\$\,a-zA-Z0-9\-\_\.\!\~\*\'\(\)%0-9A-F]+

    *context* is something that looks like
    ;phone-context=([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9]\.)?([a-
    zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9]) or
    ;phone-context=+([0-9]+[\-\.\(\)]*)?[0-9]+([0-9]+[\-\.\(\)]*)?

METHODS
  new( tel URI )
    "new" is provided with a tel URI and return an instance of this package.

  as_string
    Returns a string representation of the tel uri. This package is
    overloaded, so one can get the same result by doing

        my $str = $tel->as_string;

  aton( [ telephone ] )
    If no phone number is given as argument, it will use the *subscriber*
    value of the object used to call this method. It returns the phone
    number with the letters replaced by their digit counterparts.

    For example a subscriber such as "tel:+1-800-LAWYERS" would return
    "tel:+1-800-5299377"

  canonical
    Return the tel uri in a canonical form, ie without any visualisation
    characters, ie no "hyphen", "comma", "dot", etc

  clone
    Returns an exact copy of the current object.

  context( [ CONTEXT ] )
    Given a telephone context, sets the value accordingly. It returns the
    current existing value.

    For example, with a phone number of 03-1234-5678, this is a local
    number, and one could set some context, such as

        $tel->context( '+81' )

    Thus, when called upon as a string, the object would return:

        03-1234-5678;phone-context=+81

  country
    If the current telephone uri is as global number, this method will try
    to find out to which country it belongs. It returns an array in list
    context and an array reference in scalar context.

    If there are more than one country using the same international dialling
    code, it will return multiple entry in the array. This is typically true
    for countries like Canada and the United States who both uses the same
    +1 international dialling code.

    One could then do something like the following:

        my $ref = $tel->country;
        print( "Country: ", @$ref > 1 ? join( ' or ', map( $_->{name}, @$ref ) ) : @$ref ? $ref->[0]->{name} : 'not found', "\n" );

    which would produce:

        Country: Canada or United States

    Each array entry is a reference to an associative array, which contains
    the following fields:

    *cc* for the iso 3166 2-letters code
    *cc3* for the iso 3166 3-letters code
    *name* for the country name
    *idd* for the international dialling code. *idd* is an array reference
    which may contains one or more entries, as there may be multiple
    international dialling code per country.

  international_code( [ PHONE DIGITS ] )
    This returns the international code, if any. The international code is
    the international country code unique to each country or territory. It
    may be found as a prefix to the subscriber number or as a context to the
    phone number. For example:

        +1-418-656-9254;ext=102;phone-context=example.com
        tel:656-9254;ext=102;phone-context=+1-212
        tel:911;phone-context=+1

    If an international country code is provided, it will be used to get
    information such as country name and iso 3166 country codes and also it
    will be used in formatting the phone number by prefixing the subscriber
    number with the international country code provided. If, instead you
    want to just set a context, then use the "context" method instead. For
    example with a subscriber number such as *911*, you may want to give it
    some context by adding +1 such as :

        my $tel = URI::tel->new( "911" );
        $tel->context( '+1' );
        print( "$tel\n" ); # will produce 911;phone-context=+1

        # But don't do this!
        $tel->international_code( 1 );
        # print will now trigger a bad phone number
        print( "$tel\n" ); " will produce +1-911

  is_global
    Returns true or false depending on whether the phone number is a global
    one, ie starting with "+".

  is_local
    Returns true or false depending on whether the phone number is a local
    one, ie a number without the "+" prefix. This can happen of course with
    numbers such as "03-1234-5678", but also for emergency number, such as
    110 (police in Japan) or 911 (police in the U.S.).

    One could set a prefix to clarify, such as:

        my $tel = URI::tel->new( '110' );
        $tel->context( '+81' );
        ## which would produce:
        ## 110;phone-context=+81

  is_other
    Normally, as per rfc 3966, a non global number must have a context, but
    in everyday life this is rarely the case, so "is_other" flags those
    numbers who are local but lack a context.

    It returns true or false.

  is_vanity
    Returns true or false whether the telephone number is a vanity number,
    such as "+1-800-LAWYERS".

  isub( [ ISDN SUBADDRESS ] )
    Optionally sets the isdn subaddress if a value is provided. It returns
    the current value set.

        $tel->isub( 1420 );

  local_number
    Returns the local phone number. For example for a number such as
    "+81-090-1234-5678", this would return "090-1234-5678"

  original
    Returns the original telephone number provided, before any possible
    changes were brought.

  private( [ NAME, [ VALUE ] ] )
    Given a *NAME*, "private" returns the value entry for that parameter. If
    a *VALUE* is provided, it will set this value for the given name. if no
    *NAME*, and no *VALUE* was provided, "private" returns a list of all the
    name-value pair currently set, or a reference to that associative array
    in scalar context.

  subscriber( [ PHONE ] )
    Returns the current telephone number set for this telephone uri. For
    example:

        my $tel = URI::tel->new( 'tel:+1-418-656-9254;ext=102' );
        my $subscriber = $tel->subscriber;

    will return: "+1-418-656-9254"

  type
    This is a read-only method. It returns the type of the telephone number.
    The type can be one of the following values: global, local, other,
    vanity

SEE ALSO
    List of country calling codes:
    <https://en.wikipedia.org/wiki/List_of_country_calling_codes>

CREDITS
    Credits to Thiago Berlitz Rondon for the initial version.

COPYRIGHT
    Copyright (c) 2016-2018 Jacques Deguest <jack@deguest.jp>

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

