phony 1.9.0 → 2.19.14

data/lib/phony/dsl.rb

@@ -1,27 +1,3 @@
-# # Switzerland (simplified):
-# #
-# country('41', fixed(2) >> local([3,2,2]))
-#
-# # Germany. Too big, we use a separate file:
-# #
-# Phony.define do
-#   country '49', match(...) >> split([...]) ||
-#                 one_of([...], :max_length => 5) >> split([...])
-# end
-#
-# # Denmark:
-# #
-# country('45', none >> split([2,2,2,2]))
-#
-# # Hungary:
-# #
-# country('36',
-#         match(/^104|105|107|112/) >> split([3,3]) ||
-#         one_of([1], :max_length => 2) >> split([3,4])
-# )
-#
-# Note: Perhaps the DSL should operate directly on country codes.
-#
 module Phony
 
   # For country definitions.
@@ -36,22 +12,84 @@ module Phony
   #
   # Phony.define.country ...
   #
-  def self.define
+  def self.define(&block)
     dsl = DSL.new
-    dsl.instance_eval &Proc.new if block_given?
+    dsl.instance_eval(&block) if block_given?
     dsl
   end
 
+  # Contains a number of DSL methods. Is used e.g. in the countries.rb file.
+  #
+  # Do not use directly, but instead use {Phony.define} to execute a block
+  # in the DSL instance's context.
+  #
+  # @example
+  #   Phony.define { ... }
+  #
   class DSL
 
-    # Start defining a country.
+    # Define a country's rules.
+    #
+    # Use the other DSL methods to define the country's rules.
+    #
+    # @param [String] country_code The country code of the country.
+    # @param [Phony::CountryCodes] definition Rules for this country.
+    #
+    # @return Undefined.
     #
-    # Example:
+    # @example Add a country with country code 27.
     #   country '27', # CC, followed by rules, for example fixed(2) >> ...
     #
-    def country country_code, country, validator = nil
-      Phony::CountryCodes.instance.add country_code, country
-      Phony::Validators.instance.add country_code, validator if validator
+    def country country_code, definition, options = {}
+      return unless Phony.config.load?(country_code)
+      
+      definition.with country_code, options
+      Phony::CountryCodes.instance.add country_code, definition
+    end
+    
+    # Designates a country code as reserved.
+    # A reserved country will result in an exception when trying to be used.
+    #
+    # @param [String] country_code The country code of the country.
+    #
+    # @return nil
+    #
+    # @example Designate country code 27 as reserved.
+    #   reserved('27')
+    #
+    def reserved country_code
+      # Does nothing, will just fail with an exception.
+    end
+    
+    # Define a country to use default rules (and to be done at some point).
+    #
+    # @return Rules for a country.
+    #
+    # @example Define country 27 to use default rules.
+    #   country '27', todo
+    #
+    def todo
+      none >> split(10)
+    end
+    
+    # This country uses a trunk code.
+    #
+    # @param [String] code The trunk code.
+    # @param [Hash] options Options hash. Pass :normalize (true/false) to indicate whether it needs to be normalized.
+    #
+    # @return TrunkCode A trunk code handler.
+    #
+    # @example Hungary uses 06.
+    #   country '36', trunk('06', normalize: false) | ...
+    #
+    # @example North America uses 1.
+    #   country '1', trunk('1%s', normalize: true) | ...
+    #
+    # @example Most countries which use a trunk code use 0. E.g. Romania.
+    #   country '40', trunk('0') | ...
+    #
+    def trunk code, options = {}
+      TrunkCode.new code, options
     end
 
     # National matcher & splitters.
@@ -61,25 +99,24 @@ module Phony
     # uses a zero prefix when formatted
     # with format :national.
     #
-    # Options:
-    #  * length: Length of the fixed length NDC.
-    #  * options: Set :zero to false to not add a zero on format :national.
+    # @param [Fixnum] length The length of the fixed length NDC.
+    # @param [Hash] options An options hash (set zero: 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.
+    # @return NationalSplitters::Fixed A fixed length national splitter.
+    #
+    # @example France. Uses a fixed NDC of size 1.
+    #   country '33', fixed(1) >> split(2,2,2,2)
     #
     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.
+    # Marks the country as not using an NDC. This rule will always match.
+    #
+    # @return NationalSplitters::None A no-ndc national splitter.
     #
