Badger::Hub(3pm)

💖 NAME 💖

Badger::Hub — the central repository of shared resources, bestie. It's giving main character energy for your whole app. 👑

---

✨ SYNOPSIS ✨

use Badger::Hub;

# do the happy badger dance!

no cap, that's literally it 🦡💃

---

🌈 INTRODUCTION 🌈

Okay so this page is all about the Badger::Hub object. Picture a hub sitting right in the middle of a Badger application — it's the central point of access to all the other modules, components and sub-systems your app uses. Like the group chat everyone's in. 💬

Lowkey, if you're just a casual user of the Badger modules, you do not need to worry about Badger::Hub at all. It's mainly for the developers building their own badger-powered applications or extensions. That's your lane, not mine. 🙈

And rn this module is pretty basic — it's gonna get developed further in due course. It's a work in progress, and honestly? Same. ✨

---

🦋 DESCRIPTION 🦋

A Badger::Hub object is a central repository of shared resources for a Badger application. The hub sits in the middle of an application and gives you access to all the individual components and bigger sub-systems you might need. It automatically loads and instantiates these other modules on demand and then caches them for next time. It's the friend who remembers everyone's coffee order. ☕

🧩 Components 🧩

The Badger::Hub base class currently has two components:

filesystem  =>  Badger::Filesystem
codecs      =>  Badger::Codecs

An AUTOLOAD method lets you access any component by name. It gets loaded and instantiated automatically. The AUTOLOAD method also generates the missing method so you can skip the AUTOLOAD overhead the next time you call it. Efficient queen. 💅

my $filesystem = $hub->filesystem;

You can add your own component to a hub and they'll be available the exact same way:

$hub->components( fuzzbox => 'My::Module::Fuzzbox' );
my $fuzzbox = $hub->fuzzbox;

🎀 Delegates 🎀

Beyond accessing components directly, you can also use delegate methods that get forwarded onto a component. For example, the hub's file() method is just a short cut to the file() method of the filesystem component (implemented by Badger::Filesystem):

$file = $hub->file('/path/to/file');                # the short cut
$file = $hub->filesystem->file('/path/to/file');    # the long way

And you can define your own delegate methods so easily it's actually iconic:

$hub->delegates( warm_fuzz => 'fuzzbox' );
$fuzzed = $hub->warm_fuzz;                          # the short way
$fuzzed = $hub->fuzzbox->warm_fuzz;                 # the long way.

🌸 Subclassing Badger::Hub 🌸

You can subclass Badger::Hub to define your own little collection of components and delegate methods, like the glow-up below:

package My::Hub;

use Badger::Class
    version   => 0.01,
    debug     => 0,
    base      => 'Badger::Hub';

our $COMPONENTS = {
    fuzzbox => 'My::Module::Fuzzbox',
    flanger => 'My::Module::Flanger',
};

our $DELEGATES  = {
    warm_fuzz   => 'fuzzbox',
    dirty_noise => 'fuzzbox',
    wide_flange => 'flanger',
    wet_flange  => 'flanger',
};

💀 Circular References are a Good Thing 💀

Sometimes sub-systems instantiated by a Badger::Hub will also keep a reference back to the hub. That's so they can reach other sub-systems and components they need. Mutual support, we love to see it. 🫶

