wirer

Wirer

A lightweight dependency injection framework to help wire up objects in Ruby.

Some usage examples for now:

container = Wirer do |c|

SHOWING THE CONTAINER HOW TO CONSTRUCT AN EXISTING CLASS:

This is registered as providing class Logger.

It will be constructed via Logger.new('/option_for_logger.txt')

c.add Logger, '/option_for_logger.txt'

This is registered as providing class Logger, and also providing feature :special_logger

which can then be used to request it in particular situations

c.add :special_logger, Logger, '/special_log.txt'

You can supply a custom block for constructing the dependency if you want;

specifying the class upfront means it still knows what class is provided by the block

c.add(:other_special_logger, Logger) do Logger.new(foo, bar, baz) end

You don't actually have to specify the class that's provided; it will just

provide_class Object by default. In this case you really need to specify

a feature name for it, or else you'll have no way to refer to it:

c.add(:mystery_meat) do rand(2) == 0 ? Mystery.new : Meat.new end

add_new_factory is the more explicit but verbose way to do this.

note in this case you need to specify a :method_name separately if you want a method defined on

the container for it.

c.add_new_factory(:class => Foo, :features => [:foo, :bar], :method_name => :foo) {Foo.new(...)} c.add_new_factory(:class => Logger, :features => [:logger], :method_name => :logger, :args => ['/arg_for_logger.txt'])

SPECIFYING DEPENDENCIES (which will then automatically get constructed and passed into your constructor)

This will be constructed via LogSpewer.new(:logger => logger)

c.add LogSpewer, :logger => Logger

however since two Loggers are available, we might want to specify

a particular one, by making it depend on the feature :special_logger

provided by only one of them.

c.add :special_log_spewer, LogSpewer, :logger => :special_logger

You can specify a combination of class/module and feature name requirements for a

dependency:

c.add :fussy_log_spewer, LogSpewer, :logger => [SpecialLogger, :providing, :these, :features]

USING DEFAULTS and PREFERRED FEATURES TO CHOOSE FROM MANY AVAILABLE DEPENDENCIES

If there are many Loggers available, and you have a dependency on a Logger, how does it

decide which one to give you?

Answer: It will never make an arbitrary choice for you. If there are multiple matching

factories and it has no way to differentiate between them, it will raise an error complaining

about it and let you fix the issue.

You can either refine the dependency to a particular logger, as in the example above

where we asked for a :special_logger.

But it would also be nice if you could nominate one logger as the default to use in the

case of multiple loggers, without having to specifically request it in each case:

c.add Logger, :default => true

which is shorthand for:

c.add Logger, :features => [:default]

this will then be chosen over any other options when resolving a dependency.

(if more than one 'default' is available, it will still complain).

Defaults are actually implemented under the hood using 'preferred features'.

These are extra feature names in addition to the required features for a dependency,

which you'd kinda like if possible but if not then no worries.

eg:

c.add ColourfulLogSpewer, :logger => {:class => Logger, :prefer => :colour_capable_logger}

If there are multiple matches for the logger dependency here, it will prefer one which

provides the :colour_capable_logger feature.

(if there are multiple :colour_capable_loggers, it will still complain).

By default, dependencies come with a preferred feature of :default, as though they

were constructed via:

c.add LogSpewer, :logger => {:class => Logger, :prefer => :default}

You can even have multiple preferred_features, in which case it'll try to pick the

dependency providing the greatest number of them. However if you need more advanced

logic to choose the particular dependency you want

MULTIPLE AND OPTIONAL DEPENDENCIES

intended to be useful for extension points in plugin systems - you can have for example a

multiple dependency on 'anything interested in listening to me' or 'anything interested

in plugging in to this extension point'.

You can specify cardinality options on dependencies via a longer argument form:

by default one and only one dependency is required, but you can make it

:multiple to get an array of all matching dependencies.

This will be constructed as NoisyLogSpewer.new(:loggers => [logger1, logger2, ...])

c.add :i_spew_to_all_logs, NoisyLogSpewer, :loggers => {:class => Logger, :multiple => true}

if you don't mind getting a nil if there dependency isn't available, you can make it :optional

c.add :i_spew_to_a_log_if_present, HesitantLogSpewer, :logger => {:class => Logger, :optional => true}

or maybe you want as many are as available but don't mind if that number is zero:

if you don't mind getting a nil if there dependency isn't available, you can make it :optional

c.add :i_spew_to_what_i_can_get, HesitantLogSpewer, :loggers => {:class => Logger, :multiple => true, :optional => true}

a particularly complicated dependency example:

