has_phone_numbers 0.1.0 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,5 +1,15 @@
 == master
 
+== 0.2.0 / 2009-04-19
+
+* Add the ability to parse raw values [Matt Lightner]
+* Validate that the country code is known
+* Validate number lengths on a per-country code basis
+* Add the list of available country codes
+* Remove PhoneNumber#display_value in favor of using the Rails helper
+* Add dependency on Rails 2.3
+* Remove dependency on plugins_plus
+
 == 0.1.0 / 2008-12-14
 
 * Remove the PluginAWeek namespace

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2008 Aaron Pfeifer
+Copyright (c) 2006-2009 Aaron Pfeifer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -52,5 +52,8 @@ To run against a specific version of Rails:
 
 == Dependencies
 
-* Rails 2.1 or later
-* plugins_plus[http://github.com/pluginaweek/plugins_plugins] (optional if app files are copied to your project tree)
+* Rails 2.3 or later
+
+== References
+
+* Casey West - {Parse-PhoneNumber}[http://search.cpan.org/~cwest/Parse-PhoneNumber-1.1]

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'has_phone_numbers'
-  s.version           = '0.1.0'
+  s.version           = '0.2.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Demonstrates a reference implementation for handling phone numbers.'
   

data/app/models/phone_number.rb

@@ -1,42 +1,131 @@
 # Represents a phone number split into multiple parts:
-# * +country_code+ - Uniquely identifiers the country to which the number belongs. This value is based on the E.164 standard (http://en.wikipedia.org/wiki/E.164)
+# * +country_code+ - Uniquely identifiers the country to which the number belongs.
+#   This value is based on the E.164 standard (http://en.wikipedia.org/wiki/E.164)
 # * +number+ - The subscriber number (10 digits in length)
 # * +extension+ - A number that can route to different phones at a location
 # 
 # This phone number format is biased towards those types found in the United
 # States and may need to be adjusted for international support.
 class PhoneNumber < ActiveRecord::Base
-  belongs_to  :phoneable,
-                :polymorphic => true
+  # The valid lengths allowed per country code for area code + subscriber number
+  VALID_LENGTHS = {
+    1 =>  10,     7 => 10,      20 => 9,       27 => 9,      30 => 10,      31 => 9,
+    32 => 8..9,   33 => 9..10,  34 => 9,       36 => 8..9,   39 => 9,       40 => 9,
+    41 => 9..10,  43 => 7..13,  44 => 10..11,  45 => 8,      46 => 9,       47 => 8,     
+    48 => 9,      49 => 7..11,  51 => 8..9,    52 => 8..10,  53 => 8,       54 => 8..9, 
+    55 => 10,     56 => 8..9,   57 => 9..10,   58 => 10,     60 => 9..10,   61 => 9,
+    62 => 8..11,  63 => 8..10,  64 => 8..9,    65 => 8..9,   66 => 9..10,   81 => 9..10,
+    82 => 8..9,   84 => 7..10,  86 => 7..11,   90 => 10,     91 => 10,      92 => 9..10,
+    93 => 8..9,   94 => 10,     95 => 7..8,    98 => 10,     212 => 8,      213 => 8,
+    216 => 8,     218 => 8..9,  220 => 7,      221 => 7,     222 => 7,      223 => 8,
+    224 => 8,     225 => 8,     226 => 8,      227 => 8,     228 => 7,      229 => 8,
+    230 => 7,     231 => 6..8,  232 => 8,      233 => 5..8,  234 => 7..8,   235 => 7,
+    236 => 8,     237 => 8,     238 => 7,      239 => 6..7,  240 => 6,      241 => 6..8,
+    242 => 7,     243 => 8,     244 => 9,      245 => 7,     246 => 4..7,   247 => 4,
+    248 => 6,     249 => 9,     250 => 5..8,   251 => 9,     252 => 7..8,   253 => 6,
+    254 => 9,     255 => 9,     256 => 9,      257 => 8,     258 => 8..9,   260 => 9,
+    261 => 9,     262 => 10,    263 => 8..11,  264 => 6..7,  265 => 8,      266 => 8,
+    267 => 7,     268 => 7,     269 => 7,      290 => 4,     291 => 7,      297 => 7,
+    298 => 6,     299 => 6,     350 => 8,      351 => 9,     352 => 9,      353 => 9,
+    354 => 7..9,  355 => 7..9,  356 => 8,      357 => 8,     358 => 9,      359 => 8..10,
+    370 => 8,     371 => 8,     372 => 7..8,   373 => 8,     374 => 8,      375 => 9,
+    376 => 6..9,  377 => 8..9,  378 => 9..12,  380 => 8..9,  381 => 9,      382 => 8,
+    385 => 8,     386 => 8,     387 => 8,      388 => 8..10, 389 => 7..8,   420 => 9,
+    421 => 9,     423 => 7,     500 => 5,      501 => 7,     502 => 8,      503 => 8,
+    504 => 7..8,  505 => 8,     506 => 8,      507 => 7,     508 => 6,      509 => 8,
+    590 => 10,    591 => 8,     592 => 6..7,   593 => 8..9,  594 => 10,     595 => 9,
+    596 => 10,    597 => 6,     598 => 7..8,   599 => 7,     670 => 7,      672 => 6,
+    673 => 7,     674 => 7,     675 => 7,      676 => 5..7,  677 => 5,      678 => 5..7,
+    679 => 7,     680 => 7,     681 => 6,      682 => 5,     683 => 4,      685 => 6..7,
+    686 => 5,     687 => 6,     688 => 5,      689 => 6,     690 => 4,      691 => 7,
+    692 => 7,     800 => 8..12, 808 => 8,      850 => 8..9,  852 => 8,      853 => 8,
+    855 => 8,     856 => 8,     870 => 9,      871 => 9,     872 => 9,      873 => 9,
+    874 => 9,     878 => 9,     880 => 10,     881 => 6,     882 => 6,      883 => 6,
+    886 => 7..8,  960 => 7,     961 => 8,      962 => 8..9,  963 => 7..8,   964 => 8..10,
+    965 => 7,     966 => 8..9,  967 => 7..9,   968 => 8,     970 => 8,      971 => 7..9,
+    972 => 7..9,  973 => 8,     974 => 7,      975 => 7..8,  976 => 7..10,  977 => 7..8,
+    979 => 9,     991 => 9,     992 => 9,      993 => 8,     994 => 8..9,   995 => 9,
+    996 => 9,     998 => 9
+  }.stringify_keys
   
-  validates_presence_of     :phoneable_id,
-                            :phoneable_type,
-                            :country_code,
-                            :number
-  validates_numericality_of :country_code,
-                            :number
-  validates_numericality_of :extension,
-                              :allow_nil => true
-  validates_length_of       :country_code,
-                              :in => 1..3
-  validates_length_of       :number,
-                              :is => 10
-  validates_length_of       :extension,
-                              :maximum => 10,
-                              :allow_nil => true
+  # The list of country calling codes as defined by ITU-T recommendation E.164
+  COUNTRY_CODES = VALID_LENGTHS.keys
   
-  # Generates a human-readable version of the phone number, based on all of the
-  # various parts of the number.
-  # 
-  # For example,
-  # 
-  #   phone = PhoneNumber.new(:country_code => '1', :number => '123-456-7890')
-  #   phone.display_value     # => "1- 123-456-7890"
-  #   phone.extension = "123"
-  #   phone.display_value     # => "1- 123-456-7890 ext. 123"
-  def display_value
-    human_number = "#{country_code}- #{number}"
-    human_number << " ext. #{extension}" if extension
-    human_number
+  # Whether to always use the default country code configured for this model
+  # when parsing the raw content of a phone number
+  cattr_accessor :use_default_country_code_on_parse
+  @@use_default_country_code_on_parse = false
+  
+  belongs_to :phoneable, :polymorphic => true
+  
+  validates_presence_of :phoneable_id, :phoneable_type, :country_code, :number
+  validates_numericality_of :number
+  validates_numericality_of :extension, :allow_nil => true
+  validates_length_of :extension, :maximum => 10, :allow_nil => true
+  validates_inclusion_of :country_code, :in => COUNTRY_CODES
+  validates_each :number do |phone_number, attr, value|
+    country_code = phone_number.country_code
+    
+    if country_code && length = VALID_LENGTHS[country_code]
+      if length.is_a?(Range)
+        if value.nil? || value.size < length.begin
+          phone_number.errors.add(attr, :too_short, :count => length.begin)
+        elsif value.size > length.end
+          phone_number.errors.add(attr, :too_long, :count => length.end)
+        end
+      elsif value.nil? || value.size != length
+        phone_number.errors.add(attr, :wrong_length, :count => length) 
+      end
+    end
   end
+  
+  # The raw, unparsed content containing the phone number.  This can be parsed
+  # in various formats, such as:
+  # * 600 600 11 22
+  # * + 386 1 5853 449
+  # * +48 (22) 64 0001
+  # * 36 1 267-4636
+  # * +39-02-48230001
+  # * 202 331 996 x4621
+  # * 358 2 141 540 65 ext. 1423
+  attr_accessor :content
+  before_validation_on_create :parse_content, :if => :content
+  
+  private
+    # Parses the raw content of a phone number, extracting the following
+    # attributes:
+    # * country_code
+    # * number
+    # * extension
+    def parse_content
+      content = self.content.strip
+      
+      # Check for extension
+      if match = content.match(/\s*(?:(?:ext|ex|xt|x)[\s.:]*(\d+))$/i)
+        self.extension = match[1]
+        content.gsub!(match.to_s, '')
+      end
+ 
+      # Remove non-digits and leading 0
+      content.gsub!(/\D/, '')
+      content.gsub!(/^0+/, '')
+      
+      if use_default_country_code_on_parse
+        # Scrub pre-determined country code
+        content.gsub!(/^#{country_code}/, '')
+      else
+        # Try to figure out the country code.  It is not possible for one
+        # country code's number to overlap another.
+        (1..3).each do |length|
+          code = content[0, length]
+          if VALID_LENGTHS[code] # Fast lookup
+            self.country_code = code
+            content.gsub!(/^#{code}/, '')
+            break
+          end
+        end
+      end
+      
+      self.number = content
+    end
 end

data/lib/has_phone_numbers.rb

@@ -4,8 +4,7 @@ module HasPhoneNumbers
     # Creates the following association:
     # * +phone_number+ - All phone numbers associated with the current record.
     def has_phone_numbers
-      has_many  :phone_numbers,
-                  :as => :phoneable
+      has_many :phone_numbers, :as => :phoneable
     end
   end
 end

data/test/app_root/db/migrate/002_migrate_has_phone_numbers_to_version_1.rb

@@ -1,9 +1,13 @@
 class MigrateHasPhoneNumbersToVersion1 < ActiveRecord::Migration
   def self.up
-    Rails::Plugin.find(:has_phone_numbers).migrate(1)
+    ActiveRecord::Migrator.new(:up, "#{Rails.root}/../../db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:up)
+    end
   end
   
   def self.down
-    Rails::Plugin.find(:has_phone_numbers).migrate(0)
+    ActiveRecord::Migrator.new(:up, "#{Rails.root}/../../db/migrate", 0).migrations.each do |migration|
+      migration.migrate(:down)
+    end
   end
 end

data/test/unit/phone_number_test.rb

@@ -50,26 +50,13 @@ class PhoneNumberTest < Test::Unit::TestCase
     assert phone_number.errors.invalid?(:country_code)
   end
   
-  def test_should_require_country_code_be_a_number
-    phone_number = new_phone_number(:country_code => 'a')
+  def test_should_require_a_known_country_code
+    phone_number = new_phone_number(:country_code => '2')
     assert !phone_number.valid?
     assert phone_number.errors.invalid?(:country_code)
-  end
-  
-  def test_should_require_country_codes_be_between_1_and_3_numbers
-    phone_number = new_phone_number(:country_code => '')
-    assert !phone_number.valid?
-    assert phone_number.errors.invalid?(:country_code)
-    
-    phone_number.country_code += '1'
-    assert phone_number.valid?
     
-    phone_number.country_code += '11'
+    phone_number.country_code = '1'
     assert phone_number.valid?
-    
-    phone_number.country_code += '1'
-    assert !phone_number.valid?
-    assert phone_number.errors.invalid?(:country_code)
   end
   
   def test_should_require_a_number
@@ -84,17 +71,33 @@ class PhoneNumberTest < Test::Unit::TestCase
     assert phone_number.errors.invalid?(:number)
   end
   
-  def test_should_require_number_be_exactly_10_numbers
-    phone_number = new_phone_number(:number => '1' * 9)
+  def test_should_require_number_be_exact_for_country_code_without_range
+    phone_number = new_phone_number(:country_code => '1', :number => '1' * 9)
     assert !phone_number.valid?
-    assert phone_number.errors.invalid?(:number)
+    assert_equal 'is the wrong length (should be 10 characters)', phone_number.errors.on(:number)
     
     phone_number.number += '1'
     assert phone_number.valid?
     
     phone_number.number += '1'
     assert !phone_number.valid?
-    assert phone_number.errors.invalid?(:number)
+    assert_equal 'is the wrong length (should be 10 characters)', phone_number.errors.on(:number)
+  end
+  
+  def test_should_require_number_be_within_range_for_country_code_with_range
+    phone_number = new_phone_number(:country_code => '32', :number => '1' * 7)
+    assert !phone_number.valid?
+    assert_equal 'is too short (minimum is 8 characters)', phone_number.errors.on(:number)
+    
+    phone_number.number += '1'
+    assert phone_number.valid?
+    
+    phone_number.number += '1'
+    assert phone_number.valid?
+    
+    phone_number.number += '1'
+    assert !phone_number.valid?
+    assert_equal 'is too long (maximum is 9 characters)', phone_number.errors.on(:number)
   end
   
   def test_should_not_require_an_extension
@@ -102,7 +105,7 @@ class PhoneNumberTest < Test::Unit::TestCase
     assert phone_number.valid?
   end
   
-  def test_should_require_extension_be_at_most_10_numbers
+  def test_should_require_extension_be_at_most_10_digits
     phone_number = new_phone_number(:extension => '1' * 9)
     assert phone_number.valid?
     
@@ -150,18 +153,167 @@ class PhoneNumberAfterBeingCreatedTest < Test::Unit::TestCase
   def test_should_have_a_phoneable_association
     assert_equal @person, @phone_number.phoneable
   end
+end
+
+class PhoneNumberParserTest < Test::Unit::TestCase
+  def setup
+    @person = create_person
+    @phone_number = new_phone_number(:phoneable => @person, :country_code => nil, :number => nil, :extension => nil)
+  end
+  
+  def test_should_parse_country_code_with_1_digit
+    @phone_number.content = '11234567890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
   
-  def test_should_have_a_display_value
-    assert_equal '1- 1234567890', @phone_number.display_value
+  def test_should_parse_country_code_with_2_digits
+    @phone_number.content = '20123456789'
+    
+    assert @phone_number.valid?
+    assert_equal '20', @phone_number.country_code
+    assert_equal '123456789', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_country_code_with_3_digits
+    @phone_number.content = '21212345678'
+    
+    assert @phone_number.valid?
+    assert_equal '212', @phone_number.country_code
+    assert_equal '12345678', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_number_with_spaces
+    @phone_number.content = '1 123 456 7890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_number_with_dashes
+    @phone_number.content = '1-123-456-7890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_number_with_parentheses
+    @phone_number.content = '1- (123) 456-7890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_number_with_leading_zero
+    @phone_number.content = '011234567890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_number_with_multiple_leading_zeroes
+    @phone_number.content = '0011234567890'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_nil @phone_number.extension
+  end
+  
+  def test_should_parse_extension_with_leading_ext
+    @phone_number.content = '11234567890 ext. 123'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_equal '123', @phone_number.extension
+  end
+  
+  def test_should_parse_extension_with_leading_ex
+    @phone_number.content = '11234567890 ex:123'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_equal '123', @phone_number.extension
+  end
+  
+  def test_should_parse_extension_with_leading_xt
+    @phone_number.content = '11234567890 xt: 123'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_equal '123', @phone_number.extension
+  end
+  
+  def test_should_parse_extension_with_leading_x
+    @phone_number.content = '11234567890 x.  123'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_equal '123', @phone_number.extension
+  end
+  
+  def test_should_parse_extension_with_mixed_case
+    @phone_number.content = '11234567890 xT 123'
+    
+    assert @phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '1234567890', @phone_number.number
+    assert_equal '123', @phone_number.extension
+  end
+  
+  def test_should_not_be_valid_if_parse_fails
+    @phone_number.content = '1123456789'
+    
+    assert !@phone_number.valid?
+    assert_equal '1', @phone_number.country_code
+    assert_equal '123456789', @phone_number.number
+    assert_nil @phone_number.extension
   end
 end
 
-class PhoneNumberWithExtensionTest < Test::Unit::TestCase
+class PhoneNumberParserWithDefaultCountryCodeTest < Test::Unit::TestCase
   def setup
-    @phone_number = create_phone_number(:country_code => '1', :number => '1234567890', :extension => '123')
+    PhoneNumber.use_default_country_code_on_parse = true
+    
+    @person = create_person
+    @phone_number = new_phone_number(:phoneable => @person, :content => '7234567890 ex. 12')
+    @valid = @phone_number.valid?
+  end
+  
+  def test_should_be_valid
+    assert @valid
+  end
+  
+  def test_should_use_default_country_code
+    assert_equal '1', @phone_number.country_code
+  end
+  
+  def test_should_parse_number
+    assert_equal '7234567890', @phone_number.number
+  end
+  
+  def test_should_parse_extension
+    assert_equal '12', @phone_number.extension
   end
   
-  def test_should_have_a_display_value
-    assert_equal '1- 1234567890 ext. 123', @phone_number.display_value
+  def teardown
+    PhoneNumber.use_default_country_code_on_parse = false
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: has_phone_numbers
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Aaron Pfeifer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-14 00:00:00 -05:00
+date: 2009-04-19 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -38,8 +38,6 @@ files:
 - test/app_root/db/migrate
 - test/app_root/db/migrate/002_migrate_has_phone_numbers_to_version_1.rb
 - test/app_root/db/migrate/001_create_people.rb
-- test/app_root/config
-- test/app_root/config/environment.rb
 - test/app_root/app
 - test/app_root/app/models
 - test/app_root/app/models/person.rb
@@ -70,7 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: pluginaweek
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: Demonstrates a reference implementation for handling phone numbers.

data/test/app_root/config/environment.rb

@@ -1,9 +0,0 @@
-require 'config/boot'
-require "#{File.dirname(__FILE__)}/../../../../plugins_plus/boot"
-
-Rails::Initializer.run do |config|
-  config.plugin_paths << '..'
-  config.plugins = %w(plugins_plus has_phone_numbers)
-  config.cache_classes = false
-  config.whiny_nils = true
-end