i18n_phone_numbers 0.0.1

data/lib/i18n_phone_numbers/constants.rb

@@ -0,0 +1,58 @@
+module I18nPhoneNumbers
+  
+  module CountryCodeSource
+    
+    FROM_NUMBER_WITH_PLUS_SIGN = 1
+    FROM_NUMBER_WITH_IDD = 5
+    FROM_NUMBER_WITHOUT_PLUS_SIGN = 10
+    FROM_DEFAULT_COUNTRY = 20
+    
+  end
+  
+  module PhoneNumberType
+    
+    FIXED_LINE = 0
+    MOBILE = 1
+    # In some regions (e.g. the USA), it is impossible to distinguish between
+    # fixed-line and mobile numbers by looking at the phone number itself.
+    FIXED_LINE_OR_MOBILE = 2
+    # Freephone lines
+    TOLL_FREE = 3
+    PREMIUM_RATE = 4
+    # The cost of this call is shared between the caller and the recipient, and
+    # is hence typically less than PREMIUM_RATE calls. See
+    # http://en.wikipedia.org/wiki/Shared_Cost_Service for more information.
+    SHARED_COST = 5
+    # Voice over IP numbers. This includes TSoIP (Telephony Service over IP).
+    VOIP = 6
+    # A personal number is associated with a particular person, and may be routed
+    # to either a MOBILE or FIXED_LINE number. Some more information can be found
+    # here: http://en.wikipedia.org/wiki/Personal_Numbers
+    PERSONAL_NUMBER = 7
+    PAGER = 8
+    # Used for "Universal Access Numbers" or "Company Numbers". They may be
+    # further routed to specific offices, but allow one number to be used for a
+    # company.
+    UAN = 9
+    # Used for 'Voice Mail Access Numbers'.
+    VOICEMAIL = 10
+    # A phone number is of type UNKNOWN when it does not fit any of the known
+    # patterns for a specific country.
+    UNKNOWN = -1
+    
+  end
+  
+  # INTERNATIONAL and NATIONAL formats are consistent with the definition in
+  # ITU-T Recommendation E. 123. For example, the number of the Google Zurich
+  # office will be written as "+41 44 668 1800" in INTERNATIONAL format, and as
+  # "044 668 1800" in NATIONAL format. E164 format is as per INTERNATIONAL format
+  # but with no formatting applied, e.g. +41446681800.
+  module PhoneNumberFormat
+    
+    E164 = 0
+    INTERNATIONAL = 1
+    NATIONAL = 2
+    
+  end
+  
+end

data/lib/i18n_phone_numbers/metadata.rb

