Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Ruby library that parses a phone number and automatically formats it correctly, depending on the country/locale you set.
Ruby
branch: master

This branch is 1 commit ahead, 39 commits behind habermann24:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
LICENCE
README.rdoc
Rakefile
phoney.gemspec

README.rdoc

phoney

This is a library for representing phone numbers. It provides a PhoneNumber class that can format phone numbers depending on the region you set.

Installation

Gem

gem install phoney

Source

git clone git://github.com/habermann24/phoney.git

Feature overview

  • Create phone number by parsing a string

    require 'phoney'
    # region defaults to US
    pn = PhoneNumber.new("+17041234567")
    pn.to_s          # "+1 (704) 123-4567"
    pn.area_code     # "704"
    pn.country_code  # "1"
    pn.number        # "1234567"
  • Deals with many specific region formatting rules (e.g. DE)

    require 'phoney'
    
    PhoneNumber.default_region = :de
    
    pn = PhoneNumber.new("04105456789")
    pn.to_s           # "+49 4105 456789"
    pn.area_code      # "4105"
    pn.country_code   # "49"
    pn.number         # "456789"

Creating PhoneNumber instances

Phoney gives you a PhoneNumber class that wraps all the logic of phone number parsing and representation. The default region phoney uses for formatting is the US-region format. So if you want to parse phone numbers from a different country, you have to set PhoneNumber.default_region or pass the region code every time!

PhoneNumber.default_region = :us

The most common way to create a PhoneNumber object is by parsing from a string:

PhoneNumber.new("7041231234")         # uses region :us
PhoneNumber.new("01805708090", :de)   # uses region :de

Or instead of parsing a string, you can provide a hash for the first parameter:

PhoneNumber.new(:number => "1231234", :area_code => "704", :country_code => "1")

# falls back to US region, so also uses "1" for <tt>country_code</tt>
PhoneNumber.new(:number => "1231234", :area_code => "704")

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)

  • %n - number (5125486)

    pn = PhoneNumber.new('+446546546546')
    
    pn.to_s                     # => "+44 65 4654 6546"
    pn.format("%a/%n")          # => "64/46546546"
    pn.format("+ %c (%a) %n")   # => "+ 44 (65) 46546546"

Usually you will just want PhoneNumber to figure out how to format the number correctly. When given a symbol you can let the parser guess the best format and pass in one of the following auto-formatting symbols:

pn.format(:default) # => "+44 65 4654 6546"

# :national omits the country code and assumes a representation within the region
pn.format(:national) # => "65 4654 6546"

# :local even omits the area code and assumes a default area, so be careful!
pn.format(:local) # => "46 5465 46"

TODOs

  • More test specs for different countries

Licence

see LICENSE

Something went wrong with that request. Please try again.