uk_postcode 0.0.1 → 0.0.2

data/README.md

@@ -1,7 +1,7 @@
 uk_postcode
 ===========
 
-UK postcode parsing and validation for Ruby.
+UK postcode parsing and validation for Ruby. I've checked it against every postcode I can get my hands on: that's about 1.8 million of them.
 
 Usage
 -----
@@ -10,23 +10,37 @@ Usage
 
 Validate and extract sections of a full postcode:
 
-    pc = UKPostcode.new("W1A 1AA")
-    pc.valid?  #=> true
-    pc.full?   #=> true
-    pc.outcode #=> "W1A"
-    pc.incode  #=> "1AA"
+    pc = UKPostcode.new("W1A 2AB")
+    pc.valid?   #=> true
+    pc.full?    #=> true
+    pc.outcode  #=> "W1A"
+    pc.incode   #=> "2AB"
+    pc.area     #=> "W"
+    pc.district #=> "1A"
+    pc.sector   #=> "2"
+    pc.unit     #=> "AB"
 
 Or of a partial postcode:
 
     pc = UKPostcode.new("W1A")
-    pc.valid?  #=> true
-    pc.full?   #=> false
-    pc.outcode #=> "W1A"
-    pc.incode  #=> nil
+    pc.valid?   #=> true
+    pc.full?    #=> false
+    pc.outcode  #=> "W1A"
+    pc.incode   #=> nil
+    pc.area     #=> "W"
+    pc.district #=> "1A"
+    pc.sector   #=> nil
+    pc.unit     #=> nil
 
 Normalise postcodes:
 
-    UKPostcode.new("w1a1aa").to_str #=> "W1A 1AA"
+    UKPostcode.new("w1a1aa").norm #=> "W1A 1AA"
+
+Fix mistakes with IO/10:
+
+    pc = UKPostcode.new("WIA OAA")
+    pc.outcode #=> "W1A"
+    pc.incode  #=> "0AA"
 
 Gem?
 ----

data/Rakefile

@@ -21,14 +21,14 @@ end
 
 spec = Gem::Specification.new do |s|
   s.name              = "uk_postcode"
-  s.version           = "0.0.1"
+  s.version           = "0.0.2"
   s.summary           = "UK postcode parsing and validation"
   s.author            = "Paul Battley"
   s.email             = "pbattley@gmail.com"
 
   s.has_rdoc          = true
 
-  s.files             = %w(Rakefile README.md) + Dir.glob("{bin,test,lib}/**/*")
+  s.files             = %w(Rakefile README.md) + Dir.glob("{bin,test,lib}/**/*") - ["test/samples/postzon.list"]
   s.executables       = FileList["bin/**"].map { |f| File.basename(f) }
 
   s.require_paths     = ["lib"]

data/lib/uk_postcode.rb

@@ -1,46 +1,102 @@
 class UKPostcode
