Wiki::...::Grid(3pm)

💖 Wiki::Toolkit::Plugin::Locator::Grid — a Wiki::Toolkit plugin to manage co-ordinate data 💖

okay bestie, so this is Wiki::Toolkit::Plugin::Locator::Grid, a Perl module (that's the 3pm vibe, iykyk) and it's literally here to handle co-ordinate data for your wiki. Let's get into it. 🦋

---

✨ DESCRIPTION ✨

So basically: this gives you access to — and does math on — the co-ordinate metadata that gets supplied to a Wiki::Toolkit wiki when you write a node. Iconic.

Note: this is read-only access, bestie. If you wanna write to a node's metadata, you gotta do it through the write_node method of Wiki::Toolkit. No shortcuts, periodt.

We assume that the points are located on a flat, square grid with unit squares of side 1 metre. Just a lil grid. A vibe. 🎀

---

🌈 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",
                                                   );

look at that. chef's kiss. 👑

---

💅 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, bestie. It hands you back the name of the metadata field that's storing the x-coordinate. That's it. That's the whole job. 🫶

🌸 y_field

my $y_field = $locator->y_field;

Another accessor, same energy — returns the name of the metadata field used to store the y-coordinate. 💜

🌸 coordinates

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

Gives you the x and y co-ordinates that were stored as metadata the last time the node was written. Last write wins, no cap. ✨

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

Straight-line distance, as the crow flies, the way that geometry intended. 🌈

Defaults to metres if unit isn't supplied or isn't recognised. Recognised units right now: "metres", "kilometres".

Returns undef if one of the endpoints doesn't exist, or doesn't have both co-ordinates defined. And heads up: the node specification of an endpoint overrides the x/y co-ords if both are specified — (but don't do that, bestie, why would you).

Note: Works to the nearest metre. Well, actually, it 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, main character energy fr fr. 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. Glow-up moment. 🦋

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.

---

🙈 POD ERRORS 🙈

Hey! The above document had some coding errors, which are explained below:

Around line 269:

    You forgot a '=back' before '=head1'

not the =back being missing 😭 it's giving "forgot to close the tag" energy. we still love it tho. 💖

---

and that's the whole page, bestie! This was perl v5.34.0, dated 2022-06-14, and the manual name was Wiki::...::Grid(3pm) — slay, ate, no crumbs. 💅✨🌸