UR::ModuleBase(3pm)

💖 UR::ModuleBase(3pm) 💖

okay bestie, welcome to the perl manual page for UR::ModuleBase, and honestly? it's giving foundation. it's giving load-bearing. 🫶

---

✨ NAME ✨

UR::ModuleBase — methods common to all UR classes and object instances. periodt. 💅

---

🌸 DESCRIPTION 🌸

So UR::ModuleBase is a base class for packages, classes, and objects that need to manage the basic functionality of the UR framework — stuff like inheritance, AUTOLOAD/AUTOSUB methods, and error/status/warning/etc messages. it's the whole vibe of "i handle the boring plumbing so you don't have to". 🎀

and listen — UR::ModuleBase is in the @ISA list for UR::Object, but UR::ModuleBase is not a formal UR class. it's just out here doing the work behind the scenes, main character energy but off-camera. 💜

---

👑 METHODS 👑

• class

$class = $obj->class;

this hands you the class name of a class or an object, as a string. and it is exactly equivalent to this, no cap:

(ref($self) ? ref($self) : $self)

• super_can

$sub_ref = $obj->super_can('func');

this one checks whether any of the super classes of the $obj object can do the method func. if even one of them can, you get back a reference to the subroutine that would actually get called — and that's determined using a depth-first search of the @ISA array. and if none of the super classes provide a method named func? you get undef. sorry bestie. 😭

• inheritance

@classes = $obj->inheritance;

this returns a depth-first list of all the classes (packages) that the class $obj was blessed into inherits from. this order is the same order that gets searched when perl goes looking for inherited methods to execute. if the class has no super classes, you get an empty list back. and heads up — the UNIVERSAL class is not returned unless it was explicitly put into the @ISA array by the class or one of its super classes. iykyk. ✨

• parent_classes

MyClass->parent_classes;

this returns the immediate parent class — or parent classes, in the case of multiple inheritance. and in no case does it follow the inheritance hierarchy the way ->inheritance() does. it stays right where it is, no wandering. 🦋

• base_dir

MyModule->base_dir;

this returns the base directory for a given module — the place where that module's supplemental data gets stored, like config files and glade files, data caches, etc. 🍓

it uses %INC.

• methods

