phony 1.9.0 → 2.19.14

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f497a4a52bd0c47e845d1fa471e5465e1c949349fdcf78cf5e6f4ef6f501ee9
+  data.tar.gz: 64bff396ac5a0a20fd27a8b8176ea71ec3fc569c129c7297e7910ae02b1a473d
+SHA512:
+  metadata.gz: 20f087521f9e50b8fa1b31418ad24363fe97949ca7eae3b787429dbfdd2c8ee83d66a99f898033e5890e76351517fc237746084e68d33878d7a258c69179bfb8
+  data.tar.gz: a29e55bf204811d025b7ba758ab04e3584eabb43ccefc9011c8bc4c6b1e122f5e50ad5b8f714012a35c6c4e637d5894a2272ea40810765e01de3b3c24d85497a

data/README.textile

@@ -1,164 +1,116 @@
 "!{float:right}https://secure.travis-ci.org/floere/phony.png!":http://travis-ci.org/floere/phony
+!https://coveralls.io/repos/floere/phony/badge.svg?branch=master(Coverage Status)!:https://coveralls.io/r/floere/phony?branch=master
+"!https://codeclimate.com/github/floere/phony.png!":https://codeclimate.com/github/floere/phony
+!http://inch-ci.org/github/floere/phony.png!:http://inch-ci.org/github/floere/phony
 
 h1. Phony
 
-Used in e.g.: "airbnb.com":http://airbnb.com, "restorm.com":http://restorm.com, "socialcam.com":http://socialcam.com, "zendesk.com":http://www.zendesk.com/ (and many, many others).
+Disclaimer: Phony works with international numbers only, such as @61 412 345 678@!
 
-There's also a Rails wrapper: https://github.com/joost/phony_rails.
+The (admittedly crazy) goal of this Gem is to be able to normalize/format/split all phone numbers in the world.
 
