phony 1.7.12 → 1.8.0

data/README.textile

@@ -13,7 +13,7 @@ This gem can normalize, format and split E164 numbers.
 
 The (admittedly crazy) *goal* of this Gem is to be able to format/split all phone numbers in the world.
 
-Currently handles Abhas, Afghan, Algerian, Austrian, Australian, Belgian, Brazilian, Chilean, Chinese, Croatian, Cuban, Czech, Danish, Dutch, Egyptian, French, German, Ghanan, Greek, Hungarian, Italian, Irish, Kazakh, Lithuanian, Malaysian, Mexican, New Zealand, Norwegian, Peruvian, Polish, Romanian, Russian, Singapore, Slovakian, South African, South Korean, South Osetian, Spanish, Swedish, Swiss, Thailand, Tunisian, Turkish, Liechtenstein, UK, US, Venezuelan, and Vietnamese numbers.
+Currently handles Abhas, Afghan, Algerian, Austrian, Australian, Belgian, Brazilian, Chilean, Chinese, Croatian, Cuban, Czech, Danish, Dutch, Egyptian, French, German, Ghanan, Greek, Hungarian, Italian, Irish, Kazakh, Lithuanian, Luxembourgian, Malaysian, Mexican, New Zealand, Nigerian, Norwegian, Peruvian, Polish, Romanian, Russian, Singapore, Slovakian, South African, South Korean, South Osetian, Spanish, Swedish, Swiss, Thailand, Tunisian, Turkish, Liechtenstein, UK, US, Venezuelan, and Vietnamese numbers.
 And to some extent, all others. Just try if it works for you.
 
 If it doesn't, please "enter an issue":http://github.com/floere/phony/issues.

data/lib/phony/countries.rb

@@ -295,7 +295,7 @@ Phony.define do
   country '244', todo # Angola
   country '245', todo # Guinea-Bissau
   country '246', todo # Diego Garcia
-  country '247', todo # Ascension
+  country '247', none >> split(4) # Ascension
   country '248', todo # Seychelles
   country '249', todo # Sudan
 

data/lib/phony/dsl.rb

@@ -44,7 +44,10 @@ module Phony
 
   class DSL
 
+    # Start defining a country.
     #
+    # Example:
+    #   country '27', # CC, followed by rules, for example fixed(2) >> ...
     #
     def country country_code, country, validator = nil
       Phony::CountryCodes.instance.add country_code, country
@@ -62,13 +65,36 @@ module Phony
     #  * length: Length of the fixed length NDC.
     #  * options: Set :zero to false to not add a zero on format :national.
     #
+    # Example:
+    #   country '33', fixed(1) >> split(2,2,2,2) # France, uses a fixed NDC of size 1.
+    #
     def fixed length, options = {}
       options[:zero] = true if options[:zero].nil?
       NationalSplitters::Fixed.instance_for length, options
     end
+    
+    # This country does not use an NDC. This rule will always match.
+    #
+    # Examples:
+    #   * Denmark
+    #   * Norway
+    #   * Iceland
+    #   (and more)
+    #
     def none
       NationalSplitters::None.instance_for
     end
+    
+    # If you have a number of (possibly) variable length NDCs
+    # that cannot be well expressed via regexp, use this.
+    #
+    # Parameters:
+    #   * ndcs A list of ndcs of variable length.
+    #   * Can contain :max_length => number to denote a maximum NDC length.
+    #
+    # Example:
+    #   country '51', one_of('103', '105') >> split(3,3) # If it's either 103 or 105, then split ...
+    #
     def one_of *ndcs
       options = Hash === ndcs.last ? ndcs.pop : {}
 
@@ -78,6 +104,19 @@ module Phony
 
       NationalSplitters::Variable.new options[:max_length], ndcs
     end
