uk_postcode 1.0.0 → 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fd5d3327b3f2fff64453bb32cbf18941c6e668ed
+  data.tar.gz: 9e8d9284064d002eb6b004ed1fbd0d5779b9a9aa
+SHA512:
+  metadata.gz: efa1121b17ba18e5d1c33ddd6a8d0ee7a239e1c1baa35a1699400e5e2f3892542636d585fe597bd66be3fa7a4f0148ec824d5a335430a1dd06daf13b6887325e
+  data.tar.gz: 26f43a092dce9d1f706cf36eee76af39d076b988af4d08ff581ee7ac21c84465f8a2f8d34b570e7021b68038f9e1558bf6c28e21b3c42bd18c221a7526122b31

data/README.md

@@ -1,66 +1,114 @@
-uk_postcode
-===========
+# uk_postcode
 
-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.
+UK postcode parsing and validation for Ruby for writing friendly software.
 
-Usage
------
+Features:
 
-    require "uk_postcode"
+* Handles errors with `I`/`1` and `O`/`0`.
+* Does not require postcodes to contain spaces.
+* Normalises postcodes (e.g. `wiaiaa` to `W1A 1AA`).
+* Parses full postcodes or outcodes (`W1A`)
+* Allows extraction of fields within postcode.
+* Validated against 2.5 million postcodes in England, Wales, Scotland, Northern
+  Ireland, the Channel Islands, and the Isle of Man.
+
+## Usage
+
+```ruby
+require "uk_postcode"
+```
 
 Validate and extract sections of a full postcode:
 
-    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"
+```ruby
+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.area     #=> "W"
-    pc.district #=> "1A"
-    pc.sector   #=> nil
-    pc.unit     #=> nil
+```ruby
+pc = UKPostcode.new("W1A")
+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:
+Normalise postcodes with `normalize` (or just `norm`):
 
-    UKPostcode.new("w1a1aa").norm #=> "W1A 1AA"
+```ruby
+UKPostcode.new("w1a1aa").normalize #=> "W1A 1AA"
+```
 
 Fix mistakes with IO/10:
 
-    pc = UKPostcode.new("WIA OAA")
-    pc.outcode #=> "W1A"
-    pc.incode  #=> "0AA"
+```ruby
+pc = UKPostcode.new("WIA OAA")
+pc.outcode #=> "W1A"
+pc.incode  #=> "0AA"
+```
+
+## Gem?
 
-Gem?
-----
+```sh
+$ gem install uk_postcode
+```
 
-    gem install uk_postcode
+## Testing
 
-Testing
--------
+To run the test suite:
+
+```sh
+$ rake
+```
 
 The full list of UK postcodes is not included in the repository due to its
 size.
+Additional sample files under `test/samples` will automatically be used.
+
+The format of each line in a sample file must be `OOOOIII` or `OOO III` (where
+`O` = outcode, `I` = incode), e.g.:
+
+```
+AB1 0AA
+BT109AH
+```
+
+You can obtain lists of postcodes by processing various datasets available
+from [mySociety][mys].
+
+### Code-Point Open
+
+This does not include postcodes for Northern Ireland, the Channel Islands,
+or the Isle of Man.
+
+```sh
+$ cut -c 2-8 Data/CSV/*.csv | \
+sort -uV > test/samples/large/code_point_open.list
+```
 
-To test against the full UK postcode set, you need to obtain the
-[Code-Point® Open data set][cpo] from Ordnance Survey, and to extract and
-transform it:
+### ONS Postcode Directory
 
