OpenGu...::Utils(3pm)

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

okay so bestie 💖 you just pulled up OpenGu...::Utils(3pm) — yeah, one of the User Contributed Perl Documentation pages — and honestly? it's giving "internals only, but make it iconic." buckle up 🎀

✨ NAME ✨

OpenGuides::Utils — General utility methods for OpenGuides scripts. periodt. 💅

🌸 DESCRIPTION 🌸

okay so this one hands you the general utility methods that OpenGuides scripts need. it gets distributed and installed as part of the OpenGuides project, so it is NOT meant for independent installation — do not come for it, it's not for you like that. 🙈

and real talk: this documentation is probably only useful to OpenGuides developers. if that's not you, no cap, you might be in the wrong room. but hi anyway 🫶

🦋 SYNOPSIS 🦋

use OpenGuide::Config;
use OpenGuides::Utils;

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

💜 METHODS 💜

🌈 make_wiki_object

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

so this one croaks unless you hand it an OpenGuides::Config object — like, it will literally refuse, no cap 😭. on success it returns a Wiki::Toolkit object built from the config file you gave it, and if literally any other error pops off, it croaks again. fr fr.

your config file has to define at least these variables or it's over bestie:

  • dbtype — one of postgres, mysql and sqlite 👑
  • dbname
  • indexing_directory — this is where the Search::InvertedIndex, Plucene, or Lucy files go to live 🏠

🧚 get_wgs84_coords

returns coordinate data that's suitable for use with Google Maps (and all the other GIS systems that assume WGS-84 data). slay. ✨

my ($wgs84_long, $wgs84_lat) = OpenGuides::Utils->get_wgs84_coords(
                                    longitude => $longitude,
                                    latitude => $latitude,
                                    config => $config
                               );

⭐ get_wgs84_min_max

give it a set of WGS84 coordinate data, and it hands back the minimum, maximum, and centre latitude and longitude. the whole glow-up package 💅

%data = OpenGuides::Utils->get_wgs84_min_max(
    nodes => [
               { wgs84_lat => 51.1, wgs84_long => 1.1 },
               { wgs84_lat => 51.2, wgs84_long => 1.2 },
             ]
);
print "Top right-hand corner is $data{max_lat}, $data{max_long}";
print "Centre point is $data{centre_lat}, $data{centre_long}";

the hashes inside the nodes argument are allowed to carry other key/value pairs too — those just get ignored, they're not the main character, it's fine.

and if it can't find any valid geodata in the nodes? it returns false. 💀

🎀 get_index_page_description

$tt_vars{page_description} =
    OpenGuides::Utils->get_index_page_description(
        format => "map",
        criteria => [ type => "locale", value => "croydon" ],
    );

returns a sentence you can use as a summary of what's being shown on an index page. one lil sentence, doing the absolute most. 🫶

🦋 detect_redirect

$redir = OpenGuides::Utils->detect_redirect( content => "foo" );

checks the content of a node to see if that node is actually a redirect to another node. if it is, you get back the name of the node it redirects to. if it's not, you get false.

also lowkey: it returns false if no content is provided at all. (yes, even then.) 🙈

🔥 validate_edit

my $fails = OpenGuides::Utils->validate_edit(
    id       => $node,
    cgi_obj  => $q
);

checks the content you supplied for general validity. if anything is invalid, it returns an array ref of errors so you can go report them to the user. it's giving helpful, honestly. 👑

💖 parse_change_comment

my $change_comment = parse_change_comment($string, $base_url);

give it a base URL (for example, http://example.com/wiki.cgi?), hand it a string, and it replaces [[page]] and [[page|titled link]] with

<a href="http://example.com/wiki.cgi?page">page</a>

and

<a href="http://example.com/wiki.cgi?page">titled link</a>

respectively, then returns it. 🎀

heads up: this is a limited subset of wiki markup — specifically suitable for use in page change comments. it's not the whole thing, don't ask it to be. 💅

🌸 send_email

eval { OpenGuides::Utils->send_email(
        config        => $config,
        subject       => "Subject",
        body          => "Test body",
        admin         => 1,
        nobcc         => 1,
        return_output => 1
) };

if ($@) {
    print "Error mailing admin: $@\n";
} else {
    print "Mailed admin\n";
}

sends out email, obviously. here's the tea ☕:

  • if admin is true, the email goes to the site admin 👑
  • if to is defined, the email goes to the addresses in that arrayref 📬
  • if nobcc is true, there will be no Bcc to the admin
subject and body are mandatory arguments. like, you cannot skip them. it will not be cute about it. 😭

and for debugging: if return_output is true, the message comes back as a string instead of being sent by email. iconic for testing. ✨

🧚 in_moderate_whitelist

if (OpenGuides::Utils->in_moderate_whitelist( '127.0.0.1' )) {
    # skip moderation and apply new verson to published site
}

admins can supply a comma separated list of IP addresses or CIDR-notation subnets, indicating which hosts get to bypass enforced moderation. main character hosts only, honestly. 💅

and any values that NetAddr::IP can't parse? they just get ignored. no drama. 🙈

👑 AUTHOR 👑

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

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

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay, legally speaking. ✨

and that's the whole vibe check bestie 🎀 this was perl v5.32.0, dated 2021-01-30, serving OpenGu...::Utils(3pm) — go forth and make wiki objects, ily, bye 💖🦋

📦 where this page comes from