uk_postcode 1.0.1 → 2.0.0.alpha

data/lib/uk_postcode.rb

@@ -1,112 +1,19 @@
-class UKPostcode
-  MATCH = /\A \s* (?:
-             ( G[I1]R \s* [0O]AA )           # special postcode
-           |
-             ( [A-PR-UWYZ01][A-Z01]? )       # area
-             ( [0-9IO][0-9A-HJKMNPR-YIO]? )  # district
-             (?: \s*
-               ( [0-9IO] )                   # sector
-               ( [ABD-HJLNPQ-Z10]{2} )       # unit
-             )?
-           ) \s* \Z/x
-
-  attr_reader :raw
-
-  # Initialise a new UKPostcode instance from the given postcode string
-  #
-  def initialize(postcode_as_string)
-    @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?
-    !!outcode
-  end
-
-  # Returns true if the postcode is a valid full postcode (e.g. W1A 1AA)
-  #
-  def full?
-    !!(outcode && incode)
-  end
-
-  # The left-hand part of the postcode, e.g. W1A 1AA -> W1A
-  #
-  def outcode
-    area && district && [area, district].join
-  end
-
-  # The right-hand part of the postcode, e.g. W1A 1AA -> 1AA
-  #
-  def incode
-    sector && unit && [sector, unit].join
-  end
-
-  # The first part of the outcode, e.g. W1A 2AB -> W
-  #
-  def area
-    parts[0]
-  end
-
-  # The second part of the outcode, e.g. W1A 2AB -> 1A
-  #
-  def district
-    parts[1]
-  end
-
-  # The first part of the incode, e.g. W1A 2AB -> 2
-  #
-  def sector
-    parts[2]
-  end
+require "uk_postcode/version"
+require "uk_postcode/geographic_postcode"
+require "uk_postcode/giro_postcode"
+require "uk_postcode/invalid_postcode"
 
-  # The second part of the incode, e.g. W1A 2AB -> AB
-  #
-  def unit
-    parts[3]
-  end
+module UKPostcode
+  module_function
 
-  # 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.
+  # Attempt to parse the string str as a postcode. Returns an object
+  # representing the postcode, or an InvalidPostcode if the string cannot be
+  # parsed.
   #
-  def norm
-    [outcode, incode].compact.join(" ")
-  end
-  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
-    return @parts if @matched
-
-    @matched = true
-    matches = raw.upcase.match(MATCH) || []
-    if matches[1]
-      @parts = %w[ G IR 0 AA ]
-    else
-      a, b, c, d = (2..5).map{ |i| matches[i] }
-      if a =~ /^[A-Z][I1]$/
-        a = a[0, 1]
-        b = "1" + b
-      end
-      @parts = [letters(a), digits(b), digits(c), letters(d)]
+  def parse(str)
+    [GiroPostcode, GeographicPostcode, InvalidPostcode].each do |klass|
+      pc = klass.parse(str)
+      return pc if pc
     end
   end
-
-  def letters(s)
-    s && s.tr("10", "IO")
-  end
-
-  def digits(s)
-    s && s.tr("IO", "10")
-  end
 end
-
-require "uk_postcode/version"

data/test/country_finder_test.rb

@@ -0,0 +1,33 @@
+require_relative "./test_helper"
+require "uk_postcode"
+
+describe UKPostcode do
+  it 'should find the country of a full postcode in England' do
+    UKPostcode.parse('W1A 1AA').country.must_equal :england
+  end
+
+  it 'should find the country of a full postcode in Scotland' do
+    UKPostcode.parse('EH8 8DX').country.must_equal :scotland
+  end
+
+  it 'should find the country of a full postcode in Wales' do
+    UKPostcode.parse('CF99 1NA').country.must_equal :wales
+  end
+
+  it 'should find the country of a full postcode in Northern Ireland' do
+    UKPostcode.parse('BT4 3XX').country.must_equal :northern_ireland
+  end
+
+  it 'should find the country of a postcode in a border region' do
+    UKPostcode.parse('CA6 5HS').country.must_equal :scotland
+    UKPostcode.parse('CA6 5HT').country.must_equal :england
+  end
+
+  it 'should find the country of an unambiguous partial postcode' do
+    UKPostcode.parse('BT4').country.must_equal :northern_ireland
+  end
+
+  it 'should return :unknown for an ambiguous partial postcode' do
+    UKPostcode.parse('DG16').country.must_equal :unknown
+  end
+end

data/test/full_postcode_test.rb

