phonelib 0.6.2 → 0.6.3

data/lib/phonelib/data_importer.rb

@@ -1,7 +1,7 @@
 require 'phonelib/data_importer_helper'
 
 module Phonelib
-  # module processes creation of data files needed for this gem
+  # @private module processes creation of data files needed for this gem
   module DataImporter
     require 'nokogiri'
 
@@ -13,7 +13,7 @@ module Phonelib
       Importer.new
     end
 
-    # class with functionality for importing data
+    # @private class with functionality for importing data
     class Importer
       include Phonelib::DataImporterHelper
 
@@ -31,18 +31,25 @@ module Phonelib
       # carrier data dir in repo
       CARRIER_DIR = 'resources/carrier/en/'
       # timezones data dir in repo
-      TIMEZONES_DIR= 'resources/timezones/'
+      TIMEZONES_DIR = 'resources/timezones/'
 
       # class initialization method
       def initialize
         @destination = File.path(
-            "#{File.dirname(__FILE__)}/../../data/libphonenumber/")
+          "#{File.dirname(__FILE__)}/../../data/libphonenumber/")
         @data = {}
         @prefixes = {}
         @geo_names = []
         @timezones = []
         @carriers = []
 
+        run_import
+      end
+
+      private
+
+      # running import method
+      def run_import
         clone_repo
         import_main_data
         import_short_data
@@ -53,8 +60,6 @@ module Phonelib
         save_data_file
       end
 
-      private
-
       # method saves parsed data to data files
       def save_data_file
         data_file =
@@ -84,7 +89,7 @@ module Phonelib
 
         system("rm -rf #{@destination}")
         cloned = system("git clone #{repo} #{@destination} --depth 1 -b master")
-        raise 'Could not clone repo' unless cloned
+        fail 'Could not clone repo' unless cloned
       end
 
       # method parses main data file
@@ -125,15 +130,14 @@ module Phonelib
       def import_alternate_formats
         puts 'IMPORTING ALTERNATE FORMATS'
 
-
         main_from_xml("#{@destination}#{FORMATS_FILE}").elements.each do |el|
-          el.children.each do | phone_type |
-            if phone_type.name == 'availableFormats'
-              formats = parse_formats(phone_type.children)
+          el.children.each do |phone_type|
+            next unless phone_type.name == 'availableFormats'
 
-              country_code = el.attribute('countryCode').value
-              @data[get_country_by_code(country_code)][:formats] += formats
-            end
+            formats = parse_formats(phone_type.children)
+
+            country_code = el.attribute('countryCode').value
+            @data[get_country_by_code(country_code)][:formats] += formats
           end
         end
       end
@@ -175,7 +179,7 @@ module Phonelib
         types = {}
         formats = []
 
-        without_comments(children).each do | phone_type |
+        without_comments(children).each do |phone_type|
           if phone_type.name == 'availableFormats'
             formats = parse_formats(phone_type.children)
           else
@@ -218,7 +222,7 @@ module Phonelib
 
           without_comments(format.children).each do |f|
             current_format[name2sym(f.name)] =
-                str_clean(f.children.first, is_not_format(f.name))
+                str_clean(f.children.first, not_format?(f.name))
           end
 
           current_format
@@ -242,13 +246,13 @@ module Phonelib
 
       # method finds country by country prefix
       def get_country_by_code(country_code)
-        match = @data.select { |k, v| v[:country_code] == country_code }
+        match = @data.select { |_k, v| v[:country_code] == country_code }
         if match.size > 1
-          match = match.select { |k, v| v[:main_country_for_code] == 'true' }
+          match = match.select { |_k, v| v[:main_country_for_code] == 'true' }
         end
 
         match.keys.first
       end
     end
   end
-end
+end

data/lib/phonelib/data_importer_helper.rb

@@ -1,5 +1,5 @@
 module Phonelib
