uk_postcode 0.0.1

data/README.md

@@ -0,0 +1,34 @@
+uk_postcode
+===========
+
+UK postcode parsing and validation for Ruby.
+
+Usage
+-----
+
+    require "uk_postcode"
+
+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"
+
+Or of a partial postcode:
+
+    pc = UKPostcode.new("W1A")
+    pc.valid?  #=> true
+    pc.full?   #=> false
+    pc.outcode #=> "W1A"
+    pc.incode  #=> nil
+
+Normalise postcodes:
+
+    UKPostcode.new("w1a1aa").to_str #=> "W1A 1AA"
+
+Gem?
+----
+
+    gem install uk_postcode

data/Rakefile

@@ -0,0 +1,44 @@
+require "rubygems"
+require "rake/gempackagetask"
+require "rake/testtask"
+
+task :default => [:test]
+
+Rake::TestTask.new("test") do |t|
+  t.libs   << "test"
+  t.pattern = "test/**/test_*.rb"
+  t.verbose = true
+end
+
+task :default => :test
+
+require "rake/testtask"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+spec = Gem::Specification.new do |s|
+  s.name              = "uk_postcode"
+  s.version           = "0.0.1"
+  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.executables       = FileList["bin/**"].map { |f| File.basename(f) }
+
+  s.require_paths     = ["lib"]
+
+  s.add_development_dependency("thoughtbot-shoulda")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc 'Clear out generated packages'
+task :clean => [:clobber_package]

data/lib/uk_postcode.rb

@@ -0,0 +1,46 @@
+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/
+
+  attr_reader :raw
+
+  # Initialise a new UKPostcode instance from the given postcode string
+  #
+  def initialize(postcode_as_string)
+    @raw = postcode_as_string.upcase
+  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)
+  end
+
+  # Returns true if the postcode is a valid full postcode (e.g. W1A 1AA)
+  #
+  def full?
+    raw.match(RE_FULL)
+  end
+
+  # The left-hand part of the postcode, e.g. W1A 1AA -> W1A
+  #
+  def outcode
+    raw[RE_FULL, 1] || raw[RE_OUTCODE_ONLY]
+  end
+
+  # The right-hand part of the postcode, e.g. W1A 1AA -> 1AA
+  #
+  def incode
+    raw[RE_FULL, 2]
+  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
+    [outcode, incode].compact.join(" ")
+  end
+  alias_method :to_s, :to_str
+end

data/test/test_uk_postcode.rb

@@ -0,0 +1,174 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require "test/unit"
+require "shoulda"
+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
+
+    should "all be valid" do
+      @samples.each do |sample|
+        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+      end
+    end
+
+    should "all be full" do
+      @samples.each do |sample|
+        assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+      end
+    end
+
+    should "extract outcodes" do
+      @samples.zip(VALID_OUTCODES).each do |sample, outcode|
+        assert_equal outcode, UKPostcode.new(sample).outcode
+      end
+    end
+
+    should "extract incodes" do
+      @samples.zip(VALID_INCODES).each do |sample, incode|
+        assert_equal incode, UKPostcode.new(sample).incode
+      end
+    end
+  end
+
+  context "full samples without spaces" do
+    setup do
+      @samples  = VALID_SAMPLES.map{ |s| s.sub(/\s/, "") }
+    end
+
+    should "all be valid" do
+      @samples.each do |sample|
+        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+      end
+    end
+
+    should "all be full" do
+      @samples.each do |sample|
+        assert UKPostcode.new(sample).full?, "'#{sample}' should be full"
+      end
+    end
+
+    should "extract outcodes" do
+      @samples.zip(VALID_OUTCODES).each do |sample, outcode|
+        assert_equal outcode, UKPostcode.new(sample).outcode
+      end
+    end
+
+    should "extract incodes" do
+      @samples.zip(VALID_INCODES).each do |sample, incode|
+        assert_equal incode, UKPostcode.new(sample).incode
+      end
+    end
+  end
+
+  context "outcode samples" do
+    setup do
+      @samples = VALID_OUTCODES
+    end
+
+    should "all be valid" do
+      @samples.each do |sample|
+        assert UKPostcode.new(sample).valid?, "'#{sample}' should be valid"
+      end
+    end
+
+    should "not be full" do
+      @samples.each do |sample|
+        assert !UKPostcode.new(sample).full?, "'#{sample}' should not be full"
+      end
+    end
+
+    should "keep outcode unchanged" do
+      @samples.each do |sample|
+        assert_equal sample, UKPostcode.new(sample).outcode
+      end
+    end
+
+    should "have nil incode" do
+      @samples.each do |sample|
+        assert_nil UKPostcode.new(sample).incode
+      end
+    end
+  end
+
+  context "when the postcode is supplied in lower case" do
+    setup do
+      @postcode = UKPostcode.new("w1a 1aa")
+    end
+
+    should "extract outcode in upper case" do
+      assert_equal "W1A", @postcode.outcode
+    end
+
+    should "extract incode in upper case" do
+      assert_equal "1AA", @postcode.incode
+    end
+
+    should "be valid" do
+      assert @postcode.valid?
+    end
+  end
+
+  { "when the postcode is blank" => "",
+    "when the incode is truncated" => "W1A 1A",
+    "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
+
+      should "not be valid" do
+        assert !@postcode.valid?
+      end
+
+      should "not be full" do
+        assert !@postcode.full?
+      end
+
+      should "return an empty string for to_str" do
+        assert_equal "", @postcode.to_str
+      end
+
+      should "return nil for outcode" do
+        assert_nil @postcode.outcode
+      end
+
+      should "return nil for incode" do
+        assert_nil @postcode.incode
+      end
+    end
+  end
+
+  context "when used as a string" do
+    should "normalise spacing" do
+      assert_equal "W1A 1AA", UKPostcode.new("W1A1AA").to_str
+    end
+
+    should "convert case" do
+      assert_equal "W1A 1AA", UKPostcode.new("w1a 1aa").to_str
+    end
+
+    should "ignore a missing incode" do
+      assert_equal "W1A", UKPostcode.new("W1A").to_str
+    end
+  end
+
+  should "have same output for to_s and to_str" do
+    ["W1A1AA", "w1a 1aa", "W1A"].each do |s|
+      postcode = UKPostcode.new(s)
+      assert_equal s.to_str, s.to_s
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: uk_postcode
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Paul Battley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-06 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: pbattley@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- README.md
+- test/test_uk_postcode.rb
+- lib/uk_postcode.rb
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: UK postcode parsing and validation
+test_files: []
+