-    unzip /path/to/codepo_gb.zip
-    cat Code-Point\ Open/data/*.csv | cut -c 2-8 | sort -V | uniq > test/samples/code_point_open.list
+This includes postcodes for the whole UK as well as the Channel Islands and the
+Isle of Man.
+It also includes some defunct postcodes, most notably the NPT outcode, which
+must be filtered out.
 
-Alternatively, a [pre-generated list][dl] is available for download.
+```sh
+$ cut -c 2-8 ONSPD_*.csv | grep '[A-Z]' | grep -v ^NPT | \
+sort -uV > test/samples/large/onspd.list
+```
 
-[cpo]: https://www.ordnancesurvey.co.uk/opendatadownload/products.html
-[dl]:  https://github.com/threedaymonk/uk_postcode/downloads
+[mys]: http://parlvid.mysociety.org/os/

data/lib/uk_postcode/version.rb

@@ -1,3 +1,3 @@
 class UKPostcode
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/test/samples_test.rb

@@ -1,30 +1,17 @@
-$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
-require "test/unit"
-require "shoulda"
+require_relative "./test_helper"
 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 =~ /^#|^$/
-          outcode = line[0,4].strip
-          incode  = line[4,4].strip
-          postcode = UKPostcode.new(outcode + incode)
-          assert postcode.valid?, "'#{outcode} #{incode}' should be valid"
-          assert_equal outcode, postcode.outcode, "incorrect outcode for '#{outcode} #{incode}'"
-          assert_equal incode,  postcode.incode,  "incorrect incode for '#{outcode} #{incode}'"
-        end
+describe "Sample files" do
+  Dir[File.expand_path("../samples/**/*.list", __FILE__)].each do |path|
+    it "should be valid for each line in #{File.basename(path, ".list")}" do
+      open(path).each_line do |line|
+        next if line =~ /^#|^$/
+        outcode = line[0,4].strip
+        incode  = line[4,3].strip
+        postcode = UKPostcode.new(outcode + incode)
+        postcode.must_be :valid?
+        postcode.outcode.must_equal outcode
+        postcode.incode.must_equal incode
       end
     end
   end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+lib = File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+require "minitest/spec"
+require "minitest/autorun"

data/test/uk_postcode_test.rb

@@ -1,10 +1,7 @@
-# -*- coding: undecided -*-
-$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
-require "test/unit"
-require "shoulda"
+require_relative "./test_helper"
 require "uk_postcode"
 
-class UKPostcodeTest < Test::Unit::TestCase
+describe UKPostcode do
 
   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],
@@ -13,122 +10,122 @@ class UKPostcodeTest < Test::Unit::TestCase
     %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]] },
+  { "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"
+    describe desc do
+      let(:samples) {
+        VALID_SAMPLES.map(&mapping)
+      }
+
+      it "should all be valid" do
+        samples.each do |sample, _|
+          UKPostcode.new(sample).must_be :valid?
         end
       end
 
-      should "all be full" do
-        @samples.each do |sample, _|
-          assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+      it "should all be full" do
+        samples.each do |sample, _|
+          UKPostcode.new(sample).must_be :full?
         end
       end
 
-      should "extract outcodes" do
-        @samples.each do |sample, parts|
-          assert_equal parts[0]+parts[1], UKPostcode.new(sample).outcode
+      it "should extract outcodes" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).outcode.must_equal parts[0] + parts[1]
         end
       end
 
-      should "extract incodes" do
-        @samples.each do |sample, parts|
-          assert_equal parts[2]+parts[3], UKPostcode.new(sample).incode
+      it "should extract incodes" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).incode.must_equal parts[2] + parts[3]
         end
       end
 
-      should "extract area" do
-        @samples.each do |sample, parts|
-          assert_equal parts[0], UKPostcode.new(sample).area
+      it "should extract area" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).area.must_equal parts[0]
         end
       end
 
-      should "extract district" do
-        @samples.each do |sample, parts|
-          assert_equal parts[1], UKPostcode.new(sample).district
+      it "should extract district" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).district.must_equal parts[1]
         end
       end
 
-      should "extract sector" do
-        @samples.each do |sample, parts|
-          assert_equal parts[2], UKPostcode.new(sample).sector
+      it "should extract sector" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).sector.must_equal parts[2]
         end
       end
 
-      should "extract unit" do
-        @samples.each do |sample, parts|
-          assert_equal parts[3], UKPostcode.new(sample).unit
+      it "should extract unit" do
+        samples.each do |sample, parts|
+          UKPostcode.new(sample).unit.must_equal parts[3]
         end
       end
 
-      should "be the same when normalised" do
-        @samples.each do |sample, parts|
+      it "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
+          UKPostcode.new(sample).norm.must_equal expected
         end
       end
     end
   end
 
-  context "outcode samples" do
-    setup do
-      @samples = VALID_SAMPLES.map{ |a,b,c,d| [a, b].join }
-    end
+  describe "outcode samples" do
+    let(:samples) {
+      VALID_SAMPLES.map{ |a,b,c,d| [a, b].join }
+    }
 
