countries-phone_numbers 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d299eda3bc0d2e84c08d735a501c4c47398964c
+  data.tar.gz: b33baf81c54d96734b71fc0f82383d35704e4b12
+SHA512:
+  metadata.gz: 68f5972c6d39e1106b576408360cbdb69c4cdcd81c56af2e7a85193b41edc22dc6af128ae05c6a4d519f96b124bc8b90c30a0bd58e2081431cf28cf44cc79c65
+  data.tar.gz: 42d5ee3f67a0874ec07b5a303be69a1a172b590e7c724e45c67e988b3073f4a672e3ebadd8afc1f65d0d1900fa763766ff8539ac88ce2d0dd2b6576a82851a17

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in countries-phone_numbers.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Ian Lloyd
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# Countries::PhoneNumbers
+
+Integrate phone number to country lookup functionality into the ever-popular [Countries](https://github.com/hexorx/countries) gem using the excellent [Phony](https://github.com/floere/phony) gem. This lets you find the country for a given phone number quickly and easily.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'countries-plus-phonenumbers'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install countries-plus-phonenumbers
+
+## Usage
+
+It's easy. Just use the `Country.find_country_by_phone_number(number)` or `Country.find_by_phone_number(number)` methods just like you would for any other Country search. And just like with default Country search methods, it will return either an array of data or a Country object.
+
+Time for some examples. Let's say you need to call your best pal, President Obama in the US White House.
+
+    country = Country.find_country_by_phone_number( '+1 202-456-1111' )
+    => #<Country:0x007febbac72ad8 @data={"continent"=>"North America", "address_format"=>"{{recipient}}\n{{street}}\n{{city}} {{region}} {{postalcode}}\n{{country}}", "alpha2"=>"US", "alpha3"=>"USA", "country_code"=>"1", "currency"=>"USD", "international_prefix"=>"011", "ioc"=>"USA", "latitude"=>"38 00 N", "longitude"=>"97 00 W", "name"=>"United States", "names"=>["United States of America", "Vereinigte Staaten von Amerika", "États-Unis", "Estados Unidos", "アメリカ合衆国", "Verenigde Staten"], "translations"=>{"en"=>"United States of America", "it"=>"Stati Uniti D'America", "de"=>"Vereinigte Staaten von Amerika", "fr"=>"États-Unis", "es"=>"Estados Unidos", "ja"=>"アメリカ合衆国", "nl"=>"Verenigde Staten"}, "national_destination_code_lengths"=>[3], "national_number_lengths"=>[10], "national_prefix"=>"1", "number"=>"840", "region"=>"Americas", "subregion"=>"Northern America", "un_locode"=>"US", "languages"=>["en"], "nationality"=>"American"}> 
+
+This gives you the normal country object. Treat it like you would any other search from the Country gem.
+
+    country.name
+    => "United States"
+
+    country.alpha2
+    => "US"
+
+## What about countries that share the same Country Code?
+
+When multiple countries share a single country code - for instance, the North American Number Plan (NANP) - CountryDetectors are employed to provide additional analysis and intepretation. These detectors are not perfect, but they should catch most ambiguous situations.
+
+The detectors are configured in `country_detectors.yaml`.
+
+## Why are there a boatload of pending specs?
+
+Any entries in the Country gem that do not have test cases will appear as pending specs. This is to help track which countries still need solid tests. If you can help by offering some numbers to validate, please contribute!
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/countries-phone_numbers.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'countries/phone_numbers/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "countries-phone_numbers"
+  spec.version       = Countries::PhoneNumbers::VERSION
+  spec.authors       = ["Ian Lloyd"]
+  spec.email         = ["ian.w.lloyd@me.com"]
+  spec.description   = %q{Find countries by phone numbers}
+  spec.summary       = %q{Integrate phone number searching into the Country gem using Phony}
+  spec.homepage      = "http://github.com/illoyd/countries-phone_numbers"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'countries', '>= 0.9'
+  spec.add_dependency 'phony', '>= 1.9'
+  
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/countries/iso3166.rb

@@ -0,0 +1,116 @@
+require 'countries'
+require 'phony'
+
+class ISO3166::Country
+
+  def self.normalize_phone_number( number )
+    Phony.normalize( number )
+  end
+
+  def self.tokenize_phone_number( number )
+    Phony.split( Phony.normalize( number ) )
+  end
+
+  ##
+  # Find the first country by the given telephone number. Returns an array of country code and data
+  def self.find_by_phone_number( number )
+    found = find_all_by_phone_number(number)
+    found.nil? ? nil : found.first
+  end
+
+  ##
+  # Find all possible countries for the given telephone number.
+  # Generally we try to eliminate duplicates by using country code specific detectors.
+  def self.find_all_by_phone_number( number )
+    normalised_number = tokenize_phone_number( number )
+    
+    # Is this a detector country?
+    detector = phone_number_detectors[normalised_number.first]
+    if detector
+      return detector.find_all_by_phone_number( normalised_number )
+     
+    # Otherwise ask the general code base for the number
+    else
+      return self.find_all_by_country_code( normalised_number.first )
+    end
+
+  rescue
+   return nil
+  end
+  
+  ##
+  # Find the first country by the given telephone number. Returns the country object itself.
+  def self.find_country_by_phone_number( number )
+    found = find_all_countries_by_phone_number(number)
+    found.nil? ? nil : found.first
+  end
+  
+  ##
+  # Find all possible countries for the given telephone number.
+  # Generally we try to eliminate duplicates by using country code specific detectors.
+  def self.find_all_countries_by_phone_number( number )
+    normalised_number = tokenize_phone_number( number )
+    
+    # Is this a detector country?
+    detector = phone_number_detector_for normalised_number.first
+    if detector
+      return detector.find_all_countries_by_phone_number( normalised_number )
+     
+    # Otherwise ask the general code base for the number
+    else
+      return self.find_all_countries_by_country_code( normalised_number.first )
+    end
+
+  rescue
+   return nil
+  end
+
+  ##
+  # Get the requested phone number detector based on the phone number's prefix.
+  def self.phone_number_detector_for( prefix )
+    prefix = prefix.to_s
+    detector = phone_number_detectors[ prefix ]
+    if detector.is_a? Hash
+      detector = Countries::PhoneNumbers::CountryDetector.build( detector )
+      phone_number_detectors[ prefix ] = detector
+    end
+    detector
+  end
+  
+  ##
+  # Find all countries with shared country codes.
+  def self.shared_country_codes
+    codes = Country.all.map { |cc| Country[cc[1]].country_code }.uniq
+    shared = codes.each_with_object({}){ |cc,h| h[cc] = Country.find_all_countries_by_country_code(cc) }
+    shared.reject!{ |key,entry| entry.nil? or entry.count <= 1 }
+    shared.each{ |cc,countries| shared[cc] = countries.map{ |c| c.name } }
+  end
+
+  ##
+  # Find all countries with shared country codes and do not have a dedicated detector.
+  def self.unresolved_country_codes
+    self.shared_country_codes.reject{ |key,value| self.phone_number_detectors.keys.include? key or key == '' }
+  end
+  
+protected
+
+  ##
+  # Collection of country detectors. Detectors are instantiated only when first needed.
+  def self.phone_number_detectors
+    @@phone_number_detectors ||= load_phone_number_detector_config
+  end
+  
+  ##
+  # Load phone number detector configuration.
+  def self.load_phone_number_detector_config
+    filename = File.join( 'lib', 'countries', 'phone_numbers', 'country_detectors.yaml' )
+    config = {}
+    File.open( filename ) do |file|
+      YAML.load_documents( file ) do |doc|
+        config[doc['applies_to'].to_s] = doc
+      end
+    end
+    config
+  end
+  
+end

data/lib/countries/phone_numbers/country_detector.rb

@@ -0,0 +1,44 @@
+class Countries::PhoneNumbers::CountryDetector
+
+  attr_accessor :country_codes, :applies_to, :default
+  
+  def self.build config
+    # Build a new config tool based on the given strategy
+    return case
+      when config.include?('start_with')
+        Countries::PhoneNumbers::StartWithCountryDetector.new config
+      when config.include?('one_of')
+        Countries::PhoneNumbers::OneOfCountryDetector.new config
+      else
+        Countries::PhoneNumbers::CountryDetector.new config
+      end
+  end
+  
+  def initialize config
+    self.applies_to = config['applies_to'].to_s
+    self.default = config['default'].to_s
+  end
+
+  def find_all_by_phone_number number
+    [ find_by_phone_number(number) ]
+  end
+  
+  def find_by_phone_number number
+    return Country.find_by_alpha2 find_alpha2(number)
+  end
+  
+  def find_all_countries_by_phone_number number
+    [ find_country_by_phone_number(number) ]
+  end
+  
+  def find_country_by_phone_number number
+    return Country[find_alpha2(number)]
+  end
+  
+protected
+
+  def find_alpha2(number)
+    self.default
+  end
+  
+end

data/lib/countries/phone_numbers/country_detectors.yaml

@@ -0,0 +1,123 @@
+--- # North American Numbering Plan
+applies_to: 1
+default: US
+one_of: {
+    CA: [ # Canada
+      403, 587, 780, 825, # Alberta
+      236, 250, 604, 672, 778, # British Columbia
+      204, 431, # Manitoba
+      506, # New Brunswick
+      709, # Newfoundland and Labrador
+      902, # Nova Scotia
+      226, 249, 289, 343, 365, 416, 437, 519, 613, 647, 705, 807, 905, # Ontario
+      902, # Prince Edward Island
+      418, 438, 450, 514, 579, 581, 819, 873, # Quebec
+      306, 639, # Saskatchewan
+      867 # Yukon, Northwest Territories, and Nunavut
+    ],
+    AS: [ 684 ], # American Samoa
+    AI: [ 264 ], # Anguila
+    AG: [ 268 ], # Antigua & Barbuda
+    BS: [ 242 ], # The Bahamas
+    BB: [ 246 ], # Barbados
+    BM: [ 441 ], # Bermuda
+    VG: [ 284 ], # British Virgin Islands
+    KY: [ 345 ], # Cayman Islands
+    DM: [ 767 ], # Dominica
+    DO: [ 809, 829, 849 ], # Dominican Republic
+    GD: [ 473 ], # Grenada
+    GU: [ 671 ], # Guam
+    JM: [ 876 ], # Jamaica
+    MS: [ 664 ], # Montserrat
+    KN: [ 869 ], # St Kitts & Nevis
+    MP: [ 670 ], # Northern Mariana Islands
+    PR: [ 787, 939 ], # Puerto Rico
+    LC: [ 758 ], # St. Lucia
+    VC: [ 784 ], # St Vincent & the Grenadines
+    SX: [ 721 ], # Sint Martin
+    TT: [ 868 ], # Trinidad & Tobago
+    TC: [ 649 ], # Turks & Caicos Islands
+    VI: [ 340 ] # Virgin Islands
+  }
+
+--- # Russia & Kazakhastan
+applies_to: 7
+default: RU
+start_with: {
+    KZ: [ 6, 7 ]
+  }
+
+--- # Italy & Vatican City
+applies_to: 39
+default: IT
+start_with: {
+    VA: [ '06698' ]
+  }
+
+--- # United Kingdom, Jersey, Gurnssey, & Isle of Man
+applies_to: 44
+default: GB
+start_with: {
+    GG: [ 1481, 7781, 7839, 7911 ],
+    JE: [ 1534, 7509, 7797, 7937, 7700, 7829 ],
+    IM: [ 1624, 7624, 7524, 7924 ],
+  }
+
+--- # Norway & Svalbard
+applies_to: 47
+default: 'NO'
+start_with: {
+    SJ: [ 79 ]
+  }
+
+--- # Australian Telephone Numbering Plan
+applies_to: 61
+default: AU
+start_with: {
+    CX: [ 89164 ],
+    CC: [ 89162 ]
+  }
+
+--- # Morocco & Western Sahara
+applies_to: 212
+default: MA
+start_with: {
+    SH: [ 5288, 5289 ]
+  }
+
+--- # Ascension Island (part of St Helena)
+applies_to: 247
+default: SH
+
+--- # Reunion & Mayotte
+applies_to: 262
+default: RE
+start_with: {
+    YT: [ 269, 639 ]
+  }
+
+--- # Finland & Analand Island
+applies_to: 358
+default: FI
+start_with: {
+    AX: [ 18, 457 ]
+  }
+
+--- # Falklands; South Sandwith Islands
+applies_to: 500
+default: FK
+
+--- # Guadalupe; Saint Barthelemy; Saint Martin (default to Guadalupe)
+applies_to: 590
+default: GP
+
+--- # Netherlands Antilles; Bonaire, Sint Eustatius and Saba; Curacao
+applies_to: 599
+default: AN
+start_with: {
+    CW: [ 97 ]
+  }
+
+--- # Norfolk Island & Antartica (We're just going to ignore Antartica)
+applies_to: 672
+default: NF

data/lib/countries/phone_numbers/one_of_country_detector.rb

@@ -0,0 +1,27 @@
+class Countries::PhoneNumbers::OneOfCountryDetector < Countries::PhoneNumbers::CountryDetector
+
+  def initialize( config )
+    super config
+    self.country_codes = config['one_of']
+    
+    # Standardise all country codes
+    self.country_codes.each do |alpha2, codes|
+      self.country_codes[alpha2.to_s] = codes.map{ |code| code.to_s }
+    end
+  end
+  
+protected
+
+  def find_alpha2 number
+    # Split the given number unless it is an array (assumes that it has already been split)
+    number = Country.tokenize_phone_number(number) unless number.is_a?(Array)
+  
+    # Loop over all prefixes
+    self.country_codes.each do |alpha2, codes|
+      return alpha2.to_s if codes.include? number[1]
+    end
+    
+    return self.default
+  end
+
+end

data/lib/countries/phone_numbers/start_with_country_detector.rb

@@ -0,0 +1,30 @@
+class Countries::PhoneNumbers::StartWithCountryDetector < Countries::PhoneNumbers::CountryDetector
+
+  def initialize( config )
+    super config
+    self.country_codes = config['start_with']
+    
+    # Standardise all country codes
+    self.country_codes.each do |alpha2, codes|
+      self.country_codes[alpha2.to_s] = codes.map{ |code| code.to_s }
+    end
+  end
+  
+protected
+
+  def find_alpha2 number
+    # Split the given number unless it is an array (assumes that it has already been split)
+    number = Country.tokenize_phone_number(number) unless number.is_a?(Array)
+    number = number.drop(1).join
+  
+    # Loop over all prefixes
+    self.country_codes.each do |alpha2, codes|
+      codes.each do |prefix|
+        return alpha2 if number.start_with? prefix.to_s
+      end
+    end
+    
+    return self.default
+  end
+
+end

data/lib/countries/phone_numbers/version.rb

@@ -0,0 +1,5 @@
+module Countries
+  module PhoneNumbers
+    VERSION = "0.0.1"
+  end
+end

data/lib/countries/phone_numbers.rb

@@ -0,0 +1,18 @@
+require "countries/phone_numbers/version"
+
+# Primary gems
+require 'countries'
+require 'phony'
+
+# Country::PhoneNumber
+require 'countries/phone_numbers/country_detector'
+require 'countries/phone_numbers/one_of_country_detector'
+require 'countries/phone_numbers/start_with_country_detector'
+
+# Gem extensions
+require 'countries/iso3166'
+
+module Countries
+  module PhoneNumbers
+  end
+end

data/spec/countries/country_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+require 'countries/phone_numbers'
+
+describe ISO3166::Country, '#find_*_by_phone_number' do
+  subject { Country }
+
+  # Test a bogus phone number
+  it 'ignores bogus phone numbers (single digit)' do
+    Country.find_country_by_phone_number( '5' ).should == nil
+  end
+  
+  # Test another bogus phone number
+  it 'ignores bogus phone numbers (text)' do
+    Country.find_country_by_phone_number( 'abc' ).should == nil
+  end
+  
+  # Test all data given in the 'TEST' block above
+  TEST_DATA.each do |alpha2, numbers|
+    numbers.each do |number|
+      it "recognises #{number} as #{alpha2.to_s}" do
+        Country.find_country_by_phone_number(number).should_not be_nil
+        Country.find_country_by_phone_number(number).alpha2.should == alpha2.to_s
+      end
+      it "returns only one country for #{number}" do
+        Country.find_all_countries_by_phone_number(number).should have(1).country
+      end
+    end
+  end
+  
+  Country.unresolved_country_codes.each do |country_code, countries|
+    pending "Need to resolve CC: #{country_code} for #{countries.join(', ')}."
+  end
+  
+  (Country.all.map{ |country| country[1] } - TEST_DATA.keys).each do |alpha2|
+    pending "No tests for #{Country[alpha2].name} (#{alpha2})."
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'countries/phone_numbers'
+
+require 'yaml'
+TEST_DATA = YAML.load_file( File.join( File.dirname(__FILE__), 'test_data.yaml' ) )
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end