global_phone 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fece23d3eace739f32573747853124109fc041e8
+  data.tar.gz: d826cae724c7d1e985a1202cfd1eb391a68a719e
+SHA512:
+  metadata.gz: 9fa62cde3524560b518b052fc641e2630b946b53acb0edfda89394e2e5073430a420b11ec7892da19796414323cc7cf994810c7573a5c1bc36a419c8978b49d5
+  data.tar.gz: 4a74924a77e4c1560d1027825d65d5dd0f239fbb2b8f173f83c8157d7d934415db14a9f17cbecec034620ba763795982bfc8541b0d1fb22d8749b593115a70fd

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Sam Stephenson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# GlobalPhone
+
+GlobalPhone parses, validates, and formats local and international phone numbers according to the [E.164 standard](http://en.wikipedia.org/wiki/E.164).
+
+**Store and display phone numbers in your app.** Accept phone number input in national or international format. Convert phone numbers to international format (`+13125551212`) for storage and retrieval. Present numbers in national format (`(312) 555-1212`) in your UI.
+
+**Designed with the future in mind.** GlobalPhone uses format specifications from Google's open-source [libphonenumber](http://code.google.com/p/libphonenumber/) database. No need to upgrade the library when a new phone format is introduced—just generate a new copy of the database and check it into your app.
+
+**Pure Ruby. No dependencies.** GlobalPhone is designed for Ruby 1.9.3 and up. (Works in 1.8.7, too—just bring your own `json` gem.)
+
+## Installation
+
+1. Add the `global_phone` gem to your app. For example, using Bundler:
+
+        $ echo "gem 'global_phone'" >> Gemfile
+        $ bundle install
+
+2. Use `global_phone_dbgen` to convert Google's libphonenumber `PhoneNumberMetaData.xml` file into a JSON database for GlobalPhone.
+
+        $ gem install global_phone_dbgen
+        $ global_phone_dbgen > db/global_phone.json
+
+3. Tell GlobalPhone where to find the database. For example, in a Rails app, create an initializer in `config/initializers/global_phone.rb`:
+
+        require 'global_phone'
+        GlobalPhone.db_path = Rails.root.join('db/global_phone.json')
+
+## Examples
+
+Parse an international number string into a `GlobalPhone::Number` object:
+
+    >> number = GlobalPhone.parse('+1-312-555-1212')
+    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+
+Query the country code and likely territory name of the number:
+
+    >> number.country_code
+    => "1"
+
+    >> number.territory.name
+    => "US"
+
+Present the number in national and international formats:
+
+    >> number.national_format
+    => "(312) 555-1212"
+
+    >> number.international_format
+    => "+1 312-555-1212"
+
+Is the number valid? (Note: this is not definitive. For example, the number here is "valid" by format, but there are no US numbers that start with 555. The `valid?` method may return false positives, but *should not* return false negatives unless the database is out of date.)
+
+    >> number.valid?
+    true
+
+Get the number's normalized E.164 international string:
+
+    >> number.international_string
+    => "+13125551212"
+
+Parse a number in national format for a given territory:
+
+    >> number = GlobalPhone.parse("(0) 20-7031-3000", :gb)
+    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+
+Parse an international number using a territory's international dialing prefix:
+
+    >> number = GlobalPhone.parse("00 1 3125551212", :gb)
+    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+
+Set the default territory to Great Britain (territory names are [ISO 3166-1 Alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes):
+
+    >> GlobalPhone.default_territory_name = :gb
+    => :gb
+
+    >> GlobalPhone.parse("(0) 20-7031-3000")
+    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+
+Shortcuts for validating a phone number:
+
+    >> GlobalPhone.validate("+1 312-555-1212")
+    => true
+
+    >> GlobalPhone.validate("+442070313000")
+    => true
+
+    >> GlobalPhone.validate("(0) 20-7031-3000")
+    => false
+
+    >> GlobalPhone.validate("(0) 20-7031-3000", :gb)
+    => true
+
+Shortcuts for normalizing a phone number in E.164 format:
+
+    >> GlobalPhone.normalize("(312) 555-1212")
+    => "+13125551212"
+
+    >> GlobalPhone.normalize("+442070313000")
+    => "+442070313000"
+
+    >> GlobalPhone.normalize("(0) 20-7031-3000")
+    => nil
+
+    >> GlobalPhone.normalize("(0) 20-7031-3000", :gb)
+    => "+442070313000"
+
+## Caveats
+
+GlobalPhone currently does not parse emergency numbers or SMS short code numbers.
+
+Validation is not definitive and may return false positives, but *should not* return false negatives unless the database is out of date.
+
+Territory heuristics are imprecise. Parsing a number will usually result in the territory being set to the primary territory of the region. For example, Canadian numbers will be parsed with a territory of `US`. (In most cases this does not matter, but if your application needs to perform geolocation using phone numbers, GlobalPhone may not be a good fit.)
+
+## Development
+
+The GlobalPhone source code is [hosted on GitHub](https://github.com/sstephenson/global_phone). You can check out a copy of the latest code using Git:
+
+    $ git clone https://github.com/sstephenson/global_phone.git
+
+If you've found a bug or have a question, please open an issue on the [issue tracker](https://github.com/sstephenson/global_phone/issues). Or, clone the GlobalPhone repository, write a failing test case, fix the bug, and submit a pull request.
+
+GlobalPhone is heavily inspired by Andreas Gal's [PhoneNumber.js](https://github.com/andreasgal/PhoneNumber.js) library.
+
+### Version History
+
+**1.0.0** (May 28, 2013)
+
+* Initial public release.
+
+### License
+
+Copyright &copy; 2013 Sam Stephenson
+
+Released under the MIT license. See [`LICENSE`](LICENSE) for details.

data/lib/global_phone/context.rb

@@ -0,0 +1,36 @@
+require 'global_phone/database'
+
+module GlobalPhone
+  module Context
+    attr_accessor :db_path
+
+    def db
+      @db ||= begin
+        raise NoDatabaseError, "set `db_path=' first" unless db_path
+        Database.load_file(db_path)
+      end
+    end
+
+    def default_territory_name
+      @default_territory_name ||= :US
+    end
+
+    def default_territory_name=(territory_name)
+      @default_territory_name = territory_name.to_s.intern
+    end
+
+    def parse(string, territory_name = default_territory_name)
+      db.parse(string, territory_name)
+    end
+
+    def normalize(string, territory_name = default_territory_name)
+      number = parse(string, territory_name)
+      number.international_string if number
+    end
+
+    def validate(string, territory_name = default_territory_name)
+      number = parse(string, territory_name)
+      number && number.valid?
+    end
+  end
+end

data/lib/global_phone/database.rb

@@ -0,0 +1,48 @@
+require 'global_phone/parsing'
+require 'global_phone/region'
+
+module GlobalPhone
+  class Database
+    include Parsing
+
+    def self.load_file(filename)
+      load(File.read(filename))
+    end
+
+    def self.load(json)
+      require 'json'
+      new(JSON.parse(json))
+    end
+
+    attr_reader :regions
+
+    def initialize(record_data)
+      @regions = record_data.map { |data| Region.new(data) }
+      @territories_by_name = {}
+    end
+
+    def region(country_code)
+      regions_by_country_code[country_code.to_s]
+    end
+
+    def territory(name)
+      name = name.to_s.upcase
+      @territories_by_name[name] ||= if region = region_for_territory(name)
+        region.territory(name)
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    protected
+      def regions_by_country_code
+        @regions_by_country_code ||= Hash[*regions.map { |r| [r.country_code, r] }.flatten]
+      end
+
+      def region_for_territory(name)
+        regions.find { |r| r.has_territory?(name) }
+      end
+  end
+end

data/lib/global_phone/format.rb

@@ -0,0 +1,27 @@
+require 'global_phone/record'
+
+module GlobalPhone
+  class Format < Record
+    field 0, :pattern do |p| /^#{p}$/ end
+    field 1, :national_format_rule
+    field 2, :leading_digits do |d| /^#{d}/ end
+    field 3, :national_prefix_formatting_rule
+    field 4, :international_format_rule, :fallback => :national_format_rule
+
+    def match(national_string)
+      return false if leading_digits && national_string !~ leading_digits
+      national_string =~ pattern
+    end
+
+    def format_replacement_string(type)
+      format_rule = send(:"#{type}_format_rule")
+      format_rule.gsub("$", "\\") if format_rule && format_rule != "NA"
+    end
+
+    def apply(national_string, type)
+      if replacement = format_replacement_string(type)
+        national_string.gsub(pattern, replacement)
+      end
+    end
+  end
+end

data/lib/global_phone/number.rb

@@ -0,0 +1,82 @@
+require 'forwardable'
+
+module GlobalPhone
+  class Number
+    extend Forwardable
+
+    E161_MAPPING       = Hash[*"a2b2c2d3e3f3g4h4i4j5k5l5m6n6o6p7q7r7s7t8u8v8w9x9y9z9".split("")]
+    VALID_ALPHA_CHARS  = /[a-zA-Z]/
+    LEADING_PLUS_CHARS = /^\++/
+    NON_DIALABLE_CHARS = /[^,#+\*\d]/
+    SPLIT_FIRST_GROUP  = /^(\d+)(.*)$/
+
+    def self.normalize(string)
+      string.to_s.
+        gsub(VALID_ALPHA_CHARS) { |c| E161_MAPPING[c.downcase] }.
+        gsub(LEADING_PLUS_CHARS, "+").
+        gsub(NON_DIALABLE_CHARS, "")
+    end
+
+    attr_reader :territory, :national_string
+
+    def_delegator :territory, :region
+    def_delegator :territory, :country_code
+    def_delegator :territory, :national_prefix
+    def_delegator :territory, :national_pattern
+
+    def initialize(territory, national_string)
+      @territory = territory
+      @national_string = national_string
+    end
+
+    def national_format
+      @national_format ||= begin
+        if format && result = format.apply(national_string, :national)
+          apply_national_prefix_format(result)
+        end
+      end
+    end
+
+    def international_string
+      @international_string ||= begin
+        if international_format
+          international_format.gsub(NON_DIALABLE_CHARS, "")
+        end
+      end
+    end
+
+    def international_format
+      @international_format ||= begin
+        if format && formatted_number = format.apply(national_string, :international)
+          "+#{country_code} #{formatted_number}"
+        end
+      end
+    end
+
+    def valid?
+      !!(format && national_string =~ national_pattern)
+    end
+
+    def inspect
+      "#<#{self.class.name} territory=#{territory.inspect} national_string=#{national_string.inspect}>"
+    end
+
+    protected
+      def format
+        @format ||= region.formats.detect { |format| format.match(national_string) }
+      end
+
+      def apply_national_prefix_format(result)
+        prefix = national_prefix_formatting_rule
+        return result unless prefix && match = result.match(SPLIT_FIRST_GROUP)
+
+        prefix = prefix.gsub("$NP", national_prefix)
+        prefix = prefix.gsub("$FG", match[1])
+        result = "#{prefix} #{match[2]}"
+      end
+
+      def national_prefix_formatting_rule
+        format.national_prefix_formatting_rule || territory.national_prefix_formatting_rule
+      end
+  end
+end

data/lib/global_phone/parsing.rb

@@ -0,0 +1,52 @@
+require 'global_phone/number'
+require 'global_phone/utils'
+
+module GlobalPhone
+  module Parsing
+    def parse(string, territory_name)
+      string = Number.normalize(string)
+      territory = self.territory(territory_name)
+      raise ArgumentError, "unknown territory `#{territory_name}'" unless territory
+
+      if starts_with_plus?(string)
+        parse_international_string(string)
+      elsif string =~ territory.international_prefix
+        string = strip_international_prefix(territory, string)
+        parse_international_string(string)
+      else
+        territory.parse_national_string(string)
+      end
+    end
+
+    def parse_international_string(string)
+      string = Number.normalize(string)
+      string = strip_leading_plus(string) if starts_with_plus?(string)
+
+      if region = region_for_string(string)
+        region.parse_national_string(string)
+      end
+    end
+
+    protected
+      def starts_with_plus?(string)
+        string[0, 1] == "+"
+      end
+
+      def strip_leading_plus(string)
+        string[1..-1]
+      end
+
+      def strip_international_prefix(territory, string)
+        string.sub(territory.international_prefix, "")
+      end
+
+      def region_for_string(string)
+        candidates = country_code_candidates_for(string)
+        Utils.map_detect(candidates) { |country_code| region(country_code) }
+      end
+
+      def country_code_candidates_for(string)
+        (1..3).map { |length| string[0, length] }
+      end
+  end
+end

data/lib/global_phone/record.rb

@@ -0,0 +1,26 @@
+require 'forwardable'
+
+module GlobalPhone
+  class Record
+    extend Forwardable
+
+    def self.field(index, name, options = {}, &block)
+      if block
+        transform_method_name = :"transform_field_#{name}"
+        define_method(transform_method_name, block)
+      end
+
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}
+          value = @data[#{index.inspect}]
+          #{"value = #{transform_method_name}(value) if value" if block}
+          value #{"|| #{options[:fallback]}" if options[:fallback]}
+        end
+      RUBY
+    end
+
+    def initialize(data)
+      @data = data
+    end
+  end
+end

data/lib/global_phone/region.rb

@@ -0,0 +1,62 @@
+require 'global_phone/format'
+require 'global_phone/record'
+require 'global_phone/territory'
+require 'global_phone/utils'
+
+module GlobalPhone
+  class Region < Record
+    field 0, :country_code
+    field 1, :format_record_data
+    field 2, :territory_record_data
+    field 3, :international_prefix do |p| /^(?:#{p})/ end
+    field 4, :national_prefix
+    field 5, :national_prefix_for_parsing do |p| /^(?:#{p})/ end
+    field 6, :national_prefix_transform_rule
+
+    def formats
+      @formats ||= format_record_data.map { |data| Format.new(data) }
+    end
+
+    def territories
+      @territories ||= territory_record_data.map { |data| Territory.new(data, self) }
+    end
+
+    def territory(name)
+      name = name.to_s.upcase
+      territories.detect { |region| region.name == name }
+    end
+
+    def has_territory?(name)
+      territory_names.include?(name.to_s.upcase)
+    end
+
+    def parse_national_string(string)
+      string = Number.normalize(string)
+      if starts_with_country_code?(string)
+        string = strip_country_code(string)
+        find_first_parsed_national_string_from_territories(string)
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} country_code=#{country_code} territories=[#{territory_names.join(",")}]>"
+    end
+
+    protected
+      def territory_names
+        territory_record_data.map(&:first)
+      end
+
+      def starts_with_country_code?(string)
+        string.index(country_code) == 0
+      end
+
+      def strip_country_code(string)
+        string[country_code.length..-1]
+      end
+
+      def find_first_parsed_national_string_from_territories(string)
+        Utils.map_detect(territories) { |territory| territory.parse_national_string(string) }
+      end
+  end
+end

data/lib/global_phone/territory.rb

@@ -0,0 +1,58 @@
+require 'global_phone/number'
+require 'global_phone/record'
+
+module GlobalPhone
+  class Territory < Record
+    field 0, :name
+    field 1, :possible_pattern do |p| /^#{p}$/ end
+    field 2, :national_pattern do |p| /^#{p}$/ end
+    field 3, :national_prefix_formatting_rule
+
+    attr_reader :region
+
+    def_delegator :region, :country_code
+    def_delegator :region, :international_prefix
+    def_delegator :region, :national_prefix
+    def_delegator :region, :national_prefix_for_parsing
+    def_delegator :region, :national_prefix_transform_rule
+
+    def initialize(data, region)
+      super(data)
+      @region = region
+    end
+
+    def parse_national_string(string)
+      string = normalize(string)
+      Number.new(self, string) if possible?(string)
+    end
+
+    def inspect
+      "#<#{self.class.name} country_code=#{country_code} name=#{name}>"
+    end
+
+    protected
+      def strip_national_prefix(string)
+        if national_prefix_for_parsing
+          transform_rule = national_prefix_transform_rule || ""
+          transform_rule = transform_rule.gsub("$", "\\")
+          string_without_prefix = string.sub(national_prefix_for_parsing, transform_rule)
+        elsif starts_with_national_prefix?(string)
+          string_without_prefix = string[national_prefix.length..-1]
+        end
+
+        possible?(string_without_prefix) ? string_without_prefix : string
+      end
+
+      def normalize(string)
+        strip_national_prefix(Number.normalize(string))
+      end
+
+      def possible?(string)
+        string =~ possible_pattern
+      end
+
+      def starts_with_national_prefix?(string)
+        national_prefix && string.index(national_prefix) == 0
+      end
+  end
+end

data/lib/global_phone/utils.rb

@@ -0,0 +1,14 @@
+module GlobalPhone
+  module Utils
+    extend self
+
+    def map_detect(collection)
+      collection.each do |value|
+        if result = yield(value)
+          return result
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/global_phone.rb

@@ -0,0 +1,10 @@
+require 'global_phone/context'
+
+module GlobalPhone
+  VERSION = '1.0.0'
+
+  class Error < ::StandardError; end
+  class NoDatabaseError < Error; end
+
+  extend Context
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: global_phone
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sam Stephenson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-28 00:00:00.000000000 Z
+dependencies: []
+description: GlobalPhone parses, validates, and formats local and international phone
+  numbers according to the E.164 standard using the rules specified in Google's libphonenumber
+  database.
+email:
+- sstephenson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/global_phone/context.rb
+- lib/global_phone/database.rb
+- lib/global_phone/format.rb
+- lib/global_phone/number.rb
+- lib/global_phone/parsing.rb
+- lib/global_phone/record.rb
+- lib/global_phone/region.rb
+- lib/global_phone/territory.rb
+- lib/global_phone/utils.rb
+- lib/global_phone.rb
+homepage: https://github.com/sstephenson/global_phone
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Parse, validate, and format phone numbers using Google's libphonenumber database
+test_files: []