NAME

CGI::Wiki::Plugin::Locator::UK - A CGI::Wiki plugin to manage UK location data.

DESCRIPTION

Access to and calculations using British National Grid location metadata supplied to a CGI::Wiki wiki when writing a node. (For converting between British National Grid co-ordinates and latitude/longitude, you may wish to look at Geography::NationalGrid.)

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 CGI::Wiki.

SYNOPSIS

  use CGI::Wiki;
  use CGI::Wiki::Plugin::Locator::UK;

  my $wiki = CGI::Wiki->new( ... );
  my $locator = CGI::Wiki::Plugin::Locator::UK->new;
  $wiki->register_plugin( plugin => $locator );

  $wiki->write_node( "Jerusalem Tavern",
                     "A good pub",
                     $checksum,
                     { os_x => 531674,
                       os_y => 181950
                     }
                    );

  # Just retrieve the co-ordinates.
  my ( $x, $y ) = $locator->coordinates( node => "Jerusalem Tavern" );

  # Find the straight-line distance between two nodes, in kilometres.
  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 );

METHODS

new

  my $locator = CGI::Wiki::Plugin::Locator::UK->new;

coordinates

  my ($x, $y) = $locator->coordinates( node => "Jerusalem Tavern" );

Returns the OS x and y co-ordinates stored as metadata last time the node was written.

distance

  # Find the straight-line distance between two nodes, in kilometres.
  my $distance = $locator->distance( from_node => "Jerusalem Tavern",
                                     to_node   => "Calthorpe Arms" );

  # Or in metres between a node and a point.
  my $distance = $locator->distance(from_os_x => 531467,
                                    from_os_y => 183246,
                                    to_node   => "Duke of Cambridge",
                                    unit      => "metres" );

  # Or specify the point via latitude and longitude.
  my $distance = $locator->distance(from_lat  => 51.53,
                                    from_long => -0.1,
                                    to_node   => "Duke of Cambridge",
                                    unit      => "metres" );

Defaults to kilometres 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( os_x => 530774,
                                               os_y => 182260,
                                               metres => 200 );

Units currently understood: metres, kilometres. If both node and os_x/os_y are supplied then node takes precedence. Croaks if insufficient start point data supplied.

SEE ALSO

• CGI::Wiki

• Geography::NationalGrid

• My test wiki that uses this plugin - http://the.earth.li/~kake/cgi-bin/cgi-wiki/wiki.cgi

AUTHOR

Kake Pugh (kake@earth.li).

COPYRIGHT

     Copyright (C) 2003 Kake Pugh.  All Rights Reserved.

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

CREDITS

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.