-  # helper module for parsing raw libphonenumber data
+  # @private helper module for parsing raw libphonenumber data
   module DataImporterHelper
     # xml comments attributes names that should not be parsed
     XML_COMMENT_ATTRIBUTES = %w(text comment)
@@ -20,7 +20,7 @@ module Phonelib
     end
 
     # method for checking if element name is not a format element
-    def is_not_format(name)
+    def not_format?(name)
       !XML_FORMAT_NAMES.include? name
     end
 
@@ -35,18 +35,18 @@ module Phonelib
     def get_hash_from_xml(data, type)
       hash = {}
       case type
-        when :attributes
-          data.attributes.each do |k, v|
-            hash[name2sym(k)] = str_clean(v)
-          end
-        when :children
-          data.each do |f|
-            hash[name2sym(f[0])] = f[1]
-          end
-        when :element
-          data.elements.each do |child|
-            hash[name2sym(child.name)] = str_clean(child.children.first)
-          end
+      when :attributes
+        data.attributes.each do |k, v|
+          hash[name2sym(k)] = str_clean(v)
+        end
+      when :children
+        data.each do |f|
+          hash[name2sym(f[0])] = f[1]
+        end
+      when :element
+        data.elements.each do |child|
+          hash[name2sym(child.name)] = str_clean(child.children.first)
+        end
       end
       hash
     end
@@ -66,7 +66,7 @@ module Phonelib
     # get main body from parsed xml document
     def main_from_xml(file)
       xml_data = File.read(file)
-      xml_data.force_encoding("utf-8")
+      xml_data.force_encoding('utf-8')
 
       doc = Nokogiri::XML(xml_data)
       doc.elements.first.elements.first
@@ -87,4 +87,4 @@ module Phonelib
       s.gsub(/[A-Z]+/) { |m| "_#{m.downcase}" }
     end
   end
-end
+end

data/lib/phonelib/phone.rb

@@ -1,26 +1,26 @@
 module Phonelib
   # class for parsed phone number, includes validation and formatting methods
   class Phone
-    # defining reader methods for class variables
-    # original phone number passed for parsing
+    # @!attribute [r] original
+    # @return [String] original phone number passed for parsing
     attr_reader :original
-    # phone extension passed for parsing after a number
+    # @!attribute [r] extension
+    # @return [String] phone extension passed for parsing after a number
     attr_reader :extension
 
     # including module that has all phone analyzing methods
     include Phonelib::PhoneAnalyzer
     include Phonelib::PhoneExtendedData
+    include Phonelib::PhoneFormatter
 
     # class initialization method
-    #
-    # ==== Attributes
-    #
-    # * +phone+   - Phone number for parsing
-    # * +country+ - Country specification for parsing. Must be ISO code of
-    #   country (2 letters) like 'US', 'us' or :us for United States
-    #
-    def initialize(original, country = nil)
-      @original, @extension = separate_extension(original)
+    # @param phone [String] Phone number for parsing
+    # @param country [String|Symbol] Country specification for parsing.
+    #   Must be ISO code of country (2 letters) like 'US', 'us' or :us
+    #   for United States
+    # @return [Phonelib::Phone] parsed phone instance
+    def initialize(phone, country = nil)
+      @original, @extension = separate_extension(phone.to_s)
       @extension.gsub!(/[^0-9]/, '') if @extension
 
       if sanitized.empty?
@@ -33,6 +33,7 @@ module Phonelib
     end
 
     # method to get sanitized phone number (only numbers)
+    # @return [String] Sanitized phone number
     def sanitized
       @sanitized = if Phonelib.strict_check
                      @original
@@ -42,36 +43,43 @@ module Phonelib
     end
 
     # Returns all phone types that matched valid patterns
+    # @return [Array] all valid phone types
     def types
-      @data.flat_map { |iso2, data| data[:valid] }.uniq
+      @data.flat_map { |_iso2, data| data[:valid] }.uniq
     end
 
     # Returns all possible types that matched possible patterns
+    # @return [Array] all possible phone types
     def possible_types
