/ 
Geo-UK-Postcode-Regex-0.006
River stage one • 2 direct dependents • 2 total dependents
/ Geo::UK::Postcode::Regex

NAME

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

VERSION

version 0.006

SYNOPSIS

use Geo::UK::Postcode::Regex;

## REGULAR EXPRESSIONS

my $lax_re    = Geo::UK::Postcode::Regex->regex;
my $strict_re = Geo::UK::Postcode::Regex->regex_strict;
my $valid_re  = Geo::UK::Postcode::Regex->valid_regex;

if ( $foo =~ $lax_re ) {
    my ( $area, $district, $sector, $unit ) = ( $1, $2, $3, $4 );
    my $subdistrict = $district =~ s/([A-Z])$// ? $1 : undef;
    ...
}

if ( $foo =~ $strict_re ) {
    my ( $area, $district, $sector, $unit ) = ( $1, $2, $3, $4 );
    my $subdistrict = $district =~ s/([A-Z])$// ? $1 : undef;
    ...
}

if ( $foo =~ $valid_re ) {
    my ( $outcode, $sector, $unit ) = ( $1, $2, $3 );
    ...
}


## VALIDATION METHODS
use Geo::UK::Postcode::Regex qw/ is_valid_pc is_strict_pc is_lax_pc /;

if (is_valid_pc("GE0 1UK")) {
    ...
}
if (is_strict_pc("GE0 1UK")) {
    ...
}
if (is_lax_pc("GE0 1UK")) {
    ...
}


## PARSING
my $parsed = Geo::UK::Postcode::Regex->parse("WC1H 9EB");

# returns:
# {   area             => 'WC',
#     district         => '1',
#     subdistrict      => 'H',
#     sector           => '9',
#     unit             => 'EB',
#     outcode          => 'WC1H',
#     incode           => '9EB',
#     valid_outcode    => 1 | 0,
#     strict           => 1 | 0,
#     partial          => 1 | 0,
#     non_geographical => 1 | 0,
#     bfpo             => 1 | 0,
# }

# 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'

my $outcode = Geo::UK::Postcode::Regex->outcode( $postcode, { valid => 1 } )
    or die "Invalid postcode";


## POSTTOWNS
my @posttowns = Geo::UK::Postcode::Regex->outcode_to_posttowns($outcode);


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

DESCRIPTION

Parsing UK postcodes with regular expressions. This package has been separated from Geo::UK::Postcode so it can be installed and used without 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

NOTES AND LIMITATIONS

When parsing a partial postcode, whitespace may be required to separate the outcode from the sector.

For example the sector 'B1 1' cannot be distinguished from the district 'B11' without whitespace.

METHODS

strict_regex, regex, valid_regex

Return regular expressions to parse postcodes and capture the constituent parts: area, district, sector and unit (or outcode, sector and unit in the case of valid_regex).

strict_regex checks that the postcode only contains valid characters according to the postcode specifications.

valid_regex checks that the outcode currently exists.

strict_regex_partial, regex_partial, valid_regex_partial

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

is_valid_pc, is_strict_pc, is_lax_pc

if (is_valid_pc( "AB1 2CD" ) ) { ... }

Alternative way to access the regexes.

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);

SEE ALSO

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/mjemmeson/geo-uk-postcode-regex/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/mjemmeson/geo-uk-postcode-regex

git clone git://github.com/mjemmeson/geo-uk-postcode-regex.git

AUTHOR

Michael Jemmeson <mjemmeson@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Michael Jemmeson.

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