OpenGu...Search(3pm)

📦
version 0.84 · 3 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

💖 OpenGu...Search — the perl manual, but make it make sense 💖

okay bestie, so this is OpenGu...Search(3pm), and yeah the name is giving "someone truncated a filename and gave up" 💀 but it's real and it's from the User Contributed Perl Documentation collection. Sit with me, we're gonna get through this together 🫶

✨ NAME ✨

OpenGuides::Search — it does search form generation and search processing, specifically for OpenGuides. That's the whole job. That's the vibe. 🎀

🌸 DESCRIPTION 🌸

So this module "does search stuff for OpenGuides" — literally, that's the assignment, and it ate. 💅

It's distributed and installed as part of the OpenGuides project, and it is not intended for independent installation, so please don't try to adopt it and raise it on your own, bestie, it's not built for that.

Also, real talk: this documentation is probably only useful to OpenGuides developers. If you're not one, you're lowkey just vibing in someone else's group chat 🙈 but you're welcome here anyway.

✨ SYNOPSIS ✨

here's the whole flow, verbatim, no cap:

use CGI;
use OpenGuides::Config;
use OpenGuides::Search;

my $config = OpenGuides::Config->new( file => "wiki.conf" );
my $search = OpenGuides::Search->new( config => $config );
my %vars = CGI::Vars();
$search->run( vars => \%vars );

like. that's it. config, search object, vars, run. iconic behavior honestly 🌈

🦋 METHODS 🦋

💜 new

my $config = OpenGuides::Config->new( file => "wiki.conf" );
my $search = OpenGuides::Search->new( config => $config );

yeah you make a config, then you make a search with that config. two-step. slay. ✨

💜 wiki

my $wiki = $search->wiki;

An accessor — it hands you back the underlying Wiki::Toolkit object. that's it, that's the whole method, and honestly we respect the brevity. 👑

💜 config

my $config = $search->config;

Another accessor — this one returns the underlying OpenGuides::Config object. 🎀

💜 run

my %vars = CGI::Vars();
$search->run(
              vars           => \%vars,
              return_output  => 1,   # defaults to 0
              return_tt_vars => 1,  # defaults to 0
            );

okay so run is the main character here, obviously. ✨

The return_output parameter is optional. If you supply it and it's true, the stuff that would normally get printed to STDOUT gets returned as a string instead. handy? yes. for testing? absolutely.

The return_tt_vars parameter is also optional. If you supply it and it's true, the template is not processed at all — instead, the variables that would have been passed to it are returned as a hash. and heads up: this parameter takes precedence over return_output. 👀

These two parameters exist to make testing easier. You probably don't want to use them in production. fr fr. 🫶

You can also just ask for the raw search results, like:

my %results = $search->run(
                            os_x    => 528864,
                            os_y    => 180797,
                            os_dist => 750,
                            format  => "raw",
                          );

Results come back as a hash, keyed on the page name. And ALL results are returned, not just the first "page" — no sneaky pagination hiding things from you. 💅

The values in that hash are hashes themselves, each with these key/value pairs:

  • name
  • wgs84_lat — WGS-84 latitude
  • wgs84_long — WGS-84 longitude
  • summary
  • distance — distance (in metres) from origin, if origin exists
  • score — relevance to search string, if search string exists; higher score means more relevance

And in case you're struggling to follow the code (no shame, it happens to the best of us 😭), here's exactly what it does:

  1. Processes the parameters, and bails out if it hit a problem with them
  2. If a search string was given, do a text search
  3. If distance search paramaters were given, do a distance search
  4. If no search has occured, print out the search form
  5. If an error occured, bail out
  6. If we got a single hit on a string search, redirect to it
  7. If no results were found, give an empty search results page
  8. Sort the results by either score or distance
  9. Decide which results to show, based on paging
  10. Display the appropriate page of the results

(yes, "paramaters" and "occured" are spelled that way in the source and I am not touching them, they're part of the lore now 🎀)

🎀 INPUT 🎀

so here's how you actually talk to this thing. vibe check on the search syntax:

word

a single word will be matched as-is. For example, a search on

escalator

will return all pages containing the word "escalator". one word, one job, ate. ✨

AND searches

a list of words with no punctuation will be ANDed, for example:

restaurant vegetarian

will return all pages containing both the word "restaurant" and the word "vegetarian". both. not either. BOTH. 🫶

OR searches

a list of words separated by commas (and optional spaces) will be ORed, for example:

restaurant, cafe

will return all pages containing either the word "restaurant" or the word "cafe". either one, we're not picky, we're in our generous era 🌸

phrase searches

enclose phrases in double quotes, for example:

"meat pie"

will return all pages that contain the exact phrase "meat pie" — and not pages that only contain, for example, "apple pie and meat sausage". the quotes are doing the heavy lifting, don't skip them. 💅

🌈 SEARCHING BY DISTANCE 🌈

To perform a distance search, you need to supply one of the following sets of criteria to specify the distance to search within, and the origin (centre) of the search:

os_dist, os_x, and os_y

Only works if you chose to use British National Grid in wiki.conf. 🇬🇧

osie_dist, osie_x, and osie_y

Only works if you chose to use Irish National Grid in wiki.conf. 🇮🇪

latlong_dist, latitude, and longitude

Should always work — but it has a habit of "finding" things a couple of metres away from themselves. 😭 yeah. it's like that. it's giving "mirror selfie with the location tag on".

You can perform both pure distance searches and distance searches in combination with text searches. mix and match, bestie, go off. 🔥

⭐ OUTPUT ⭐

Results will be put into some form of relevance ordering. These are the rules we have tests for so far — and hence the only rules that can be relied on:

  • A match on page title will score higher than a match on page category or locale.
  • A match on page category or locale will score higher than a match on page content.
  • Two matches in the title beats one match in the title and one in the content.

that's the whole scoring hierarchy we can promise you. everything else is unverified vibes, and we don't do unverified vibes in the docs. 👑

👑 AUTHOR 👑

The OpenGuides Project (openguides-dev@lists.openguides.org)

     Copyright (C) 2003-2013 The OpenGuides Project.  All Rights Reserved.

The OpenGuides distribution is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

🌟 SEE ALSO 🌟

OpenGuides

okay that's the whole page, you made it, I'm so proud of you 🥹 this was perl v5.32.0, dated 2021-01-30, brought to you by the fine people at OpenGu...Search(3pm). go forth and search responsibly, bestie. 💅✨🌸

📦 where this page comes from