-      @data.flat_map { |iso2, data| data[:possible] }.uniq
+      @data.flat_map { |_iso2, data| data[:possible] }.uniq
     end
 
     # Returns first phone type that matched
+    # @return [Symbol] valid phone type
     def type
       types.first
     end
 
     # Returns human representation of all matched phone types
+    # @return [Array] Array of human readable valid phone types
     def human_types
       types.map { |type| Core::TYPES_DESC[type] }
     end
 
     # Return human representation of phone type
+    # @return [String] Human readable valid phone type
     def human_type
       Core::TYPES_DESC[type]
     end
 
     # Returns all countries that matched valid patterns
+    # @return [Array] Possible ISO2 country codes array
     def countries
-      @data.map { |iso2, data| iso2 }
+      @data.map { |iso2, _data| iso2 }
     end
 
     # Return countries with valid patterns
+    # @return [Array] Valid ISO2 country codes array
     def valid_countries
       @valid_countries ||= countries.select do |iso2|
         @data[iso2][:valid].any?
@@ -79,124 +87,60 @@ module Phonelib
     end
 
     # Return valid country
+    # @return [String] valid ISO2 country code
     def valid_country
-      @valid_country ||= get_main_country(valid_countries)
+      @valid_country ||= main_country(valid_countries)
     end
 
     # Returns first country that matched valid patterns
+    # @return [String] valid country ISO2 code or first matched country code
     def country
-      @country ||= valid_country || get_main_country(countries)
-    end
-
-    # Returns the country code from the original phone number.
-    def country_code
-      if country_data = Phonelib.phone_data[country]
-        country_data[:country_code]
-      end
+      @country ||= valid_country || main_country(countries)
     end
 
     # Returns whether a current parsed phone number is valid
+    # @return [Boolean] parsed phone is valid
     def valid?
-      @data.select { |iso2, data| data[:valid].any? }.any?
+      @data.select { |_iso2, data| data[:valid].any? }.any?
     end
 
     # Returns whether a current parsed phone number is invalid
+    # @return [Boolean] parsed phone is invalid
     def invalid?
       !valid?
     end
 
     # Returns whether a current parsed phone number is possible
+    # @return [Boolean] parsed phone is possible
     def possible?
-      @data.select { |iso2, data| data[:possible].any? }.any?
+      @data.select { |_iso2, data| data[:possible].any? }.any?
     end
 
     # Returns whether a current parsed phone number is impossible
+    # @return [Boolean] parsed phone is impossible
     def impossible?
       !possible?
     end
 
-    # returns area code of parsed number
-    def area_code
-      return nil unless possible?
-      format_match, format_string = get_formatting_data
-
-      if format_string =~ /^.*[0-9]+.*\$1/ && format_match
-        format_string.gsub(/\$1.*$/, format_match[1]).gsub(/[^\d]+/, '')
-      end
-    end
-
     # returns local number
+    # @return [String] local number
     def local_number
       return national unless possible?
-      format_match, format_string = get_formatting_data
+      format_match, format_string = formatting_data
 
       if format_string =~ /^.*[0-9]+.*\$1/ && format_match
-        format_string.gsub(/^.*\$2/, '$2').
-            gsub(/\$\d/) { |el| format_match[el[1].to_i] }
+        format_string.gsub(/^.*\$2/, '$2')
+          .gsub(/\$\d/) { |el| format_match[el[1].to_i] }
       else
         national
       end
     end
 
