NAME

Geo::Postcodes::Tutorial - How to use the Geo::Postcodes::* modules

SYNOPSIS

use Geo::Postcodes::U2;

my $postcode = '1104';
my $location = Geo::Postcodes::U2::location_of($postcode);

INTRODUCING UTOPIA

This tutorial uses the fictious country Utopia (with country code 'U2'), and the rest of this document will refer to the non-existent module Geo::Postcodes::U2. Any differences with the two existing country modules (Geo::Postcodes::DK; Denmark and Geo::Postcodes::NO; Norway) are explained.

INSTALLING UTOPIA

The latest version of Geo::Postcodes::U2 if had it existed, that is) can be installed or updated from CPAN with the following commands (, preferably as root. This will automatically install or update the core module Geo::Postcodes as well.

shell> perl -MCPAN -e shell
cpan> install Geo::Postcodes::U2

It may be possible to use the command cpan instead of the first line.

USING UTOPIA

Include the following line in the program, after installing the module:

use Geo::Postcodes::U2;

VERIFYING UTOPIA

legal

Use the legal procedure to check that the specified postcode is legal, i.e. that it follows the syntax rules for our utopian postcodes.

Utopian postcodes are four digit numbers, and the lowest number in use is '1003'. This procedure is programmed to return true for any four digit number where the first digit is non-zero.

$boolean = Geo::Postcodes::U2::legal('ABBA'); # 0 -> Illegal
$boolean = Geo::Postcodes::U2::legal('0900'); # 0 -> Illegal
$boolean = Geo::Postcodes::U2::legal('1900'); # 1 -> Legal
$boolean = Geo::Postcodes::U2::legal('1000'); # 1 -> Legal

valid

The procedure valid will check if the postcode is valid; that it is in actual use. The code may or may not be legal.

$boolean = Geo::Postcodes::U2::valid('1000'); # 0 -> Not in use
$boolean = Geo::Postcodes::U2::valid('ABBA'); # 0 -> Not in use

UTOPIAN FIELDS

Utopian postcodes support all the 8 fields set up by the core module. Every field is available as $P->xxx or xxx_of($postcode), where xxx is the field name. The procedures/methods will return undef if the value is unspecified for the given postcode.

postcode - postcode_of

$postcode = $P->postcode();
$postcode = Geo::Postcodes::U2::location_of($postcode); # Silly

The actual postcode value is available with postcode method, as the object itself does not have this information. The corresponding postcode_of-procedure is used internally by selection-procedure/method, but should be avoided in applications.

location - location_of

$location = $P->location();
$location = Geo::Postcodes::U2::location_of($postcode);

The location (or postal location) of the postcode. This is the value shown after the postcode in addresses.

borough - borough_of

$borough = $P->borough();
$borough = $Geo::Postcodes::U2::borough_of($postcode);

The borough where the postcode is located.

This field is not used by danish postcodes.

county

$county = $P->county();
$county = $Geo::Postcodes::U2::county_of($postcode);

The county where the postcode is located.

This field is not used by danish postcodes.

owner - owner_of

$owner = $P->owner();
$owner = $Geo::Postcodes::U2::owner_of($postcode);

The owner of the postcode. This value is only used if the postcode is used by a single user.

This field is not used by norwegian postcodes.

address - address_of

$address = $P->address();
$address = $Geo::Postcodes::U2::address_of($postcode);

The street address of the postcode. This value is only used if the postcode is used by a single street, and the street does not use any other posrcode.

This field is not used by norwegian postcodes.

type - type_of

$type = $P->type();
$type = $Geo::Postcodes::U2::type_of($postcode);

The type of the postcode, as a short (2-4 characters) code. The types supported by the core module are:

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 as many of the codes as they want. Utopian postcodes support them all.

type_verbose - type_verbose_of

A textual description of the codes, as specified in the previous section, as the codes themselves are not very user friendly.

$utopian_description = $P->type_verbose();
$utopian_description = Geo::postcodes::U2::type_verbose_of($postcode);

This will give the description in utopian, if set up by the utopian module, and english otherwise.

The individual country classes are responsible for translating the descriptions of the codes they use to the native language, if appropriate.

$english_description = Geo::postcodes::type_verbose_of($postcode);
$english_description = $P->Geo::Postcodes::type_verbose();

Use the version in the base class for the english version.

The danish and norwegian modules have translations for the codes they use.

MAKING UTOPIA

The modules can be used as procedures on postcodes, or object oriented.

Example Using Procedures

my $postcode = '1010';

if (Geo::Postcodes::U2::valid($postcode))
{
  printf "Postcode"        '%s'.\n", $postcode;
  printf "Postal location: '%s'.\n", location_of($postcode);
  printf "Borough:         '%s'.\n", borough_of($postcode);
  printf "County:          '%s'.\n", county_of($postcode);
  printf "Owner:           '%s'.\n", owner_of($postcode);
  printf "Address:         '%s'.\n", address_of($postcode);
  printf "Postcode type:   '%s'.\n", type_of($postcode); 
  printf "- in utopian:    '%s'.\n", type_of_verbose($postcode); 
  printf "- in english:    '%s'.\n", Geo::Postcodes::type_of_verbose($postcode); 
}

The fields are described in the prevoius section; "UTOPIAN FIELDS".

Object Oriented Example

if (Geo::Postcodes::U2::valid($postcode))
{
  my $P = Geo::Postcodes::U2->new($postcode);
  printf "Postcode         '%s'.\n", $P->postcode();
  printf "Postal location: '%s'.\n", $P->location();
  printf "Borough:         '%s'.\n", $P->borough();
  printf "County:          '%s'.\n", $P->county();
  printf "Owner:           '%s'.\n", $P->owner();
  printf "Address:         '%s'.\n", $P->address();
  printf "Postcode type:   '%s'.\n", $P->type(); 
  printf "- in norwegian:  '%s'.\n", $P->type_verbose(); 
  printf "- in english:    '%s'.\n", $P->Geo::Postcodes::type_verbose(); 
}

If speed is a concern, use the procedure version.

new

my $P = Geo::Postcodes::U2->new($postcode);

Create a new postcode object. Internally this will call the xxx_of procedures for the fields supported by utopian postcodes.

The constructor will return undef if given an invalid or illegal postcode. Do not try method calls on it, as it is not an object (and will result in a runtime error). See the description of the legal and valid procedures above.

COMPACT UTOPIA

The test for a valid postcode can also be done on the object itself, as it will be undef when passed an illegal or invalid postcode (and thus no object at all.)

The example in the prevous section had a line for each field, but it is possible to use a loop instead:

if ($P = Geo::Postcodes::U2->new($postcode))
{
  foreach my $field (Geo::Postcodes::U2::get_fields())
  {
    printf("%-20s %s\n", ucfirst($field), $P->$field())
  }
}

This will not show the english description of the type, and the printed labels are slightly different than in the previous example.

get_fields

Use this procedure/method to get a list of the supported ields for utopian postcodes.

my @fields = Geo::postcodes::U2::get_fields();
my @fields = $P->get_fields();

is_field

Use this procedure/method to check if the specified field exist for utopian postcodes.

my $boolean = Geo::postcodes::U2::is_field($field);
my $boolean = $P->is_field($field);

A sample program

This sample program is available as "eg/basic_dk" in the danish, and "eg/basic_no" in the norwegian distributions. The line numbers are used for clarity only.

Specify one or more postcodes on the command line; e.g. "basic_u2 1001 1003".

01 #! /usr/bin/perl -w
02 use strict;
03 use Geo::Postcodes::U2 0.30;

The example will not work with older versions of the module.

04 unless (@ARGV)
05 {
06   print "Usage: basic_u2 <one or more utopian postcodes>\n";
07   exit;
08 }

Exit with an error message if the program hasn't been given any arguments.

09 foreach my $postcode (@ARGV)
10 {

Loop through the arguments, and create a postcode object for each one.

11   if (my $P = Geo::Postcodes::U2->new($postcode)))
12   {

Skip the argument if it isn't a valid postcode. The new-call returns an object reference on success, and undef on failure (i.e. an illegal or unvalid postcode).

13     foreach my $field (Geo::Postcodes::U2::get_fields())
14     {
15       printf("%-10s\t%s\n", ucfirst($field), $P->$field() || ""),
16     }

For each field supported by the module, we print the field name (with an initial uppercase letter), followed by the value of the field. All tabulated nicely.

17      printf("%-10s\t%s\n\n", "Type_english", 
18        Geo::Postcodes::type2verbose($P->type()));
19   }

We must ask for the english description of the type manually.

20   else # Not valid.
21   {
22     if (Geo::Postcodes::U2::legal($postcode))
23     {
24       print "Postcode '$postcode' not in use.\n\n";
25     }
26     else
27     {
28       print "Illegal postcode '$postcode'.\n\n";
29     }
30   }
31 }

