Components

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

An "AUTOLOAD" method allows you to access any component by name. It will be loaded and instantiated automatically. The "AUTOLOAD" method also generates the missing method so that you can avoid the overhead of the "AUTOLOAD" method the next time you call it.

    my $filesystem = $hub->filesystem;

You can add your own component to a hub and they will be available in the same way.

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

Delegates

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

You can easily define your own delegate methods.

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

Subclassing Badger::Hub

    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

Note that this behaviour implicitly creates circular references between the hub and its delegates. This is intentional. It ensures that the hub and delegates keep each other alive until the hub is explicitly destroyed and the references are freed. Having the hub stick around for as long as possible is usually a Good Thing. It acts as a singleton providing a central point of access to the resources that 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 the cases where you would need to are few and far between) then you are responsible for calling the destroy() method when you're done with it. This will manually break the circular references and free up any memory used by the hub and any delegates it is using. If you don't call the destroy() method then the hub will remain alive until the end of the program when the memory will be freed as usual. In most cases this is perfectly acceptable.

However, you generally don't need to worry about any of this because you wouldn't normally create a hub manually. Instead, you would 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 is no reference from the hub back to the Badger façade object you don't have to worry about circular references. The Badger object is correctly freed and that ensures the hub gets cleaned up.

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

If you call "Badger" methods as class methods then they are forwarded to a prototype object (effectively a singleton object). That in turn will use a prototype hub object. In this case, both the "Badger" and "Badger::Hub" objects will exist until the end of the program. This ensures that 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');

new()

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

components()

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

component($name)

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

delegates()

    # 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)

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

destroy()

construct($component,\%params)

    # 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)

auto_component($name,$module)

auto_delegate($name,$component)

config()