+    
+    # If you have a number of (possibly) variable length NDCs
+    # that can be well expressed via regexp, use this.
+    #
+    # Parameters:
+    #   * regex A regexp describing the NDCs (First group must contain the NDC, eg. /^(0\d{2})\d+$/) contains all NDCs with 0xx...
+    #
+    # Example:
+    #   country '52',
+    #     match(/^(0\d{2})\d+$/)   >> split(2,2,2,2) |
+    #     match(/^(33|55|81)\d+$/) >> split(2,2,2,2) |
+    #     match(/^(\d{3})\d+$/)    >> split(3,2,2)
+    #
     def match regex, options = {}
       # Check if regexp has a group in it.
       #
@@ -86,6 +125,9 @@ module Phony
       on_fail_take = options.delete :on_fail_take
       NationalSplitters::Regex.instance_for regex, options[:on_fail_take], options
     end
+    
+    # This country still uses a default NDC (and needs to be done, hence the todo).
+    #
     def todo
       none >> NationalSplitters::Default.instance_for
     end
@@ -93,18 +135,44 @@ module Phony
     # Local splitters.
     #
 
+    # Splits the number into groups of given sizes.
     #
+    # Example:
+    #   match(/^(0\d{2})\d+$/) >> split(2,2,2,2) # If it matches, split in 4 groups of size 2.
     #
     def split *local
       local << local.pop + 10 # Allow for call-through numbers with an arbitrary size.
       LocalSplitters::Fixed.instance_for local
     end
+    
+    # Matches on the rest of the number and splits according
+    # to the given value for the regexp key.
+    #
+    # Options:
+    #   * fallback A fallback amount of group sizes in case it doesn't match.
+    #
+    # Example:
+    #   country '47',
+    #     none >> matched_split(/^[1].*$/   => [3],
+    #                           /^[489].*$/ => [3,2,3],
+    #                           :fallback   => [2,2,2,2])
+    #
     def matched_split options = {}
       Phony::LocalSplitters::Regex.instance_for options
     end
     
     # Validators
     #
+    
+    # Which NDCs are explicitly invalid?
+    #
+    # Takes a regexp or a string.
+    #
+    # Example:
+    #   country '1',
+    #     fixed(3, :zero => false) >> split(3,4),
+    #     invalid_ndcs('911') # The regexp /911/ would also work.
+    #
     def invalid_ndcs ndc
       Validator.new.ndc_check ndc
     end

data/lib/phony/national_splitters/default.rb

@@ -9,7 +9,7 @@ module Phony
       end
 
       def split national_number
-        [nil, nil, national_number]
+        [national_number]
       end
 
     end

data/spec/lib/phony/countries_spec.rb

@@ -9,6 +9,9 @@ describe 'country descriptions' do
   end
 
   describe 'splitting' do
+    describe 'Ascension Island' do
+      it_splits '2473551', ['247', false, '3551']
+    end
     describe 'Afghanistan' do
       it_splits '93201234567', ['93', '20', '1234567'] # Kabul
     end

data/spec/lib/phony/dsl_spec.rb

@@ -8,7 +8,7 @@ describe Phony::DSL do
 
   it 'has a todo' do
     Phony.define do
-      todo.split("123456789012345").should == [nil, false, nil, nil, '123456789012345']
+      todo.split("123456789012345").should == [nil, false, '123456789012345']
     end
   end
   

data/spec/lib/phony/validations_spec.rb

@@ -22,6 +22,9 @@ describe 'validations' do
     # it 'is correct' do
     #   Phony.plausible?('+1911').should be_false
     # end
+    it "correctly plausibilizes to#{}do countries" do
+      Phony.plausible?('6327332350').should be_true
+    end
     it 'is correct' do
       Phony.plausible?('45 44 11 22 33').should be_true
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phony
 version: !ruby/object:Gem::Version
-  version: 1.7.12
+  version: 1.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-25 00:00:00.000000000 Z
+date: 2012-08-30 00:00:00.000000000 Z
 dependencies: []
 description: ! 'Fast international phone number (E164 standard) normalizing, splitting
   and formatting. Lots of formatting options: International (+.., 00..), national