Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Ruby library for phone number parsing, validation and formatting
branch: master

This branch is 99 commits behind carr:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
data
lib
test
.gitignore
LICENSE
Rakefile
Readme.rdoc
phone.gemspec
test_usa_phones_with_extensions.csv

Readme.rdoc

Phone

Parsing, validating and creating phone numbers

Install

You can install the phone library as a gem

gem sources -a http://gemcutter.org
gem install phone

Or as a Rails plugin

script/plugin install git://github.com/carr/phone.git

Initializing

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

Phone.new('5125486', '91', '385')

or

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. Phone does it's best to detect the country and area codes:

Phone.parse '+385915125486'
Phone.parse '00385915125486'

If the country or area code isn't given in the string, you must set it, otherwise it doesn't work:

Phone.parse '091/512-5486', :country_code => '385'
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):

Phone.default_country_code = '385'    
Phone.parse '091/512-5486'
Phone.parse '(091) 512 5486'

Same goes for the area code:

Phone.parse '451-588', :country_code => '385', :area_code => '47'

or

Phone.default_country_code = '385'  
Phone.default_area_code = '47'

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. Do do this, phone uses data stored in data/countries.yml.

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

If an area_code regular expression isn't specified, the default, Phone::DEFAULT_AREA_CODE (correct for the US) is used.

Validating

Validating is very relaxed, basically it strips out everything that's not a number or '+' character:

Phone.valid? 'blabla 091/512-5486 blabla'

Formatting

Formating is done via the format method. The method accepts a Symbol or a String.

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 Phone.n1_length), default is 3 (512)

  • %l - last characters of number (5486)

  • %x - the extension number

    pn = 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 the Phone.named_formats hash.

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:

Phone.named_formats[:short] = '%A/%n1-%n2'    
pn.format(:short) # => 091/512-5486

TODO

Parse testing for different countries.

Currently tested on:

AU

Australia

BA

Bosnia and Herzegovina

BE

Belgium

DE

Germany

FR

France

GB

United Kingdom

HR

Croatia

HU

Hungary

NL

Netherlands

RS

Serbia

SE

Sweden

SI

Slovenia

UA

Ukraine

US

United States

ZA

South Africa

Author

Copyright © 2010 Tomislav Car, Infinum

Contributors

Don Morrison, Michael Squires, Todd Eichel (Fooala, Inc.), chipiga, Etienne Samson, Luke Randall

Something went wrong with that request. Please try again.