/ 
Kaiten-Container-0.25
River stage zero No dependents
/ Kaiten::Container

NAME

Kaiten::Container - Simples dependency-injection (DI) container, distant relation of IoC.

VERSION

Version 0.25

SYNOPSIS

This module resolve dependency injection conception in easiest way ever. You are just create some code first and put it on kaiten in named container. Later you take it by name and got yours code result fresh and crispy.

No more humongous multi-level dependency configuration, service provider and etc.

You got what you put on, no more, no less.

Ok, a little bit more - Kaiten::Container run |probe| sub every time when you want to take something to ensure all working properly.

And another one - KC try to re-use |handler| return if it requested.

Ah, last but not least - KC MAY resolve deep dependencies, if you need it. Really. A piece of cake!

use Kaiten::Container;

my $config = {
     ExampleP => {
         handler  => sub {
            return DBI->connect( "dbi:ExampleP:", "", "", { RaiseError => 1 } ) or die $DBI::errstr;
          },
         probe    => sub { shift->ping() },
         settings => { reusable => 1 }
     },
};

my $container = Kaiten::Container->new( init => $config );
my $dbh = $container->get_by_name('ExampleP');

All done, now we are have container and may get DB handler on call. Simple!

SUBROUTINES/METHODS

new(%init_configuration?)

This method create container with entities as |init| configuration hash values, also may called without config. Its possible add all entities later, with add method.

my $config = {
     examplep_config => {
        handler  => sub { { RaiseError => 1 } },
        probe    => sub { 1 },
        settings => { reusable => 1 },
     },
     examplep_dbd => {
        handler  => sub { "dbi:ExampleP:" },
        probe    => sub { 1 },
        settings => { reusable => 1 },      
     },
     # yap! this is deep dependency example.
     ExampleP => {
         handler  => sub { 
            my $c = shift;
            
            my $dbd = $c->get_by_name('examplep_dbd');
            my $conf = $c->get_by_name('examplep_config');
            
            return DBI->connect( $dbd, "", "", $conf ) or die $DBI::errstr;
          },
         probe    => sub { shift->ping() },
         settings => { reusable => 1 }
     },
     test => {
         handler  => sub        { return 'Hello world!' },
         probe    => sub        { return 1 },
    },
};

my $container = Kaiten::Container->new( init => $config );

Entity MUST have:

- unique name

- |handler| sub - its return something helpfully

- |probe| sub - its must return true, as first arguments this sub got |handler| sub result.

Entity MAY have settings hashref:

- 'reusable' if it setted to true - KC try to use cache. If cached handler DONT pass probe KC try to create new one instance.

NB. New instance always be tested by call |probe|. If you dont want test handler - just cheat with

probe => sub { 1 }

but its bad idea, I notice you.

Something about deep dependencies

Its here, its worked.

handler  => sub {
   # any handler sub get container as first arg
   my $container = shift;
   
   my $dbd = $container->get_by_name('examplep_dbd');
   my $conf = $container->get_by_name('examplep_config');
   
   return DBI->connect( $dbd, "", "", $conf ) or die $DBI::errstr;
 },

Warning! Its been worked predictably only at ONE container scope. Mixing deep dependencies from different containers seems... hm, you know, very strange.

What about circular dependencies? Its cause 'die'. Don`t do that.

get_by_name($what)

Use this method to execute |handler| sub and get it as result.

my $dbh = $container->get_by_name('ExampleP');
# now $dbh contain normal handler to ExampleP DB

add(%config)

Use this method to add some more entities to container.

my $configutarion_explodable = {
       explode => {
                    handler  => sub        { return 'ExplodeSQL there!' },
                    probe    => sub        { state $a= [ 1, 0, 0 ]; return shift @$a; },
                    settings => { reusable => 1 }
                  },
       explode_now => { 
                    handler => sub { return 'ExplodeNowSQL there!' },
                    probe    => sub        { 0 },
                    settings => { reusable => 1 }
                  },
};

$container->add(%$configutarion_explodable); # list, NOT hashref!!!

remove(@what)

This method remove some entities from container

$container->remove('explode_now','ExampleP'); # list, NOT arayref!!!

show_list

Use this method to view list of available handler in container

my @handler_list = $container->show_list;

# @handler_list == ( 'explode', 'test' )

NB. Entities sorted with perl sort function

test(@what?)

Use this method to test handlers works correctly. If no handlers name given - will be tested ALL.

my $test_result = $container->test();

Method return 1 if it seems all ok, or die.

READ THIS TWISE:

Very helpfully for TEST suite, especially if deep dependency used. Using this method at production are pointless, remember that.

AUTHOR

Meettya, <meettya at cpan.org>

BUGS

Please report any bugs or feature requests to bug-kaiten-container at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Kaiten-Container. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

DEVELOPMENT

Repository

https://github.com/Meettya/Kaiten-Container

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Kaiten::Container

You can also look for information at:

SEE ALSO

Bread::Board - a Moose-based DI framework

IOC - the ancestor of Bread::Board

Peco::Container - another DI container

IOC::Slinky::Container - an alternative DI container

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Meettya.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.