-    should "all be valid" do
-      @samples.each do |sample|
-        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+    it "should all be valid" do
+      samples.each do |sample|
+        UKPostcode.new(sample).must_be :valid?
       end
     end
 
-    should "not be full" do
-      @samples.each do |sample|
-        assert !UKPostcode.new(sample).full?, "'#{sample}' should not be full"
+    it "should not be full" do
+      samples.each do |sample|
+        UKPostcode.new(sample).wont_be :full?
       end
     end
 
-    should "keep outcode unchanged" do
-      @samples.each do |sample|
-        assert_equal sample, UKPostcode.new(sample).outcode
+    it "should keep outcode unchanged" do
+      samples.each do |sample|
+        UKPostcode.new(sample).outcode.must_equal sample
       end
     end
 
-    should "have nil incode" do
-      @samples.each do |sample|
-        assert_nil UKPostcode.new(sample).incode
+    it "should have nil incode" do
+      samples.each do |sample|
+        UKPostcode.new(sample).incode.must_be_nil
       end
     end
 
-    should "be the same when normalised" do
-      @samples.each do |sample|
-        assert_equal sample, UKPostcode.new(sample).norm
+    it "should be the same when normalised" do
+      samples.each do |sample|
+        UKPostcode.new(sample).norm.must_equal sample
       end
     end
   end
 
-  context "when the postcode is supplied in lower case" do
-    setup do
-      @postcode = UKPostcode.new("w1a 1aa")
-    end
+  describe "when the postcode is supplied in lower case" do
+    let(:postcode) {
+      UKPostcode.new("w1a 1aa")
+    }
 
-    should "extract outcode in upper case" do
-      assert_equal "W1A", @postcode.outcode
+    it "should extract outcode in upper case" do
+      postcode.outcode.must_equal "W1A"
     end
 
-    should "extract incode in upper case" do
-      assert_equal "1AA", @postcode.incode
+    it "should extract incode in upper case" do
+      postcode.incode.must_equal "1AA"
     end
 
-    should "be valid" do
-      assert @postcode.valid?
+    it "should be valid" do
+      postcode.must_be :valid?
     end
   end
 
@@ -137,147 +134,145 @@ class UKPostcodeTest < Test::Unit::TestCase
     "when the outcode is truncated" => "W",
     "when the postcode is invalid" => "ABC DEFG"
   }.each do |desc, sample|
-    context desc do
-      setup do
-        @postcode = UKPostcode.new(sample)
-      end
+    describe desc do
+      let(:postcode) {
+        UKPostcode.new(sample)
+      }
 
-      should "not be valid" do
-        assert !@postcode.valid?
+      it "should not be valid" do
+        refute postcode.valid?
       end
 
-      should "not be full" do
-        assert !@postcode.full?
+      it "should not be full" do
+        refute postcode.full?
       end
 
-      should "return an empty string when normalised" do
-        assert_equal "", @postcode.norm
+      it "should return an empty string when normalised" do
+        postcode.norm.must_equal ""
       end
 
-      should "return nil for outcode" do
-        assert_nil @postcode.outcode
+      it "should return nil for outcode" do
+        postcode.outcode.must_be_nil
       end
 
-      should "return nil for incode" do
-        assert_nil @postcode.incode
+      it "should return nil for incode" do
+        postcode.incode.must_be_nil
       end
     end
   end
 
-  context "when used as a string" do
-    should "normalise spacing when no spacing has been used in the input" do
-      assert_equal "W1A 1AA", UKPostcode.new("W1A1AA").norm
+  describe "when used as a string" do
+    it "should normalise spacing when no spacing has been used in the input" do
+      UKPostcode.new("W1A1AA").norm.must_equal "W1A 1AA"
     end
 
-    should "normalise spacing when too much spacing has been used in the input" do
-      assert_equal "W1A 1AA", UKPostcode.new("W1A  1AA").norm
+    it "should normalise spacing when too much spacing has been used in the input" do
+      UKPostcode.new("W1A  1AA").norm.must_equal "W1A 1AA"
     end
 
-    should "convert case" do
-      assert_equal "W1A 1AA", UKPostcode.new("w1a 1aa").norm
+    it "should convert case" do
+      UKPostcode.new("w1a 1aa").norm.must_equal "W1A 1AA"
     end
 
