Object...ner::ja(3pm)

✨ NAME ✨

Object::Container::ja — a simple object container interface, periodt 💅✨

---

🦋 SYNOPSIS 🦋

use Object::Container;

## OO インタフェース
# 初期化
my $container = Object::Container->new;

# クラスを登録
$container->register('HTML::TreeBuilder');

# クラスをイニシャライザ指定して登録
$container->register('WWW::Mechanize', sub {
    my $mech = WWW::Mechanize->new( stack_depth => 1 );
    $mech->agent_alias('Windows IE 6');
    return $mech;
});

# 登録したオブジェクトを得る
my $mech = $container->get('WWW::Mechanize');

## Singletonインタフェース
my $container = Object::Container->instance;

# Singletonインタフェースの場合はregister/getはクラスメソッドとして動作する
Object::Container->register('WWW::Mechanize');
my $mech = Object::Container->get('WWW::Mechanize');

# Singletonインタフェースはget関数を任意の名前でエクスポートできる
use Object::Container 'container';
container->register('WWW::Mechanize');
my $mech = container->get('WWW::Mechanize');
my $mech = container('WWW::Mechanize'); # save as above

# Singletonインタフェースのサブクラス化
package MyObj;
use Object::Container '-base';

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

---

💖 DESCRIPTION 💖

okay so bestie, here's the tea ☕ — Object::Container is a module that gives you a simple object container you can drive through either the Singleton interface or the OO interface. Both. Choose your fighter. ✨

Sometimes in an app you want the same object to pop up in a bunch of different places, right? And yeah, you could design around something like Class::Singleton so you can pull that object out from literally anywhere — but with that approach you end up having to subclass the class you actually wanted to use, which is giving extra work ngl 😭

This module does it differently: it hands you a container that can hold multiple objects, and by making the container itself a Singleton, you can easily get at all those objects from wherever you are. Iconic behavior.

The design philosophy is lowkey similar to a module called Object::Registrar, but there are two big differences: this one has an OO interface, and it does not initialize registered objects until they're actually needed (lazy execution). No premature vibes allowed. 💅

🌸 OOインターフェースとSingletonインターフェース 🌸

This module comes with two flavors of interface: the OO interface and the Singleton interface.

The OO interface looks like

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

— you call the constructor and then register and fetch objects through the object it hands back. In this mode, the registered objects are independent per container object. So like,

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

and you can juggle multiple containers and use whichever one you want for what. Very main character energy. 👑

The Singleton interface looks like

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

— you do not explicitly call the constructor; instead you use the one single object assigned to the class. One container to rule them all, iykyk.

When you're on the Singleton interface, functions like register and get can all be used as class methods, like

Object::Container->register('WWW::Mechanize', sub { WWW::Mechanize->new( stack_depth => 1 ) });

And if you want multiple containers while on the Singleton interface, you subclass:

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

easy peasy. 🫶

🌈 SingletonインタフェースとEXPORT関数 🌈

So for everyone out there who's like, "ugh, typing

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

every single time is so tiring" — bestie, say less, there's a feature that lets you EXPORT the container under whatever name you want. 🎀

You just specify the function name you wanna export at use time:

use MyContainer 'obj';

And then boom, you can hit the container with all these short little forms:

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

obj->get('mech');
obj('mech');      # shortcut to obj->get('mech')

So compact, so cute, so slay. 💅

💜 Singletonインタフェースとサブクラス化 💜

And for everyone who's like, "typing

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

inside a Singleton-interface subclass is also so tiring" — don't worry, there's an interface for the subclassing case too. 🦋

When you subclass, instead of doing

use base 'Object::Container';

you do

use Object::Container '-base';

and that exports a function called register. Then, instead of the __PACKAGE__->register from before, you get to write

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

obsessed, honestly. 💖

⭐ 遅延ロードと依存性解決 ⭐

Objects registered with the register method get initialized for the very first time when you first run the get method. Lazy queens only. 💅

Object::Container->register('WWW::Mechanize', sub { WWW::Mechanize->new }); # ここで WWW::Mechanize->new は実行されない
my $mech = Object::Container->get('WWW::Mechanize'); # ここで実行される

not me being obsessed with lazy loading 💅 only the classes you actually need get initialized, so you're not out here burning a ton of resources

Because of this feature, even if a whole bunch of classes are registered, only the ones you need get initialized — so you're not chewing through a massive pile of resources, which means it's easy to drop into non-persistent processes too. Resource-friendly icon behavior 🌱✨

