Object...ntainer(3pm)

✨ NAME ✨

Object::Container — literally just a simple object container, bestie. That's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

okay so here's the whole thing in one go, no cap:

use Object::Container;

# initialize container
my $container = Object::Container->new;

# register class
$container->register('HTML::TreeBuilder');

# register class with initializer
$container->register('WWW::Mechanize', sub {
    my $mech = WWW::Mechanize->new( stack_depth => 1 );
    $mech->agent_alias('Windows IE 6');
    return $mech;
});

# get object
my $mech = $container->get('WWW::Mechanize');

# also available Singleton interface
my $container = Object::Container->instance;

# With singleton interface, you can use register/get method as class method
Object::Container->register('WWW::Mechanize');
my $mech = Object::Container->get('WWW::Mechanize');

# Export singleton interface
use Object::Container 'container';
container->register('WWW::Mechanize');
my $mech = container->get('WWW::Mechanize');
my $mech = container('WWW::Mechanize'); # same as above

# Subclassing singleton interface
package MyContainer;
use Object::Container '-base';

register mech => sub { WWW::Mechanize->new };

# use it
use MyContainer 'con';

con('mech')->get('http://example.com');

---

🌸 DESCRIPTION 🌸

So this module is an object container interface, and the iconique thing about it is it supports both an OO interface and a Singleton interface. Versatile queen. 👑

If you wanna use one module from several places, you might reach for Class::Singleton to access the module from any place. But — and this is the annoying part — you'd have to subclass each module to singletonize it. 🙈

This module gives you a singleton container instead of touching the module itself, so singleton-ing multiple classes is actually easy. Main character energy fr fr.

Object::Registrar is a similar module to this one. But Object::Container also has an OO interface and supports a lazy initializer. (describing below, keep reading bestie)

💜 OO and Singleton interfaces

This module provides two interfaces: OO and Singleton.

The OO interface looks like this:

my $container = Object::Container->new;

That's the normal object oriented interface. And you can use multiple containers at the same time:

my $container1 = Object::Container->new;
my $container2 = Object::Container->new;

Singleton is also like this:

my $container = Object::Container->instance;

The instance method always returns the singleton object. With this interface, you can use register and get as class methods:

Object::Container->register('WWW::Mechanize');
my $mech = Object::Container->get('WWW::Mechanize');

When you want to use multiple containers with the Singleton interface, you have to create a subclass like this:

MyContainer1->get('WWW::Mechanize');
MyContainer2->get('WWW::Mechanize');

✨ Singleton interface with EXPORT function for lazy people

If you're a lazy person (same, bestie) and don't want to write long code like:

MyContainer->get('WWW::Mechanize');

This module provides export functions to shorten it. If you use your container with a function name, that function gets exported and acts as the container:

use MyContainer 'container';

container->register(...);

container->get(...);
container(...);             # shortcut to ->get(...);

🎀 Subclassing singleton interface for lazy people

If you're a lazy person and don't want to write long code in your subclass like:

__PACKAGE__->register( ... );

Instead of the above, this module provides a subclassing interface. To do this, you need to write the code below to subclass instead of use base.

use Object::Container '-base';

And then you can register your object via DSL functions:

register ua => sub { LWP::UserAgent->new };

🧚 lazy loading and resolve dependencies

The object that's registered by the register method is not initialized until you call the get method. It's giving patience.

Object::Container->register('WWW::Mechanize', sub { WWW::Mechanize->new }); # doesn't initialize here
my $mech = Object::Container->get('WWW::Mechanize'); # initialize here

This feature helps you create scripts that use less resources and run fast when you've got a lot of objects registered.

And you can resolve dependencies between multiple modules with the Singleton interface.

For example:

Object::Container->register('HTTP::Cookies', sub { HTTP::Cookies->new( file => '/path/to/cookie.dat' ) });
Object::Container->register('LWP::UserAgent', sub {
    my $cookies = Object::Container->get('HTTP::Cookies');
    LWP::UserAgent->new( cookie_jar => $cookies );
});

You can resolve dependencies by calling the get method inside the initializer, like above.