@@ -0,0 +1,35 @@
+require_relative "./test_helper"
+require "csv"
+require "uk_postcode"
+
+describe "Full set of postcodes" do
+  CSV_PATH = File.expand_path("../data/postcodes.csv", __FILE__)
+
+  COUNTRIES = {
+    'E92000001' => :england,
+    'N92000002' => :northern_ireland,
+    'S92000003' => :scotland,
+    'W92000004' => :wales,
+    'L93000001' => :channel_islands,
+    'M83000003' => :isle_of_man
+  }
+
+  it "should correctly parse and find the country of every extant postcode" do
+    if File.exist?(CSV_PATH)
+      CSV.foreach(CSV_PATH, headers: [:postcode, :country]) do |row|
+        outcode = row[:postcode][0,4].strip
+        incode  = row[:postcode][4,3].strip
+        country = COUNTRIES.fetch(row[:country])
+
+        postcode = UKPostcode.parse(outcode + incode)
+
+        postcode.wont_be_nil
+        postcode.outcode.must_equal outcode
+        postcode.incode.must_equal incode
+        postcode.country.must_equal country
+      end
+    else
+      skip "Skipping because #{CSV_PATH} does not exist"
+    end
+  end
+end

data/test/geographic_postcode_test.rb

@@ -0,0 +1,271 @@
+require_relative "./test_helper"
+require "uk_postcode/geographic_postcode"
+
+describe UKPostcode::GeographicPostcode do
+  described_class = UKPostcode::GeographicPostcode
+
+  describe "parse" do
+    it "should parse a full postcode" do
+      pc = described_class.parse("W1A 1AA")
+      pc.must_be_instance_of described_class
+      pc.area.must_equal "W"
+      pc.district.must_equal "1A"
+      pc.sector.must_equal "1"
+      pc.unit.must_equal "AA"
+    end
+
+    it "should parse a postcode with no unit" do
+      pc = described_class.parse("W1A 1")
+      pc.must_be_instance_of described_class
+      pc.area.must_equal "W"
+      pc.district.must_equal "1A"
+      pc.sector.must_equal "1"
+      pc.unit.must_be_nil
+    end
+
+    it "should parse an outcode" do
+      pc = described_class.parse("W1A")
+      pc.must_be_instance_of described_class
+      pc.area.must_equal "W"
+      pc.district.must_equal "1A"
+      pc.sector.must_be_nil
+      pc.unit.must_be_nil
+    end
+
+    it "should parse an area" do
+      pc = described_class.parse("W")
+      pc.must_be_instance_of described_class
+      pc.area.must_equal "W"
+      pc.district.must_be_nil
+      pc.sector.must_be_nil
+      pc.unit.must_be_nil
+    end
+
+    it "should handle extra spaces" do
+      pc = described_class.parse("  W1A   1AA  ")
+      pc.must_be_instance_of described_class
+      pc.to_s.must_equal "W1A 1AA"
+    end
+
+    it "should handle no spaces" do
+      pc = described_class.parse("W1A1AA")
+      pc.must_be_instance_of described_class
+      pc.to_s.must_equal "W1A 1AA"
+    end
+
+    it "should be case-insensitive" do
+      pc = described_class.parse("w1a 1aa")
+      pc.must_be_instance_of described_class
+      pc.to_s.must_equal "W1A 1AA"
+    end
+
+    it "should return nil if unable to parse" do
+      pc = described_class.parse("Can't parse this")
+      pc.must_be_nil
+    end
+
+    describe "single-letter area" do
+      it "should extract area without trailing I from outcode" do
+        pc = described_class.parse("B11")
+        pc.area.must_equal "B"
+        pc.district.must_equal "11"
+      end
+
+      it "should extract area without trailing I from full postcode with space" do
+        pc = described_class.parse("E17 1AA")
+        pc.area.must_equal "E"
+        pc.district.must_equal "17"
+      end
+
+      it "should extract area without trailing I from full postcode without space" do
+        pc = described_class.parse("E171AA")
+        pc.area.must_equal "E"
+        pc.district.must_equal "17"
+      end
+    end
+
+    describe "trailing O in area" do
+      it "should extract area with trailing O from outcode" do
+        pc = described_class.parse("CO1")
+        pc.area.must_equal "CO"
+        pc.district.must_equal "1"
+      end
+
+      it "should extract area with trailing O from full postcode with space" do
+        pc = described_class.parse("CO1 1BT")
+        pc.area.must_equal "CO"
+        pc.district.must_equal "1"
+      end
+
+      it "should extract area with trailing O from full postcode without space" do
+        pc = described_class.parse("CO11BT")
+        pc.area.must_equal "CO"
+        pc.district.must_equal "1"
+      end
+    end
+
+    describe "tricky postcodes" do
+      it "should parse B11 1LL" do
+        pc = described_class.parse("B111LL")
+        pc.area.must_equal "B"
+        pc.district.must_equal "11"
+        pc.sector.must_equal "1"
+        pc.unit.must_equal "LL"
+      end
+
+      it "should parse BII ILL" do
+        pc = described_class.parse("BIIILL")
+        pc.area.must_equal "B"
+        pc.district.must_equal "11"
+        pc.sector.must_equal "1"
+        pc.unit.must_equal "LL"
+      end
+
+      it "should parse BB11 1DJ" do
+        pc = described_class.parse("BB111DJ")
+        pc.area.must_equal "BB"
+        pc.district.must_equal "11"
+        pc.sector.must_equal "1"
+        pc.unit.must_equal "DJ"
+      end
+
+      it "should parse BBII IDJ" do
+        pc = described_class.parse("BBIIIDJ")
+        pc.area.must_equal "BB"
+        pc.district.must_equal "11"
+        pc.sector.must_equal "1"
+        pc.unit.must_equal "DJ"
+      end
+
+      it "should parse B10 0JP" do
+        pc = described_class.parse("B100JP")
+        pc.area.must_equal "B"
+        pc.district.must_equal "10"
+        pc.sector.must_equal "0"
+        pc.unit.must_equal "JP"
+      end
+
+      it "should parse BIO OJP" do
+        pc = described_class.parse("BIOOJP")
+        pc.area.must_equal "B"
+        pc.district.must_equal "10"
+        pc.sector.must_equal "0"
+        pc.unit.must_equal "JP"
+      end
+    end
+  end
+
+  describe "area" do
+    it "should be capitalised" do
+      described_class.new("w", "1a", "1", "aa").area.must_equal "W"
+    end
+
+    it "should correct 0 to O" do
+      described_class.new("0X", "1", "0", "AB").area.must_equal "OX"
+    end
+
+    it "should correct 1 to I" do
+      described_class.new("1G", "1", "1", "AA").area.must_equal "IG"
+    end
+  end
+
+  describe "district" do
+    it "should be capitalised" do
+      described_class.new("w", "1a", "1", "aa").district.must_equal "1A"
+    end
+
+    it "should correct O to 0" do
+      described_class.new("B", "2O", "2", "XB").district.must_equal "20"
+    end
+
+    it "should correct I to 1" do
+      described_class.new("B", "I", "I", "DF").district.must_equal "1"
+    end
+  end
+
+  describe "sector" do
+    it "should correct O to 0" do
+      described_class.new("AB", "1", "O", "DN").sector.must_equal "0"
+    end
+
+    it "should correct I to 1" do
+      described_class.new("W", "1A", "I", "AA").sector.must_equal "1"
+    end
+  end
+
+  describe "unit" do
+    it "should be capitalised" do
+      described_class.new("w", "1a", "1", "aa").unit.must_equal "AA"
+    end
+
+    # Note: neither I nor O appear in units
+  end
+
+  describe "outcode" do
+    it "should be generated from area and district" do
+      described_class.new("W", "1A").outcode.must_equal "W1A"
+    end
+
+    it "should be nil if missing district" do
+      described_class.new("W").outcode.must_be_nil
+    end
+  end
+
+  describe "incode" do
+    it "should be generated from sector and unit" do
+      described_class.new("W", "1A", "1", "AA").incode.must_equal "1AA"
+    end
+
+    it "should be nil if missing sector" do
+      described_class.new("W", "1A").incode.must_be_nil
+    end
+
+    it "should be nil if missing unit" do
+      described_class.new("W", "1A", "1").incode.must_be_nil
+    end
+  end
+
+  describe "to_s" do
+    it "should generate a full postcode" do
+      described_class.new("W", "1A", "1", "AA").to_s.must_equal "W1A 1AA"
+    end
+
+    it "should generate an outcode" do
+      described_class.new("W", "1A").to_s.must_equal "W1A"
+    end
+
+    it "should generate a postcode with no unit" do
+      described_class.new("W", "1A", "1").to_s.must_equal "W1A 1"
+    end
+
+    it "should generate an area alone" do
+      described_class.new("W").to_s.must_equal "W"
+    end
+  end
+
+  describe "full?" do
+    it "should be true if outcode and incode are given" do
+      described_class.new("W", "1A", "1", "AA").must_be :full?
+    end
+
+    it "should not be true if something is missing" do
+      described_class.new("W", "1A", "1").wont_be :full?
+    end
+  end
+
+  describe "valid?" do
+    it "should be true" do
+      described_class.new("W", "1A", "1", "AA").must_be :valid?
+    end
+  end
+
+  describe "country" do
+    it "should look up the country of a full postcode" do
+      described_class.new("EH", "8", "8", "DX").country.must_equal :scotland
+    end
+
+    it "should look up the country of a partial postcode" do
+      described_class.new("W", "1A").country.must_equal :england
+    end
+  end
+end

