global_phone_dbgen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6fb0537a5d1364a57071fb8d11787f7e593b2a96
+  data.tar.gz: a3e71b3fb80e5de63c27cd1ced8ad4c7ad986c90
+SHA512:
+  metadata.gz: ab2f6eeeb4d51582aaba0baea5a83bbf139ddc90eeb7d1260c51cd17cda6b41c7aa34ba62d60b4a248c316d5ebfb6463ec54886febfe78b95cd601a0b6badad7
+  data.tar.gz: 340ff6c3986a361a06f8d2ea4bccaa005bbb34dca99351c269af8f5b0424472f0697b4454e45a8514489f2df1736ecda7ccb8a110d41ca68a0c3ae314e48f107

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/bin/global_phone_dbgen

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+require 'global_phone/database_generator'
+require 'open-uri'
+
+REMOTE_URL = "http://libphonenumber.googlecode.com/svn/trunk/resources/PhoneNumberMetaData.xml"
+
+def usage
+  warn "Usage: #$0 [--compact] [--test] [<filename> | <url>]"
+end
+
+def help
+  warn <<-EOS
+
+    Generates a database for the Ruby GlobalNumber library in JSON format
+    and writes it to standard output.
+
+    Specify either a local path or URL pointing to a copy of Google's
+    libphonenumber PhoneNumberMetaData.xml file.
+
+    Omit the filename argument to download and use the latest version of
+    Google's database from:
+      #{REMOTE_URL}
+
+Options:
+    --compact      Strip all whitespace from the JSON output
+    --test         Generate example phone number fixtures for smoke tests
+
+  EOS
+end
+
+path = REMOTE_URL
+method = :record_data
+compact = false
+
+while arg = ARGV.shift
+  case arg
+  when "-c", "--compact"
+    compact = true
+  when "-t", "--test"
+    method = :test_cases
+  when "-h", "--help"
+    usage
+    help
+    exit
+  when /^-/
+    warn "#$0: unknown option `#{arg}'"
+    usage
+    exit 1
+  else
+    path = arg
+    break
+  end
+end
+
+generator = GlobalPhone::DatabaseGenerator.load(open(path).read)
+result = generator.send(method)
+
+if compact
+  puts JSON.generate(result)
+else
+  puts JSON.pretty_generate(result)
+end

data/lib/global_phone/database_generator.rb

@@ -0,0 +1,149 @@
+require 'json'
+require 'nokogiri'
+
+module GlobalPhone
+  class DatabaseGenerator
+    VERSION = '1.0.0'
+
+    def self.load_file(filename)
+      load(File.read(filename))
+    end
+
+    def self.load(xml)
+      new(Nokogiri.XML(xml))
+    end
+
+    attr_reader :doc
+
+    def initialize(doc)
+      @doc = doc
+    end
+
+    def test_cases
+      @test_cases ||= territory_nodes.map do |node|
+        example_numbers_for_territory_node(node)
+      end.flatten(1)
+    end
+
+    def record_data
+      @record_data ||= territory_nodes_by_region.map do |country_code, territory_nodes|
+        truncate(compile_region(territory_nodes, country_code))
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} (#{doc.search("*").size} elements)>"
+    end
+
+    protected
+      def territory_nodes
+        doc.search("territory")
+      end
+
+      def territory_nodes_by_region
+        territory_nodes.group_by { |node| node["countryCode"] }
+      end
+
+      def territory_name(node)
+        node["id"]
+      end
+
+      def example_numbers_for_territory_node(node)
+        name = territory_name(node)
+        return [] if name == "001"
+        node.search(example_numbers_selector).map { |node| [node.text, name] }
+      end
+
+      def example_numbers_selector
+        "./*[not(" + example_number_types_to_exclude.map do |type|
+          "self::#{type}"
+        end.join(" or ") + ")]/exampleNumber"
+      end
+
+      def example_number_types_to_exclude
+        %w( emergency shortCode )
+      end
+
+      def compile_region(territory_nodes, country_code)
+        territories, main_territory_node = compile_territories(territory_nodes)
+        formats = compile_formats(territory_nodes)
+
+        [
+          country_code,
+          formats,
+          territories,
+          main_territory_node["internationalPrefix"],
+          main_territory_node["nationalPrefix"],
+          squish(main_territory_node["nationalPrefixForParsing"]),
+          squish(main_territory_node["nationalPrefixTransformRule"])
+        ]
+      end
+
+      def compile_territories(territory_nodes)
+        territories = []
+        main_territory_node = territory_nodes.first
+
+        territory_nodes.each do |node|
+          territory = truncate(compile_territory(node))
+          if node["mainCountryForCode"]
+            main_territory_node = node
+            territories.unshift(territory)
+          else
+            territories.push(territory)
+          end
+        end
+
+        [territories, main_territory_node]
+      end
+
+      def compile_territory(node)
+        [
+          territory_name(node),
+          pattern(node, "generalDesc possibleNumberPattern"),
+          pattern(node, "generalDesc nationalNumberPattern"),
+          squish(node["nationalPrefixFormattingRule"])
+        ]
+      end
+
+      def compile_formats(territory_nodes)
+        format_nodes_for(territory_nodes).map do |node|
+          truncate(compile_format(node))
+        end
+      end
+
+      def compile_format(node)
+        [
+          node["pattern"],
+          text_or_nil(node, "format"),
+          pattern(node, "leadingDigits"),
+          node["nationalPrefixFormattingRule"],
+          text_or_nil(node, "intlFormat")
+        ]
+      end
+
+      def format_nodes_for(territory_nodes)
+        territory_nodes.map do |node|
+          node.search("availableFormats numberFormat").to_a
+        end.flatten
+      end
+
+      def truncate(array)
+        array.dup.tap do |result|
+          result.pop while result.any? && result.last.nil?
+        end
+      end
+
+      def squish(string)
+        string.gsub(/\s+/, "") if string
+      end
+
+      def pattern(node, selector)
+        squish(text_or_nil(node, selector))
+      end
+
+      def text_or_nil(node, selector)
+        nodes = node.search(selector)
+        nodes.empty? ? nil : nodes.text
+      end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: global_phone_dbgen
+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:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: Provides a global_phone_dbgen command to generate databases for the GlobalPhone
+  library.
+email:
+- sstephenson@gmail.com
+executables:
+- global_phone_dbgen
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- LICENSE
+- lib/global_phone/database_generator.rb
+- bin/global_phone_dbgen
+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: Generate databases for use with the GlobalPhone library
+test_files: []