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( $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" );

        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.