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, and the string either a literal text or a regular expression. The resulting list of postcodes is sorted.

It is possible to specify more than one method/string pair, but then the mode should be given (but it will default to 'and' otherwise). Use as many method/value-pairs as required. The mode can be specified initially, between the method/string pairs, or not at all.

The following examples are equivalent:

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

The method/string pairs are evaluated in the specified order, and the modes can be mixed freely:

 Geo::Postcodes::XX::selection($method1 => $string1,
                     'and',    $method2 => $string2,
                     'or',     $method3 => $string3,
                     'or not', $method3 => $string3,
                     'and not, $method4 => $string4,
                     'xor',    $method5 => $string5);

all

All the postcodes. This mode is only legal as the first argument, and any additional arguments are silentliy ignored.

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

This will return all the postcodes.

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 on the procedure version - or use selection_loop.

and

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

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'and', $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

and not

The postcode is included in the result if it is included in the first expression, but not the second one.

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'and not', $method2 => $string2);

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

nor

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

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'nor', $method2 => $string2);

nor not

The postcode is included in the result if it is included in the second expression only.

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'nor not', $method2 => $string2);

none

This will return absolutely nothing.

This mode is only legal as the first argument, and any additional arguments are silentliy ignored.

 my @postcodes = Geo::Postcodes::XX::selection('none');

This will return undef.

not

This mode can be used initially (as the first argument) to negate the first method/string pair. It is also possible to use 'and not' or any other 'xxx not'-mode initially.

Note that 'not' is not a valid mode, and it will default to 'and' for any additional method/string pairs if no mode is given.

The following examples are equivalent:

 Geo::Postcodes::XX::selection('not', $method => $string, 'and', $method2 => $string2);
 Geo::Postcodes::XX::selection('not', $method => $string, $method2 => $string2);
 Geo::Postcodes::XX::selection('or not', $method => $string, 'and', $method2 => $string2);
 Geo::Postcodes::XX::selection('and not', $method => $string, 'and', $method2 => $string2);

The following examples are equivalent:

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

one

This mode can be used initially to limit the returned list of postcodes to just one (or zero). The returned postcode is chosen randomly from the result list.

 Geo::Postcodes::XX::selection('one', $method => $string);

It can also be used on its own, just to get a random postcode.

 Geo::Postcodes::XX::selection('one');

or

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

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'or', $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

or not

The postcode is included in the result if it is included in the first expression, but not the second.

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'or not', $method2 => $string2);

It is also possible to achieved this by using 'or' and a reversed regular expression.

xor (exlusive or)

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

 my @postcodes = Geo::Postcodes::XX::selection(
    $method1 => $string1, 'xor', $method2 => $string2);

xor not

The postcode is included in the result if it is included in the first but not the second the expressions.

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 'Å' (as used in the subclasses 'NO' and 'DK') unless a use locale is used in the program, and the current locale supports these characters. (This will probably not work when the code is running with mod_perl on a web server.)

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

()

The expression '(..)' will remember the part inside the paranthesis. See the next item for usage.

It can also be used in combination with back references; \1, \2 and so on. (..)\1 will match postcodes starting with two caharcters, and ending with the same ones (e.g. '1919', 7272', but not '1221'). (.)(.)\2\1 will match postcodes where the first and fourth digit is the same, and the second and third digit is the same.

|

The expression 'A|BBB' will match either 'A' or 'BBB'.

Be careful with this construct, as '%ÅS|%SKOG' will not match '%ÅS' or '%SKOG', but rather everything starting with 'ÅS' or ending with 'SKOG' - caused by the '^...$' that the expression is wrapped in. Use '%(ÅS|SKOG)' to get the desired result.

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 a list of postcodes).

selection_loop procedure

The first argument is a pointer to a procedure which will be called for each postcode returned by the selection call, with the rest of the arguments.

 sub post_check
 {
   my $postcode = shift;
   print "$postcode\n" if log2(md5sum($postcode)) > 3.14;
 }

 Geo::Postcodes::XX::selection_loop(\&post_check, xxx, yyy);

selection_loop method

As above, but the value passed to the specified procedure is a postcode object.

 sub post_check
 {
   my $object = shift;
   print $object->postcode() . "\n" if log2(md5sum($object->postcode())) > 3.14;
 }

 Geo::Postcodes::XX->selection_loop(\&post_check, xxx, yyy);

SUPPORTING PROCEDURES

Geo::Postcodes::XX::verify_selectionlist

Use this procedure from the child class to verify that the arguments are valid for use by the selction procedure/method.

 my($status, @list) = Geo::Postcodes::XX::verify_selectionlist(@arguments);

A status value of true (1) is followed by a modified version of the original arguments. This will replace things as 'and' 'not' by 'and not', as the selection procedure does not accept the former.

A status value of false (0) is followed by a list of diagnostic messages, up to the point where the verification failed.

is_legal_selectionmode

Returns true if the mode is one of the list returned by get_selectionmodes, documented below.

is_legal_initial_selectionmode

Returns true if the mode is one of the list returned by get_initial_selectionmodes, documented below.

get_selectionmodes

A sorted list of legal selection modes; 'and', 'and not', 'nor', 'nor not', 'or', 'or not', 'xor' and 'xor not'.

get_initial_selectionmodes

As above, with the addition of 'all', none', 'not' and 'one'. The list is sorted.

type2verbose

  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 to the native language.

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

OTHER PROCEDURES AND METHODS

address =head2 address_of =head2 borough =head2 borough_of =head2 county =head2 county_of =head2 get_methods =head2 get_postcodes =head2 get_types =head2 is_method =head2 legal =head2 location =head2 location_of =head2 new =head2 owner =head2 owner_of =head2 postcode =head2 proc_pointer =head2 type =head2 type_of =head2 type_verbose =head2 type_verbose_of =head2 valid

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

The child classes can use a subset of these, and define the descriptions in the native language if appropriate.

Use type2verbose (see above) to get the description for a given code.

DESCRIPTION

Missing.

CAVEAT

This module uses "inside out objects".

AUTHOR

Arne Sommer, <perl@bbop.org>

LICENSE

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 810:: Non-ASCII character seen before =encoding in ''Æ','. Assuming CP1252

To install Geo::Postcodes, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Geo::Postcodes

CPAN shell

perl -MCPAN -e shell
install Geo::Postcodes

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

ABSTRACT

COMMON FEATURES

selection procedure

Wildcards

Regular expressions

selection method

selection_loop procedure

selection_loop method

SUPPORTING PROCEDURES

Geo::Postcodes::XX::verify_selectionlist

is_legal_selectionmode

is_legal_initial_selectionmode

get_selectionmodes

get_initial_selectionmodes

type2verbose

OTHER PROCEDURES AND METHODS

TYPE

DESCRIPTION

CAVEAT

SEE ALSO

AUTHOR

LICENSE

Module Install Instructions