phony 2.20.5 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 443ce0ac52dcde0ab0b419d6c49123ac60fdb6525ce56df52c09102b2a1b79af
-  data.tar.gz: 3db5d454a9c112ad429b1c0986379bae3230685bcc795aaedf5c0f7feba2a902
+  metadata.gz: 914522596278234ccd64fd27a07f0b32426738aa3b886233c14e5ca9469a99f9
+  data.tar.gz: 9fcbb9e8607a93d2271ff19f61215139a04f922b3f5bbfa1d309ae15b30222bb
 SHA512:
-  metadata.gz: c0081748a294e804a1e1870dc40bc9e4359733f25f54e73dbbf2ad7fd01661af91e6724fa550dc61a29f4ff0c2f3b2b9161160657c852493e63afbdc839f7ae7
-  data.tar.gz: 0f371abf103cd53b85093973e96cbf3ae91d9d44b3e4e1b7db51826ce2a9f818252d9774cdd81abcdcf5f893dd696cf2649b70a0e7960164e8f02b4ca8618088
+  metadata.gz: 17cda2331907984caf6a7a876bc7021efd08d2026082081412a93c8a93dad3211c44db1c785f7971fb645b1ee0dbfb0ac10a9849618eab8e045e667f50d7a1b2
+  data.tar.gz: d6702bd8f91fdb5aaa8a01715a12726df2a4937b9f59161ceb4951049309674aa3e9306c398fc3901b55a3a83f74a634a2aa52ea8670509645dfa5d7e05c6710

data/README.md

@@ -0,0 +1,117 @@
+[![Build Status](https://secure.travis-ci.org/floere/phony.png)](http://travis-ci.org/floere/phony)
+[![Coverage Status](https://coveralls.io/repos/floere/phony/badge.svg?branch=master)](https://coveralls.io/r/floere/phony?branch=master)
+[![Code Climate](https://codeclimate.com/github/floere/phony.png)](https://codeclimate.com/github/floere/phony)
+[![Inline docs](http://inch-ci.org/github/floere/phony.png)](http://inch-ci.org/github/floere/phony)
+
+# Phony
+
+Disclaimer: Phony works with international numbers only, such as `61 412 345 678`!
+
+The (admittedly crazy) goal of this Gem is to be able to normalize/format/split all phone numbers in the world.
+
+Used in: [airbnb.com](http://airbnb.com), [socialcam.com](http://socialcam.com), [zendesk.com](http://www.zendesk.com/) (and many, many others).
+
+## Runtime Memory Usage {#memory}
+
+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'`
+
+## Description
+
+This gem normalizes, formats and splits "**E164 phone numbers**". A valid E164 phone number **must** include a country code.
+
+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`
+
+It currently handles the countries listed at the end of this README.
+
+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).
+
+## Installation
+
+With Rails? Check out: https://github.com/joost/phony_rails.
+
+With Bundler: Append `gem 'phony'` to your `Gemfile` and `bundle install` it.
+
+Without Bundler: Run `gem install phony` from your command line.
+
+## Usage docs {#usage}
+
+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.normalize(number) {#normalizing}
+
+Normalize intelligently removes all non-numeric characters of a number. Do it before storing a number in a DB.
+
+[Phony.normalize docs](./qed/normalize.md)
+
+`Phony.normalize('1-888-407-4747').assert == '18884074747'`
+
+### Phony.format(number, options = {}) {#formatting}
+
+Format formats a normalized number according to a country's predominant formatting. Lots of options for int'l, national, local formatting.
+
+[Phony.format docs](./qed/format.md)
+
+`Phony.format('41443643532').assert == '+41 44 364 35 32'`
+
+### Phony.plausible?(number, options = {}) {#plausibility}
+
+Is a number plausible?
+
+[Phony.plausible? docs](./qed/plausibility.md)
+
+`Phony.assert.plausible?('+41 44 111 22 33')`
+
+### Phony.split(number) {#splitting}
+
+Split a number into its parts: CC, NDC, local.
+
+[Phony.split docs](./qed/split.md)
+
+`Phony.split('3928061371').assert == ['39', '2', '806', '1371']`
+
+NB If a country does not have an NDC, `#split` will return `false` in the NDC position, for example for Denmark:
+
+`Phony.split('4512121212').assert == ['45', false, '12', '12', '12', '12']`
+
+### Loading only a country subset (Phony 2.18.0+). {#loading}
+
+Use this in case you'd like to save [memory](#memory) that is used by Phony's CC rules.
+
+[Phony::Config.load docs](./qed/config.md)
+
+First, `require 'phony/config'`.
+Then, one of the following, which will load the rest of Phony.
+
+Load only these CCs:
+`Phony::Config.load(only: ['41', '44'])`
+
+Loads everything except these CCs:
+`Phony::Config.load(except: ['41', '44'])`
+
+Convenience form of `only`:
+`Phony::Config.load('41', '44')`
+
+Each of these loads the rest of Phony.
+
+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.
+
+## List of Handled Countries
+
+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, Mauritian, 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.
+
+## Proud Sponsors
+
+* Renuo AG (July 2022 – January 2025): [Github](https://github.com/renuo), [Homepage](https://www.renuo.ch). Much appreciated!
+
+## License
+
+MIT.
+See [LICENSE](./LICENSE) file.
+

data/lib/phony/config.rb

@@ -1,53 +1,53 @@
 # 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
+
+    def initialize(included_ccs, excluded_ccs)
       @included_ccs = included_ccs || []
       @excluded_ccs = excluded_ccs || []
     end
-    
-    def load? cc
+
+    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:
@@ -61,31 +61,30 @@ module Phony
       # 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
-      
+                       # 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__)
-      
+      Kernel.load File.expand_path('../phony.rb', __dir__)
+
       # Return the stored config data.
       Phony.config
     end
-    
   end
-end
+end