phone_wrangler 0.1.2 → 0.1.3

data/README.rdoc

@@ -1,6 +1,155 @@
 = phone_wrangler
 
-Description goes here.
+The phone_wrangler gem helps me parse, compare and normalize
+NANP[http://en.wikipedia.org/wiki/NANP] phone numbers (basically
+the US, Canada, and some territories).  It's not intended to be
+a generalized phone number handler for international numbers.
+There are two good reasons (and one lame one) for this:
+
+1. In the apps where I use this, I don't have any international phone numbers
+   (nor will I; they're not public-facing web apps).
+2. I need to be able to handle short phone numbers ("555-1111"), which means
+   I have to treat a number prefix starting with something-besides-1 as an
+   area code or prefix, rather than following the prefix code.
+3. I don't know how to parse the wicked prefix code for
+   <A HREF= "http://en.wikipedia.org/wiki/Country_calling_codes">country calling codes</A>.
+
+I'll let you decide which of those three is the lame one.
+
+= FAQ
+
+1) PhoneWrangler or PhoneNumber?  Are you stupid or something?
+
+Probably. This gem was going to be called phone_number (the class is called PhoneNumber),
+but I was too slow, and midas created the cool phone_number[http://github.com/midas/phone_number]
+gem while I was dorking around. I wanted to extract this anyway (for my own use) and don't
+want to change all my code at the moment to use PhoneWrangler as the class, so there we are.
+
+2. So it's more of a lazy thing?
+
+Yes.  Eventually, I will probably cave in and fix it, which will infuriate *both* the
+loyal fans of phone_wrangler (aka the PhoneNumber wrapper gem).
+
+= Installing PhoneWrangler
+
+== Requirements
+
+Ruby. And a computer, probably.
+
+== Install
+
+  gem sources -a http://gemcutter.org
+  sudo gem install phone_wrangler
+
+== Installation for Rails
+
+If you want to vendor the gem in your Rails app, add this to +config/environment.rb+ :
+
+  config.gem "phone_number", :version => '0.0.1', :source => 'http://gemcutter.org'
+
+Optionally, you can add
+
+  include PhoneWrangler
+
+to get easy access to the PhoneNumber class without having to add the module name,
+like PhoneWrangler::PhoneNumber, which is really too clunky to contemplate, yes?
+
+Then run
+
+  sudo rake:gems:install
+
+= Using PhoneWrangler
+
+You can create a PhoneNumber object from almost any phone-number-looking string:
+
+  home = PhoneNumber.new('800/555-2468 x012')
+
+or
+
+  home = PhoneNumber.new('555-2468 ext 12')
+
+or
+
+  home = PhoneNumber.new("202.444.1234")
+
+or
+
+  home = PhoneNumber.new("5551234")
+
+plus other variations.  Because users enter phone numbers in *my* app with
+reckless abandon in format, I try to accept and parse any form for which I can
+figure out with some confidence which part is which.
+
+You can also create a PhoneNumber from a hash:
+
+  home = PhoneNumber.new(:prefix => '555', :number => '1234', :area_code => '444')  # 444-555-1234
+
+or
+
+  home = PhoneNumber.new(:extension => '99', :prefix => '555', :number => '1012') # 555-1012 x 99
+
+One of the most useful things (for me) about a PhoneNumber object is it allows me to compare two
+phone numbers in different layouts:
+
+  pn1 = PhoneNumber.new("555-403-1212")
+  pn2 = PhoneNumber.new(" 1 555/403.1212 ")
+
+  pn1 == pn2  # true
+
+  pn3 = PhoneNumber.new(:prefix => '403', :number => '1212')
+  pn3.area_code = '555'
+  pn1 == pn3  # true
+
+And did I mention you can set or retrieve any of the PhoneNumber's components with accessors?
+
+  pn = PhoneNumber.new("555-403-1212")
+  pn.extension  # nil
+  pn.area_code  # '555'
+  pn.prefix = '444'   # "555-444-1212"
+
+A PhoneNumber object can return you the original input if you ask nicely:
+
+  home = PhoneNumber.new(:prefix => '555', :number => '1234', :area_code => '444')  # 444-555-1234
+  home.raw  # { :prefix => '555', :number => '1234', :area_code => '444' }
+  home = PhoneNumber.new('555-2468 ext 12')
+  home.raw  # '555-2468 ext 12'
+
+Keep in mind that if you change pieces of PhoneNumber using the accessors, the _actual_ content
+of PhoneNumber will diverge from the original input.  But we can't change the past, can we?
+
+You can also overwrite the contents of a PhoneNumber object by giving it a new phone number:
+
+  pn = PhoneNumber.new("555-1212")
+  pn.to_s  # "555-1212"
+  pn.raw = "555-444-4040"
+  pn.to_s  # "(555) 444-4040"
+  pn.raw = {:area_code => '222', :prefix => '555', :number => '0909'}
+  pn.to_s  # "(222) 555-0909"
+
+When you change PhoneNumber _this_ way, it stores the new input as the 'original' input.  Gotta
+keep up with the changing times!
+
+PhoneNumber also supports a number of named formats (:us, :us_short, :nanp_short at the moment;
+look in the code for +@@formats+), as well as sprintf-style string interpolation, as arguments
+to +to_s+.  For example:
+
+  pn = PhoneNumber.new("404-555-1212 ext 37")
+  pn.to_s  # "(404) 555-1212 x 37"
+  pn.to_s(:us_short)  # "(404) 555-1212"
+  pn.to_s("Digitz [%a] -->%p~%n")  # "Digitz [404] -->555~1212"
+
+There's more, but it's not a very long or complicated library, so look at the code!
+
+= Adulation
+
+All words of adulation, adoration, encouragement, worshipful praise, and awestruck
+respect are most welcome.
+
+But since most words are of a very different kind, I suppose I'll have to listen to
+them, too.
+
+Send either kind to me here, or find me on Twitter (@erebor) or email me.  I'll bet
+you can find my address.
 
 == Note on Patches/Pull Requests
  
@@ -15,4 +164,4 @@ Description goes here.
 
 == Copyright
 
-Copyright (c) 2010 Ryan Waldron. See LICENSE for details.
+Copyright (c) 2010 Ryan Waldron (erebor). See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/lib/phone_wrangler.rb

@@ -5,6 +5,8 @@ module PhoneWrangler
     NUMBER_PARTS = [:area_code, :prefix, :number, :extension]
     attr_accessor :area_code, :prefix, :number, :extension
 
+    attr_reader :original
+
     unless defined? @@default_area_code
       @@default_area_code = nil
     end
@@ -22,7 +24,7 @@ module PhoneWrangler
     end
 
     @@formats = {
-            :us => "%c (%a) %p-%n x %x",
+            :us => "%c (%a) %p-%n x %e",
             :us_short => "(%a) %p-%n",
             :nanp_short => "(%a) %p-%n"
     }
@@ -37,11 +39,11 @@ module PhoneWrangler
 
     #-------------------args-----------------------------------------
     def initialize(args='')
-      @original = args
       self.raw = args
     end
 
     def raw= (args)
+      @original = args
       case args
       when String
         parse_from_string(args)
@@ -91,19 +93,15 @@ module PhoneWrangler
       when Symbol
         format = @@formats[format]
       when ''
-        format += "(%a) " unless area_code.nil? or area_code.empty?
-        format += "%p-" unless prefix.nil? or prefix.empty?
-        format += "%n" unless number.nil? or number.empty?
-        format += " x%e" unless extension.nil? or extension.empty?
+        format += "(%a) " unless @area_code.nil? or @area_code.empty?
+        format += "%p-" unless @prefix.nil? or @prefix.empty?
+        format += "%n" unless @number.nil? or @number.empty?
+        format += " x%e" unless @extension.nil? or @extension.empty?
       end
 
       format_number(format)
     end
 
-    def original
-      @original
-    end
-
     # TODO: Should #digits method include the extension digits at all?  Probably not
     # with an 'x', anyway.
     def digits
@@ -186,7 +184,8 @@ module PhoneWrangler
 
     def format_number(format)
       @@pattern_map.each do |pat, field|
-        format = format.gsub( pat, self.send(field) || '' ) if self.respond_to?(field)
+        replace_with = ( self.send(field) if self.respond_to?(field) ) || ''
+        format = format.gsub( pat, replace_with)
       end
       format
     end
@@ -194,26 +193,3 @@ module PhoneWrangler
   end
 
 end
-=begin
-   home = PhoneNumber.new('800/555-2468 x012')
-# or
-   home = PhoneNumber.new
-   home.number = "256-777-7650"
-# or
-#  home = PhoneNumber.new
-({:area_code=>'800', :prefix=>'555', :number=>'2020'})
-
-   puts home.original
-   puts home.area_code
-   puts home.prefix
-   puts home.number
-   puts home.extension
-   puts home.to_s
-   puts home.to_s("(%a) %p-%n")
-   puts home.pack({:area_code=>'555', :prefix=>'888', :number=>'1212'})
-   p home.unpack
-   puts home.pack!({:area_code=>'555', :prefix=>'888', :number=>'1212'})
-   puts home.formatted
-
-=end
-

data/phone_wrangler.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{phone_wrangler}
-  s.version = "0.1.2"
+  s.version = "0.1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ryan Waldron"]
-  s.date = %q{2010-01-13}
+  s.date = %q{2010-01-14}
   s.description = %q{Handle phone numbers intelligently}
   s.email = %q{rew@erebor.com}
   s.extra_rdoc_files = [

data/test/phone_wrangler_test.rb

@@ -143,6 +143,12 @@ class PhoneWranglerTest < Test::Unit::TestCase
       assert_equal "256", PhoneNumber.default_area_code
       PhoneNumber.default_area_code = nil  # put it back, it's a class attr
     end
+
+    should "set original to new value when re-assigned with raw=" do
+      pn = PhoneNumber.new("1-234-567-8901")
+      pn.raw = "456-909-8073"
+      assert_equal "456-909-8073", pn.original
+    end
   end
 
   context "With a default_area_code set" do
@@ -222,6 +228,12 @@ class PhoneWranglerTest < Test::Unit::TestCase
       assert_equal " FF 431--4310", @pn.to_s("%a FF %p--%n")
     end
 
+    should "correctly interpolate named patterns" do
+      @pn.extension = "999"
+      assert_equal " (256) 555-1234 x 999", @pn.to_s(:us)
+      assert_equal "(256) 555-1234", @pn.to_s(:us_short)
+      assert_equal "(256) 555-1234", @pn.to_s(:nanp_short)
+    end
 
     should "return original data" do
       assert_equal @phone_hash, @pn.original

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: phone_wrangler
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors: 
 - Ryan Waldron
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-13 00:00:00 -06:00
+date: 2010-01-14 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency