= Phonie
Parsing, validating and creating phone numbers

== Install
You can install the phonie library as a gem
    gem install phonie

== Initializing
You can initialize a new phone object with the number, area code, country code and extension number

    Phonie::Phone.new('5125486', '91', '385')
or
    Phonie::Phone.new(number: '5125486', area_code: '91', country_code: '385', extension: '143')

== Parsing
You can create a new phone object by parsing from a string. Phonie::Phone does it's best to detect the country and area codes:
    Phonie::Phone.parse '+385915125486'
    Phonie::Phone.parse '00385915125486'

If the country or area code isn't given in the string, you must set it, otherwise it doesn't work:
    Phonie::Phone.parse '091/512-5486', country_code: '385'
    Phonie::Phone.parse '(091) 512 5486', country_code: '385'

If you feel that it's tedious, set the default country code once (in your config/environment.rb):
    Phonie.configuration.default_country_code = '385'
    Phonie::Phone.parse '091/512-5486'
    Phonie::Phone.parse '(091) 512 5486'

Same goes for the area code:
    Phonie::Phone.parse '451-588', country_code: '385', area_code: '47'

Alternatively Phonie can be configured via a block
    Phonie.configure do |config|
      config.default_country_code = '385'
      config.default_area_code = '47'
      config.add_custom_named_format :short, '%A/%n1-%n2'
    end

    Phonie::Phone.parse '451-588'

=== Automatic country and area code detection
Like it's stated above, Phone does it's best to automatically detect the country and area code while parsing. To do this, phone uses data stored in <tt>data/countries.yml</tt>.

Each country code can have a regular expression named <tt>area_code</tt> that describes how the area code for that particular country looks like.

== Validating
Validating is very relaxed, basically it strips out everything that's not a number or '+' character:
    Phonie::Phone.valid? 'blabla 091/512-5486 blabla'

== Formatting
Formating is done via the <tt>format</tt> method. The method accepts a <tt>Symbol</tt> or a <tt>String</tt>.

When given a string, it interpolates the string with the following fields:

* %c - country_code (385)
* %a - area_code (91)
* %A - area_code with leading zero (091)
* %n - number (5125486)
* %f - first @@n1_length characters of number (configured through Phonie.n1_length), default is 3 (512)
* %l - last characters of number (5486)
* %x - the extension number

    pn = Phonie::Phone.parse('+385915125486')
    pn.to_s # => "+385915125486"
    pn.format("%A/%f-%l") # => "091/512-5486"
    pn.format("+ %c (%a) %n") # => "+ 385 (91) 5125486"

When given a symbol it is used as a lookup for the format in <tt>Phonie::Formatter</tt>.
    pn.format(:europe) # => "+385 (0) 91 512 5486"
    pn.format(:us) # => "(234) 123 4567"
    pn.format(:default_with_extension) # => "+3851234567x143"

You can add your own custom named formats like so:
    Phonie.configuration.add_custom_named_format :short, '%A/%n1-%n2'
    pn.format(:short) # => 091/512-5486

== ActiveModel validator

Phonie includes an ActiveModel validator. If you are using ActiveModel you can validate phone numbers like so:

    class SomeModel
      include ActiveModel::Validations

      validates :phone_number, phone: true
    end

    model = SomeModel.new(phone_number: '')
    model.valid? # false

    model = SomeModel.new(phone_number: '+1 251 123 4567')
    model.valid?  # true

= TODO
Add definitions for more countries

Currently tested on:
[AE] UAE
[AF] Afghanistan
[AL] Albania
[AM] Armenia
[AR] Argentina
[AT] Austria
[AU] Australia
[AZ] Azerbaijan
[BA] Bosnia and Herzegovina
[BD] Bangladesh
[BE] Belgium
[BF] Burkina Faso
[BG] Bulgaria
[BH] Bahrain
[BO] Bolivia
[BR] Brazil
[BS] Bahamas
[BT] Bhutan
[BY] Belarus
[BZ] Belize
[CA] Canada
[CH] Switzerland
[CN] China
[CR] Costa Rica
[CY] Cyprus
[CZ] Czech Republic
[DE] Germany
[DK] Denmark
[DZ] Algeria
[EC] Ecuador
[EE] Estonia
[EG] Egypt
[ES] Spain
[ET] Ethiopia
[FI] Finland
[FR] France
[GB] United Kingdom
[GE] Georgia
[GF] French Guiana
[GH] Ghana
[GR] Greece
[GT] Guatemala
[GU] Guam
[GY] Guyana
[HK] Hong Kong
[HR] Croatia
[HU] Hungary
[IE] Ireland
[IL] Israel
[IN] India
[IQ] Iraq
[IR] Iran
[IT] Italy
[JP] Japan
[KE] Kenya
[KR] South Korea
[KW] Kuwait
[LK] Sri Lanka
[LT] Lithuania
[LU] Luxembourg
[LV] Latvia
[MA] Morocco
[ME] Montenegro
[MT] Malta
[MX] Mexico
[NG] Nigeria
[NI] Nicaragua
[NL] Netherlands
[NO] Norway
[NP] Nepal
[NZ] New Zealand
[PH] Philippines
[PK] Pakistan
[PT] Portugal
[QA] Qatar
[RS] Serbia
[RU] Russian Federation
[SA] Saudi Arabia
[SE] Sweden
[SG] Singapore
[SI] Slovenia
[SK] Slovakia
[SN] Senegal
[SV] El Salvador
[TO] Tonga
[TW] Taiwan
[UA] Ukraine
[US] United States
[UY] Uruguay
[VN] Vietnam
[ZA] South Africa
[ZW] Zimbabwe

= How you can contribute
More testing is needed to add support for missing countries, and improve support for tested countries. In many cases only minimal testing is done on area codes, local number formats and number length where more exact matching is possible.

The best places to start is to read through the country tests and data/phone_countries.rb

= Other libraries
This is based off a fork of the Phone gem (https://github.com/carr/phone), and was extensively modified for better support of country detection, and supports far more countries.

= Contributors
Tomislav Carr, Don Morrison, Michael Squires, Todd Eichel (Fooala, Inc.), chipiga, Etienne Samson, Luke Randall, Wesley Moxam