-    # Returns formatted national number
-    def national(formatted = true)
-      return @national_number unless valid?
-      format_match, format_string = get_formatting_data
-
-      if format_match
-        out = format_string.gsub(/\$\d/) { |el| format_match[el[1].to_i] }
-        formatted ? out : out.gsub(/[^0-9]/, '')
-      else
-        @national_number
-      end
-    end
-
-    # Returns e164 formatted phone number
-    def international(formatted = true)
-      return nil if sanitized.nil? || sanitized.empty?
-      return "+#{country_prefix_or_not}#{sanitized}" unless valid?
-      return "#{@data[country][Core::COUNTRY_CODE]}#{@national_number}" unless formatted
-
-      format = @data[country][:format]
-      if matches = @national_number.match(/#{format[Core::PATTERN]}/)
-        fmt = format[:intl_format] || format[:format]
-        national = fmt.gsub(/\$\d/) { |el| matches[el[1].to_i] }
-      else
-        national = @national_number
-      end
-
-      "+#{country_code} #{national}"
-    end
-
-    # returns national formatted number with extension added
-    def full_national
-      "#{national}#{formatted_extension}"
-    end
-
-    # returns international formatted number with extension added
-    def full_international
-      "#{international}#{formatted_extension}"
-    end
-
-    # returns e164 format of phone with extension added
-    def full_e164
-      "#{e164}#{formatted_extension}"
-    end
-
-    # Returns e164 unformatted phone number
-    def e164
-      international = self.international
-      international and international.gsub /[^+0-9]/, ''
-    end
-
     # Returns whether a current parsed phone number is valid for specified
     # country
-    #
-    # ==== Attributes
-    #
-    # * +country+ - ISO code of country (2 letters) like 'US', 'us' or :us
-    #   for United States
-    #
+    # @param country [String|Symbol] ISO code of country (2 letters) like 'US',
+    #   'us' or :us for United States
+    # @return [Boolean] parsed phone number is valid
     def valid_for_country?(country)
       country = country.to_s.upcase
       @data.find do |iso2, data|
@@ -206,61 +150,27 @@ module Phonelib
 
     # Returns whether a current parsed phone number is invalid for specified
     # country
-    #
-    # ==== Attributes
-    #
-    # * +country+ - ISO code of country (2 letters) like 'US', 'us' or :us
-    #   for United States
-    #
+    # @param country [String|Symbol] ISO code of country (2 letters) like 'US',
+    #   'us' or :us for United States
+    # @return [Boolean] parsed phone number is invalid
     def invalid_for_country?(country)
       !valid_for_country?(country)
     end
 
     private
 
-    def country_prefix_or_not
-      return '' unless country_code
-      sanitized.start_with?(country_code) ? '' : country_code
-    end
-
-    # returns extension with separator defined
-    def formatted_extension
-      return '' if @extension.nil? || @extension.empty?
-
-      "#{Phonelib.extension_separator}#{@extension}"
-    end
-
-    # extracts extension from passed phone number if provided
+    # @private extracts extension from passed phone number if provided
     def separate_extension(original)
       regex = cr("[#{Phonelib.extension_separate_symbols}]")
       split = (original || '').split regex
-      [split.first, split[1..-1] && split[1..-1].join]
+      [split.first || '', split[1..-1] && split[1..-1].join || '']
     end
 
-    # get main country for code among provided countries
-    def get_main_country(countries_array)
+    # @private get main country for code among provided countries
+    def main_country(countries_array)
       countries_array.find do |iso2|
         @data[iso2][Core::MAIN_COUNTRY_FOR_CODE] == 'true'
       end || countries_array.first
     end
-
-    # Get needable data for formatting phone as national number
-    def get_formatting_data
-      return @formatting_data if @formatting_data
-
-      format = @data[country][:format]
-      prefix = @data[country][Core::NATIONAL_PREFIX]
-      rule = (format[Core::NATIONAL_PREFIX_RULE] ||
-          @data[country][Core::NATIONAL_PREFIX_RULE] || '$1')
-
-      # change rule's constants to values
-      rule.gsub!(/(\$NP|\$FG)/, '$NP' => prefix, '$FG' => '$1')
-
-      # add space to format groups, change first group to rule,
-      format_string = format[:format].gsub(/(\d)\$/, '\\1 $').gsub('$1', rule)
-
-      @formatting_data =
-          [@national_number.match(/#{format[Core::PATTERN]}/), format_string]
-    end
   end
 end