NAME

Geo::Postcodes - Base class for the Geo::Postcodes::XX modules

SYNOPSIS

This is the base class for the Geo::Postcodes::XX modules.

Note that information on how to make a country specific subclass will not be written until the API is finalised.

ABSTRACT

Geo::Postcodes - Base class for the Geo::Postcodes::XX modules. It is useless on its own.

COMMON FEATURES

The child classes inherit the following methods and procedures (through some black magic):

selection procedure

my @postcodes = Geo::Postcodes::XX::selection($method => $string);

Use this to get a list of all the postcodes associated with the specified method and string, where 'XX' is substituted by a country subclass 'XX'. The methods can be anyone given by the Geo::Postcodes::XX::methods() call.

The search string is parsed as the regular expression m{^$string$}i. This has the following implications:

m{...}i

The trailing i means that the search is done case insensitive. This does not work for the special norwegian and danish characters 'Æ', 'Ø' and 'Å' unless a use locale is used in the program, and the current locale supports these characters. (This does not work when the code is running with mod_perl on my web servers, until I find a solution.)

'As' will match 'AS', 'As', 'aS', and 'as'.

m{^...$}

The first (^; caret) and last ($; dollar sign) character inside the expression force a matcth to the whole expression.

'AS' will match exactly the four variations mentioned above, and nothing else (so that 'CHAS' or 'ASIMOV' will not match).

Use "Wildcards" or "Regular expressions" to match several characters at once.

Wildcards

The character % (the percent character) will match zero or more arbitrary characters (and is borrowed from standard SQL).

'%12' will match '1112' but not '1201'. 'O%D' will match all strings starting with an 'O' and ending with a 'D'. '%A%' will match all strings with an 'A' somewhere.

(The character % is changed to the regular expression '.*' (dot star) by the module.)

Regular expressions

.

The character . (a single dot) will match exactly one character.

'..11' will match a four character string, where the first two can be anything, followed by '11'.

?

The character ? (a question mark) will match the previous character zero or one time.

'%ØYA?' will match strings ending with 'ØY' or 'ØYA'.

*

The character * (a star) will match the previous character zero or more times.

[]

The expression '[AB]' will match one of 'A' or'B'.

%'[AB]' will match all names ending with an 'A' or 'B'.

selection method

my @postcodobjects = Geo::Postcodes::XX->selection($method => $string);

This works just as the procedure version (see above), but will return a list of postcode objects (instead of just the postcodes).

type2verbose procedure

my $type_as_english_text  = $Geo::Postcodes::type2verbose($type);
my $type_as_national_text = $Geo::Postcodes::XX:type2verbose($type);

The child classes are responsible for translating the relevant types.

See the "TYPE" section for a description of the types.

TYPE

This class defines the following types for the postal locations:

BX

Post Office box

ST

Street address

SX

Service box (as a Post Office box, but the mail is delivered to the customer).

IO

Individual owner (a company with its own postcode).

STBX

Either a Street address (ST) or a Post Office box (BX)

MU

Multiple usage (a mix of the other types)

PP

Porto Paye receiver (mail where the reicever will pay the postage).

PN

Place name

DESCRIPTION

CAVEAT

This module uses "inside out objects".

SEE ALSO

The latest version of this library should always be available on CPAN, but see also the library home page; http://bbop.org/perl/GeoPostcodes for additional information and sample usage.

AUTHOR

Arne Sommer, <perl@bbop.org>

COPYRIGHT AND LICENSE

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

cpanm Geo::Postcodes

perl -MCPAN -e shell
install Geo::Postcodes