@@ -0,0 +1,345 @@
+module I18nPhoneNumbers
+  
+  class Metadata
+    
+                  # The ISO 3166-1 alpha-2 representation of a country/region
+    attr_accessor :id,
+                  
+                  # The country calling code that one would dial from overseas when trying to
+                  # dial a phone number in this country. For example, this would be "64" for
+                  # New Zealand.
+                  :country_code,
+                  
+                  # Note that the number format here is used for formatting only, not parsing.
+                  # Hence all the varied ways a user *may* write a number need not be recorded
+                  # - just the ideal way we would like to format it for them. When this element
+                  # is absent, the national significant number will be formatted as a whole
+                  # without any formatting applied.
+                  :number_formats,
+                  
+                  # This field is populated only when the national significant number is
+                  # formatted differently when it forms part of the INTERNATIONAL format
+                  # and NATIONAL format. A case in point is mobile numbers in Argentina:
+                  # The number, which would be written in INTERNATIONAL format as
+                  # +54 9 343 555 1212, will be written as 0343 15 555 1212 for NATIONAL
+                  # format. In this case, the prefix 9 is inserted when dialling from
+                  # overseas, but otherwise the prefix 0 and the carrier selection code
+                  # 15 (inserted after the area code of 343) is used.
+                  :intl_number_formats,
+                  
+                  # The general_desc contains information which is a superset of descriptions
+                  # for all types of phone numbers. If any element is missing in the
+                  # description of a specific type in the XML file, the element will inherit
+                  # from its counterpart in the general_desc. Every locale is assumed to have
+                  # fixed line and mobile numbers - if these types are missing in the XML
+                  # file, they will inherit all fields from the general_desc. For all other
+                  # types, if the whole type is missing in the xml file, it will be given a
+                  # national_number_pattern of "NA" and a possible_number_pattern of "NA".
+                  :general_desc,
+                  :fixed_line,
+                  :mobile,
+                  
+                  # The international_prefix of country A is the number that needs to be
+                  # dialled from country A to another country (country B). This is followed
+                  # by the country code for country B. Note that some countries may have more
+                  # than one international prefix, and for those cases, a regular expression
+                  # matching the international prefixes will be stored in this field.
+                  :international_prefix,
+                  
+                  # If more than one international prefix is present, a preferred prefix can
+                  # be specified here for out-of-country formatting purposes. If this field is
+                  # not present, and multiple international prefixes are present, then "+"
+                  # will be used instead.
+                  :preferred_international_prefix,
+                  
+                  # This field is populated only for countries or regions that share a country
+                  # calling code. If a number matches this pattern, it could belong to this
+                  # region. This is not intended as a replacement for IsValidForRegion, and
+                  # does not mean the number must come from this region (for example, 800
+                  # numbers are valid for all NANPA countries.) This field should be a regular
+                  # expression of the expected prefix match.
+                  :leading_digits,
+                  
+                  # The leading zero in a phone number is meaningful in some countries (e.g.
+                  # Italy). This means they cannot be dropped from the national number when
+                  # converting into international format. If leading zeros are possible for
+                  # valid international numbers for this region/country then set this to true.
+                  # This only needs to be set for the region that is the main_country_for_code
+                  # and all regions associated with that calling code will use the same
+                  # setting.
+                  :leading_zero_possible,
+                  
+                  # The national prefix of country A is the number that needs to be dialled
+                  # before the national significant number when dialling internally. This
+                  # would not be dialled when dialling internationally. For example, in New
+                  # Zealand, the number that would be locally dialled as 09 345 3456 would be
+                  # dialled from overseas as +64 9 345 3456. In this case, 0 is the national
+                  # prefix.
+                  :national_prefix,
+                  
+                  # This field is used for cases where the national prefix of a country
+                  # contains a carrier selection code, and is written in the form of a
+                  # regular expression. For example, to dial the number 2222-2222 in
+                  # Fortaleza, Brazil (area code 85) using the long distance carrier Oi
+                  # (selection code 31), one would dial 0 31 85 2222 2222. Assuming the
+                  # only other possible carrier selection code is 32, the field will
+                  # contain "03[12]".
+                  #
+                  # When it is missing from the XML file, this field inherits the value of
+                  # national_prefix, if that is present.
+                  :national_prefix_for_parsing,
+                  
+                  # Default value to be used in any numberFormat missing this attribute
+                  :national_prefix_formatting_rule,
+                  
+                  # This field is only populated and used under very rare situations.
+                  # For example, mobile numbers in Argentina are written in two completely
+                  # different ways when dialed in-country and out-of-country
+                  # (e.g. 0343 15 555 1212 is exactly the same number as +54 9 343 555 1212).
+                  # This field is used together with national_prefix_for_parsing to transform
+                  # the number into a particular representation for storing in the phonenumber
+                  # proto buffer in those rare cases.
+                  :national_prefix_transform_rule,
+                  
+                  # Specifies whether the mobile and fixed-line patterns are the same or not.
+                  # This is used to speed up determining phone number type in countries where
+                  # these two types of phone numbers can never be distinguished.
+                  :same_mobile_and_fixed_line_pattern, # true / false
+                  
+                  :main_country_for_code
+    
+    
+    module ClassMethods
+      
+      def load_from_xml(filename)
+        
+        file = File.open(File.join(File.dirname(__FILE__), "data", filename), "rb")
+        contents = file.read
+        Hash.from_xml(contents)
+        
+      end
+      
+      # hash indexed by country alpha2 code (ex: "FR", "CH", "MA", a.s.o)
+      def territories
+        
+        # territories are cached
+        return @territories if @territories
+        
+        
+        # if no yaml file to quickly load territories from,
+        # generate @territories from xml files
+        if !quick_load_territories
+          
+          @territories = {}
+          
+          files = [
+            "PhoneNumberMetaData.xml"
+          ]
+          
+          files.each { |filename|
+            
+            data = load_from_xml(filename)
+            
+            raw_territories = data["phoneNumberMetadata"]["territories"]["territory"]
+            raw_territories = [raw_territories] if !(Array === raw_territories) # if only 1 territory in xml file
+            
+            raw_territories.each { |territory|
+              @territories[territory["id"]] = self.new(territory)
+            }
+          
+          }
+          
+        end
+        
+        @territories
+        
+      end
+      
+      def countryToMetadata
+        
+        territories
+        
+      end
+      
+      def countryCodeToRegionCodeMap
+        
+        return @countryCodeToRegionCodeMap if @countryCodeToRegionCodeMap
+        
+        @countryCodeToRegionCodeMap = {}
+        
+        territories.each do |id, t|
+          
+          if !t.country_code.blank?
+            
+            # main country should be first in the list
+            if t.main_country_for_code
+              (@countryCodeToRegionCodeMap[t.country_code] ||= []).unshift(id)
+            else
+              (@countryCodeToRegionCodeMap[t.country_code] ||= []) << id
+            end
+            
+          end
+          
+        end
+        
+        @countryCodeToRegionCodeMap
+      end
+      
+      
+      # code to generate a YAML dump of @territories,
+      # generated file is used to quickly load territories next time
+      def dump_territories
+        
+        # .yml file location
+        file_path = File.join(File.dirname(__FILE__), "data", "quick_load.yml")
+        
+        # remove previous dump if exists
+        File.delete(file_path) if File.exists?(file_path)
+        
+        # generate territories from xml files
+        t = territories
+        
+        # quick fix multiline regexp strings that are not correctly dumped in yaml
+        t.each { |id, territory|
+          territory.national_prefix_for_parsing = territory.national_prefix_for_parsing.blank? ? territory.national_prefix_for_parsing :
+                                                                                                 territory.national_prefix_for_parsing.gsub(/\r?\n */, '')
+        }
+        
+        # and dump into .yml file !
+        
+        # Following code equivalent to :
+        #
+        #     destFile = File.new(destPath,"w")
+        #     destFile.print sql
+        #
+        # But when switching to ruby 1.9, we will be able to force output encoding to UTF-8 :
+        # (see : http://blog.grayproductions.net/articles/ruby_19s_three_default_encodings )
+        #
+        #     File.open(destPath, "w:UTF-8") do |file|  ...
+        #
+        File.open(file_path, "w") do |file|
+          file << "# ClicRDV comment :\n"
+          file << "#\n"
+          file << "#    This is an auto-generated file, DON'T MODIFY IT MANUALLY !\n"
+          file << "#\n"
+          file << "#    Call I18nPhoneNumbers::Metadata.dump_territories to generate\n"
+          file << "#    it from xml files instead.\n"
+          file << "#\n"
+          file << YAML.dump(t)
+        end
+        
+      end
+      
+      # helper to quickly load territories from YAML dump instead of parsing XML files
+      def quick_load_territories
+        
+        if File.exists?(File.join(File.dirname(__FILE__), "data", "quick_load.yml"))
+          
+          @territories = File.open( File.join(File.dirname(__FILE__), "data", "quick_load.yml") ) { |infile|
+            YAML::load( infile )
+          }
+          
+          return true
+        end
+        
+        return false
+        
+      end
+      
+    end
+    
+    
+    module InstanceMethods
+    
+      def initialize(hash = {})
+        
+        self.country_code = hash["countryCode"].to_i
+        self.id = hash["id"]
+        self.main_country_for_code = hash["mainCountryForCode"] == "true"
+        self.international_prefix = hash["internationalPrefix"]
+        self.leading_digits = hash["leadingDigits"]
+        self.leading_zero_possible = hash["leadingZeroPossible"] == "true"
+        self.national_prefix = hash["nationalPrefix"] || ''
+        self.national_prefix_for_parsing = hash["nationalPrefixForParsing"] || self.national_prefix
+        self.national_prefix_formatting_rule = (hash["nationalPrefixFormattingRule"] || '').
+                                                sub("$NP", self.national_prefix).
+                                                sub("$FG", "\\\\1")
+        
+        self.national_prefix_transform_rule = hash["nationalPrefixTransformRule"].blank? ? nil :
+                                              hash["nationalPrefixTransformRule"].gsub("$", '\\') # regexp substitution in ruby uses '\1' references instead of '$1'
+        
+        self.preferred_international_prefix = hash["preferredInternationalPrefix"]
+        
+        
+        self.general_desc = Hash === hash["generalDesc"] ? I18nPhoneNumbers::PhoneNumberDesc.new(hash["generalDesc"]) : nil
+        
+        self.fixed_line = Hash === hash["fixedLine"] ? I18nPhoneNumbers::PhoneNumberDesc.new(hash["fixedLine"]) : nil
+        if !self.fixed_line.nil? && self.fixed_line.possible_number_pattern.blank? && !self.general_desc.nil?
+          self.fixed_line.possible_number_pattern = self.general_desc.possible_number_pattern
+        end
+        
+        self.mobile = Hash === hash["mobile"] ? I18nPhoneNumbers::PhoneNumberDesc.new(hash["mobile"]) : nil
+        if !self.mobile.nil? && self.mobile.possible_number_pattern.blank? && !self.general_desc.nil?
+          self.mobile.possible_number_pattern = self.general_desc.possible_number_pattern
+        end
+        
+        if !self.mobile.nil? && !self.fixed_line.nil?
+          self.same_mobile_and_fixed_line_pattern = (self.mobile.national_number_pattern == self.fixed_line.national_number_pattern)
+        else
+          self.same_mobile_and_fixed_line_pattern = false # TODO : we don't know ?!?
+        end
+        
+        
+        # populate with available formats
+        self.number_formats = []
+        self.intl_number_formats = []
+        
+        if Hash === hash["availableFormats"]
+          
+          if !hash["availableFormats"]["numberFormat"].blank?
+            
+            # we get either a string or and array of strings (damn you XML !)
+            numberFormatList = hash["availableFormats"]["numberFormat"].class == Array ?
+                                    hash["availableFormats"]["numberFormat"] :
+                                    [hash["availableFormats"]["numberFormat"]]
+            
+            numberFormatList.each { |numberFormat|
+              
+              
+              # national format
+              nf = I18nPhoneNumbers::NumberFormat.new(numberFormat, self)
+              
+              self.number_formats << nf
+              
+              
+              # international format
+              next if numberFormat["intlFormat"] == "NA" # skip national-only rule
+              
+              numberFormat["format"] = numberFormat["intlFormat"] || numberFormat["format"]
+              
+              nf = I18nPhoneNumbers::NumberFormat.new(numberFormat, self)
+              
+              self.intl_number_formats << nf
+              
+            }
+            
+          end
+          
+        end
+        
+      end
+      
+      def national_prefix_for_parsing
+        
+        @national_prefix_for_parsing.nil? ? self.national_prefix : @national_prefix_for_parsing
+        
+      end
+      
+    end
+    
+    extend ClassMethods
+    include InstanceMethods
+    
+  end
+  
+end

