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

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'

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: US, South Africa, Croatia, Slovenia, Hungary, Serbia, Bosnia and Herzegovina, Germany, France, Ukraine.

Author¶ ↑

Contributors¶ ↑

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

chipiga/phone