data/test/giro_postcode_test.rb

@@ -0,0 +1,100 @@
+require_relative "./test_helper"
+require "uk_postcode/giro_postcode"
+
+describe UKPostcode::GiroPostcode do
+  described_class = UKPostcode::GiroPostcode
+
+  let(:subject) { described_class.instance }
+
+  describe "parse" do
+    it "should parse the canonical form" do
+      pc = described_class.parse("GIR 0AA")
+      pc.must_be_instance_of described_class
+    end
+
+    it "should parse transcribed 0/O and 1/I" do
+      pc = described_class.parse("G1R OAA")
+      pc.must_be_instance_of described_class
+    end
+
+    it "should handle extra spaces" do
+      pc = described_class.parse("  GIR   0AA   ")
+      pc.must_be_instance_of described_class
+    end
+
+    it "should handle no spaces" do
+      pc = described_class.parse("GIR0AA")
+      pc.must_be_instance_of described_class
+    end
+
+    it "should be case-insensitive" do
+      pc = described_class.parse("gir 0aa")
+      pc.must_be_instance_of described_class
+    end
+
+    it "should return nil if unable to parse" do
+      pc = described_class.parse("Can't parse this")
+      pc.must_be_nil
+    end
+  end
+
+  describe "area" do
+    it "should be nil" do
+      subject.area.must_be_nil
+    end
+  end
+
+  describe "district" do
+    it "should be nil" do
+      subject.district.must_be_nil
+    end
+  end
+
+  describe "sector" do
+    it "should be nil" do
+      subject.sector.must_be_nil
+    end
+  end
+
+  describe "unit" do
+    it "should be nil" do
+      subject.unit.must_be_nil
+    end
+  end
+
+  describe "outcode" do
+    it "should be GIR" do
+      subject.outcode.must_equal("GIR")
+    end
+  end
+
+  describe "incode" do
+    it "should be 0AA" do
+      subject.incode.must_equal("0AA")
+    end
+  end
+
+  describe "to_s" do
+    it "should be the canonical form" do
+      subject.to_s.must_equal "GIR 0AA"
+    end
+  end
+
+  describe "full?" do
+    it "should be true" do
+      subject.must_be :full?
+    end
+  end
+
+  describe "valid?" do
+    it "should be true" do
+      subject.must_be :valid?
+    end
+  end
+
+  describe "country" do
+    it "should be England" do
+      subject.country.must_equal :england
+    end
+  end
+end