c.add :complicated, LogSpewer, :loggers => {:class => Logger, :features => [:foo, :bar], :multiple => true, :optional => true}

CUSTOM ARGS OR CONSTRUCTOR BLOCK

By default, dependencies are passed to the class's new method as a hash argument.

you can customize this with a block though:

c.add(:foo, Foo, :logger => Logger) do |dependencies| Foo.new(dependencies[:logger]) end

And you can specify initial :args which will be passed before the dependencies hash.

in this case it'll be constructed as

Foo.new('initial arg', :logger => logger)

c.add(:foo, Foo, 'initial arg', :logger => Logger)

If you need to specify any other keyword arguments for the factory, :dependencies need to be supplied separately, eg:

c.add(:foo, Foo, :dependencies => {:logger => Logger}, :args => ['initial arg'], :features => [:extra, :feature, :names])

SETTER DEPENDENCIES AND TWO-PHASE INITIALIZATION

Sometimes you need depdendencies to be supplied after the object has been constructed.

Eg if you need to break a cyclic dependency.

These kinds of dependencies can be specified as :setter_dependencies.

An example:

c.add(Foo, :setter_dependencies => {:bar => Bar}) c.add(Bar, :setter_dependencies => {:bar => Foo})

this situation will be wired up like so:

foo = Foo.new

bar = Bar.new

foo.send(:bar=, bar)

bar.send(:foo=, foo)

foo.send(:post_initialize) if foo.respond_to?(:post_initialize)

bar.send(:post_initialize) if bar.respond_to?(:post_initialize)

Note you can get a post_initialize callback once your entire dependency graph

is wired up and ready for action.

Note that the setters and post_initialize hook used for this purpose

can be private, if you want to limit them only to use by the container

during two-phase initialization.

If you need precise control over two-phase initialization, you can add your own

Factory provided it implements Wirer::Factory::Interface.

The factory implementation can, if it wants, override the default mechanism for

injecting dependencies into instances created from it, and the default mechanism

for post_initializing them.

It can also make the setter_dependencies requested conditional on the particular

instance constructed, which may be useful if they vary depending on arguments to

the constructor.

add_factory_instance(my_custom_factory, :method_name => :my_custom_factory)

ADDING AN EXISTING GLOBAL OBJECT

Useful if you're using some (doubtless third-party ;-) library which has

hardcoded global state or singletons in a global scope, but you want to add them

to your container anyway so they at least appear as modular components for use by

other stuff.

this will work provided the global thing is not itself a class or module:

c.add :naughty_global_state, SomeLibraryWithA::GLOBAL_THINGUMY

or this is more explicit:

c.add_instance SomeLibraryWithA::GLOBAL_THINGUMY, :method_name => :naughty_global_state

the object will be added as providing the class of which it is an instance,

together with any extra feature name or names that you specify.

here multiple feature names are specified

c.add :instance => SomeLibraryWithA::GLOBAL_THINGUMY, :features => [:foo, :bar]

NON-SINGLETON FACTORIES

So far every factory we added to our container has been a singleton in the scope of the container.

This is the default and means that the container will only ever construct one instance of it, and

will cache that instance.

You can turn this off it you want though, via eg:

c.add :foo, Foo, :singleton => false

The container will then construct a new instance whenever a Foo is required.

Factories which are added as singletons can also support arguments, eg:

container.foo(args, for, factory)

These will then be passed on as additional arguments to the constructor

block where you supply one, eg:

c.add(:foo, Foo, :singleton => false, :dependencies => {:logger => Logger}) do |dependencies, *other_args| Foo.new(other_args, dependencies[:logger]) end

Where you only supply a class, by default they'll be passed as additional

arguments to the new method before the dependencies hash.

If the last argument is a hash, dependencies will be merged into it. eg:

c.add(:foo, Foo, :singleton => false, :dependencies => {:logger => Logger})

here,

c.foo(:other => arg)

will lead to

Foo.new(:other => arg, :logger => logger)

and

c.foo(arg1, arg2, :arg3 => 'foo')

to

Foo.new(arg1, arg2, :arg3 => 'foo', :logger => logger)

If you don't like this, just make sure to supply a constructor block.

Note that the singleton-ness or otherwise, is not a property of the factory itself, rather

it's specific to the context of that factory within a particular container.

Note that when using non-singleton factories, all bets are off when it comes to wiring up

object graphs which have cycles in them - since it can't keep constructing new instances

all the way down.

Similarly, if the same dependency occurs twice in your dependency graph,

where a non-singleton factory is used for it, you'll obviously get multiple distinct instances

rather than references to one shared instance.

