Ruby library that parses a phone number and automatically formats it correctly, depending on the country/locale you set.
Ruby
Latest commit cc8626b Aug 17, 2013 Jan Merge pull request #13 from Smudge/master
Renaming 'PhoneNumber' to 'Phoney' to reduce chance of conflict.
Permalink
Failed to load latest commit information.
lib Renaming 'PhoneNumber' to 'Phoney' to reduce chance of conflict. Aug 16, 2013
resources Renaming 'PhoneNumber' to 'Phoney' to reduce chance of conflict. Aug 16, 2013
test Renaming 'PhoneNumber' to 'Phoney' to reduce chance of conflict. Aug 16, 2013
.gitignore
Gemfile Use minitest. Mar 6, 2013
Gemfile.lock Version bump Mar 18, 2013
MIT-LICENCE
README.rdoc Renaming 'PhoneNumber' to 'Phoney' to reduce chance of conflict. Aug 16, 2013
Rakefile Complete rewrite of parsing algorithm. Use more recent .phoneformat f… Mar 18, 2013
phoney.gemspec

README.rdoc

phoney

This is a library for representing phone numbers. It provides a Phoney 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 = Phoney.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'
    
    Phoney.region = :de
    
    pn = Phoney.new("04105456789")
    pn.to_s           # "+49 4105 456789"
    pn.area_code      # "4105"
    pn.country_code   # "49"
    pn.number         # "456789"

Creating Phoney instances

Phoney gives you a Phoney 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 Phoney.region or pass the region code every time!

Phoney.region = :us

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

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

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

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

# falls back to US region, so also uses "1" for <tt>country_code</tt>
Phoney.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 = Phoney.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 Phoney 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 tests for different countries