-    # Examples:
-    #   * Denmark
-    #   * Norway
-    #   * Iceland
-    #   (and more)
+    # @example Denmark, Norway, Iceland.
     #
     def none
       NationalSplitters::None.instance_for
@@ -88,12 +125,14 @@ module Phony
     # 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.
+    # @param [Array<String>] ndcs A list of NDCs of variable length. Can contain :max_length => number to denote a maximum NDC length.
+    #
+    # @return NationalSplitters::Variable A variable size national splitter.
     #
-    # Example:
-    #   country '51', one_of('103', '105') >> split(3,3) # If it's either 103 or 105, then split ...
+    # @example With two NDCs
+    #   country '51',
+    #     # If it's either 103 or 105, then split ...
+    #     one_of('103', '105') >> split(3,3)
     #
     def one_of *ndcs
       options = Hash === ndcs.last ? ndcs.pop : {}
@@ -102,16 +141,17 @@ module Phony
       #
       ndcs = ndcs.first if Array === ndcs.first
 
-      NationalSplitters::Variable.new options[:max_length], ndcs
+      NationalSplitters::Variable.new options[:max_length], ndcs.map(&:freeze)
     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...
+    # @param [Regexp] regex A Regexp describing the NDCs (First group must contain the NDC, eg. /^(0\d{2})\d+$/) contains all NDCs with 0xx...
     #
-    # Example:
+    # @return NationalSplitters::Regex A regexp-based national splitter.
+    #
+    # @example With several NDC matchers.
     #   country '52',
     #     match(/^(0\d{2})\d+$/)   >> split(2,2,2,2) |
     #     match(/^(33|55|81)\d+$/) >> split(2,2,2,2) |