data/lib/i18n_phone_numbers/number_format.rb

@@ -0,0 +1,87 @@
+module I18nPhoneNumbers
+  
+  class NumberFormat
+    
+                  # pattern is a regex that is used to match the national (significant)
+                  # number. For example, the pattern "(20)(\d{4})(\d{4})" will match number
+                  # "2070313000", which is the national (significant) number for Google London.
+                  # Note the presence of the parentheses, which are capturing groups what
+                  # specifies the grouping of numbers.
+    attr_accessor :pattern,
+                  
+                  # format specifies how the national (significant) number matched by
+                  # pattern should be formatted.
+                  # Using the same example as above, format could contain "$1 $2 $3",
+                  # meaning that the number should be formatted as "20 7031 3000".
+                  # Each $x are replaced by the numbers captured by group x in the
+                  # regex specified by pattern.
+                  :format,
+                  
+                  # This field is a regex that is used to match a certain number of digits
+                  # at the beginning of the national (significant) number. When the match is
+                  # successful, the accompanying pattern and format should be used to format
+                  # this number. For example, if leading_digits="[1-3]|44", then all the
+                  # national numbers starting with 1, 2, 3 or 44 should be formatted using the
+                  # accompanying pattern and format.
+                  #
+                  # The first leadingDigitsPattern matches up to the first three digits of the
+                  # national (significant) number; the next one matches the first four digits,
+                  # then the first five and so on, until the leadingDigitsPattern can uniquely
+                  # identify one pattern and format to be used to format the number.
+                  #
+                  # In the case when only one formatting pattern exists, no
+                  # leading_digits_pattern is needed.
+                  :leading_digits_patterns,
+                  
+                  # This field specifies how the national prefix ($NP) together with the first
+                  # group ($FG) in the national significant number should be formatted in
+                  # the NATIONAL format when a national prefix exists for a certain country.
+                  # For example, when this field contains "($NP$FG)", a number from Beijing,
+                  # China (whose $NP = 0), which would by default be formatted without
+                  # national prefix as 10 1234 5678 in NATIONAL format, will instead be
+                  # formatted as (010) 1234 5678; to format it as (0)10 1234 5678, the field
+                  # would contain "($NP)$FG". Note $FG should always be present in this field,
+                  # but $NP can be omitted. For example, having "$FG" could indicate the
+                  # number should be formatted in NATIONAL format without the national prefix.
+                  # This is commonly used to override the rule from generalDesc.
+                  #
+                  # When this field is missing, a number will be formatted without national
+                  # prefix in NATIONAL format. This field does not affect how a number
+                  # is formatted in other formats, such as INTERNATIONAL.
+                  :national_prefix_formatting_rule,
+                  
+                  # This field specifies how any carrier code ($CC) together with the first
+                  # group ($FG) in the national significant number should be formatted
+                  # when formatWithCarrierCode is called, if carrier codes are used for a
+                  # certain country.
+                  :carrier_code_formatting_rule
+                  
+    def initialize(hash, regionMetadata)
+      
+      self.pattern = hash["pattern"] || ''
+      self.format = (hash["format"] || '').gsub("$", '\\') # regexp substitution in ruby uses '\1' references instead of '$1'
+      
+      if !hash["leadingDigits"].blank?
+        leadingDigits = hash["leadingDigits"].class != Array ? [hash["leadingDigits"]] : hash["leadingDigits"]
+        self.leading_digits_patterns = leadingDigits.collect { |ld| ld.gsub(/\r?\n */,'') }
+      else
+        self.leading_digits_patterns = []
+      end
+      
+      # national_prefix_formatting_rule
+      self.national_prefix_formatting_rule = hash["nationalPrefixFormattingRule"] ||
+                                             regionMetadata.national_prefix_formatting_rule
+      
+      if !self.national_prefix_formatting_rule.blank?
+        self.national_prefix_formatting_rule = self.national_prefix_formatting_rule.
+                                                    sub("$NP", regionMetadata.national_prefix).
+                                                    sub("$FG", "\\\\1")
+      end
+      
+      self.carrier_code_formatting_rule = hash["carrierCodeFormattingRule"] || ''
+      
+    end
+    
+  end
+  
+end

