Geo::P...ocation(3pm)

NAME ✨

Geo::Postcode::Location — bestie, this is the little helper class that does the grid reference lookups for Geo::Postcode 💖 (it's a Perl module, from the User Contributed Perl Documentation, and it's giving "quiet sidekick with main character energy")

---

🎀 SYNOPSIS 🎀

okay so here's the vibe in code:

$Geo::Postcode::Location::datafile = '/usr/local/lib/postcodes.db';
my ($x, $y) = Geo::Postcode->coordinates('EC1R 8BB');

literally that's it, that's the whole thing 💅

---

🦋 DESCRIPTION 🦋

So Geo::Postcode::Location is where all the gridref-lookup functions of Geo::Postcode live. They got moved out here on purpose — two reasons, both iconic:

• it keeps the footprint of the main module tiny 🐜
• it makes subclassing way easier 🧚

ngl, it doesn't really have a useful direct interface, because it needs a Geo::Postcode object (or a subclass of one) and you'll basically always reach it through that object. BUT. It does have a couple of configuration variables, and there's method documentation down below for anyone who wants to subclass it or swap out the data source. iykyk 🫶

---

🌈 GRIDREF DATA 🌈

There are at least three ways to supply your own gridref data. pick your fighter 👑

✨ replace the data file

If you can get your data into a SQLite file, you're basically done. All you have to do is set either Geo::Postcode::Location::datafile or $ENV{POSTCODE_DATA} to the full path of 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. no thoughts, it just works 💀

✨ replace the database handle

The query we use to retrieve location information is very simple, and it should work with any DBI database handle. If your application already makes a suitable database handle available, or you'd rather create one externally and make sure it gets 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 you're running under mod_perl, you probably don't want to share the handle like that. You can get the same result with instance methods and dodge the 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 a subclass

The data-retrieval process is split up specifically to make this as simple as possible — check the method descriptions below for the deets. You should be able to swap 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 { ... }

slay, you're a module author now 👑

---

💜 METHODS 💜

🍓 new ()

Constructs and returns a location object. Must be supplied with a postcode object of the class dictated by postcode_class. (yes it's picky, it has standards 💅)

🍓 postcode_class ()

Returns the full name of the postcode class we should be expecting. 👀

🍓 postcode ()

Returns the postcode object that was used to construct this object. it's the origin story fr

🍓 retrieve ()

Retrieves location information for this postcode. This method gets called during construction, and it grabs all the necessary information in one go — so all the rest of the methods have to do is look up internal values. efficient queen 🌸

🍓 disconnect_after_use ()

If this returns a true value, then dbh->disconnect will be called after location information is retrieved. bye bestie 🫶

🍓 dbh ()

Accepts, returns — and creates, if necessary — the DBI handle that will be used to retrieve location information.

It's only separate so that it's easy to override. that's the whole reason. iconic behaviour honestly ✨

🍓 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. it goes looking, bestie 🔍

🍓 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. chill about it 😌

🍓 AUTOLOAD ()

Turns the columns defined by cols into lookup methods. You can't set values this way: the whole module is strictly read-only. 🔒 no writing, only reading, periodt

🍓 gridref ()

Returns a proper concatenated grid reference for this postcode, in classic Ordnance Survey AA123456 form — not the all-digits version we use internally.

For more about grid references, see http://www.ordnancesurvey.co.uk/oswebsite/freefun/nationalgrid/nghelp2.html or the more sober http://vancouver-webpages.com/peter/osgbfaq.txt

Unlike the other grid methods here, this one will also strip redundant trailing zeros from the eastings and northings for the sake of readability. it's doing a little cleanup for you, you're welcome 🎀

🍓 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 by passing in a second parameter. Either way it must be one of 'miles', 'km' or 'm'. The default is 'km'. don't come at me with anything else, it will not go well 💀

🍓 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'. it's the compass rose but make it casual 🌈

---

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

---

and that's the whole page, bestie 🫶 this was perl v5.32.0, dated 2021-01-07, filed under Geo::P...ocation(3pm) in the User Contributed Perl Documentation. mwah, go calculate some distances 💅✨