data/test/invalid_postcode_test.rb

@@ -0,0 +1,75 @@
+require_relative "./test_helper"
+require "uk_postcode/invalid_postcode"
+
+describe UKPostcode::InvalidPostcode do
+  described_class = UKPostcode::InvalidPostcode
+
+  let(:subject) { described_class.new("anything") }
+
+  describe "parse" do
+    it "should parse anything" do
+      pc = described_class.parse("Any old junk")
+      pc.must_be_instance_of described_class
+    end
+  end
+
+  describe "area" do
+    it "should be nil" do
+      subject.area.must_be_nil
+    end
+  end
+
+  describe "district" do
+    it "should be nil" do
+      subject.district.must_be_nil
+    end
+  end
+
+  describe "sector" do
+    it "should be nil" do
+      subject.sector.must_be_nil
+    end
+  end
+
+  describe "unit" do
+    it "should be nil" do
+      subject.unit.must_be_nil
+    end
+  end
+
+  describe "outcode" do
+    it "should be nil" do
+      subject.outcode.must_be_nil
+    end
+  end
+
+  describe "incode" do
+    it "should be nil" do
+      subject.incode.must_be_nil
+    end
+  end
+
+  describe "to_s" do
+    it "should return the initialisation string" do
+      subject.to_s.must_equal "anything"
+    end
+  end
+
+  describe "full?" do
+    it "should be false" do
+      subject.wont_be :full?
+    end
+  end
+
+  describe "valid?" do
+    it "should be false" do
+      subject.wont_be :valid?
+    end
+  end
+
+  describe "country" do
+    it "should be unknown" do
+      subject.country.must_equal :unknown
+    end
+  end
+end

data/test/special_postcode_test.rb

@@ -0,0 +1,50 @@
+require_relative "./test_helper"
+require "uk_postcode"
+
+describe "Special postcodes" do
+  # Special postcodes listed in http://en.wikipedia.org/wiki/UK_postcode
+  SPECIAL = %w[
+    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
+  ]
+
+  SPECIAL.each_slice(2) do |outcode, incode|
+    it "should correctly handle special postcode #{outcode} #{incode}" do
+      postcode = UKPostcode.parse(outcode + incode)
+      postcode.wont_be_nil
+      postcode.outcode.must_equal outcode
+      postcode.incode.must_equal incode
+    end
+  end
+end