This part will be called if the new-call fails, and we will get an error message telling us what is wrong; if the argument is illegal (not following the rules for utopian postcodes) or invalid (not in use).

ADVANCED UTOPIA

The procedures and methods mentioned till now will only give us one (or zero) postcode at a time, but it is possibly to get several postcodes at once.

get_postcodes

@postcodes =      Geo::postcodes::U2::get_postcodes(); # Unsorted
@postcodes = sort Geo::postcodes::U2::get_postcodes(); # Sorted

This procedure returns an unsorted list of all the postcodes.

It is possible to use this call to write your own selection code:

my @list;
foreach my $postcode (Geo::postcodes::U2::get_postcodes())
{
  push(@list, $postcode) if check_the_postcode_for_something($postcode);
}

Write the check_the_postcode_for_something-procedure to decide if the postcode should be included. Use the xxx_of-procedures, or whatever else is needed. Do not create postcode objects inside this loop, as this will increase the time of execution quite a lot.

selection

The module has a selection procedure/method, that can be used if the check can be expressed as a regular expression on one or more if the fields.

See the selection manual (perldoc Geo::Postcodes::Selection or man Geo::Postcodes::Selection) for further information.

selection_loop

This procedure/method can be used to get rid of the loop in the following example:

my @list = Geo::postcodes::U2::selection(....);
foreach my $postcode (@list)
{
  do_something($postcode)
}

