NAME¶
Wiki::Toolkit::Plugin::Locator::Grid - A Wiki::Toolkit plugin to manage
co-ordinate data.
DESCRIPTION¶
Access to and calculations using co-ordinate metadata supplied to a
Wiki::Toolkit wiki when writing a node.
Note: This is
read-only access. If you want to write to a node's
metadata, you need to do it using the "write_node" method of
Wiki::Toolkit.
We assume that the points are located on a flat, square grid with unit squares
of side 1 metre.
SYNOPSIS¶
use Wiki::Toolkit;
use Wiki::Toolkit::Plugin::Locator::Grid;
my $wiki = Wiki::Toolkit->new( ... );
my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new;
$wiki->register_plugin( plugin => $locator );
$wiki->write_node( "Jerusalem Tavern", "A good pub", $checksum,
{ x => 531674, y => 181950 } ) or die "argh";
# Just retrieve the co-ordinates.
my ( $x, $y ) = $locator->coordinates( node => "Jerusalem Tavern" );
# Find the straight-line distance between two nodes, in metres.
my $distance = $locator->distance( from_node => "Jerusalem Tavern",
to_node => "Calthorpe Arms" );
# Find all the things within 200 metres of a given place.
my @others = $locator->find_within_distance( node => "Albion",
metres => 200 );
# Maybe our wiki calls the x and y co-ordinates something else.
my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new(
x => "os_x",
y => "os_y",
);
METHODS¶
- new
-
# By default we assume that x and y co-ordinates are stored in
# metadata called "x" and "y".
my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new;
# But maybe our wiki calls the x and y co-ordinates something else.
my $locator = Wiki::Toolkit::Plugin::Locator::Grid->new(
x => "os_x",
y => "os_y",
);
- x_field
-
my $x_field = $locator->x_field;
An accessor, returns the name of the metadata field used to store the
x-coordinate.
- y_field
-
my $y_field = $locator->y_field;
An accessor, returns the name of the metadata field used to store the
y-coordinate.
- coordinates
-
my ($x, $y) = $locator->coordinates( node => "Jerusalem Tavern" );
Returns the x and y co-ordinates stored as metadata last time the node was
written.
- distance
-
# Find the straight-line distance between two nodes, in metres.
my $distance = $locator->distance( from_node => "Jerusalem Tavern",
to_node => "Calthorpe Arms" );
# Or in kilometres, and between a node and a point.
my $distance = $locator->distance( from_x => 531467,
from_y => 183246,
to_node => "Duke of Cambridge",
unit => "kilometres" );
Defaults to metres if "unit" is not supplied or is not recognised.
Recognised units at the moment: "metres",
"kilometres".
Returns "undef" if one of the endpoints does not exist, or does
not have both co-ordinates defined. The "node" specification of
an endpoint overrides the x/y co-ords if both specified (but don't do
that).
Note: Works to the nearest metre. Well, actually, calls
"int" and rounds down, but if anyone cares about that they can
send a patch.
- find_within_distance
-
# Find all the things within 200 metres of a given place.
my @others = $locator->find_within_distance( node => "Albion",
metres => 200 );
# Or within 200 metres of a given location.
my @things = $locator->find_within_distance( x => 530774,
y => 182260,
metres => 200 );
Units currently understood: "metres", "kilometres". If
both "node" and "x"/"y" are supplied then
"node" takes precedence. Croaks if insufficient start point data
supplied.
SEE ALSO¶
- * Wiki::Toolkit
- * OpenGuides - an application that uses this plugin.
AUTHOR¶
Kake Pugh (kake@earth.li). The Wiki::Toolkit team (
http://www.wiki-toolkit.org/)
COPYRIGHT¶
Copyright (C) 2004 Kake L Pugh. All Rights Reserved.
Copyright (C) 2006 the Wiki::Toolkit Team. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
CREDITS¶
This module is based heavily on (and is the replacement for)
Wiki::Toolkit::Plugin::Locator::UK.
The following thanks are due to people who helped with
Wiki::Toolkit::Plugin::Locator::UK: Nicholas Clark found a very silly bug in a
pre-release version, oops :) Stephen White got me thinking in the right way to
implement "find_within_distance". Marcel Gruenauer helped me make
"find_within_distance" work properly with postgres.