fixed bug for when no address is found, added test. Also added docs.

Author: coderifous

README.textile

@@ -5,6 +5,9 @@ Find and/or replace mailing addresses in strings.
 h2. Examples
 
 <pre><code>
+require 'rubygems'
+require 'address_extractor'
+  
 string = <<EOF
 Please send the package to 123 Foo St., Someplace FL
 

lib/address_extractor.rb

@@ -1,29 +1,43 @@
 class AddressExtractor
   class << self
 
+    # Returns hash for address if address found.
+    # Returns nil if no address found.
     def first_address(string)
       hashify_results string.scan(ADDRESS_PATTERN).first
     end
-    
+
+    # Returns array of hashes for each address found.
+    # Returns empty array if no addresses found.
     def find_addresses(string)
       string.scan(ADDRESS_PATTERN).collect { |a| hashify_results(a) }.compact
     end
 
+    # Pass it a block that recieves 2 parameters: 
+    #   address hash
+    #   matched address string ($&)
+    # Whatever your block returns will be used for the substition.
+    # Returns new string with substition applied to first identified address.
+    # If no address found, returns same string unaltered.
     def replace_first_address(string)
       hash = first_address(string)
       string.sub(ADDRESS_PATTERN) do |match|
         yield(hash, $&)
       end
     end
-    
+
+    # Same as +replace_first_address+ but applies substition to all identified addresses.
     def replace_addresses(string)
       string.gsub(ADDRESS_PATTERN) do |match|
         hash = hashify_results match.scan(ADDRESS_PATTERN).first
         useful_address?(hash) ? yield(hash, $&) : match
       end
     end
 
+  private
+    
     def hashify_results(matches)
+      return nil if matches.nil?
       result = { }
       capture_index = 0
       CAPTURE_MAP.each do |field|

test/test_address_extractor.rb

@@ -33,6 +33,13 @@ def test_replace_addresses
     assert string =~ /via mail at:\n  skidoosh/
   end
 
+  def test_no_addresses_found
+    assert_nil AddressExtractor.first_address("foo")
+    assert_equal [], AddressExtractor.find_addresses("foo")
+    assert_equal "foo", AddressExtractor.replace_first_address("foo")
+    assert_equal "foo", AddressExtractor.replace_addresses("foo")
+  end
+  
   module Helpers
     def assert_first_address(a)
       assert_not_nil a