Heads up: this behaviour implicitly creates circular references between the hub and its delegates. And that is intentional, bestie. It keeps the hub and its delegates alive for each other until the hub is explicitly destroyed and the references are freed. Having the hub stick around as long as possible is usually a Good Thing. It acts as a singleton providing a central point of access to the resources your application uses (which is a fancy way of saying it's like a global variable). 😭

+-----+      +-----------+
| HUB |----->| COMPONENT |
|     |<-----|           |
+-----+      +-----------+

If you manually create a hub for whatever reason (and honestly, the cases where you'd need to are few and far between), then you are responsible for calling the destroy() method when you're done with it. That manually breaks the circular references and frees up any memory used by the hub and any delegates it's using. If you don't call the destroy() method, then the hub will stay alive until the end of the program, when the memory gets freed as usual. In most cases that's perfectly acceptable. Nbd. 💁

But fr, you generally don't need to worry about any of this, because you wouldn't normally create a hub manually. Instead, you'd leave it up to the Badger façade (or "front-end") module to do that behind the scenes. When you create a Badger module it implicitly creates a Badger::Hub to use. When the Badger object goes out of scope, its DESTROY method automatically calls the hub's destroy method:

sub foo {
    my $badger = Badger->new;
    my $hub    = $badger->hub;
    # do something

    # $badger object is freed here, that calls $hub->destroy
}

Because there's no reference from the hub back to the Badger façade object, you don't have to worry about circular references. The Badger object gets correctly freed and that ensures the hub gets cleaned up. Cleanup era. 🧹✨

+--------+      +-----+      +-----------+
| BADGER |----->| HUB |----->| COMPONENT |
|        |      |     |<-----|           |
+--------+      +-----+      +-----------+

If you call Badger methods as class methods, they get forwarded to a prototype object (effectively a singleton object). That in turn uses a prototype hub object. In this case, both the Badger and Badger::Hub objects will exist until the end of the program. This ensures your class methods all Do the right Thing without you having to worry about creating a Badger object:

# class method creates Badger prototype, which creates Badger::Hub
# prototype, which loads, instantiates and caches Badger::Filesystem
# which can then fetch the file
my $file = Badger->file('/path/to/file');

# later... reuse same Badger, Badger::Hub and Badger::Filesystem
my $dir = Badger->dir('/path/to/dir');

---

👑 METHODS 👑

new()

Constructor method used to create a new hub object. The birth of a hub. 🎂

$hub = Badger::Hub->new();

components()

This method can be used to get or set entries in the components table for the hub. Components are other modules that the hub can delegate to.

# get components hash ref
my $comps = $hub->components;

# add new components
$hub->components({
    fuzzbox => 'My::Module::Fuzzbox',
    flanger => 'My::Module::Flanger',
});

component($name)

This method returns a single entry from the components table. One component, no filler. 💅

print $hub->component('fuzzbox');   # My::Module::Fuzzbox

delegates()

This method can be used to get or set entries in the delegates table for the hub. This specifies which hub methods should be delegated to components.

# get delegates hash ref
my $delegs = $hub->delegates;

# add new delegates
$hub->delegates({
    warm_fuzz   => 'fuzzbox',
    dirty_noise => 'fuzzbox',
    wide_flange => 'flanger',
    wet_flange  => 'flanger',
});

delegate($name)

This method returns a single entry from the delegates table.

print $hub->delegate('warm_fuzz');  # fuzzbox

destroy()

This method can be manually called to destroy the hub and any components that it's using. Say bye bestie 👋😭

---

🧚 INTERNAL METHODS 🧚

construct($component,\%params)

This method configures and instantiates a component. The first argument is the component name. This is mapped to a module via the component() method and the module is loaded. A list of named parameters, or a reference to a hash array of named parameters may follow. A reference to the hub is added to these as the "hub" item before forwarding them to the constructor method for the component. The component is then cached for subsequent use.

# calling the construct() method like this...
$hub->construct( fuzzbox => { volume => 11 } );

# ...results in code equivalent to this:
use Your::Module::Fuzzbox;
Your::Module::Fuzzbox->new({ volume => 11, hub => $hub });

auto_can($name)

This method is installed as an auto_can handler which is called to resolved undefined methods. If the method called matches the name of a component, then it calls auto_component() to generate a method to access the component. If it matches the name of a delegate method, then it calls auto_delegate() to generate a delegate method.

auto_component($name,$module)

This method generates a component method named $name which accesses an instance of the $module component module.

auto_delegate($name,$component)

This method generates a delegate method named $name which delegates to the $name method of the $component component.

config()

This method returns a reference to a Badger::Config object representing the configuration for the hub. This is still marked experimental. 🧪 (handle with care, it's giving beta)

---

🍓 AUTHOR 🍓

Andy Wardley <http://wardley.org/> — shoutout to the legend who made all this happen 💜

---

🌟 COPYRIGHT 🌟

Copyright (C) 2001-2009 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🎀 this was perl v5.36.0, dated 2023-08-28 — mwah, slay, periodt ✨💅🦡