NAME

Geo::Postcodes::Update - Helper module for keeping the postcodes up to date

SYNOPSIS

 #! /usr/bin/perl -w
 use strict;
 use Geo::Postcodes::Update;

 my $class     = 'NO';
 my $file      = 'tilbud5';
 my $url       = 'http://epab.posten.no/Norsk/Nedlasting/_Files/tilbud5';
 my $procedure = \&parse_no;
 my $update    = @ARGV && $ARGV[0] eq "-update";

 Geo::Postcodes::Update::update($class, $file, $url, $procedure, $update);

 sub parse_no
 {
   my @in = @_;
   my @out;
   ...
   return @out;
 }

This is how the norwegian postcodes are treated, without showing the inner workings of parse_no which receives the lines from the file tilbud5 and returns suitable perl code for inclusion in the module. (The program is included as misc/update_no in the norwegian module.)

Run the program from the root (or the ./misc) directory of the distribution.

PROCEDURES

This module has only one external procedure.

update

Call this procedure with the following four parameters:

Class Name: The name of the class in upper case letters, e.g. 'DK', 'NO' or 'U2'. This is a two-letter country code, as defined in ISO 3166-1, except for our utopian 'U2' (as used in the tutorial; perldoc Geo::Postcodes::Tutorial or man Geo::Postcodes::Tutorial).
File Name: The file where the postcodes are taken from. It is located in the ./misc directory of the distribution, together with the update_xx program.
URL: An optional URL, where the program can download the postcode file if allowed to do so by the user. Use undef if no URL is available.
Procedure: A pointer to a procedure that parses the postcode data. It will receive the lines from the postcode file as input, and must return a list of perl code lines with a suitable data structure, ready for writing to the country module file.
Update Flag: Set this to true to get the procedure to actually offer to update the module. It will display the perl code on-screen otherwise. This is usefull for debugging purposes when making the parsing procedure.

WALK-THROUGH

The update_* programs will do the following, when executed:

1.: (URL Specified:) The program offers to fetch the postcode file, if it cannot locate the postcode file (in the ./misc directory). The user can decline the offer.
2.: The program terminates if it cannot locate the postcode file (in the ./misc directory).
3.: If the 'update' flag is not set, the program outputs the data structure (as lines of perl code on-screen) and terminates.
4.: The program compares the data structure in the module with the one taken from the postcode file. The module is updated if the data structures differ, and the program will terminate.
5.: The program terminates if it has fetched the postcode file already (in point 1).
6.: As point 1.
7.: As point 2.
8.: As point 4.

REQUIREMENTS

This module requires the CPAN-module libwww-perl to work. It is used for semiautomatic downloading of the postcode file.

COPYRIGHT AND LICENCE

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