In that case, only LWP::UserAgent and HTTP::Cookies are initialized. Efficient. Slay. 💅

---

🔥 METHODS 🔥

new

Create a new object. Fresh out the box. ✨

instance

Create a singleton object and return it.

register( $class, @args )

register( $class_or_name, $initialize_code )

register( { class => $class_or_name ... } )

Register classes to the container.

The most simple usage is:

Object::Container->register('WWW::Mechanize');

The first argument is the class name to object. In this case, it executes WWW::Mechanize->new when the first get method is called.

Object::Container->register('WWW::Mechanize', @args );

also executes WWW::Mechanize->new(@args).

If you use a different constructor from new, want a custom initializer, or want to include dependencies, you can pass a custom initializer as a coderef for the second argument.

Object::Container->register('WWW::Mechanize', sub {
    my $mech = WWW::Mechanize->new( stack_depth );
    $mech->agent_alias('Windows IE 6');
    return $mech;
});

This coderef (the initialize) should return the object to contain.

With the last way, you can pass any name to the first argument instead of a class name:

Object::Container->register('ua1', sub { LWP::UserAgent->new });
Object::Container->register('ua2', sub { LWP::UserAgent->new });

If you want to initialize and register at the same time, the following works:

Object::Container->register({ class => 'LWP::UserAgent', preload => 1 });

The initializer option can be specified:

Object::Container->register({ class => 'WWW::Mechanize', initializer => sub {
    my $mech = WWW::Mechanize->new( stack_depth );
    $mech->agent_alias('Windows IE 6');
    return $mech;
}, preload => 1 });

This is the same as written below:

Object::Container->register('WWW::Mechanize', sub {
    my $mech = WWW::Mechanize->new( stack_depth );
    $mech->agent_alias('Windows IE 6');
    return $mech;
});
Object::Container->get('WWW::Mechanize');

If you specify the args option it's:

Object::Container->register({ class => 'LWP::UserAgent', args => \@args, preload => 1 });

It is, as you know, the same as below:

Object::Container->register('LWP::UserAgent', @args);
Object::Container->get('LWP::UserAgent');

unregister($class_or_name)

Unregister classes from the container. Bye bestie 👋

get($class_or_name)

Get the object that was registered by the register method.

The first argument is the same as the register method.

remove($class_or_name)

Remove the cached object that was created by the get method above.

The return value is the deleted object, if it exists.

ensure_class_loaded($class)

This is a utility method that loads $class if $class is not loaded.

It's useful when you want to include a dependency in an initializer and want to lazy load the modules.

load_all

load_all_except(@classes_or_names)

This module basically does lazy object initializations, but in some situations — for Copy-On-Write or for runtime speed, for example — you might want to preload objects. For that purpose, the load_all and load_all_except methods exist.

Object::Container->load_all;

This method loads all registered objects at once. Boom. 🔥

Also, if you have some objects that should keep lazy loading, do like following:

Object::Container->load_all_except(qw/Foo Bar/);

This means all objects except Foo and Bar are loaded.

---

🌈 EXPORT FUNCTIONS ON SUBCLASS INTERFACE 🌈

The same functions for load_all and load_all_except exist on the subclass interface. Below is the list of these functions.

preload(@classes_or_names)

preload_all

preload_all_except

As you can predict by the name, preload_all is equals to load_all and preload_all_except is equals to <load_all_except>. Naming skills: immaculate. 💅

---

👀 SEE ALSO 👀

Class::Singleton, Object::Registrar. Go read those too, bestie, iykyk.

---

💖 AUTHOR 💖

Daisuke Murase <typester@cpan.org>

---

📜 COPYRIGHT & LICENSE 📜

Copyright (c) 2009 KAYAC Inc. All rights reserved.

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

The full text of the license can be found in the LICENSE file included with this module.

ok so that's the whole page, and yes, the legal stuff matters, do not skip it. periodt. 🫶

---

and that's a wrap, gorgeous — this was Object...ntainer(3pm) from perl v5.34.0, dated 2022-07-22. go register some objects. mwah. 💜✨