On top of that, the Singleton interface can also resolve dependencies between objects when you pair it with initializer functions.

Like, picture an LWP::UserAgent that depends on an HTTP::Cookies object. In that case:

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 );
});

By using the get method inside the initializer function like this, you resolve the dependency. 🧚

In the above case,

my $ua = Object::Container->get('LWP::UserAgent');

will initialize both LWP::UserAgent and HTTP::Cookies. Two for one, we love to see it 🔥

If you wanna initialize at the same time as registering, you can do it like this:

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

You can also specify the initializer option:

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 });

And this is the same as writing:

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');

And if you specify the args option:

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

well, as you already know by now, that's the same as:

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

💖 METHODS 💖

---

🌸 register( $class, @args )

🌸 register( $class_or_name, $initialize_code )

Okay bestie so this is how you put an object into the Object::Container. Let's go. ✨

The most babygirl-simple way to do it is registering just the class name, like:

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

and when you get it, it literally just calls WWW::Mechanize->new with no arguments at all. Clean. Simple. Iconic.

But wait — what if you want to pass arguments to new? Then you do:

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

and everything from the second argument onward gets passed straight to new, untouched, exactly as-is. No notes. 💅

Now, if you need a constructor that isn't new, or you've got extra setup to do, or you've got some dependent modules hanging around — that's when you hand over a code reference as the second argument and it'll run literally any initialization you want:

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

🫶 Heads up bestie: this code reference has to return the object that's gonna go into the container. That's the whole point, no cap.

And here's the cute part — when you pass an init function like this, the first argument doesn't have to be a class name at all! You can call it literally anything you want:

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

and that's a totally valid vibe too. Multiple user agents, each with their own lil name. Obsessed. 🎀

---

🌸 get($class_or_name)

This is how you go get an object you already registered with the register method. 🦋

The argument you pass it is literally the same thing as the first argument you gave to register. Matchy matchy, that's the rule. ✨

---

🌸 ensure_class_loaded($class)

A lil utility function that checks whether $class is loaded, and if it isn't, it goes ahead and uses it for you. So helpful honestly. 😭

It's lowkey perfect for when your init function has dependencies baked in and you want to lazy-load those dependent modules. Chef's kiss. 👑

---

🌸 load_all

🌸 load_all_except(@classes_or_names)

So here's the tea: this module basically does not initialize objects until it absolutely has to (like, until get gets called). Delayed gratification, main character energy. ✨

But sometimes you want everything initialized upfront — like for "Copy-On-Write", or when you're prioritizing runtime speed. In those cases you just go:

Object::Container->load_all;

and boom, every single object is now already initialized. Done. 💅

And if there's a specific object you don't want initialized? Say less:

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

That initializes every object except the ones you don't want initialized. So in the example above, everything except the objects called Foo and Bar gets initialized. So specific. So demure. 🎀

---

🌈 EXPORT FUNCTIONS ON SUBCLASS INTERFACE 🌈

package MyContainer;
use strict;
use warnings;
use Object::Container '-base';

Do that and you inherit from Object::Container and get to define your very own container class. Your container, your rules. 👑

And inside this subclass, you can define objects using the following functions. Let's go:

---

🌸 register( $class, @args )

🌸 register( $class_or_name, $initialize_code )

register Foo => sub {
    my ($self) = @_;
    $self->ensure_class_loaded('Foo');
    Foo->new;
};

This registers an object, and it does the exact same job as the class (object) method "register" we already talked about up there. Same energy, different interface. 💖

---

🌸 preload(@classes_or_names)

🌸 preload_all

🌸 preload_all_except

These are the functions you can use just like the class (object) methods "load_all" and "load_all_except" — and like, the names literally tell you everything: "preload_all" corresponds to "load_all", and "preload_all_except" corresponds to "load_all_except". Matching pairs, as they should be. ✨

---

🌸 SEE ALSO 🌸

Class::Singleton, Object::Registrar.

---

💜 AUTHOR 💜

Daisuke Murase <typester@cpan.org>

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright (c) 2009 by KAYAC Inc.

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.

---

And that's a wrap bestie!! 🫶 This page is perl v5.34.0, dated 2022-07-22, and it's the Object...ner::ja(3pm) manpage — go forth and containerize your objects, you absolute legend. 💖✨🌸