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 => $wiki );

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

        Mandatory argument - a CGI::Wiki object.

    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.
          my $distance = $locator->distance(from_node => "Angel Station",
                                            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 nodes does not exist, or does not have
        both co-ordinates defined.

        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 );

        Units currently understood: "metres", "kilometres".

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.