.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Object::Container 3pm"
.TH Object::Container 3pm "2022-07-22" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Object::Container \- simple object container
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Object::Container;
\&    
\&    # initialize container
\&    my $container = Object::Container\->new;
\&    
\&    # register class
\&    $container\->register(\*(AqHTML::TreeBuilder\*(Aq);
\&    
\&    # register class with initializer
\&    $container\->register(\*(AqWWW::Mechanize\*(Aq, sub {
\&        my $mech = WWW::Mechanize\->new( stack_depth => 1 );
\&        $mech\->agent_alias(\*(AqWindows IE 6\*(Aq);
\&        return $mech;
\&    });
\&    
\&    # get object
\&    my $mech = $container\->get(\*(AqWWW::Mechanize\*(Aq);
\&    
\&    # also available Singleton interface
\&    my $container = Object::Container\->instance;
\&    
\&    # With singleton interface, you can use register/get method as class method
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq);
\&    my $mech = Object::Container\->get(\*(AqWWW::Mechanize\*(Aq);
\&    
\&    # Export singleton interface
\&    use Object::Container \*(Aqcontainer\*(Aq;
\&    container\->register(\*(AqWWW::Mechanize\*(Aq);
\&    my $mech = container\->get(\*(AqWWW::Mechanize\*(Aq);
\&    my $mech = container(\*(AqWWW::Mechanize\*(Aq); # same as above
\&    
\&    # Subclassing singleton interface
\&    package MyContainer;
\&    use Object::Container \*(Aq\-base\*(Aq;
\&    
\&    register mech => sub { WWW::Mechanize\->new };
\&    
\&    # use it
\&    use MyContainer \*(Aqcon\*(Aq;
\&    
\&    con(\*(Aqmech\*(Aq)\->get(\*(Aqhttp://example.com\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a object container interface which supports both \s-1OO\s0 interface and Singleton interface.
.PP
If you want to use one module from several places, you might use Class::Singleton to access the module from any places. But you should subclass each modules to singletonize.
.PP
This module provide singleton container instead of module itself, so it is easy to singleton multiple classes.
.PP
Object::Registrar is a similar module to this. But Object::Container has also \s-1OO\s0 interface and supports lazy initializer. (describing below)
.SS "\s-1OO\s0 and Singleton interfaces"
.IX Subsection "OO and Singleton interfaces"
This module provide two interfaces: \s-1OO\s0 and Singleton.
.PP
\&\s-1OO\s0 interface is like this:
.PP
.Vb 1
\&    my $container = Object::Container\->new;
.Ve
.PP
It is normal object oriented interface. And you can use multiple container at the same Time:
.PP
.Vb 2
\&    my $container1 = Object::Container\->new;
\&    my $container2 = Object::Container\->new;
.Ve
.PP
Singleton is also like this:
.PP
.Vb 1
\&    my $container = Object::Container\->instance;
.Ve
.PP
instance method always returns singleton object. With this interface, you can 'register' and 'get' method as class method:
.PP
.Vb 2
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq);
\&    my $mech = Object::Container\->get(\*(AqWWW::Mechanize\*(Aq);
.Ve
.PP
When you want use multiple container with Singleton interface, you have to create subclass like this:
.PP
.Vb 2
\&    MyContainer1\->get(\*(AqWWW::Mechanize\*(Aq);
\&    MyContainer2\->get(\*(AqWWW::Mechanize\*(Aq);
.Ve
.SS "Singleton interface with \s-1EXPORT\s0 function for lazy people"
.IX Subsection "Singleton interface with EXPORT function for lazy people"
If you are lazy person, and don't want to write something long code like:
.PP
.Vb 1
\&    MyContainer\->get(\*(AqWWW::Mechanize\*(Aq);
.Ve
.PP
This module provide export functions to shorten this.
If you use your container with function name, the function will be exported and act as container:
.PP
.Vb 1
\&    use MyContainer \*(Aqcontainer\*(Aq;
\&    
\&    container\->register(...);
\&    
\&    container\->get(...);
\&    container(...);             # shortcut to \->get(...);
.Ve
.SS "Subclassing singleton interface for lazy people"
.IX Subsection "Subclassing singleton interface for lazy people"
If you are lazy person, and don't want to write something long code in your subclass like:
.PP
.Vb 1
\&    _\|_PACKAGE_\|_\->register( ... );
.Ve
.PP
Instead of above, this module provide subclassing interface.
To do this, you need to write below code to subclass instead of \f(CW\*(C`use base\*(C'\fR.
.PP
.Vb 1
\&    use Object::Container \*(Aq\-base\*(Aq;
.Ve
.PP
And then you can register your object via \s-1DSL\s0 functions:
.PP
.Vb 1
\&    register ua => sub { LWP::UserAgent\->new };
.Ve
.SS "lazy loading and resolve dependencies"
.IX Subsection "lazy loading and resolve dependencies"
The object that is registered by 'register' method is not initialized until calling 'get' method.
.PP
.Vb 2
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq, sub { WWW::Mechanize\->new }); # doesn\*(Aqt initialize here
\&    my $mech = Object::Container\->get(\*(AqWWW::Mechanize\*(Aq); # initialize here
.Ve
.PP
This feature helps you to create less resource and fast runtime script in case of lots of object registered.
.PP
And you can resolve dependencies between multiple modules with Singleton interface.
.PP
For example:
.PP
.Vb 5
\&    Object::Container\->register(\*(AqHTTP::Cookies\*(Aq, sub { HTTP::Cookies\->new( file => \*(Aq/path/to/cookie.dat\*(Aq ) });
\&    Object::Container\->register(\*(AqLWP::UserAgent\*(Aq, sub {
\&        my $cookies = Object::Container\->get(\*(AqHTTP::Cookies\*(Aq);
\&        LWP::UserAgent\->new( cookie_jar => $cookies );
\&    });
.Ve
.PP
You can resolve dependencies by calling 'get' method in initializer like above.
.PP
In that case, only LWP::UserAgent and HTTP::Cookies are initialized.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Create new object.
.SS "instance"
.IX Subsection "instance"
Create singleton object and return it.
.ie n .SS "register( $class, @args )"
.el .SS "register( \f(CW$class\fP, \f(CW@args\fP )"
.IX Subsection "register( $class, @args )"
.ie n .SS "register( $class_or_name, $initialize_code )"
.el .SS "register( \f(CW$class_or_name\fP, \f(CW$initialize_code\fP )"
.IX Subsection "register( $class_or_name, $initialize_code )"
.ie n .SS "register( { class => $class_or_name ... } )"
.el .SS "register( { class => \f(CW$class_or_name\fP ... } )"
.IX Subsection "register( { class => $class_or_name ... } )"
Register classes to container.
.PP
Most simple usage is:
.PP
.Vb 1
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq);
.Ve
.PP
First argument is class name to object. In this case, execute 'WWW::Mechanize\->new' when first get method call.
.PP
.Vb 1
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq, @args );
.Ve
.PP
is also execute 'WWW::Mechanize\->new(@args)'.
.PP
If you use different constructor from 'new', want to custom initializer, or want to include dependencies, you can custom initializer to pass a coderef as second argument.
.PP
.Vb 5
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq, sub {
\&        my $mech = WWW::Mechanize\->new( stack_depth );
\&        $mech\->agent_alias(\*(AqWindows IE 6\*(Aq);
\&        return $mech;
\&    });
.Ve
.PP
This coderef (initialize) should return object to contain.
.PP
With last way you can pass any name to first argument instead of class name.
.PP
.Vb 2
\&    Object::Container\->register(\*(Aqua1\*(Aq, sub { LWP::UserAgent\->new });
\&    Object::Container\->register(\*(Aqua2\*(Aq, sub { LWP::UserAgent\->new });
.Ve
.PP
If you want to initialize and register at the same time, the following can.
.PP
.Vb 1
\&    Object::Container\->register({ class => \*(AqLWP::UserAgent\*(Aq, preload => 1 });
.Ve
.PP
\&\fIinitializer\fR option can be specified.
.PP
.Vb 5
\&    Object::Container\->register({ class => \*(AqWWW::Mechanize\*(Aq, initializer => sub {
\&        my $mech = WWW::Mechanize\->new( stack_depth );
\&        $mech\->agent_alias(\*(AqWindows IE 6\*(Aq);
\&        return $mech;
\&    }, preload => 1 });
.Ve
.PP
This is the same as written below.
.PP
.Vb 6
\&    Object::Container\->register(\*(AqWWW::Mechanize\*(Aq, sub {
\&        my $mech = WWW::Mechanize\->new( stack_depth );
\&        $mech\->agent_alias(\*(AqWindows IE 6\*(Aq);
\&        return $mech;
\&    });
\&    Object::Container\->get(\*(AqWWW::Mechanize\*(Aq);
.Ve
.PP
If you specify \fIargs\fR option is:
.PP
.Vb 1
\&    Object::Container\->register({ class => \*(AqLWP::UserAgent\*(Aq, args => \e@args, preload => 1 });
.Ve
.PP
It is, as you know, the same below.
.PP
.Vb 2
\&    Object::Container\->register(\*(AqLWP::UserAgent\*(Aq, @args);
\&    Object::Container\->get(\*(AqLWP::UserAgent\*(Aq);
.Ve
.SS "unregister($class_or_name)"
.IX Subsection "unregister($class_or_name)"
Unregister classes from container.
.SS "get($class_or_name)"
.IX Subsection "get($class_or_name)"
Get the object that registered by 'register' method.
.PP
First argument is same as 'register' method.
.SS "remove($class_or_name)"
.IX Subsection "remove($class_or_name)"
Remove the cached object that is created at \f(CW\*(C`get\*(C'\fR method above.
.PP
Return value is the deleted object if it's exists.
.SS "ensure_class_loaded($class)"
.IX Subsection "ensure_class_loaded($class)"
This is utility method that load \f(CW$class\fR if \f(CW$class\fR is not loaded.
.PP
It's useful when you want include dependency in initializer and want lazy load the modules.
.SS "load_all"
.IX Subsection "load_all"
.SS "load_all_except(@classes_or_names)"
.IX Subsection "load_all_except(@classes_or_names)"
This module basically does lazy object initializations, but in some situation, for Copy-On-Write or for runtime speed for example, you might want to preload objects.
For the purpose \f(CW\*(C`load_all\*(C'\fR and \f(CW\*(C`load_all_except\*(C'\fR method are exists.
.PP
.Vb 1
\&    Object::Container\->load_all;
.Ve
.PP
This method is load all registered object at once.
.PP
Also if you have some objects that keeps lazy loading, do like following:
.PP
.Vb 1
\&    Object::Container\->load_all_except(qw/Foo Bar/);
.Ve
.PP
This means all objects except 'Foo' and 'Bar' are loaded.
.SH "EXPORT FUNCTIONS ON SUBCLASS INTERFACE"
.IX Header "EXPORT FUNCTIONS ON SUBCLASS INTERFACE"
Same functions for \f(CW\*(C`load_all\*(C'\fR and \f(CW\*(C`load_all_except\*(C'\fR exists at subclass interface.
Below is list of these functions.
.SS "preload(@classes_or_names)"
.IX Subsection "preload(@classes_or_names)"
.SS "preload_all"
.IX Subsection "preload_all"
.SS "preload_all_except"
.IX Subsection "preload_all_except"
As predictable by name, \f(CW\*(C`preload_all\*(C'\fR is equals to \f(CW\*(C`load_all\*(C'\fR and \f(CW\*(C`preload_all_except\*(C'\fR is equals to <load_all_except>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Class::Singleton, Object::Registrar.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daisuke Murase <typester@cpan.org>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2009 \s-1KAYAC\s0 Inc. All rights reserved.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.