The following line of code will do the same thing:

Geo::postcodes::U2::selection_loop(\&do_something, ....);

The loop can use postcode objects instead of plain postcodes, as with selection.

Geo::postcodes::U2->selection_loop(\&do_something, ....);

The benefit of this is that the selection-method will generate all the postcode objects, before passing them on, while this method will generate one at a time, destroying the prevoius one before creating a new.

verify_selectionlist

This will check the list of arguments for correctness, and should be used before calling selection or selection_loop. The procedure returns a modified version of the arguments on success, and diagnostic messages on failure.

my ($status, @modified) = Geo::Postcodes::U2::verify_selectionlist(@args);

if ($status)
{
  my @result = Geo::Postcodes::U2::selection(@modified);
   # And do something with the list of postcodes.
}
else
{
  print "Diagnostic messages:\n";
  map { print " - $_\n" } @modified;
}

A second program

This sample program is available as "eg/selection_dk" in the danish, and "eg/selectionc_no" in the norwegian distributions. The line numbers are used for clarity only.

Specify a field and a value on the command line, e.g. "selection_u2 postcode %12".

01 #! /usr/bin/perl -w
02 use strict;
03 use Geo::Postcodes::DK 0.30;

04 unless (@ARGV == 2)
05 {
06  print "Usage: selection_u2 <field> <value>\n";
07  print "Legal fields: ", join(" ", Geo::Postcodes::U2::get_fields()), ".\n";
08  exit;
09 }

This program requires exactly two arguments, a field and a value, and is terminated if the are missing.

10 my $field = shift(@ARGV);
11 my $value = shift(@ARGV);
12 my @fields;