@@ -122,43 +162,45 @@ module Phony
       #
       raise "Regexp /#{regex.source}/ needs a group in it that defines which digits belong to the NDC." unless regex.source =~ /\(/
       
-      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
 
     # Local splitters.
     #
 
     # Splits the number into groups of given sizes.
     #
-    # Example:
+    # Also takes ranges.
+    #
+    # @param [Array<Fixnum>] local The local group sizes to split the local number part into.
+    #
+    # @return LocalSplitters::Fixed A fixed size local splitter.
+    #
+    # @example Splitting in 4 even groups of two digits.
     #   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.
+      # 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.
+    # Also takes ranges.
+    #
+    # @param [Hash] options Can contain option :fallback A fallback amount of group sizes in case it doesn't match.
+    #
+    # @return LocalSplitters::Regex A regexp-based local splitter.
     #
-    # Example:
+    # @example Norway
     #   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
+      LocalSplitters::Regex.instance_for options
     end
     
     # Validators
@@ -166,17 +208,20 @@ module Phony
     
     # Which NDCs are explicitly invalid?
     #
-    # Takes a regexp or a string.
+    # @param [Regexp, String] ndc A regexp or a string of invalid NDCs.
     #
-    # Example:
+    # @return Validators::NDC An NDC validator 
+    #
+    # @example NANP
     #   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
+    def invalid_ndcs *ndc
+      Validators::NDC.new invalid: ndc
     end
 
+
   end
 
 end

data/lib/phony/local_splitters/fixed.rb

@@ -27,7 +27,23 @@ module Phony
       # The format [3, 2, 2] splits a number like '3332222' into ['333', '22', '22'].
       #
       def initialize format = nil
-        @format = format || [3, 2, 2]
+        format = format && format.dup || [3, 2, 2]
+        @format, @length = extract_params format
+        @format << @format.pop + 10
+      end
+      
+      #
+      #
+      def extract_params format
+        if format.last.respond_to? :max
+          last = format.pop
+          length = format.inject(0) { |total, part| total + part }
+          length = (length+last.min..length+last.max)
+          format << last.min
+        else
+          length = format.inject(0) { |total, part| total + part }
+        end
+        [format, length]
       end
     
       # Split a local number according to an assumed country specific format.
@@ -43,6 +59,14 @@ module Phony
         end
       end
       
+      #
+      #
+      def plausible? rest, hints = {}
+        return true if hints[:check_length] == false
+        
+        @length === rest.inject(0) { |total, part| total + part.size }
+      end
+      
     end
     
   end

data/lib/phony/local_splitters/regex.rb

@@ -42,6 +42,15 @@ module Phony
         split_with number, fallback
       end
       
+      def plausible? rest, hints = {}
+        number = rest.inject('', :+)
+        mapping.each do |regex, format|
+          next unless number =~ regex
+          return plausible_with? number, format
+        end
+        plausible_with? number, fallback
+      end
+      
       private
         
         def split_with number, format
@@ -49,9 +58,14 @@ module Phony
             result << number.slice!(0..size-1)
             return result if number.empty?
             result
-          end
+          end << number
         end
-      
+        
+        def plausible_with? number, format
+          length = format.inject 0, :+
+          number.length == length
+        end
+
     end
     
   end

data/lib/phony/national_code.rb

@@ -3,13 +3,14 @@ module Phony
   # NationalCodes have a special numbers splitter, a national code splitter and a local code splitter.
   #
   class NationalCode
-
+    
+    attr_reader :local_splitter
+    
     #
     #
-    def initialize national_splitter, local_splitter, normalize = nil
+    def initialize national_splitter, local_splitter
       @national_splitter = national_splitter
       @local_splitter    = local_splitter
-      @normalize         = normalize != false
     end
 
     # Split gets a number without country code and splits it into
@@ -25,11 +26,10 @@ module Phony
     #
     # Note: Some cases, like Italy, don't remove the relative zero.
     #
-    def normalize national_number
-      return national_number unless @normalize
-      national_number.gsub(/^0+/, '')
+    def normalize national_number, options = {}
+      national_number.gsub(/\A0+/, EMPTY_STRING)
     end
 
   end
 
-end
+end

data/lib/phony/national_splitters/default.rb

@@ -1,15 +1,47 @@
 module Phony
 
   module NationalSplitters
-
+    
+    # TODO Default = Fixed.new(...)?
+    #
     class Default < DSL
 
       def self.instance_for
         @instance ||= new
       end
-
+      
+      # "Splits" the national part of a phone number into a single piece.
+      #
+      # @param [String] national_number An national part of a number.
+      #
+      # @return [Array<String>] An Array with the given number part as its element.
+      #
+      # @example Split the national part of a Swiss number.
+      #   Phony.split("1234567") # => ["1234567"]
+      #
       def split national_number
-        [national_number]
+        [nil, national_number]
+      end
+      
+      # By default, the national part of a number is always plausible.
+      #
+      # @param [String] rest An national part of a number (ignored).
+      # @param [Fixnum] size Size (ignored).
+      # @param [Hash] hints Hints (ignored).
+      #
+      # @return [Boolean] Always true.
+      #
+      # @example Split the national part of a Swiss number.
+      #   Phony.plausible?("1234567") # => true
+      #
+      def plausible? rest, size, hints = {}
+        true
+      end
+      
+      # A valid length (at least 3).
+      #
+      def length
+        3
       end
 
     end

data/lib/phony/national_splitters/dsl.rb

@@ -9,15 +9,20 @@ module Phony
       #
       #
       def >> local_splitter
-        country_for local_splitter, true
+        country_for local_splitter
       end
       
-      private
-      
-        def country_for local_splitter, with_zero
-          national_code = Phony::NationalCode.new self, local_splitter, with_zero
-          Phony::Country.new national_code
-        end
+      #
+      #
+      def country_for local_splitter
+        Phony::Country.new Phony::NationalCode.new(self, local_splitter)
+      end
+
+      # TODO Remove?
+      #
+      def reserved
+
+      end
       
     end
     

data/lib/phony/national_splitters/fixed.rb

@@ -20,7 +20,7 @@ module Phony
       
       def initialize size, options = {}
         @size = size
-        @zero = options[:zero] == false ? nil : '0'
+        @zero = nil # options[:zero] == false ? nil : '0'
       end
       
       # Takes a national number and splits it into ndc and rest.
@@ -30,6 +30,12 @@ module Phony
         [@zero, national_number.slice!(0...@size), national_number]
       end
       
+      # A valid length.
+      #
+      def length
+        @size
+      end
+      
     end
     
   end

data/lib/phony/national_splitters/none.rb

@@ -31,14 +31,18 @@ module Phony
       # since using nil is dangerous and breaks
       # abstraction)
       #
-      # Note: Actually, it might stay in.
-      #
-      # TODO Flip nil/false?
+      # Note: Decided it stays in. When formatting, it's turned into nil.
       #
       def split national_number
         [nil, false, national_number]
       end
       
+      # A valid length.
+      #
+      def length
+        0
+      end
+      
     end
     
   end

data/lib/phony/national_splitters/regex.rb

@@ -42,6 +42,12 @@ module Phony
         super national_number
       end
       
+      # A valid length.
+      #
+      def length
+        # raise "#{self.class.name} has no length that can be automatically extracted."
+      end
+      
     end
     
   end

data/lib/phony/national_splitters/variable.rb

@@ -18,17 +18,19 @@ module Phony
         
         # Extract a starting point.
         #
+        # This if can possibly be removed.
+        #
         presumed_code = if @mapped_ndc_min_length > 0
-          national_number.slice!(0..@mapped_ndc_min_length-1)
+          presumed_code = national_number.slice!(0..@mapped_ndc_min_length-1)
         else
           ''
         end
         
         # Try for all possible mapped.
         #
-        @mapped_ndc_min_length.upto(@mapped_ndc_max_length) do |i|
-          sized_ndcs = @ndcs[i]
-          return [@zero, presumed_code, national_number] unless sized_ndcs && !sized_ndcs.include?(presumed_code)
+        @mapped_ndc_min_length.upto @mapped_ndc_max_length do |i|
+          ndcs_of_size_i = @ndcs[i]
+          return [@zero, presumed_code, national_number] unless ndcs_of_size_i && !ndcs_of_size_i.include?(presumed_code)
           presumed_code << national_number.slice!(0..0)
         end
         
@@ -37,15 +39,17 @@ module Phony
         super fallback_number
       end
       
+      # A valid length.
+      #
+      def length
+        (@mapped_ndc_min_length..@mapped_ndc_max_length)
+      end
+      
       private
         
-        # def restructure ndc_map
-        #   optimize ndc_map.values.flatten
-        # end
-        
         # Optimizes and restructures the given ndcs array.
         #
-        def optimize(ndc_ary)
+        def optimize ndc_ary
           ndcs = {}
           ndc_ary.each do |ndc|
             ndcs[ndc.length] ||= []

data/lib/phony/trunk_code.rb

@@ -0,0 +1,57 @@
+module Phony
+
+  class TrunkCode
+  
+    # Parameters:
+    #  * code: The trunk code, e.g. 0.
+    #
+    # Options:
+    #  * normalize: [true (default), false] Remove the trunk code when normalizing (only use if number scheme is defined unambiguously).
+    #  * split: [true, false (default)] Remove the trunk code when splitting (only use if number scheme is defined unambiguously).
+    #  * format: [true (default), false] Add the trunk code when formatting (passing `false` will not add it).
+    #
+    def initialize code, options = {}
+      @code = code
+      @trunk_code_replacement = /\A#{code.gsub(%r{%s}, '')}/
+      @normalize = options[:normalize] || options[:normalize].nil?
+      @split     = options[:split]
+      @format    = options[:format] || options[:format].nil?
+    end
+    
+    # Prepends itself to the other codes.
+    #
+    def | other
+      other.codes.unshift self
+      other
+    end
+
+    # Split gets a number without country code and splits it into
+    # its parts.
+    #
+    def split national_number
+      national_number.gsub! @trunk_code_replacement, EMPTY_STRING if @split
+      return [self, national_number]
+    end
+    
+    # Normalize normalizes the given national number.
+    #
+    def normalize national_number, options = {}
+      national_number.gsub! @trunk_code_replacement, EMPTY_STRING if @normalize && options[:cc]
+      return national_number
+    end
+    
+    # Format the trunk code using the spaces given.
+    #
+    def format space, force = nil
+      if force || @format
+        if @code.size > 1
+          (@code % space).gsub(/\D/, ' ')
+        else
+          @code
+        end
+      end
+    end
+  
+  end
+
+end

data/lib/phony/vanity.rb

@@ -16,11 +16,11 @@ module Phony
     # Replaces (and normalizes) vanity characters of passed number with correct digits.
     #
     def self.replace number
-      number.tr *mapping
+      number.tr(*mapping)
     end
     
     # Returns true if there is a character in the number
-    # after the first four numbers.
+    # after the first three numbers.
     #
     @@vanity_regexp = /\A\d{3}[a-zA-Z]{6,12}\Z/
     def self.vanity? number
@@ -29,7 +29,7 @@ module Phony
     
     # Vanity-Normalized.
     #
-    @@vanity_normalizing_regexp = /^0*|[^\d\w]/
+    @@vanity_normalizing_regexp = /^0*|[^\w]/
     def self.normalized number
       number.gsub @@vanity_normalizing_regexp, ''
     end