-    should "ignore a missing incode" do
-      assert_equal "W1A", UKPostcode.new("W1A").norm
+    it "should ignore a missing incode" do
+      UKPostcode.new("W1A").norm.must_equal "W1A"
     end
 
-    should "trim whitespace from start and end of the string" do
-      assert_equal "W1A 1AA", UKPostcode.new(" W1A 1AA ").norm
+    it "should trim whitespace from start and end of the string" do
+      UKPostcode.new(" W1A 1AA ").norm.must_equal "W1A 1AA"
     end
   end
 
-  should "return original input for to_s" do
+  it "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
+      UKPostcode.new(s).to_s.must_equal s
     end
   end
 
-  should "return original input for to_str" do
+  it "should return original input for to_str" do
     ["W1A1AA", "w1a 1aa", "W1A"].each do |s|
-      postcode = UKPostcode.new(s)
-      assert_equal s, postcode.to_str
+      UKPostcode.new(s).to_str.must_equal s
     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
+  describe "when letters are used instead of digits" do
+    describe "in a full postcode" do
+      let(:postcode) {
+        UKPostcode.new("SWIA OPW")
+      }
 
-      should "be valid" do
-        assert @postcode.valid?
+      it "should be valid" do
+        postcode.must_be :valid?
       end
 
-      should "be full" do
-        assert @postcode.full?
+      it "should be full" do
+        postcode.must_be :full?
       end
 
-      should "normalise to digits" do
-        assert_equal "SW1A 0PW", @postcode.norm
+      it "should normalise to digits" do
+        postcode.norm.must_equal "SW1A 0PW"
       end
     end
   end
 
-  context "when digits are used instead of letters" do
-    context "in a full postcode" do
-      setup do
-        @postcode = UKPostcode.new("0X1 0AB")
-      end
+  describe "when digits are used instead of letters" do
+    describe "in a full postcode" do
+      let(:postcode) {
+        UKPostcode.new("0X1 0AB")
+      }
 
-      should "be valid" do
-        assert @postcode.valid?
+      it "should be valid" do
+        postcode.must_be :valid?
       end
 
-      should "be full" do
-        assert @postcode.full?
+      it "should be full" do
+        postcode.must_be :full?
       end
 
-      should "normalise to letters" do
-        assert_equal "OX1 0AB", @postcode.norm
+      it "should normalise to letters" do
+        postcode.norm.must_equal "OX1 0AB"
       end
     end
   end
 
-  context "single-letter area code" do
+  describe "single-letter area code" do
     %w[B E G L M N S W].each do |area|
-      context area do
-        should "not convert 1 to I in two-digit outcode" do
+      describe area do
+        it "should not convert 1 to I in two-digit outcode" do
           outcode = area + "11"
           postcode = UKPostcode.new(outcode)
-          assert_equal area,    postcode.area
-          assert_equal outcode, postcode.outcode
+          postcode.area.must_equal area
+          postcode.outcode.must_equal outcode
         end
 
-        should "not convert 1 to I in full postcode with space" do
+        it "should not convert 1 to I in full postcode with space" do
           outcode = area + "13"
           postcode = UKPostcode.new(outcode + " 1AA")
-          assert_equal area,    postcode.area
-          assert_equal outcode, postcode.outcode
+          postcode.area.must_equal area
+          postcode.outcode.must_equal outcode
         end
 
-        should "not convert 1 to I in full postcode without space" do
+        it "should not convert 1 to I in full postcode without space" do
           outcode = area + "13"
           postcode = UKPostcode.new(outcode + "2AA")
-          assert_equal area,    postcode.area
-          assert_equal outcode, postcode.outcode
+          postcode.area.must_equal area
+          postcode.outcode.must_equal outcode
         end
       end
     end
   end
 
-  context "GIR 0AA" do
-    setup do
-      @norm = "GIR 0AA"
-    end
+  describe "GIR 0AA" do
+    let(:norm) {
+      "GIR 0AA"
+    }
 
-    should "stay as is" do
-      assert_equal @norm, UKPostcode.new(@norm).norm
+    it "should stay as is if already normalised" do
+      UKPostcode.new(norm).norm.must_equal norm
     end
 
-    should "be normalised" do
-      assert_equal @norm, UKPostcode.new("G1ROAA").norm
+    it "should be normalised" do
+      UKPostcode.new("G1ROAA").norm.must_equal norm
     end
   end
 end