Undocumented. 💀 (yes really, that's the whole thing)

• context_return

return MyClass->context_return(@return_values);

this attempts to return either an array or a scalar based on the calling context. and it will die if it's called in scalar context while @return_values has more than 1 element. so don't do that. 🙈

---

🔥 AUTOLOAD 🔥

this package implements AUTOLOAD so that derived classes can use AUTOSUB instead of AUTOLOAD. slay.

here's the deal: when a class or object has a method called on it that isn't found in the final class or any derived classes, perl checks up the tree for AUTOLOAD. we implement AUTOLOAD at the top of the tree, and then check each class in the tree, in order, for an AUTOSUB method. where a class implements AUTOSUB, it will receive a function name as its first parameter, and it's expected to return either a subroutine reference, or undef. if undef is returned, then the inheritance tree search will continue. if a subroutine reference is returned, it gets executed immediately with the @_ that was passed into AUTOLOAD. typically, AUTOSUB will be used to generate a subroutine reference, and will then associate that subref with the function name so you avoid repeated calls to AUTOLOAD and AUTOSUB. iconic efficiency. 💅

why not just use AUTOLOAD directly in place of AUTOSUB? great question bestie:

on an object with a complex inheritance tree, AUTOLOAD is only found once, and after that, there's no way to indicate that the given AUTOLOAD has failed and that the inheritance tree trek should continue on to other AUTOLOADs which might implement the given method. it's a dead end. 🚧

example:

package MyClass;
our @ISA = ('UR');
##- use UR;

sub AUTOSUB
{
    my $sub_name = shift;
    if ($sub_name eq 'foo')
    {
        *MyClass::foo = sub { print "Calling MyClass::foo()\n" };
        return \&MyClass::foo;
    }
    elsif ($sub_name eq 'bar')
    {
        *MyClass::bar = sub { print "Calling MyClass::bar()\n" };
        return \&MyClass::bar;
    }
    else
    {
        return;
    }
}

package MySubClass;
our @ISA = ('MyClass');

sub AUTOSUB
{
    my $sub_name = shift;
    if ($sub_name eq 'baz')
    {
        *MyClass::baz = sub { print "Calling MyClass::baz()\n" };
        return \&MyClass::baz;
    }
    else
    {
        return;
    }
}

package main;

my $obj = bless({},'MySubClass');
$obj->foo;
$obj->bar;
$obj->baz;

---

💜 MESSAGING 💜

UR::ModuleBase implements several methods for sending and storing error, warning and status messages to the user. it's basically the group chat of your program's feelings. 🫶

# common usage

sub foo {
    my $self = shift;
    ...
    if ($problem) {
        $self->error_message("Something went wrong...");
        return;
    }
    return 1;
}

unless ($obj->foo) {
    print LOG $obj->error_message();
}

---

🎀 Messaging Methods 🎀

• message_types

@types = UR::ModuleBase->message_types;
UR::ModuleBase->message_types(@more_types);

with no arguments, this method returns all the types of messages that this class handles. with arguments, it adds a new type to the list. ✨

standard message types are fatal, error, status, warning, debug and usage.

note that the addition of new types is not fully supported/implemented yet. so like... tread carefully bestie. 🚨

for each message type, several methods are created for sending and retrieving messages, registering a callback to run when messages are sent, controlling whether the messages are printed on the terminal, and whether the messages are queued up. so much functionality, obsessed. 💖

for example, for the error message type, these methods are created:

• error_message

$obj->error_message("Something went wrong...");
$obj->error_message($format, @list);
$msg = $obj->error_message();

when called with one or more arguments, it sends an error message to the object. the error_message_callback will be run, if one is registered, and the message will be printed to the terminal. when given a single argument, it will be passed through unmodified. when given multiple arguments, error_message will assume the first is a format string and the remainder are parameters to sprintf. when called with no arguments, the last message sent will be returned. if the message is undef then no message is printed or queued, and the next time error_message is run as an accessor, it will return undef. 🌈

note that fatal_message() will throw an exception at the point it appears in the program. this exception, like others, is trappable with eval. 😱

• dump_error_messages

$obj->dump_error_messages(0);
$flag = $obj->dump_error_messages();

get or set the flag which controls whether messages sent via error_message() are printed to the terminal. this flag defaults to true for warning and error messages, and false for others. 🌸

note that fatal_message() messages and exceptions do not honor the value of dump_fatal_messages(), and always print their message and throw their exception unless trapped with an eval. no negotiating. 💀

• queue_error_messages

$obj->queue_error_messages(0);
$flag = $obj->queue_error_messages();

get or set the flag which controls whether messages sent via error_message() are saved into a list. if true, every message sent is saved and can be retrieved with error_messages() or error_messages_arrayref(). this flag defaults to false for all message types. 🎀

• error_messages_callback

$obj->error_messages_callback($subref);
$subref = $obj->error_messages_callback();

get or set the callback run whenever an error_message is sent. this callback is run with two arguments: the object or class error_message() was called on, and a string containing the message. this callback is run before the message is printed to the terminal or queued into its list. the callback can modify the message (by writing to $_[1]) and affect the message that is printed or queued. if $_[1] is set to undef, then no message is printed or queued, and the last recorded message is set to undef, just like when calling error_message with undef as the argument. 🦋

• error_messages

@list = $obj->error_messages();

if the queue_error_messages flag is on, then this method returns the entire list of queued messages. 📜

when called as an instance method, it returns the errors queued only on that object. when called as a class method, it returns the errors queued on that class, all its subclasses, and all instances of that class or subclasses. so many messages, all accounted for. 💜

• error_messages_arrayref

$listref = $obj->error_messages_arrayref();

if the queue_error_messages flag is on, then this method returns a reference to the actual list where messages get queued. this list can be manipulated to add or remove items. yes, you can touch it. 🔥

• error_message_source

%source_info = $obj->error_message_source

returns a hash of information about the most recent call to error_message. the key error_message contains the message. the keys error_package, error_file, error_line and error_subroutine contain info about the location in the code where error_message() was called. receipt: attached. 🧾

• error_package
• error_file
• error_line
• error_subroutine

these methods return the same data as $obj->error_message_source(). ⭐

---

🌈 SEE ALSO 🌈

• UR(3)

---

that's the whole page bestie, you ate that 💅✨ — this was the UR::ModuleBase(3pm) manual, generated from perl v5.32.1, dated 2022-01-17. mwah, go forth and inherit responsibly 🫶💖