NAME¶
Geo::Postcode::Location - helper class for Geo::Postcode that handles grid
reference lookups
SYNOPSIS¶
$Geo::Postcode::Location::datafile = '/usr/local/lib/postcodes.db';
my ($x, $y) = Geo::Postcode->coordinates('EC1R 8BB');
DESCRIPTION¶
Geo::Postcode::Location holds the gridref-lookup functions of Geo::Postcode. It
is separated here to minimise the footprint of the main module and to
facilitate subclassing.
It doesn't really have a useful direct interface, since it requires an object of
Geo::Postcode (or a subclass) and is most easily reached through that object,
but it does have a couple of configuration variables and there is method
documentation here for anyone interested in subclassing it or changing the
data source.
GRIDREF DATA¶
There are at least three ways to supply your own gridref data.
- •
- replace the data file
If you can get your data into a SQLite file, all you have to do is set the
either "Geo::Postcode::Location::datafile" or
$ENV{POSTCODE_DATA} to the full path to your data file:
$Geo::Postcode::Location::datafile = '/home/site/data/postcodes.db';
# or
PerlSetEnv POSTCODE_DATA /home/site/data/postcodes.db
I've included (in ./useful) an idiot script that I use to turn .csv data
into a SQLite file suitable for use with this module.
- •
- replace the database handle
The query that we use to retrieve location information is very simple, and
should work with any DBI database handle. If your application already
makes available a suitable database handle, or you would like to create
one externally and make sure it is reused, it should just work:
$Geo::Postcode::Location::dbh = $my_dbh;
$Geo::Postcode::Location::tablename = 'postcodedata';
my ($x, $y) = Geo::Postcode->coordinates('EC1Y 8PQ');
If running under mod_perl, you probably don't want to share the handle like
that. You can achieve the same thing with instance methods and avoid
side-effects, but you have to make the calls at the right time:
my $postcode = Geo::Postcode->new('EC1Y 8PQ');
$postcode->location->dbh( $my_dbh );
$postcode->location->tablename( 'postcodedata' );
my ($x, $y) = $postcode->coordinates;
- •
- override the lookup mechanism in subclass
The data-retrieval process is divided up to make this as simple as possible:
see the method descriptions below for details. You should be able to
replace the data source by overriding "dbh" or redo the whole
lookup by replacing "retrieve".
$Geo::Postcode->location_class('My::Location');
package My::Location;
use base qw(Geo::Postcode::Location);
sub dbh { ... }
METHODS¶
new ()¶
Constructs and returns a location object. Must be supplied with a postcode
object of the class dictated by "postcode_class".
postcode_class ()¶
Returns the full name of the postcode class we should be expecting.
postcode ()¶
Returns the postcode object used to construct this object.
retrieve ()¶
Retrieves location information for this postcode. This method is called during
construction, retrieves all the necessary information in one go, so all the
rest have to do is look up internal values.
disconnect_after_use ()¶
If this returns a true value, then dbh->disconnect will be called after
location information is retrieved.
dbh ()¶
Accepts, returns - and creates, if necessary - the DBI handle that will be used
to retrieve location information.
This is only separate to make it easy to override.
datafile ( path_to_file )¶
Accepts and returns the location of the SQLite file we expect to provide
location data.
If no file path is supplied, or found by checking
$Geo::Postcode::Location::datafile and $ENV{POSTCODE_DATA}, then we will scan
the path to locate the default data file that is installed with this module.
tablename ()¶
Sets and gets the name of the database table that should be expected to hold
postcode data.
cols ()¶
Returns a list of the columns we should pull from the database row into the
location object's internal hash (and also provide as instance methods). This
isn't used in the SQL query (which just SELECTs *), so we don't mind if
columns are missing.
AUTOLOAD ()¶
Turns the columns defined by "cols" into lookup methods. You can't set
values this way: the whole module is strictly read-only.
gridref ()¶
Returns a proper concatenated grid reference for this postcode, in classic
Ordnance Survey AA123456 form rather than the all-digits version we use
internally.
See
http://www.ordnancesurvey.co.uk/oswebsite/freefun/nationalgrid/nghelp2.html
or the more sober
http://vancouver-webpages.com/peter/osgbfaq.txt
for more about grid references.
Unlike other grid methods here, this one will also strip redundant trailing
zeros from the eastings and northings for the sake of readability.
distance_from ()¶
We prefer to use grid references to calculate distances, since they're laid out
nicely on a flat plane and don't require us to remember our A-levels. This
method just returns a single distance value.
You can specify the units of distance by setting $Geo::Postcode::Location::units
or passing in a second parameter. Either way it must be one of 'miles', 'km'
or 'm'. The default is 'km'.
bearing_to ()¶
Returns the angle from grid north, in degrees clockwise, of the line from this
postcode to the postcode object supplied.
friendly_bearing_to ()¶
Returns a readable approximation of the bearing from here to there, in a form
like 'NW' or 'SSE'.
AUTHOR¶
William Ross, wross@cpan.org
COPYRIGHT¶
Copyright 2004 William Ross, spanner ltd.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.