data/lib/i18n_phone_numbers/phone_number.rb

@@ -0,0 +1,41 @@
+module I18nPhoneNumbers
+  
+  class PhoneNumber
+    
+    attr_accessor :raw_input,
+                  :country_code,
+                  :country_code_source,
+                  :national_number,
+                  :preferred_domestic_carrier_code,
+                  :italian_leading_zero
+    
+    def initialize(attrs = {})
+      
+      attrs.each_pair { |key, value|
+        
+        if [:raw_input, :country_code, :country_code_source, :national_number,
+            :preferred_domestic_carrier_code, :italian_leading_zero].include?(key.to_sym)
+          self.send(key.to_s + "=", value)
+        end
+        
+      }
+      
+    end
+    
+    # for tests purpose
+    def equals(other)
+      
+      return false if !(self.class === other) # not the same class
+      
+      [:country_code, :national_number, :italian_leading_zero].each do |attribute|
+        return false if self.send(attribute) != other.send(attribute)
+      end
+      
+      return true
+      
+    end
+    
+    
+  end
+  
+end

data/lib/i18n_phone_numbers/phone_number_desc.rb

@@ -0,0 +1,33 @@
+module I18nPhoneNumbers
+  
+  class PhoneNumberDesc
+    
+                  # The national_number_pattern is the pattern that a valid national
+                  # significant number would match. This specifies information such as its
+                  # total length and leading digits.
+    attr_accessor :national_number_pattern,
+                  
+                  # The possible_number_pattern represents what a potentially valid phone
+                  # number for this region may be written as. This is a superset of the
+                  # national_number_pattern above and includes numbers that have the area code
+                  # omitted. Typically the only restrictions here are in the number of digits.
+                  # This could be used to highlight tokens in a text that may be a phone
+                  # number, or to quickly prune numbers that could not possibly be a phone
+                  # number for this locale.
+                  :possible_number_pattern,
+                  
+                  # An example national significant number for the specific type. It should
+                  # not contain any formatting information.
+                  :example_number
+    
+    def initialize(hash)
+      
+      self.national_number_pattern = (hash["nationalNumberPattern"] || '').gsub(/\r?\n */,'')
+      self.possible_number_pattern = (hash["possibleNumberPattern"] || '').gsub(/\r?\n */,'')
+      self.example_number = (hash["exampleNumber"] || '').gsub(/\r?\n */,'')
+      
+    end
+    
+  end
+  
+end