NAME

Geo::UK::Postcode::Regex - regular expressions for handling British postcodes

VERSION

version 0.002

SYNOPSIS

  use Geo::UK::Postcode::Regex;
  
  ## REGULAR EXPRESSIONS
  
  my $strict_re = Geo::UK::Postcode::Regex->regex_strict;
  my $loose_re  = Geo::UK::Postcode::Regex->regex;
  
  ## PARSING
  my $parsed = Geo::UK::Postcode::Regex->parse( "WC1H 9EB" );
  # returns:
  #   { area        => 'WC',
  #     district    => '1',
  #     subdistrict => 'H',
  #     sector      => '9',
  #     unit        => 'EB',
  #   }
  
  # strict parsing (only valid characters):
  ...->parse( $pc, { strict => 1 } )
  
  # valid outcodes only
  ...->parse( $pc, { valid => 1 } )
  
  # match partial postcodes, e.g. 'WC1H', 'WC1H 9'
  ...->parse( $pc, { partial => 1 } )  

  ## EXTRACT OUTCODE
  my $outcode = Geo::UK::Postcode::Regex->outcode( "AB101AA" );
  # returns:
  #   'AB10'
  
  ## POSTTOWNS
  my (@posttowns) = Geo::UK::Postcode::Regex->posttowns( $pc );

DESCRIPTION

Parsing UK postcodes with regular expressions. This package can be used separately to avoid the overhead of loading any dependencies.

Can handle partial postcodes (just the outcode or sector) and can test against valid characters and currently valid outcodes.

Also can determine the posttown(s) from a postcode.

Districts and post town information taken from: https://en.wikipedia.org/wiki/Postcode_districts

METHODS

strict_regex, regex

Return regular expressions to parse postcodes and capture the constituent parts (area, district, sector and unit).

The strict regex checks that for valid characters according to the postcode specifications.

strict_regex_partial, regex_partial

As above, but matches on partial postcodes of just the outcode or sector

parse

    my $parsed = Geo::UK::Postcode::Regex->parse( $pc, \%opts );

Returns hashref of the constituent parts.

Options:

strict

Returns false if string contains invalid characters (e.g. a Q as first letter)

valid

Returns false if string is not a currently existing outcode.

partial

Allows partial postcodes to be matched. In practice this means either an outcode ( area and district ) or an outcode together with the sector .

outcode

    my $outcode = Geo::UK::Postcode::Regex->outcode( $pc, \%opts );

Extract the outcode (area and district) from a postcode string. Will work on full or partial postcodes.

Second argument is a hashref of options - see parse()

outcode_to_posttowns

    my ( $posttown1, $posttown2, ... )
        = Geo::UK::Postcode::Regex->outcode_to_posttowns($outcode);

Returns posttown(s) for supplied outcode.

Note - most outcodes will only have one posttown, but some are shared between two posttowns.

posttown_to_outcodes

    my @outcodes = Geo::UK::Postcode::Regex->posttown_to_outcodes($posttown);

Returns the outcodes covered by a posttown. Note some outcodes are shared between posttowns.

outcodes_lookup

    my %outcodes = %{ Geo::UK::Postcodes::Regex->outcodes_lookup };
    print "valid outcode" if $outcodes{$outcode};
    my @posttowns = @{ $outcodes{$outcode} };

Hashref of outcodes to posttown(s);

posttowns_lookup

    my %posttowns = %{ Geo::UK::Postcodes::Regex->posttowns_lookup };
    print "valid posttown" if $posttowns{$posttown};
    my @outcodes = @{ $[posttowns{$posttown} };

Hashref of posttown to outcode(s);

AUTHOR

Michael Jemmeson <mjemmeson@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Michael Jemmeson <mjemmeson@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Geo::UK::Postcode

perl -MCPAN -e shell
install Geo::UK::Postcode