uk_postcode 1.0.1 → 2.0.0.alpha

checksums.yaml

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

data/COPYING.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2010-2014 Paul Battley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The regular expressions in lookup.rb are generated from the ONS Postcode
+Directory under the terms of the Open Government Licence (OGL). The following
+source accreditation is given to fulfil the terms of this licence.
+
+http://www.ons.gov.uk/ons/guide-method/geography/products/postcode-directories/-nspp-/index.html

data/README.md

@@ -11,6 +11,7 @@ Features:
 * 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.
+* Finds the country corresponding to a postcode, where possible.
 
 ## Usage
 
@@ -18,52 +19,106 @@ Features:
 require "uk_postcode"
 ```
 
-Validate and extract sections of a full postcode:
+Parse and extract sections of a full postcode:
 
 ```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"
+pc = UKPostcode.parse("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:
 
 ```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
+pc = UKPostcode.parse("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 with `normalize` (or just `norm`):
+Postcodes are converted to a normal or canonical form:
 
 ```ruby
-UKPostcode.new("w1a1aa").normalize #=> "W1A 1AA"
+pc = UKPostcode.parse("w1a1aa")
+pc.valid?   # => true
+pc.area     # => "W"
+pc.district # => "1A"
+pc.sector   # => "1"
+pc.unit     # => "AA
+pc.to_s     # => "W1A 1AA"
 ```
 
-Fix mistakes with IO/10:
+And mistakes with I/1 and O/0 are corrected:
 
 ```ruby
-pc = UKPostcode.new("WIA OAA")
-pc.outcode #=> "W1A"
-pc.incode  #=> "0AA"
+pc = UKPostcode.parse("WIA OAA")
+pc.valid?   # => true
+pc.area     # => "W"
+pc.district # => "1A"
+pc.sector   # => "0"
+pc.unit     # => "AA
+pc.to_s     # => "W1A 0AA"
 ```
 
-## Gem?
+Find the country of a full or partial postcode (if possible: some outcodes span
+countries):
 
-```sh
-$ gem install uk_postcode
+```ruby
+UKPostcode.parse("W1A 1AA").country # => :england
+UKPostcode.parse("BT4").country # => :northern_ireland
+UKPostcode.parse("CA6").country # => :unknown
+UKPostcode.parse("CA6 5HS").country # => :scotland
+UKPostcode.parse("CA6 5HT").country # => :england
+```
+
+The country returned for a postcode is derived from the [ONS Postcode
+Directory][onspd] and might not always be correct in a border region:
+
+> Users should note that postcodes that straddle two geographic areas will be
+> assigned to the area where the mean grid reference of all the addresses
+> within the postcode falls.
+
+Invalid postcodes:
+
+```ruby
+pc = UKPostcode.parse("Not Valid")
+pc.valid?  # => false
+pc.full?   # => false
+pc.area    # => nil
+pc.to_s    # => "Not valid"
+pc.country # => :unknown
+```
+
+## For users of version 1.x
+
+The interface has changed significantly, so code that worked with version 1.x
+will not work with version 2.x without changes.
+
+Specifically:
+
+* Use `UKPostcode.parse(str)` where you previously used `UKPostcode.new(str)`.
+* `parse` will return either a `GeographicPostcode`, a `GiroPostcode`, or an
+  `InvalidPostcode`.
+* You may prefer to use `GeographicPostcode.parse` directly if you wish to
+  exclude `GIR 0AA` and invalid postcodes.
+
+## As a gem
+
+In your `Gemfile`:
+
+```ruby
+gem "uk_postcode", "~> 2.0.0.alpha"
 ```
 
 ## Testing
@@ -71,44 +126,39 @@ $ gem install uk_postcode
 To run the test suite:
 
 ```sh
-$ rake
+$ make
 ```
 
 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.
+size, but will be fetched automatically from [mySociety][mys].
 
-The format of each line in a sample file must be `OOOOIII` or `OOO III` (where
-`O` = outcode, `I` = incode), e.g.:
+If you are running an automatic build process, please find a way to cache these
+files and run the tests via Rake instead:
 
 ```
-AB1 0AA
-BT109AH
+$ rake
 ```
 
-You can obtain lists of postcodes by processing various datasets available
-from [mySociety][mys].
+## Licensing
 
-### Code-Point Open
+You may use this library according to the terms of the MIT License; see
+COPYING.txt for details.
 
-This does not include postcodes for Northern Ireland, the Channel Islands,
-or the Isle of Man.
+The regular expressions in `lookup.rb` are derived from the ONS Postcode
+Directory according to the terms of the [Open Government
+Licence][onspd-lic].
 
-```sh
-$ cut -c 2-8 Data/CSV/*.csv | \
-sort -uV > test/samples/large/code_point_open.list
-```
-
-### ONS Postcode Directory
+> Under the terms of the Open Government Licence (OGL) […] anyone wishing to
+> use or re-use ONS material, whether commercially or privately, may do so
+> freely without a specific application for a licence, subject to the
+> conditions of the OGL and the Framework. Users reproducing ONS content must
+> include a source accreditation to ONS.
 
-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.
-
-```sh
-$ cut -c 2-8 ONSPD_*.csv | grep '[A-Z]' | grep -v ^NPT | \
-sort -uV > test/samples/large/onspd.list
-```
+In order to avoid the restrictive commercial terms of the Northern Ireland
+data in the ONSPD, this is not used to generate the regular expressions.
+Fortunately, Northern Ireland postcodes are very simple: they all start with
+`BT`!
 
 [mys]: http://parlvid.mysociety.org/os/
+[onspd]: http://www.ons.gov.uk/ons/guide-method/geography/products/postcode-directories/-nspp-/index.html
+[onspd-lic]: http://www.ons.gov.uk/ons/guide-method/geography/beginner-s-guide/licences/index.html

data/lib/uk_postcode/country_finder.rb

@@ -0,0 +1,15 @@
+require 'uk_postcode/country_lookup'
+
+module UKPostcode
+  module CountryFinder
+    module_function
+
+    def country(postcode)
+      normalized = [postcode.outcode, postcode.incode].compact.join
+      COUNTRY_LOOKUP.each do |name, regexp|
+        return name if normalized.match(regexp)
+      end
+      :unknown
+    end
+  end
+end

data/lib/uk_postcode/country_lookup.rb

@@ -0,0 +1,10 @@
+module UKPostcode
+  COUNTRY_LOOKUP = {
+    england: /^(?:AL|B[123456789ABDHLNRS]|C(?:A(?:1|2|3|4|5|6(?:4|5(?:G|H[TU]|L[GHJLNPQRSTUWXYZ]|N|P|Q|R|S|T|U|W|X|Y)|6|7)|7|8|9)|B|H(?:1(?:1|2|3|4(?:A|B|D|E|F|G|H|J|L|N|P|Q[ABDFGHJNPQRSTUWX]|R|S|W|X|Y|Z)|5|6(?:A|B[DEFGHJU]|D[ABEFGHLNPQRSTUWXYZ]|E[ADEFGHJLNPQRSTUWXYZ]|F|G|H[DEFGJLNQSTUWXYZ]|J|L|N|P|Q[AP]|R|W|X|Y|Z)|9)|2(?:1|2|3|4|5|6|7|89(?:A[ABEFGHJLNPQRSTUWXYZ]|B)|99(?:A[BDEFGHJLNPQRSTUWXYZ]|B|D|E))|3(?:5|6|7|8|9|0|1|2|3|49(?:A[ABDEFGHJLNQRSTUWXYZ]|B|D|E|S|T|Z))|4(?:0(?:EJ|W[BDFGHRU]|Y[HJ]|Z[ADEFGHJLPTUWY])|7|8(?:A|B|D|E|H|J|L[BDEFLNPSUXYZ]|N[DEFGLNPQRSTUWXYZ]|P[ADEFGHJLNPQRSTUWXZ]|Q[ADU]|R[AD]|W[ABDEFGHJLPQRSTUWXYZ]|X|Y|Z|0|1|2|3|4|5|6|7|8|9)|9(?:A[DEFG]|BW|D[EFGHJLNPQRSTUW]|E[BDEFGJLNPQRSTUWXYZ]|F|G[ABJ]|H|J|L|N|P[XZ]|Q|R|T|U|W|X[SUY]|Y|Z|0|1|2|3|4|5|6|7|8|9)|1|2|3|4|5|6)|6(?:5[0123456789]|6[0123456789]|9AB|0|1|2|3|4)|708(?:A[ADEGHJLNPQRSTUWXYZ]|B|D)|883|9)|M|O|R|T|V|W)|D(?:A|E|G165(?:H[TUZ]|J[AB])|H|L|N|T|Y)|E[123456789CNX]|FY|G(?:I|L(?:1(?:1|2|3|4|5|9|0|6(?:7|8(?:A|B|D|E|H|J|L|N|P[ADEFGHJLNPQRSTUWXYZ]|Q|R|S|T|W|Y|Z)|9)|7|8)|2|3|4|5|6|7|8|9)|U)|H(?:A|D|G|P|R(?:1|2|3(?:5(?:AL|B[BDERZ]|E[NPRSTUWXYZ]|FE|H|Q[XYZ]|R[ABDFGNQW]|S[TUXY]|T[ABDEFGP]|W[NUX]|XA|Y[ADFJNQRSTWX])|6(?:A|B|D|E[ABDEFGHJLNPQRSTUWZ]|H[EFGHJPQSTUWXYZ]|J[ABDEFGHLNPQRSTZ]|L|N|P|Q|R|S|W|Y[ABDEFHJLNPQU]|Z))|4|5(?:3(?:A|B|D|E[ABDEFGHJLNQRSTUWXYZ]|F|G|H|J|L|N[ABEFGHJLNQ]|P[BFGHQTUXYZ]|QA|R[BDEFGHJLNPQRSTUWXYZ]|S|T|U|W|X|Y|Z)|8)|6|7|8|9)|U|X)|I[GP]|KT|L(?:1|2|3|4|5|6|7|8|9|A|D(?:71(?:DY|EA|N[BDEF]|T[NPRSUWY]|U[ABDEFW]|Y[SUY]|ZJ)|82(?:H[HLNPRSTUWY]|L[EGHLNPRSTUWY]|N[ABD]|P[RS]))|E|L145(?:B[UY]|D[ABDEFGLNPRSUWY]|E[ABDEFHLNW]|L[JP])|N|S|U)|M[123456789EK]|N(?:1|2|3|4|5|6|7|8|9|E|G|N|P(?:167(?:A|B|D|E|F|H|J|L|N[AFGHJLNPQRSTUW]|P|Q|R|WA|Y[BDEFGJLN]|Z[AB])|25(?:3S[RSTUX]|4(?:AS|L[DHJLNPQRTXYZ]|N[ABDE])|5(?:Q[JL]|R[DGHJLNPQRSTWY]))|5(?:3(?:Q[JL]|R[GHJLNPQRSTWY]|S[RSTUX])|4(?:L[HJLNPQRSTUWXYZ]|N[AB]))|6(?:6SG|7(?:A|B|D|E|F|H|J|L|N[AFGJLNPQRSTUW]|P|Q|R|Y|Z))|78(?:EB|HH))|R|W)|O|P[ELOR]|R|S(?:1|2|3|4|5|6|7|8|9|E|G|K|L|M|N|O|P|R|S|T|W|Y(?:1(?:1|2|3(?:A|B|D|E|F|G|H|J|L|N|P|Q|R|S|T|W|X|Y|Z|1|2(?:A|B|D|E|F|G|H|J[ABDEFGL]|L[FGT]|N|P[ADEFGHPQRSTUXYZ]|Q|R|S|T|W|X|Y|Z)|3(?:A[AB]|J[GHJLNPQRSTUWXYZ]|L|N[EFGHJLNPQRSTUWXY]|P[FG]|W[ADFGHJXYZ]|X|Y)|4(?:A|B|D|E|H|J|L|N|P|Q|R[ABDFG]|W)|9)|4(?:A|B|D|E|H|J|L|N|P|Q|R|S|T|U|W|Y|7(?:A[ABDEFGHJLPQRSTUWXY]|B|D|E|H[ABDEFGHJLNPQRSTUWXZ]|J[ABDEFJLNPRSWXY]|N[EFGHJQ]|P|U|W|Y)|8)|9[ABDEFGHJLSTUWX]|0(?:0(?:W[AHJQZ]|Z)|1|7(?:A|B|D|E|G|H|J[ABDPRSUXYZ]|L|N[ABDGHJLNPQRW]|P[BDEHJLNPQRW]|R|S|T|U|W|X|Y|Z)|8|9(?:A|B[ABDEFGHJLNQSTUXYZ]|D|E|F|H[ABDEFGHJLNPQRSTUWXY]|J[ABDEFQ]|L[SUXYZ]|N|P[BDEFGHJLNPQRSTUWXYZ]|Q|R|W|Y))|56(?:A[XY]|B[DEGHJLNPQSTUWXYZ]|D[ABDEFGPR]|E[DEP]|H[TUY]|S[PYZ]|T[RZ]|U[BDEFGHQ]|Z))|2(?:2(?:P|5WD|6(?:E[ABDEFGHJLQ]|H[BD]|JX|L[GLNQUWXYZ]|N[TW]|W[ABEHJXYZ]))|5[ABDEGHJLNPQRSTUWXYZ]|6|18(?:D[LN]|E[PRW]|J[LNPQRSTUWXY]|LB))|3|4|5(?:0(?:A|B|D|E|F|H|J[ABDEFGHPQWXYZ]|L|N|P|Q|R|S|T|U|W|X|Y|Z)|6|7|8|9(?:A[ABDEFGHJLNPQ]|B[XYZ]|D|E[ABDEFGHJLNPQRSTWXYZ]|FA|G[ABDEFGHJLQXYZ]|H|J|L[ABEFGHJLNPQRSTUWXYZ]|N|P|Q|R|SA|W|X|Y|Z))|6|7(?:0|7|8(?:A|B|D|E|H|J|L|N|P[ABDEFGHJLNPQRW]|Q|W)|9)|8|9(?:5(?:A|B|D|E|F|H|J[GHJLNQRSTUXY]|L|N|P|W)|9)))|T(?:A|D(?:1(?:24(?:Q[ABDEFGHJLNPQRSTW]|R|S|T|U|WB|X[ABDFGHJLNQ])|5(?:1(?:A|B[ABEFGHJLNPQSUWXYZ]|D|E|H|J|L|N|P|Q|R|S[ABDEJLNPWXY]|T[ABQUX]|U[ABDENPQRTUXY]|W[FX]|X[XY]|Y|Z)|2|9))|90T[JPRSTW])|F|N|Q|R|S|W)|U|W|Y)/,
+    scotland: /^(?:AB|CA65(?:A|B|D|E|H[ABDEFGHJLNPQRSWXYZ]|J|L[ABDE])|D(?:D|G(?:1(?:1|2|3|4|9|0|65(?:A|B|D|E|F|G|H[ABDEFGHJLNPQRSWXY]|J[DEFGHJLNPQRSTUWXYZ]|L|N|Q|U|W|X|Y))|2|3|4|5|6|7|8|9))|EH|FK|G[123459678]|HS|IV|K[AWY]|ML|P[AH]|TD(?:1(?:1|2(?:A|B|D|E|H|J|L|N|P|Q|R|S|T|U|W|Y|4(?:A|B|D|E|F|H|J|L|N|QU|W[ADX]|XE|Y)|9)|3|9|0|4|51(?:BT|S[UZ]|T[DEFGHJLNPRSTW]|U[FGHJLSWZ]|W[YZ]|X[ABGHJLNQTUWZ]))|2|3|4|5|6|7|8|9(?:0(?:A|B|D|E|H|J|L|N|P|Q|R|S|T[ABDEFGHLNQUXY]|W|Y|Z)|1|7|8|9))|Z)/,
+    wales: /^(?:C(?:F|H(?:1(?:4QL|6(?:B[ABLPQRSTWXYZ]|D[DJ]|EB|H[ABH]|Q[BEFGQ]))|2(?:89AD|99AA)|349AP|4(?:0(?:A|B|D|E[ABDEFGHLNPQRSTUWXYZ]|F|G|H|J|L|N|P|Q|R|S|T|W[AE]|X|Y[PRSTUXY]|Z[BNQRS])|8(?:G|L[AGHJQRTW]|N[ABH]|P[BY]|Q[BEFGHJLNPQRSTWYZ]|R[BEFGHJLNPQRSTUWXYZ]|S|T|U|WN)|9(?:A[ABHJLNPQRSTUWXYZ]|B[ABDEFGHJLNPQRSTUXYZ]|D[ABDXYZ]|E[AH]|GD|P[ABDFG]|XA))|5|6(?:5[ABDEFGHJLNPQRSTUWXYZ]|6[ABDEFHJLZ]|9(?:A[DEFGJLNPQRSTUWXYZ]|B|D))|7(?:1|2|3|4|5|6|9|08A[BF])|8(?:7|8[ABDEHJLNPQRSTWYZ]|9)))|GL168PB|HR(?:3(?:5(?:A[ABDEFGHJNPQRSTUWXYZ]|B[AGHJLNPQSTUWXY]|D|E[ABDEFGHJLQ]|F[AD]|J|L|N|P|Q[ABDEFGHJLNPQRSTUW]|R[EHJLPRSTUXYZ]|S[ABDEFGHJLNPQRSWZ]|T[HRSTUX]|W[ALPQRSTWYZ]|XZ|Y[BEGHLPU]|Z)|6(?:E[XY]|H[ALN]|J[JUWXY]|YG))|53(?:EP|N[DPRSTUWXYZ]|P[ADEJLNPRW]|Q[BDEFGHJLNPQRSTUWXZ]|RA))|L(?:D(?:1|2|3|4|5|6|7(?:1(?:A|B|D[ABDEFGHJLNPQRSTUW]|E[BDEFGHNPRSTUWY]|H|L|N[AGHJLNPQRSTUWY]|P|R|S|T[ABDET]|U[GHPRTUY]|W|Y[ABDEFGHLNPRTW]|ZY)|9)|82(?:A|B|D|E|G|H[ABDEFG]|L[ABDF]|N[EFGHJLNPQRSTUWXY]|P[ABDEFGHLNPTUWY]|R|S|T|U|W|Y|Z))|L(?:1(?:1|2|3|4(?:1|2|3|4|5(?:A|B[ABDEFGHJLNPQSTWXZ]|D[HJ]|E[PQRSTUYZ]|H|L[ABDEFGHLNQRSTUWY]|N|P|Q|R|S|W|Y|Z)|6)|5|6|7|8|9)|2|3|4|5|6|7))|NP(?:1(?:0|2|4|5|6(?:A|B|D|E|F|G|H|J|L|N|P|Q|R|X|Y|Z|5|6|7(?:NX|W[EJLNPQRSTUWXYZ]|Y[AHPQRSTUWY]|Z[SX])|9)|7|8|9|1|3)|2(?:0|1|2|3|4|5(?:A|B|D|E|H|J|L|N|P|Q|R|X|Y|3(?:A|B|D|E|G|H|J|L|N|P|Q|S[ABDEFGHJLNPQWYZ]|T|U|W|X|Y|Z)|4(?:A[BDEFGHJLNPQRTW]|B|D|E|H|J|L[EGUW]|N[YZ]|P|Q|R|S|T|U|W|X|Y|Z)|5(?:A|B|D|E|F|G|H|J|L|N|P|Q[ABDEFGHQXYZ]|R[ABEFZ]|S|T|U|W|X|Y|Z)|9)|6)|3|4|5(?:1|2|3(?:A|B|D|E|G|H|J|L|N|P|Q[ABDEFGHQXYZ]|R[ABDEFZ]|S[ABDEFGHJLNPQWZ]|T|U|X|Y|Z)|4(?:A|B|D|E|F|H|J|L[ABDEFG]|N[FGHJLNPQRSTUWXYZ]|P|Q|R|S|T|U|X|Y))|6(?:1|2|3|4|5|6(?:A|B|D|E|H|J|L|N|P|Q|R|S[ABDEFHJLNPQRSTUWXYZ]|T|U|X|Y)|7N[HX])|7(?:0|1|5|6|7|8(?:A|B|D|E[ADEFGHLNPQRSTWXY]|H[ABDEFGLNPRSTUWY]|L|N|P|R|S|T|U|W|Y|Z)|9)|8|9)|S(?:A|Y(?:1(?:3(?:2(?:J[HJNPQRSTUWXYZ]|L[ABDEHJLNPQRSUWX]|PB)|3(?:A[DEFGHJLNPQRSTUWXYZ]|B|D|E|G|H|J[AB]|NZ|P[ABDE]|W[BE])|4RE)|47(?:A[NZ]|HY|J[HTUZ]|L|N[ABD])|97|0(?:0(?:A|B|D|E|G|H|J|L|N|P|W[BDEFG])|7(?:J[EFGHJLNQW]|N[EFSTUXYZ]|P[AGSTUXYZ]|Q)|9(?:B[PW]|HZ|J[GHJLNPRSTUWXYZ]|L[ABDEFGHJLNPQRTW]|PA))|56(?:A[ABDEFGHJLNPQRSTUWZ]|B[AB]|D[HJLNQSTUWXYZ]|E[ABFGHJLNQRSTUWXYZ]|H[ABDEFGHJLNPQRSWXZ]|J|L|N|P|Q|R|S[ABDEFGHQRSTUX]|T[ABDEFGHJLNPQWY]|U[AJLNPR]|W|Y)|6|7|8)|2(?:2(?:5(?:A|B|D|E|H|J|L|N|W[ABPZ])|6(?:A|B|D|E[NPRSTUWXYZ]|F|G|H[AEFLNPRSTUWXYZ]|J[ABDEFGHJLNPQRSTWYZ]|L[ABDEFHJPRST]|N[ABDEFGHJLNPQRSXYZ]|P|Q|R|S|T|U|W[DFG]|X|Y))|56|0|1(?:0|1|7|8(?:A|B|D[ABDEFGHJPQRSTUWXYZ]|E[ABDEFGHJLNQSTUXYZ]|F|G|H|J[ABDEFGHJZ]|L[ADEFGHJLNPQRSTUWXYZ]|N|P|Q|R|S|T|W|X|Z)|9)|3|4)|5(?:0J[JLN]|9(?:A[RSTUWXYZ]|B[ABDEFGHJLNPQSTUW]|EU|FB|GN|LD|SB))|78PS|95J[PW])))/,
+    channel_islands: /^(?:GY|J)/,
+    isle_of_man: /^IM/,
+    northern_ireland: /^BT/
+  }
+end

data/lib/uk_postcode/geographic_postcode.rb

@@ -0,0 +1,98 @@
+require "uk_postcode/country_finder"
+
+module UKPostcode
+
+  # GeographicPostcode models the majority of postcodes, containing an area,
+  # a district, a sector, and a unit.
+  #
+  # Despite the name, it also handles non-geographic postcodes that follow the
+  # geographic format.
+  #
+  class GeographicPostcode
+    PATTERN = %r{
+      \A ( [A-PR-UWYZ01][A-HJ-Z0]? )        # area
+      (?: ( [0-9IO][0-9A-HJKMNPR-YIO]? ) # district
+        (?: \s* ( [0-9IO] )              # sector
+          ( [ABD-HJLNPQ-Z]{2} )? )? )?   # unit
+      \Z
+    }ix
+
+    # Attempts to parse the postcode given in str, and returns an instance of
+    # GeographicPostcode on success, or nil on failure.
+    #
+    def self.parse(str)
+      matched = PATTERN.match(str.strip)
+      if matched
+        new(*(1..4).map { |i| matched[i] })
+      else
+        nil
+      end
+    end
+
+    # Initialise a new GeographicPostcode instance with the given area,
+    # district, sector, and unit. Only area is required.
+    #
+    def initialize(area, district = nil, sector = nil, unit = nil)
+      @area = letters(area)
+      @district = digits(district)
+      @sector = digits(sector)
+      @unit = letters(unit)
+    end
+
+    attr_reader :area, :district, :sector, :unit
+
+    # The left-hand part of the postcode, e.g. W1A 1AA -> W1A
+    #
+    def outcode
+      return nil unless district
+      [area, district].join('')
+    end
+
+    # The right-hand part of the postcode, e.g. W1A 1AA -> 1AA
+    #
+    def incode
+      return nil unless sector && unit
+      [sector, unit].join('')
+    end
+
+    # Returns the canonical string representation of the postcode.
+    #
+    def to_s
+      [area, district, " ", sector, unit].compact.join('').strip
+    end
+
+    # Returns true if the postcode is a valid full postcode (e.g. W1A 1AA)
+    #
+    def full?
+      area && district && sector && unit && true
+    end
+
+    # Any geographic postcode is assumed to be valid
+    #
+    def valid?
+      true
+    end
+
+    # Find the country associated with the postcode. Possible values are
+    # :england, :scotland, :wales, :northern_ireland, :isle_of_man, 
+    # :channel_islands, or :unknown.
+    #
+    # Note that, due to limitations in the underlying data, the country might
+    # not always be correct in border regions.
+    #
+    def country
+      CountryFinder.country(self)
+    end
+
+  private
+    def letters(str)
+      return nil unless str
+      str.upcase.tr("10", "IO")
+    end
+
+    def digits(str)
+      return nil unless str
+      str.upcase.tr("IO", "10")
+    end
+  end
+end

data/lib/uk_postcode/giro_postcode.rb

@@ -0,0 +1,61 @@
+require "singleton"
+
+module UKPostcode
+
+  # GiroPostcode models the single, peculiar GIR 0AA postcode originally used
+  # by Girobank.
+  #
+  # area, district, sector, and unit all return nil, because this postcode
+  # does not meaningfully possess these distinctions.
+  #
+  class GiroPostcode
+    include Singleton
+
+    PATTERN = /\A G[I1]R \s* [0O]AA \z/ix
+
+    # Returns an instance of GiroPostcode if str represents GIR 0AA, and nil
+    # otherwise.
+    #
+    def self.parse(str)
+      PATTERN.match(str.strip) ? instance : nil
+    end
+
+    attr_reader :area, :district, :sector, :unit
+
+    # The left-hand part of the postcode, always "GIR".
+    #
+    def outcode
+      "GIR"
+    end
+
+    # The right-hand part of the postcode, always "0AA".
+    #
+    def incode
+      "0AA"
+    end
+
+    # The canonical string representation of the postcode, i.e.  "GIR 0AA".
+    #
+    def to_s
+      "GIR 0AA"
+    end
+
+    # GIR 0AA is always valid.
+    #
+    def valid?
+      true
+    end
+
+    # GIR 0AA is always full.
+    #
+    def full?
+      true
+    end
+
+    # GIR 0AA is in England. (In Bootle, in fact.)
+    #
+    def country
+      :england
+    end
+  end
+end

data/lib/uk_postcode/invalid_postcode.rb

@@ -0,0 +1,38 @@
+module UKPostcode
+
+  # InvalidPostcode is a singleton null object returned by UKPostcode.parse
+  # when it is unable to parse the supplied postcode.
+  #
+  # The sub-fields of the postcode (outcode, area, etc.) are all nil.
+  #
+  class InvalidPostcode
+    def self.parse(str)
+      new(str)
+    end
+
+    def initialize(input)
+      @input = input
+    end
+
+    attr_reader :area, :district, :sector, :unit, :incode, :outcode
+
+    # Returns the literal string supplied at initialisation. This may be
+    # helpful when returning erroneous input to the user.
+    #
+    def to_s
+      @input
+    end
+
+    def full?
+      false
+    end
+
+    def valid?
+      false
+    end
+
+    def country
+      :unknown
+    end
+  end
+end

data/lib/uk_postcode/tree.rb

@@ -0,0 +1,75 @@
+module UKPostcode
+  class Tree
+    def initialize(tree = {})
+      @root = tree
+    end
+
+    def insert(path, value)
+      path[0..-2].inject(@root) { |n, p| n[p] ||= {} }[path.last] = value
+    end
+
+    def compress
+      self.class.new(compress_node(@root))
+    end
+
+    def filter(leaf_value)
+      self.class.new(filter_node(@root, leaf_value))
+    end
+
+    def regexp
+      Regexp.new('^' + node_regexp(@root))
+    end
+
+    def to_h
+      @root
+    end
+
+  private
+
+    def leaf?(node)
+      node.is_a?(Symbol)
+    end
+
+    def contains_identical_leaves?(node)
+      node.values.all? { |t| leaf?(t) } && node.values.uniq.length == 1
+    end
+
+    def compress_node(node)
+      if leaf?(node)
+        node
+      else
+        comp = Hash[node.map { |k, v| [k, compress_node(v)] }]
+        contains_identical_leaves?(comp) ? comp.values.first : comp
+      end
+    end
+
+    def filter_node(node, leaf_value)
+      if node == leaf_value
+        node
+      elsif leaf?(node)
+        nil
+      else
+        h = Hash[node.map { |k, v| [k, filter_node(v, leaf_value)] }.
+                 select { |_, v| v }]
+        h.empty? ? nil : h
+      end
+    end
+
+    def node_regexp(node)
+      if leaf?(node)
+        ''
+      else
+        segments = node.map { |k, v| k + node_regexp(v) }
+        if segments.length > 1
+          if segments.all? { |s| s.length == 1 }
+            '[' + segments.join('') + ']'
+          else
+            '(?:' + segments.join('|') + ')'
+          end
+        else
+          segments.first
+        end
+      end
+    end
+  end
+end

data/lib/uk_postcode/version.rb

@@ -1,3 +1,3 @@
-class UKPostcode
-  VERSION = "1.0.1"
+module UKPostcode
+  VERSION = "2.0.0.alpha"
 end