-  RE_OUTCODE      = /[A-Z]{1,2}[0-9R][0-9A-Z]?/
-  RE_INCODE       = /[0-9][ABD-HJLNP-UW-Z]{2}/
-  RE_OUTCODE_ONLY = /\A(#{RE_OUTCODE})\Z/
-  RE_FULL         = /\A(#{RE_OUTCODE}) ?(#{RE_INCODE})\Z/
+  MATCH = /\A
+           ( [A-PR-UWYZ][A-Z]? )           # area
+           ( [0-9IO][0-9A-HJKMNPR-YIO]? )  # district
+           (?:
+             \s?
+             ( [0-9IO] )                   # sector
+             ( [ABD-HJLNPQ-Z10]{2} )       # unit
+                                     )?
+           \Z/x
 
   attr_reader :raw
 
   # Initialise a new UKPostcode instance from the given postcode string
   #
   def initialize(postcode_as_string)
-    @raw = postcode_as_string.upcase
+    @raw = postcode_as_string
   end
 
   # Returns true if the postcode is a valid full postcode (e.g. W1A 1AA) or outcode (e.g. W1A)
   #
   def valid?
-    raw.match(RE_FULL) || raw.match(RE_OUTCODE_ONLY)
+    !!outcode
   end
 
   # Returns true if the postcode is a valid full postcode (e.g. W1A 1AA)
   #
   def full?
-    raw.match(RE_FULL)
+    !!(outcode && incode)
   end
 
   # The left-hand part of the postcode, e.g. W1A 1AA -> W1A
   #
   def outcode
-    raw[RE_FULL, 1] || raw[RE_OUTCODE_ONLY]
+    area && district && [area, district].join
   end
 
   # The right-hand part of the postcode, e.g. W1A 1AA -> 1AA
   #
   def incode
-    raw[RE_FULL, 2]
+    sector && unit && [sector, unit].join
+  end
+
+  # The first part of the outcode, e.g. W1A 2AB -> W
+  #
+  def area
+    letters(parts[0])
+  end
+
+  # The second part of the outcode, e.g. W1A 2AB -> 1A
+  #
+  def district
+    digits(parts[1])
+  end
+
+  # The first part of the incode, e.g. W1A 2AB -> 2
+  #
+  def sector
+    digits(parts[2])
+  end
+
+  # The second part of the incode, e.g. W1A 2AB -> AB
+  #
+  def unit
+    letters(parts[3])
   end
 
   # Render the postcode as a normalised string, i.e. in upper case and with spacing.
   # Returns an empty string if the postcode is not valid.
   #
-  def to_str
+  def norm
     [outcode, incode].compact.join(" ")
   end
-  alias_method :to_s, :to_str
+  alias_method :normalise, :norm
+  alias_method :normalize, :norm
+
+  alias_method :to_s,   :raw
+  alias_method :to_str, :raw
+
+  def inspect(*args)
+    "<#{self.class.to_s} #{raw}>"
+  end
+
+private
+  def parts
+    if @matched
+      @parts
+    else
+      @matched = true
+      matches = raw.upcase.match(MATCH) || []
+      @parts = (1..4).map{ |i| matches[i] }
+    end
+  end
+
+  def letters(s)
+    s && s.tr("10", "IO")
+  end
+
+  def digits(s)
+    s && s.tr("IO", "10")
+  end
 end

data/test/samples/wikipedia.list

@@ -0,0 +1,36 @@
+# Special postcodes listed in http://en.wikipedia.org/wiki/UK_postcode
+
+SW1A 0AA
+SW1A 1AA
+SW1A 2AA
+BS98 1TL
+BX1  1LT
+BX5  5AT
+CF99 1NA
+DH99 1NS
+E16  1XL
+E98  1NW
+E98  1SN
+E98  1ST
+E98  1TT
+EC4Y 0HQ
+EH99 1SP
+EN8  9SL
+G58  1SB
+GIR  0AA
+L30  4GB
+LS98 1FD
+M2   5BE
+N81  1ER
+S2   4SU
+S6   1SW
+SE1  8UJ
+SE9  2UG
+SN38 1NW
+SW1A 0PW
+SW1A 2HQ
+SW1W 0DT
+TS1  3BA
+W1A  1AA
+W1F  9DJ
+GIR  0AA

data/test/test_samples.rb

@@ -0,0 +1,28 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require "test/unit"
+require "shoulda"
+require "uk_postcode"
+
+class UKPostcodeTest < Test::Unit::TestCase
+
+  Dir[File.join(File.dirname(__FILE__), "samples", "*.list")].each do |path|
+    context "in sample file #{File.basename(path, ".list")}" do
+      setup do
+        @file = open(path)
+      end
+
+      teardown do
+        @file.close
+      end
+
+      should "be valid for each line in sample file" do
+        @file.each_line do |line|
+          next if line =~ /^#|^$/
+          sample = line.chomp.sub(/\s+/, "")
+          postcode = UKPostcode.new(sample)
+          assert postcode.valid?, "'#{sample}' should be valid"
+        end
+      end
+    end
+  end
+end

data/test/test_uk_postcode.rb

@@ -5,75 +5,81 @@ require "uk_postcode"
 
 class UKPostcodeTest < Test::Unit::TestCase
 
-  VALID_SAMPLES  = [ "A9 9AA", "A99 9AA", "AA9 9AA", "AA99 9AA", "A9A 9AA", "AA9A 9AA",
-                     "SW1A 0AA", "SW1A 0PW", "SW1A 1AA", "SW1A 2HQ", "W1A 1AA", "W1A 1AB",
-                     "N81 1ER", "EH99 1SP" ]
-  VALID_OUTCODES = VALID_SAMPLES.map{ |s| s.split(/\s/).first }
-  VALID_INCODES  = VALID_SAMPLES.map{ |s| s.split(/\s/).last  }
-
-  context "full samples with spaces" do
-    setup do
-      @samples  = VALID_SAMPLES
-    end
+  VALID_SAMPLES  = [
+    %w[A   9 9 AA], %w[A  99 9 AA], %w[AA  9 9 AA], %w[AA 99 9 AA], %w[A  9A 9 AA],
+    %w[AA 9A 9 AA], %w[SW 1A 0 AA], %w[SW 1A 0 PW], %w[SW 1A 1 AA], %w[SW 1A 2 HQ],
+    %w[W  1A 1 AA], %w[W  1A 1 AB], %w[N  81 1 ER], %w[EH 99 1 SP], %w[CV  1 1 FL],
+    %w[EX  1 1 AE], %w[TQ  1 1 AG]
+  ]
+
+  { "full samples with spaces"    => lambda{ |a,b,c,d| [[a, b, " ", c, d].join, [a, b, c, d]] },
+    "full samples without spaces" => lambda{ |a,b,c,d| [[a, b, c, d].join, [a, b, c, d]] },
+  }.each do |desc, mapping|
+    context desc do
+      setup do
+        @samples = VALID_SAMPLES.map(&mapping)
+      end
 
-    should "all be valid" do
-      @samples.each do |sample|
-        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+      should "all be valid" do
+        @samples.each do |sample, _|
+          assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+        end
       end
-    end
 
-    should "all be full" do
-      @samples.each do |sample|
-        assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+      should "all be full" do
+        @samples.each do |sample, _|
+          assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+        end
       end
-    end
 
-    should "extract outcodes" do
-      @samples.zip(VALID_OUTCODES).each do |sample, outcode|
-        assert_equal outcode, UKPostcode.new(sample).outcode
+      should "extract outcodes" do
+        @samples.each do |sample, parts|
+          assert_equal parts[0]+parts[1], UKPostcode.new(sample).outcode
+        end
       end
-    end
 
-    should "extract incodes" do
-      @samples.zip(VALID_INCODES).each do |sample, incode|
-        assert_equal incode, UKPostcode.new(sample).incode
+      should "extract incodes" do
+        @samples.each do |sample, parts|
+          assert_equal parts[2]+parts[3], UKPostcode.new(sample).incode
+        end
       end
-    end
-  end
 
-  context "full samples without spaces" do
-    setup do
-      @samples  = VALID_SAMPLES.map{ |s| s.sub(/\s/, "") }
-    end
+      should "extract area" do
+        @samples.each do |sample, parts|
+          assert_equal parts[0], UKPostcode.new(sample).area
+        end
+      end
 
-    should "all be valid" do
-      @samples.each do |sample|
-        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+      should "extract district" do
+        @samples.each do |sample, parts|
+          assert_equal parts[1], UKPostcode.new(sample).district
+        end
       end
-    end
 
-    should "all be full" do
-      @samples.each do |sample|
-        assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+      should "extract sector" do
+        @samples.each do |sample, parts|
+          assert_equal parts[2], UKPostcode.new(sample).sector
+        end
       end
-    end
 
-    should "extract outcodes" do
-      @samples.zip(VALID_OUTCODES).each do |sample, outcode|
-        assert_equal outcode, UKPostcode.new(sample).outcode
+      should "extract unit" do
+        @samples.each do |sample, parts|
+          assert_equal parts[3], UKPostcode.new(sample).unit
+        end
       end
-    end
 
-    should "extract incodes" do
-      @samples.zip(VALID_INCODES).each do |sample, incode|
-        assert_equal incode, UKPostcode.new(sample).incode
+      should "be the same when normalised" do
+        @samples.each do |sample, parts|
+          expected = [parts[0], parts[1], " ", parts[2], parts[3]].join
+          assert_equal expected, UKPostcode.new(sample).norm
+        end
       end
     end
   end
 
   context "outcode samples" do
     setup do
-      @samples = VALID_OUTCODES
+      @samples = VALID_SAMPLES.map{ |a,b,c,d| [a, b].join }
     end
 
     should "all be valid" do
@@ -99,6 +105,12 @@ class UKPostcodeTest < Test::Unit::TestCase
         assert_nil UKPostcode.new(sample).incode
       end
     end
+
+    should "be the same when normalised" do
+      @samples.each do |sample|
+        assert_equal sample, UKPostcode.new(sample).norm
+      end
+    end
   end
 
   context "when the postcode is supplied in lower case" do
@@ -137,8 +149,8 @@ class UKPostcodeTest < Test::Unit::TestCase
         assert !@postcode.full?
       end
 
-      should "return an empty string for to_str" do
-        assert_equal "", @postcode.to_str
+      should "return an empty string when normalised" do
+        assert_equal "", @postcode.norm
       end
 
       should "return nil for outcode" do
@@ -153,22 +165,49 @@ class UKPostcodeTest < Test::Unit::TestCase
 
   context "when used as a string" do
     should "normalise spacing" do
-      assert_equal "W1A 1AA", UKPostcode.new("W1A1AA").to_str
+      assert_equal "W1A 1AA", UKPostcode.new("W1A1AA").norm
     end
 
     should "convert case" do
-      assert_equal "W1A 1AA", UKPostcode.new("w1a 1aa").to_str
+      assert_equal "W1A 1AA", UKPostcode.new("w1a 1aa").norm
     end
 
     should "ignore a missing incode" do
-      assert_equal "W1A", UKPostcode.new("W1A").to_str
+      assert_equal "W1A", UKPostcode.new("W1A").norm
+    end
+  end
+
+  should "return original input for to_s" do
+    ["W1A1AA", "w1a 1aa", "W1A"].each do |s|
+      postcode = UKPostcode.new(s)
+      assert_equal s, postcode.to_s
     end
   end
 
-  should "have same output for to_s and to_str" do
+  should "return original input for to_str" do
     ["W1A1AA", "w1a 1aa", "W1A"].each do |s|
       postcode = UKPostcode.new(s)
-      assert_equal s.to_str, s.to_s
+      assert_equal s, postcode.to_str
+    end
+  end
+
+  context "when letters are used instead of digits" do
+    context "in a full postcode" do
+      setup do
+        @postcode = UKPostcode.new("SWIA OPW")
+      end
+
+      should "be valid" do
+        assert @postcode.valid?
+      end
+
+      should "be full" do
+        assert @postcode.full?
+      end
+
+      should "normalise to digits" do
+        assert_equal "SW1A 0PW", @postcode.norm
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: uk_postcode
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Paul Battley
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-06 00:00:00 +00:00
+date: 2010-01-09 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -33,6 +33,8 @@ extra_rdoc_files: []
 files: 
 - Rakefile
 - README.md
+- test/samples/wikipedia.list
+- test/test_samples.rb
 - test/test_uk_postcode.rb
 - lib/uk_postcode.rb
 has_rdoc: true