NAME

MooseX::Orochi - Annotated Your Moose Classes With Orochi

SYNOPSIS

    package MyApp::MyClass;
    use Moose;
    use MooseX::Orochi;

    bind_constructor '/myapp/myclass' => (
        args => {
            arg1 => bind_value '/myapp/some/dep1',
            arg2 => bind_value '/myapp/some/dep2',
        }
    );

    # you can also inject random things
    inject '/foo/bar/baz' => Orochi::Injection::Constructor->new(
        class => 'FooBar',
        args  => { ... }
    );

    has arg1 => (...);
    has arg2 => (...);

    # Then, somewhere in your main code...

    my $c = Orochi->new();
    $c->inject_class( 'MyApp::MyClass' );

    my $object = $c->get( '/myapp/myclass' );

DESCRIPTION

MooseX::Orochi is a transparent add-on to your Moose-based classes that allows create a Depdency Injection Containers. If you don't know what that is, it basically allows you to define and assemble a set of objects that depend on eachother with no external configuration required.

With MooseX::Orochi, all you really need to do is

    1. Build a set of objects with MooseX::Orochi annotations
    2. use Orochi->inject_class() to inject your definitions
    3. use Orochi->get() to access the resulting objects.

PROVIDED DSL

bind_constructor $path => %injection_args

Creates a Orochi::Injection::Constructor (or subclass thereof)

bind_value $path

Returns a Orochi::Injection::BindValue object, which will materialize when the containing Injection is expanded.

inject $path => $injection

Injects the given injection.

ANNOTATIONS WITH MooseX::Orochi

Suppose you have a dependency graph like the following:

  MyApp ---> MyApp::Model::Foo ---> MyApp::Schema ---> DBI Args
                               |
                               ---> MyApp::Logger ---> File Name

If you're building everything based on moose from scratch, you will define this dependency like the following. First, MyApp:

  package MyApp;
  use Moose;
  use MooseX::Orochi;

  has 'foo' => (
    is => 'ro',
    isa => 'MyApp::Model::Foo'
  );

  bind_constructor 'myapp' => (
    args => {
      foo => bind_value 'myapp/model/foo'
    }
  );

Notice the use of MooseX::Orochi, and the calls to bind_constructor. It tells us that an instance of MyApp can be retrieved by the name 'myapp'

  $c->get('myapp');

and that the value for argument foo should be taken from another injected resource named 'myapp/model/foo'

  MyApp->new(foo => $c->get('myapp/model/foo'));

If you were to use Setter injection instead, then it will lead to Orochi calling Orochi::Injection::Setter, which in turn will call MyApp's constructor, and setter(s) like so:

  bind_constructor 'myapp' => (
    injection_type => 'Setter',
    setter_params => {
      foo => bind_value 'myapp/model/foo'
    }
  );

  # above will trigger the following code:
  my $app = MyApp->new();
  $app->foo($c->get('myapp/model/foo'));

The rest of the classes works mostly the same way. Here's MyApp::Model::Foo, and MyApp::Logger:

  package MyApp::Model::Foo;
  use Moose;
  use MooseX::Orochi;

  has 'schema' => (
    is => 'ro',
    isa => 'MyApp::Schema',
  );

  bind_constructor 'myapp/model/foo' => (
    args => {
      schema => bind_value 'myapp/schema',
      logger => bind_value 'myapp/logger',
    }
  );

  package MyApp::Logger;
  use Moose;
  use MooseX::Orochi;
  use MooseX::Types::Path::Class;

  has 'filename' => (
    is => 'ro',
    isa => 'Path::Class::File',
    coerce => 1
  );

  bind_constructor 'myapp/logger' => (
    args => {
      filename => bind_value 'myapp/logger/filename'
    }
  );

MyApp::Schema is a bit different, in that it is DBIx::Class::Schema based, and you won't be calling new() to instantiate it (you'd call connection()), and you don't pass a name => value pair (you'd pass @connect_info).

  package MyApp::Schema;
  use Moose;
  use MooseX::Orochi;
  extends 'DBIx::Class::Schema';

  bind_contructor 'schema/master' => (
    args        => bind_value 'myapp/schema/connect_info',
    deref_args  => 1,
    constructor => 'connection'
  );

Here, we declare that MyApp::Schema will use myapp/schema/connect_info as its arguments (which will be de-referenced when passed to the constructor), and that we should use the method named 'connection' as the constructor.

The value to 'myapp/schema/connect_info' needs to be declared else where:

  my $c = Orochi->new();
  $c->inject_literal(
    'myapp/schema/connect_info' => [ 'dbi:mysql:dbname=foo', .... ] );

Finally, we need to put everything together by registering these classes to our Orochi instance:

  my $c = Orochi->new();
  $c->inject_literal(
    'myapp/logger/filename' => '/path/to/file.txt');
  $c->inject_literal(
    'myapp/schema/connect_info' => [ 'dbi:mysql:dbname=foo', .... ] );
  $c->inject_class($_) for qw(
    MyApp::Logger
    MyApp::Schema
    MyApp::Model::Foo
    MyApp
  );
  # or $c->inject_namespace('MyApp');

  my $app = $c->get('myapp');

There are sometimes those modules that you just can touch from outside. In those cases, you will have to provide the objects yourself:

  $c->inject('/path/to/another/dependency' => 
    $c->construct( sub { ... } ) );

SUBCLASS

Once you use MooseX::Orochi, every subclass can re-use the bind instructions.

    package MyApp;
    use Moose;
    use MooseX::Orochi;

    bind_constructor 'myapp' => ( ... );


    package MyApp::Extended;
    use Moose;

    extends 'MyApp';

In the above case, unless you explicitly override the bind instructions in MyApp::Extended, you can inject MyApp::Extended and expect it to be available at

    $c->get('myapp');

TODO

Documentation. Samples. Tests.

AUTHOR

Daisuke Maki <daisuke@endeworks.jp>

LICENSE

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

See http://www.perl.com/perl/misc/Artistic.html

cpanm Orochi

perl -MCPAN -e shell
install Orochi