13 if (Geo::Postcodes::U2::is_field($field))
14 {

Do we have a legal field? (If not, the else-part below will give an error message.

15   @fields = Geo::Postcodes::U2::get_fields();

Get the list of available fields for this class.

16   foreach my $m (@fields)
17   {
18     printf("%-14s", ucfirst($m));
19   }
20   print "\n";

We are going to print one line for each matching postcode, and this will give us a header line.

21   Geo::Postcodes::U2->selection_loop(\&print_it, $field, $value);

This piece of magic will use the select method to find any matching postcodes, and pass them on as a postcode pbject to the specified print_it procedure - one at a time.

22   print "\n";
23 }

24 else # illegal field.
25 {
26   print "Not a legal field '$field'.\n";
27 }

A simple error message.

28 sub print_it
29 {
30   my $object = shift;
31   foreach my $method (@fields)
32   {
33     printf("%-14s", $object->$method() || "");
34   }
35   print "\n";
36 }

This procedure is called for each matching postcode, and receives a postcode object as argument. The foreach loop uses the list of fields set up in line 15. The second part of the argument in the print statement traps errors, as the call returns undef if the value is undefined for the given postcode, and printing an undefined value gives a warning.

A third program

This sample program is available as "eg/multiselection_dk" in the danish, and "eg/multiselectionc_no" in the norwegian distributions. The line numbers are used for clarity only.

Specify a field and a value on the command line, e.g. "multiselection_u2 xxxxxxxxxxxxxx".

01 #! /usr/bin/perl -w
02 use strict;
03 use Geo::Postcodes::U2 0.30;

This should be familiar by now.

04 my ($status, @lines) = Geo::Postcodes::U2::verify_selectionlist(@ARGV);

Simply passing a list of arguments on to selection is not a good idea, as it will return an empty list both on failure (as in syntax errors, illegal modes or fields) and when the call itself didn't match anything.

Use verify_selectionlist to check the argument list for errors. The $status variable is true if the argument list is legal, and false otherwise.

11 if ($status == 0)
12 {
13   print "Usage: \n",
14         " * multiselection_u2 [all|none]\n",
15         " * multiselection_u2 [" , 
16         join("|", Geo::Postcodes::get_initial_selectionmodes()),
17         "]? <field> <value> [[",
18         join("|", Geo::Postcodes::get_selectionmodes()),
19         "]? [<field> <value>]]*\n\n";
20   print "Legal fields: ", join(", ", Geo::Postcodes::U2::get_fields()), "\n\n";

We use several procedures to show the legal modes and fields. This ensures that we do not have to update the program if we add new modes or fields in the modules later on.

21   print "Diagnostic output:\n";
22   foreach (@lines)
23   {
24     print " * $_\n";
25   }

The @lines variable contains diagnostic output on failure, and they are printed as a service to the user - to help correct the error.

26   exit;
27 }

28 my @fields = Geo::Postcodes::U2::get_fields();
29 foreach my $m (@fields)
30 {
31   printf("%-14s", ucfirst($m)); # Print headers for each column
32 }
33 print "\n";

34 foreach my $P (Geo::Postcodes::U2->selection(@lines))
35 {

Note that we use the argument list as returned by the verify_selectionlist call, as it corrects some mistakes that the selection procedure/method does not cope with.

36   foreach my $method (@fields)
37   {
38     printf("%-14s", $P->$method() || "");
39   }
40   print "\n";
41 }
42 print "\n";

Advanced selection

The arguments to the selection procedure/method is not restricted to pairs of field/value, combined together with the logical operators 'and', 'or' and so on.

It is also possible to call external procedures, and have them decide if the postcode should be included. Specify 'procedure', \&procedure_to_do_the_job instead of a field/value pair.

The procedure is passed the postcode, and must return true or false.

sub procedure_to_do_the_job
{
  my postcode = shift;
  return 1 if ...
  return 0;
}

Passing a pointer to a non-existing procedure to selection will result in an empty list in return. verify_selectionlist can be used to check that any specified procedures actually exist.

A fourth example

This sample program is available as "eg/static_dk" in the danish, and "eg/static_no" in the norwegian distributions. The line numbers are used for clarity only.

01 #! /usr/bin/perl -w
02 use strict;
03 use Geo::Postcodes::U2 0.30;

This should be familiar by now.

04 use Digest::SHA1;

For the sake of this example, som computation had to be done that could not be done by a regular expression. This module was chosen.

05 my @arg1 = ('postcode' => '(.)(.)\2\1');

We start with a regular expression, matching postcodes where the first and fourth digit are identical, as is the second and third.

06 print "All norwegian postcodes where :\n";
07 my @postcodes = Geo::Postcodes::NO::selection(@arg1);
08 print join ",", @postcodes; print ".\n\n";

This prints the matching postcodes. Nothing fancy so far.

09 print "As above, but with the addition of a procedure:\n";
10 my @arg2 = (@arg1, 'procedure' => \&selector_procedure);

Now we have added a procedure to the argument list, and the selection call below does the job for us.

11 @postcodes = Geo::Postcodes::NO::selection(@arg2);
12 print join ",", @postcodes; print ".\n\n";

13 sub selector_procedure
14 {
15   my $postcode = shift;
16   my $location = Geo::Postcodes::NO::location_of($postcode);
17   my $digest = Digest::SHA1::sha1($location);
18   return 1 if substr($digest, 10, 5) =~ /[a-z]/;
19   return 0;
20 }

The procedure computes the SHA1-digest for the postal location, and returns true if the there is a lower case letter (a-z) among the 11th to 15th characters of the digest. This may not be very useful in practice...

AUTHOR

Arne Sommer, <perl@bbop.org>

LICENSE

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

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

INTRODUCING UTOPIA

INSTALLING UTOPIA

USING UTOPIA

VERIFYING UTOPIA

legal

valid

UTOPIAN FIELDS

postcode - postcode_of

location - location_of

borough - borough_of

county

owner - owner_of

address - address_of

type - type_of

type_verbose - type_verbose_of

MAKING UTOPIA

Example Using Procedures

Object Oriented Example

new

COMPACT UTOPIA

get_fields

is_field

A sample program

ADVANCED UTOPIA

get_postcodes

selection

selection_loop

verify_selectionlist

A second program

A third program

Advanced selection

A fourth example

SEE ALSO

AUTHOR

LICENSE

Module Install Instructions