-h2. Description
-
-This gem can normalize, format and split E164 numbers.
-"More about E164 numbers in this Wiki":http://en.wikipedia.org/wiki/E.164.
-
-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, Cambodian, Chilean, Chinese, Croatian, Cuban, Cypriot, Czech, Danish, Dutch, Egyptian, Estonian, French, German, Ghanan, Gibraltar, Greek, Hungarian, Italian, Irish, Kazakh, Lithuanian, Luxembourgian, Malaysian, Malta, Mexican, Monaco, Morocco, New Zealand, Nigerian, Norwegian, Peruvian, Polish, Romanian, Russian, Rwandan, Singapore, Slovakian, South African, South Korean, South Osetian, Spanish, Sudan, 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.
-
-h2. Installation
-
-<pre><code>gem install phony</code></pre>
-
-h2(#examples). Some examples
-
-h3(#plausibility). Plausibility
-
-"Plausible" means "seems reasonable or probable", not implying 100% correctness on a @true@, but implying 100% correctness on a @false@ return value. So if this returns @true@, it might still be not a plausible number. If it returns @false@, it is definitely not an E164 conform number.
-
-Use this method in combination with @normalize@ for saving it into the database. Also see https://github.com/floere/phony/issues/35 for a discussion on the topic.
-
-Note that you can add constraints to the plausibility check like the country code, @cc@, and the national destination code, @ndc@. Use the options to further limit the plausibility range. For example, only allow a small number of countries.
-
-@Phony.plausible?('0000000').should be_false@
-
-@Phony.plausible?('hello').should be_false@
-
-@Phony.plausible?('+41 44 111 22 33').should be_true@
+Used in: "airbnb.com":http://airbnb.com, "socialcam.com":http://socialcam.com, "zendesk.com":http://www.zendesk.com/ (and many, many others).
 
-@Phony.plausible?('+41 44 111 22 33', cc: '41').should be_true@
+h2(#memory). Runtime Memory Usage
 
-@Phony.plausible?('+41 44 111 22 33', ndc: '44').should be_true@
+According to "memory_profiler":https://github.com/SamSaffron/memory_profiler, the Phony gem uses roughly 1MB of memory per Ruby process.
+Usage was generated using (look for @Total retained@): @ruby -e 'require "memory_profiler"; MemoryProfiler.report(allow_files: "phony"){ require "phony" }.pretty_print'@
 
-@Phony.plausible?('+41 44 111 22 33', cc: '1').should be_false@
-
-@Phony.plausible?('+41 44 111 22 33', ndc: '43').should be_false@
-
-@Phony.plausible?('+41 44 111 22 33', cc: '41', ndc: '44').should be_true@
-
-@Phony.plausible?('+41 44 111 22 33', cc: /4(0|2)/, ndc: /4(4|5)/).should be_false@
-
-@Phony.plausible?('+41 44 111 22 33', cc: /4(0|1)/, ndc: /4(4|5)/).should be_true@
-
-h3(#normalizing). Normalizing
-
-This will often raise an error if you try normalizing a non E164-izable number (a number that does not contain enough information to be normalized into an E164 conform number). Use @Phony.plausible?@ for checking if it can be normalized first.
-
-@Phony.normalize('41443643533').should == '41443643533'@
-
-@Phony.normalize('+41 44 364 35 33').should == '41443643533'@
-
-@Phony.normalize('+41 44 364 35 33').should == '41443643533'@
-
-@Phony.normalize('+41 800 11 22 33').should == '41800112233'@
-
-@Phony.normalize('John: +41 44 364 35 33').should == '41443643533'@
-
-@Phony.normalize('1 (703) 451-5115').should == '17034515115'@
-
-@Phony.normalize('1-888-407-4747').should == '18884074747'@
-
-@Phony.normalize('1.906.387.1698').should == '19063871698'@
-
-@Phony.normalize('+41 (044) 364 35 33').should == '41443643533'@
+h2. Description
 
-h3(#formatting). Formatting
+This gem normalizes, formats and splits "*E164 phone numbers*":http://en.wikipedia.org/wiki/E.164. A valid E164 phone number *must* include a country code.
 
-@Phony.formatted('41443643532').should == '+41 44 364 35 32'@
+E164 numbers are international numbers with a country dial prefix, usually an area code and a subscriber number. For example, the Australian number @+61 412 345 678@ can be broken down into the following components:
+* Country Code (CC): a country code of @61@
+* National Destination Code (NDC): a mobile number denoted by the @4@ (specific to Australia)
+* Local Number Part: a subscriber number of @12 345 678@
 
-@Phony.formatted('41800112233').should == '+41 800 11 22 33'@
+It currently handles the countries listed at the end of this README.
 
-@Phony.formatted('43198110').should == '+43 1 98110'@
+It is covered by roughly 2,250 tests that run in 2 seconds (April 2019).
+If it doesn't work, please "enter an issue":http://github.com/floere/phony/issues or better, fork and "send a pull request":http://github.com/floere/phony/pulls.
 
-@Phony.formatted('18705551122').should == '+1 870 555 1122'@
+h2. Installation
 
-h4(#international). International
+With Rails? Check out: https://github.com/joost/phony_rails.
 
-@Phony.formatted('18091231234', :format => :international).should == '+1 809 123 1234'@
+With Bundler: Append @gem 'phony'@ to your @Gemfile@ and @bundle install@ it.
 
-@Phony.formatted('43198110', :format => :international).should == '+43 1 98110'@
+Without Bundler: Run @gem install phony@ from your command line.
 
-@Phony.formatted('43198110', :format => :international_absolute).should == '+43 1 98110'@
+h2(#usage). Usage docs
 
-@Phony.formatted('33142278186', :format => :+).should == '+33 1 42 27 81 86'@
+Phony uses "qed":https://github.com/rubyworks/qed as docs and to run its functional tests. Start here for usage docs: "Usage index":./qed/index.md.
 
-@Phony.formatted('43198110', :format => :international_relative).should == '0043 1 98110'@
+h3(#normalizing). Phony.normalize(number)
 
-@Phony.formatted('4233841148', :format => :international_relative).should == '00423 384 11 48'@
+Normalize intelligently removes all non-numeric characters of a number. Do it before storing a number in a DB.
 
-h4(#spaces). With spaces
+"Phony.normalize docs":./qed/normalize.md
 
-@Phony.formatted('18091231234', :format => :international, :spaces => '').should == '+18091231234'@
+@Phony.normalize('1-888-407-4747').assert == '18884074747'@
 
-@Phony.formatted('43198110', :format => :international, :spaces => '').should == '+43198110'@
+h3(#formatting). Phony.format(number, options = {})
 
-@Phony.formatted('43198110', :format => :international_absolute, :spaces => '').should == '+43198110'@
+Format formats a normalized number according to a country's predominant formatting. Lots of options for int'l, national, local formatting.
 
-@Phony.formatted('33142278186', :format => :+, :spaces => '').should == '+33142278186'@
+"Phony.format docs":./qed/format.md
 
-@Phony.formatted('43198110', :format => :international_relative, :spaces => '').should == '0043198110'@
+@Phony.format('41443643532').assert == '+41 44 364 35 32'@
 
-@Phony.formatted('4233841148', :format => :international_relative, :spaces => '').should == '004233841148'@
+h3(#plausibility). Phony.plausible?(number, options = {})
 
-h4(#special). With special spaces
+Is a number plausible?
 
-@Phony.formatted('18091231234', :format => :international, :spaces => :-).should == '+1-809-123-1234'@
+"Phony.plausible? docs":./qed/plausibility.md
 
-@Phony.formatted('43198110', :format => :international, :spaces => :-).should == '+43-1-98110'@
+@Phony.assert.plausible?('+41 44 111 22 33')@
 
-@Phony.formatted('43198110', :format => :international_absolute, :spaces => :-).should == '+43-1-98110'@
+h3(#splitting). Phony.split(number)
 
-@Phony.formatted('33142278186', :format => :+, :spaces => :-).should == '+33-1-42-27-81-86'@
+Split a number into its parts: CC, NDC, local.
 
-@Phony.formatted('43198110', :format => :international_relative, :spaces => :-).should == '0043-1-98110'@
+"Phony.split docs":./qed/split.md
 
-@Phony.formatted('4233841148', :format => :international_relative, :spaces => :-).should == '00423-384-11-48'@
+@Phony.split('3928061371').assert == ['39', '2', '806', '1371']@
 
-h4(#national). National
+NB If a country does not have an NDC, @#split@ will return @false@ in the NDC position, for example for Denmark:
 
-@Phony.formatted('41443643532', :format => :national).should == '044 364 35 32'@
+@Phony.split('4512121212').assert == ['45', false, '12', '12', '12', '12']@
 
-@Phony.formatted('41800112233', :format => :national).should == '0800 11 22 33'@
+h3(#loading). Loading only a country subset (Phony 2.18.0+).
 
-@Phony.formatted('43198110', :format => :national).should == '01 98110'@
+Use this in case you'd like to save "memory":#memory that is used by Phony's CC rules.
 
-h4(#local). Local
+"Phony::Config.load docs":./qed/config.md
 
-@Phony.formatted('41443643532', :format => :local).should == '364 35 32'@
+First, @require 'phony/config'@.
+Then, one of the following, which will load the rest of Phony.
 
-@Phony.formatted('493038625454', :format => :local).should == '386 25454'@
+Load only these CCs:
+@Phony::Config.load(only: ['41', '44'])@
 
-h3(#splitting). Splitting
+Loads everything except these CCs:
+@Phony::Config.load(except: ['41', '44'])@
 
-@Phony.split('43198110').should == ['43', '1', '98110']@
+Convenience form of @only@:
+@Phony::Config.load('41', '44')@
 
-@Phony.split('33112345678').should == ['33', '1', '12','34','56','78']@
+Each of these loads the rest of Phony.
 
-@Phony.split('4976112345').should == ['49', '761', '123', '45']@
+Memory usage can be checked using (look for @Total retained@):
+@ruby -e 'require "memory_profiler"; MemoryProfiler.report(allow_files: "phony"){ require "phony/config"; Phony::Config.load("1") }.pretty_print'@
+For example, when just loading the NANP CC, the retained memory usage is ~63kB.
 
-@Phony.split('3928061371').should == ['39', '2', '806', '1371']@
+h2. List of Handled Countries
 
-@Phony.split('41443643532').should == ['41', '44', '364', '35', '32']@
+Mildly unmaintained list: Abhas, Afghan, Algerian, Argentina, Austrian, Australian, Azerbaijani, Belgian, Brazilian, Cambodian, Chilean, Chinese, Croatian, Cuban, Cypriot, Czech, Danish, Dutch, Egyptian, El Salvadorian, Estonian, French, German, Ghanan, Gibraltar, Greek, Haiti, Hong Kong, Hungarian, Indian, Iran, Irish, Israel, Italian, Japanese, Kazakh, Liberian, Lithuanian, Luxembourgian, Malaysian, Malta, Mexican, Monaco, Morocco, New Zealand, Nigerian, Norwegian, Peruvian, Polish, Romanian, Russian, Rwandan, Seychelles, Singapore, Slovakian, South African, South Korean, South Osetian, Spanish, Sri Lankan, Sudan, Swedish, Swiss, Thailand, Tunisian, Turkish, Liechtenstein, UK, US, Venezuelan, Vietnamese, and Zambian numbers.
 
-@Phony.split('15551115511').should == ['1', '555', '111', '5511']@
+h2. Proud Sponsors
 
-@Phony.split('6491234567').should == ['64', '9', '123', '4567']@
+* Renuo AG (July 22 –): "Github":https://github.com/renuo, "Homepage":https://www.renuo.ch
 
-@Phony.split('41800334455').should == ['41', '800', '33', '44', '55']@
+h2. License
 
-Note: There is also a ! version of each of these methods which
-      will destroy the original string and return a new (or old) one.
-      Just work only with the returned value, and you will be fine.
+MIT.
+See "LICENSE":./LICENSE file.

data/lib/phony/config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Phony
+  
+  # Add config.
+  class << self
+    attr_writer :config
+    
+    def config
+      # Default config includes all CCs.
+      @config ||= Config.new([], [])
+    end
+  end
+  
+  # The Config class is only used to configure Phony and to load specific
+  # subsets of CCs.
+  #
+  class Config
+    
+    attr_reader :included_ccs, :excluded_ccs
+    
+    def initialize included_ccs, excluded_ccs
+      @included_ccs = included_ccs || []
+      @excluded_ccs = excluded_ccs || []
+    end
+    
+    def load? cc
+      return false if has_excluded? && excluded_ccs.include?(cc)
+      
+      if has_included?
+        # We have to check the included_ccs, otherwise false.
+        return true if included_ccs.include?(cc)
+        
+        false
+      else
+        # It's not in excluded and no included was given.
+        true
+      end
+    end
+    def has_included?
+      !included_ccs.empty?
+    end
+    def has_excluded?
+      !excluded_ccs.empty?
+    end
+    
+    # Use as follows:
+    #
+    #   require 'phony/config'
+    #   
+    #   # Load only these:
+    #   Phony::Config.load(only: ['41', '44'])
+    #   # or all except these:
+    #   Phony::Config.load(except: ['41', '44'])
+    #   # or "only", in short form.
+    #   Phony::Config.load('41', '44')
+    #   # or even shorter form:
+    #   Phony::Config.load(41, 44)
+    #
+    def self.load *options
+      # Extract options.
+      last = options.last
+      only, except = if last.respond_to?(:to_hash)
+        # We have the explicit form.
+        [last[:only], last[:except]]
+      elsif options.respond_to?(:to_ary)
+        # We have the convenience short forms.
+        [options, []]
+      end
+      
+      # Set defaults.
+      only, except = [only || [], except || []]
+      # Convert to expected format if possible.
+      only, except = [only.map(&:to_s), except.map(&:to_s)]
+      
+      # Check params.
+      raise "Params given to Phony::Config.load must be Array-like. The one given was: #{only}" unless only.respond_to?(:to_ary)
+      raise "Params given to Phony::Config.load must be Array-like. The one given was: #{except}" unless except.respond_to?(:to_ary)
+      
+      # Configure Phony.
+      Phony.config = new(only, except)
+      
+      # Load phony.
+      Kernel.load File.expand_path('../../phony.rb', __FILE__)
+      
+      # Return the stored config data.
+      Phony.config
+    end
+    
+  end
+end