I considered providing more fine-grained control over this (eg making things a singleton in the

scope of one particular 'construction session', but able to construct new instance for each

such construction session) but this is out of scope for now.

end

GETTING STUFF OUT OF A CONTAINER

Pretty crucial eh!

Things added via 'add' with a symbol method name as the first argument, are made available via

corresponding methods on the container:

container.special_logger container.mystery_meat

You can also specify this via an explicit :method_name parameter (and in fact you need to

specify it this if you use the slightly-lower-level add_factory / add_new_factory / add_instance

calls)

You can also ask the container to find any kind of dependency, via

passing dependency specification arguments to []:

container[Logger] container[:special_logger] container[Logger, :multiple => true] container[SomeClass, :and, :some, :features] container[SomeModule] container[SomeModule, :optional => true]

unless you specify :optional => true, it'll whinge if the dependency can't be fulfilled.

DSL FOR EXPRESSING DEPENDENCIES FOR A PARTICULAR CLASS

This is really handy if you're writing classes which are designed to be

components that are ready to be wired up by a Wirer::Container.

Using the DSL makes your class instance itself expose Wirer::Factory::Interface,

meaning it can be added to a container without having to manually state

its dependencies or provided features. The container will 'just know'.

(although as we shall see, you can refine the dependencies when adding it to a

container, to override the defaults within that particular context if you need to;

you can also specify extra provided features within the container context)

class Foo wireable # extends with the DSL methods (Wirer::Factory::ClassDSL)

Declare some dependencies.

dependency :logger, Logger dependency :arg_name, DesiredClass, :other, :desired, :feature, :names, :optional => true dependency :arg_name, :class => DesiredClass, :features => [:desired, :feature, :names], :optional => true

to avoid cyclic load-order dependencies between classes using this DSL, you can specify a class or module

name as a string to be resolved later. In this case you need to use the explicit :class => foo args style.

dependency :something, :class => "Some::Thing"

you can declare extra features which the class factory provides:

provides_feature :foo, :bar, :baz

and setter dependencies

setter_dependency :foo, Foo

(by default this will also define a private attr_writer :foo for you, which is

what it will use by default to inject the dependency)

you can also override the factory methods which the class has been extended with.

the most common case would be where you want to customize how instances are

constructed from the named dependencies (and any other args), via eg:

def self.new_from_dependencies(dependencies, *other_args) new(dependencies[:foo], dependencies[:bar], *other_args) end

you could also add extra instance-specific setter dependencies, eg via:

def self.setter_dependencies(instance) result = super result[:extra] = Wirer::Dependency.new(...) if instance.something? result end

Or to customize the way that setter dependencies are injected:

def self.inject_dependency(instance, arg_name, dependency) instance.instance_variable_set(:"@#{arg_name}", dependency) end end

class Bar < Foo

when using Wirer::Factory::ClassDSL, subclasses inherit their superclass's dependencies

and features, but you can add new ones:

dependency :another_thing, Wotsit provides_feature :extra

or override existing dependencies

dependency :logger, :special_logger

or if you don't want this inheritance between the class factory instances of subclasses,

you can just extend with Wirer::Factory::ClassMixin instead of using the DSL, or you

can override constructor_dependencies / setter_dependencies / provides_features class

methods, or both.

end

Adding these classes into a container is then quite simple:

Wirer do |c|

It will see that Foo.is_a?(Wirer::Factory::Interface) and add it directly as a factory

taking into account its dependencies etc

c.add Foo

You can refine the dependencies of an existing factory when adding it, eg:

c.add Foo, :logger => :special_logger

its original dependency was just on a Logger, but now it's on a Logger which also

provides_feature :special_logger.

This allows you to customize which particular instance of a given dependency this

class gets constructed with. It will be added using a Wirer::Factory::Wrapped around

the original factory.

You can also specify extra features when adding a factory, which then give you a handle

by which to refer to it when you want it passed to some other thing. Eg to provide the

special logger above:

c.add :special_logger, Logger

or both at once: adding an existing factory with some extra features and some refined

dependencies within this container's context.

c.add Foo, :features => [:special_foo], :dependencies => {:logger => :special_logger}

(if you want to specify other arguments for Factory::Wrapped, the dependency refining

arguments need to go in their own :dependencies arg)

then could then eg

c.add Bar, :foo => :special_foo

If you have an existing factory which takes arguments, you can wrap it with specific

(initial) arguments, allowing it to be added as a singleton, eg:

c.add Foo, 'args', 'for', 'foo', :logger => Logger

or to be more explicit:

c.add Foo, :args => ['args', 'for', 'foo'], :dependencies => {:logger => Logger} end