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

This simple form will give a list of postcodes matching the specified method and string. Substitute 'XX' by a valid country subclass. The methods can be anyone given by the Geo::Postcodes::XX::get_methods() call. The resulting list of postcodes is sorted.

It is possible to specify more than one method/string pair, but then the mode must be given. Use as many metod/value-pairs as required. (The mode can be specified for the one pair version of 'or|and' as well, but will have no effect.)

and

The postcode is included in the result if it is included in all the expressions.

my @postcodes = Geo::Postcodes::XX::selection('and',
   $method => $string, $method2 => $string2, ...);

Return postcodes matching all the method/string pairs.

The computation will work faster if the method/string pairs are given with the one with the most matches first, and the one with the least matches last. given first

or

The postcode is included in the result if it is included in at least one of the expressions.

my @postcodes4 = Geo::Postcodes::XX::selection('or',
   $method => $string, $method2 => $string2);

Return postcodes matching one or more of the method/string pairs.

The computation will work faster if the method/string pairs are given with the one with the least matches first, and the one with the most matches last. given first

not

The postcode is included in the result if it is included in none of the expressions.

my @postcodes4 = Geo::Postcodes::XX::selection('not',
   $method => $string, $method2 => $string2);

Return the postcodes not matching any of the method/string pairs. (This is the same as all - or, on sets of postcodes.)

all

All the postcodes.

my @postcodes4 = Geo::Postcodes::XX::selection('all');

This will simply return all the postcodes. Any additional arguments are silentliy ignored.

This is the same as sort(get_postcodes()). The object oriented version (see below for syntax) will return a postcode object for each postcode, and can be handy in some circumstances - if time and memory usage is of no concern. Otherwise create the postcode objects only when needed, inside a foreach-loop.

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

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".

Selection or and Selection not is not written efficiently, as the regular expressions are recompiled for every postcode. This will be fixed in the future.

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. The child classes that can be found there have some sample programs.

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