phoner 1.0

data/lib/phoner/phone.rb

@@ -0,0 +1,222 @@
+# An object representing a phone number.
+#
+# The phone number is recorded in 3 separate parts:
+# * country_code - e.g. '385', '386'
+# * area_code - e.g. '91', '47'
+# * number - e.g. '5125486', '451588'
+#
+# All parts are mandatory, but country code and area code can be set for all phone numbers using
+#   Phone.default_country_code
+#   Phone.default_area_code
+#
+module Phoner
+  class Phone
+    attr_accessor :country_code, :area_code, :number, :extension, :country
+
+    cattr_accessor :default_country_code
+    cattr_accessor :default_area_code
+    cattr_accessor :named_formats
+
+    # length of first number part (using multi number format)
+    cattr_accessor :n1_length
+    # default length of first number part
+    @@n1_length = 3
+
+    @@named_formats = {
+      :default => "+%c%a%n",
+      :default_with_extension => "+%c%a%nx%x",
+      :europe => '+%c (0) %a %f %l',
+      :us => "(%a) %f-%l"
+    }
+
+    def initialize(*hash_or_args)
+      if hash_or_args.first.is_a?(Hash)
+        hash_or_args = hash_or_args.first
+        keys = {:country => :country, :number => :number, :area_code => :area_code, :country_code => :country_code, :extension => :extension}
+      else
+        keys = {:number => 0, :area_code => 1, :country_code => 2, :extension => 3, :country => 4}
+      end
+
+      self.number = hash_or_args[ keys[:number] ]
+      self.area_code = hash_or_args[ keys[:area_code] ] || self.default_area_code
+      self.country_code = hash_or_args[ keys[:country_code] ] || self.default_country_code
+      self.extension = hash_or_args[ keys[:extension] ]
+      self.country = hash_or_args[ keys[:country] ]
+
+      # Santity checks
+      raise "Must enter number" if self.number.blank?
+      raise "Must enter area code or set default area code" if self.area_code.blank?
+      raise "Must enter country code or set default country code" if self.country_code.blank?
+    end
+
+    def self.parse!(string, options={})
+        parse(string, options.merge(:raise_exception_on_error => true))
+    end
+
+    # create a new phone number by parsing a string
+    # the format of the string is detect automatically (from FORMATS)
+    def self.parse(string, options={})
+      return nil unless string.present?
+
+      Country.load
+
+      extension = extract_extension(string)
+      normalized = normalize(string)
+
+      options[:country_code] ||= self.default_country_code
+      options[:area_code] ||= self.default_area_code
+
+      if options[:country_code].is_a?(Array)
+        options[:country_code].find do |country_code|
+          parts = split_to_parts(normalized, options.merge(:country_code => country_code))
+          return parts if parts
+        end
+      else
+        parts = split_to_parts(normalized, options)
+      end
+
+      pn = Phone.new(parts) if parts
+      if pn.present? and extension.present?
+        pn.extension = extension
+      end
+      pn
+    end
+
+    # is this string a valid phone number?
+    def self.valid?(string, options = {})
+      begin
+        parse(string, options).present?
+      rescue
+        false  # don't raise exceptions on parse errors
+      end
+    end
+
+    def self.is_mobile?(string, options = {})
+      pn = parse(string, options)
+      return false if pn.nil?
+      pn.is_mobile?
+    end
+
+    private
+    # split string into hash with keys :country_code, :area_code and :number
+    def self.split_to_parts(string, options = {})
+      country = Country.detect(string, options[:country_code], options[:area_code])
+
+      if country.nil?
+        raise "Could not determine country" if options[:raise_exception_on_error]
+        return nil
+      end
+
+      country.number_parts(string, options[:area_code])
+    end
+
+    # fix string so it's easier to parse, remove extra characters etc.
+    def self.normalize(string_with_number)
+      string_with_number.sub(extension_regex, '').gsub(/\(0\)|[^0-9+]/, '').gsub(/^00/, '+')
+    end
+
+    def self.extension_regex
+      /[ ]*(ext|ex|x|xt|#|:)+[^0-9]*\(*([-0-9]{1,})\)*#?$/i
+    end
+
+    # pull off anything that look like an extension
+    #
+    def self.extract_extension(string)
+      return nil if string.nil?
+      if string.match extension_regex
+        extension = $2
+        return extension
+      end
+      #
+      # We already returned any recognizable extension.
+      # However, we might still have extra junk to the right
+      # of the phone number proper, so just chop it off.
+      #
+      idx = string.rindex(/[0-9]/)
+      return nil if idx.nil?
+      return nil if idx == (string.length - 1)      # at the end
+      string.slice!((idx+1)..-1)                    # chop it
+      return nil
+    end
+
+    public # instance methods
+
+    def area_code_long
+      "0" + area_code if area_code
+    end
+
+    # For many countries it's not apparent from the number
+    # Will return false positives rather than false negatives.
+    def is_mobile?
+      country.is_mobile? "#{area_code}#{number}"
+    end
+
+    # first n characters of :number
+    def number1
+      number[0...self.class.n1_length]
+    end
+
+    # everything left from number after the first n characters (see number1)
+    def number2
+      n2_length = number.size - self.class.n1_length
+      number[-n2_length, n2_length]
+    end
+
+    # Formats the phone number.
+    #
+    # if the method argument is a String, it is used as a format string, with the following fields being interpolated:  
+    #
+    # * %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 - entire extension
+    #
+    # if the method argument is a Symbol, it is used as a lookup key for a format String in Phone.named_formats
+    #   pn.format(:europe)
+    def format(fmt)
+      if fmt.is_a?(Symbol)
+        raise "The format #{fmt} doesn't exist'" unless named_formats.has_key?(fmt)
+        format_number named_formats[fmt]
+      else
+        format_number(fmt)
+      end
+    end
+
+    # the default format is "+%c%a%n"
+    def to_s
+      format(:default)
+    end
+
+    # does this number belong to the default country code?
+    def has_default_country_code?
+      country_code == self.class.default_country_code
+    end
+
+    # does this number belong to the default area code?
+    def has_default_area_code?
+      area_code == self.class.default_area_code
+    end
+
+    # comparison of 2 phone objects
+    def ==(other)
+      methods = [:country_code, :area_code, :number, :extension]
+      methods.all? { |method| other.respond_to?(method) && send(method) == other.send(method) }
+    end
+
+    private
+
+    def format_number(fmt)
+      result = fmt.gsub("%c", country_code || "").
+             gsub("%a", area_code || "").
+             gsub("%A", area_code_long || "").
+             gsub("%n", number || "").
+             gsub("%f", number1 || "").
+             gsub("%l", number2 || "").
+             gsub("%x", extension || "")
+      return result
+    end
+  end
+end

data/lib/phoner/version.rb

@@ -0,0 +1,3 @@
+module Phoner
+  VERSION = "1.0"
+end

data/phoner.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'phoner/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "phoner"
+  gem.version       = Phoner::VERSION
+  gem.authors       = ['Tomislav Car', 'Todd Eichel', 'Don Morrison', 'Wesley Moxam', 'Paul Chavard']
+  gem.email         = ['tomislav@infinum.hr', 'todd@toddeichel.com', 'elskwid@gmail.com', 'wesley.moxam@gmail.com', "paul@chavard.net"]
+
+  gem.description = "Phone number parsing, validation and formatting."
+  gem.summary = "Phone number parsing, validation and formatting"
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "activesupport"
+  gem.add_development_dependency "rake"
+end

data/test/countries/ae_test.rb

@@ -0,0 +1,15 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## UAE
+class AETest < Phoner::TestCase
+  def test_local
+    parse_test('+97142063944',  '971', '4',  '2063944', 'United Arab Emirates', false)
+    parse_test('+97122063944',  '971', '2',  '2063944', 'United Arab Emirates', false)
+  end
+  
+  def test_mobile
+    parse_test('+971502063944', '971', '50', '2063944', 'United Arab Emirates', true)
+    parse_test('+971552063944', '971', '55', '2063944', 'United Arab Emirates', true)
+  end
+
+end

data/test/countries/af_test.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Afghanistan
+class AFTest < Phoner::TestCase
+  def test_local
+    parse_test('+93201234567', '93', '20', '1234567', 'Afghanistan', false)
+  end
+
+  def test_mobile
+    parse_test('+93712345678', '93', '7', '12345678', 'Afghanistan', true)
+  end
+end

data/test/countries/al_test.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Albania
+class ALTest < Phoner::TestCase
+  def test_local
+    parse_test('+35541234567', '355', '4', '1234567', 'Albania', false)
+  end
+
+  def test_mobile
+    parse_test('+355612345678', '355', '6', '12345678', 'Albania', true)
+  end
+end

data/test/countries/ar_test.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Argentina
+class ARTest < Phoner::TestCase
+  def test_local
+    parse_test('+541112345678', '54', '11', '12345678', 'Argentina', false)
+  end
+
+  def test_mobile
+    parse_test('+5498211534567', '54', '9821', '1534567', 'Argentina', true)
+  end
+end

data/test/countries/at_test.rb

@@ -0,0 +1,14 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Austria
+# Austrian numbers are, ugh, strange. The matching patterns used are minimal :/
+# and will result in many false positives
+class ATTest < Phoner::TestCase
+  def test_local
+    parse_test('+4354321', '43', "5432", '1', 'Austria', false)
+  end
+
+  def test_mobile
+    parse_test('+43612345678', '43', '6', '12345678', 'Austria', true)
+  end
+end

data/test/countries/au_test.rb

@@ -0,0 +1,48 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+# 0x 5551 reserved for fictitious use. (not including x=3)
+# 0x 7010 reserved for fictitious use.
+
+## Australia
+class AUTest < Phoner::TestCase
+
+  # 00 Emergency and International access
+  # 01 Alternate phone services
+  # 014 Satellite phone services
+  # 016 Paging [+3D or +6D]
+  # 018 Analogue (AMPS) mobile phone - few numbers still in use [+6D]
+  # 0198 Data networks [+2D or +6D] - e.g. 0198 379 000 is the Dial-Up POP number for iiNet
+
+  # 02 Central East region (NSW, ACT)
+  def test_central_east
+    parse_test('+61 2 5551 1234', '61', '2', '55511234')
+  end
+
+  # 03 South-east region (VIC, TAS)
+  def test_south_east
+    parse_test('+61 3 5551 1234', '61', '3', '55511234')
+  end
+
+  # 04 Mobile services (Digital - GSM, CDMA, 3G)
+  def test_mobile
+    parse_test('+61 4 5551 1234', '61', '4', '55511234', 'Australia', true)
+  end
+
+  # 05 Universal/Personal numberings (uncommon)
+  def test_personal
+    parse_test('+61 5 5551 1234', '61', '5', '55511234', 'Australia', false)
+  end
+
+  # 07 North-east region (QLD)
+  def test_north_east
+    parse_test('+61 7 5551 1234', '61', '7', '55511234')
+  end
+
+  # 08 Central and West region (SA, NT, WA)
+  def test_central
+    parse_test('+61 8 5551 1234', '61', '8', '55511234')
+  end
+
+  # (Geographical region boundaries do not exactly follow state borders.)
+  # 1 Non-geographic numbers
+end

data/test/countries/ba_test.rb

@@ -0,0 +1,9 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Bosnia and Herzegovina
+class BATest < Phoner::TestCase
+  def test_local
+    parse_test('+387 33 25 02 33', '387', '33', '250233', "Bosnia and Herzegovina", false)
+    parse_test('+387 61 25 02 33', '387', '6', '1250233', "Bosnia and Herzegovina", true)
+  end
+end

data/test/countries/bd_test.rb

@@ -0,0 +1,17 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Bangladesh
+class BDTest < Phoner::TestCase
+  def test_local
+    parse_test('+8801715379982', '880', '171', '5379982', 'Bangladesh', true)
+    parse_test('+8801191573647', '880', '119', '1573647', 'Bangladesh', true)
+    parse_test('+88021915736', '880', '2', '1915736', 'Bangladesh', false)
+  end
+
+  def test_with_default_country
+    Phoner::Phone.default_country_code = '880'
+    parse_test('1715379982', '880', '171', '5379982', 'Bangladesh', true)
+    parse_test('1191573647', '880', '119', '1573647', 'Bangladesh', true)
+    parse_test('21915736', '880', '2', '1915736', 'Bangladesh', false)
+  end
+end

data/test/countries/be_test.rb

@@ -0,0 +1,120 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+## Belgium
+class BETest < Phoner::TestCase
+
+  def test_mobile
+    parse_test('+32 4 12345678', '32', '4', '12345678', 'Belgium', true)
+  end
+
+  ## single digit
+  # 02:   Brussels (Bruxelles/Brussel)
+  def test_brussels
+    parse_test('+32 2 1234567', '32', '2', '1234567', 'Belgium', false)
+  end
+  # 03:   Antwerpen (Antwerp), Sint-Niklaas
+  def test_antwerpen
+    parse_test('+32 3 1234567', '32', '3', '1234567')
+  end
+  # 04:   Liège (Luik), Voeren (Fourons)
+  def test_liege
+    parse_test('+32 4 1234567', '32', '4', '1234567', 'Belgium', false)
+  end
+  # 09:   Gent (Ghent/Gand)
+  def test_gent
+    parse_test('+32 9 1234567', '32', '9', '1234567')
+  end
+
+  ## two digit
+  # 010:  Wavre (Waver)
+  def test_wavre
+    parse_test('+32 10 123456', '32', '10', '123456')
+  end
+  # 011:  Hasselt
+  def test_hasselt
+    parse_test('+32 11 123456', '32', '11', '123456')
+  end
+  # 012:  Tongeren (Tongres)
+  def test_tongeren
+    parse_test('+32 12 123456', '32', '12', '123456')
+  end
+  # 013:  Diest
+  def test_diest
+    parse_test('+32 13 123456', '32', '13', '123456')
+  end
+  # 014:  Herentals, Turnhout
+  # 015:  Mechelen (Malines)
+  # 016:  Leuven (Louvain), Tienen (Tirlemont)
+  # 019:  Waremme (Borgworm)
+  def test_waremme
+    parse_test('+32 19 123456', '32', '19', '123456')
+  end
+
+  # 050:  Brugge (Bruges), Zeebrugge
+  def test_brugge
+    parse_test('+32 50 123456', '32', '50', '123456')
+  end
+  # 051:  Roeselare (Roulers)
+  def test_roeselare
+    parse_test('+32 51 123456', '32', '51', '123456')
+  end
+  # 052:  Dendermonde (Termonde)
+  # 053:  Aalst (Alost)
+  # 054:  Ninove
+  # 055:  Ronse (Renaix)
+  # 056:  Kortrijk (Courtrai), Comines-Warneton, Mouscron (Moeskroen)
+  # 057:  Ieper (Ypres)
+  # 058:  Veurne (Furnes)
+  # 059:  Oostende (Ostend)
+  def test_oostende
+    parse_test('+32 59 123456', '32', '59', '123456')
+  end
+  
+  # 060:  Chimay
+  def test_chimay
+    parse_test('+32 60 123456', '32', '60', '123456')
+  end
+  # 061:  Bastogne, Libramont-Chevigny
+  # 063:  Arlon (Aarlen)
+  # 064:  La Louviere
+  # 065:  Mons (Bergen)
+  # 067:  Nivelles (Nijvel)
+  def test_nivelles
+    parse_test('+32 67 123456', '32', '67', '123456')
+  end
+  # 068:  Ath (Aat)
+  # 069:  Tournai (Doornik)
+
+  # 070:  Specialty Numbers (i.e. bus information or bank information)
+  def test_specialty
+    parse_test('+32 70 123456', '32', '70', '123456')
+  end
+  # 071:  Charleroi
+
+  # 081:  Namur (Namen)
+  def test_namur
+    parse_test('+32 81 123456', '32', '81', '123456')
+  end
+  # 082:  Dinant
+  # 083:  Ciney
+  # 084:  Jemelle, Marche-en-Famenne
+  # 085:  Huy
+  # 086:  Durbuy
+  # 087:  Verviers
+  # 089:  Genk
+
+  # 0800: toll free service
+  def test_toll_free
+    parse_test('+32 800 12345', '32', '800', '12345')
+  end
+
+  # 090x: Premium numbers (0900, 0901, 0902, 0903, 0904, 0905, 0906, 0907, 0908, 0909)
+  def test_premium_900
+    parse_test('+32 900 12345', '32', '900', '12345')
+  end
+
+  def test_premium_901
+    parse_test('+32 901 12345', '32', '901', '12345')
+  end
+
+end