dependency_injection 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2116ad6a0f9eb9fef58b268cd9413aa4fd8177c3
-  data.tar.gz: ed1755da4b8037d366fc95c3693c86ac9b346b28
+  metadata.gz: e40f369e9fe6ece4538ced539176e74e00d0154e
+  data.tar.gz: 313501c69d9d7bc6dfa3e8e824c41ba22671a1fa
 SHA512:
-  metadata.gz: ab60bdcc326a550b133d8406c459d072670af4f259a50eb5cc5c1c9edf33b671d6e544f1871e27b88e90027befeb0477c1c681e43a3f6de7a0ec52f2a913110a
-  data.tar.gz: 770dcddd3fe38639736abae27599ef504934050f29b3766ca79efba18b5fbcdb0c5c56ffda141485f2d52fb6990060073ac657f61be6fbd7a440af6ff3c97223
+  metadata.gz: 200c2f71aa5c1e9c3cebfe50723f45d28a5a5e7a11c9ca3546c8a1b0fdc273ecee599e69f12b01e3c1e85e9b6c499e8624b065e42a5cfe7224c7bc2818f72de7
+  data.tar.gz: e84f7d457b800cad35a56ea24645b6fe7797c8265b5bec545f24ccd9a44e292540c3b18657e3626a5b049b8992deef7d81233b57f6a710deb0a1e7b6b6586b67

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# 0.3.0 (2013-09-16)
+
+* Add prototype and container scope notion in service
+
+# 0.2.0
+
+* Add lazy loading option
+* Add service aliasing option
+* Add service configurator option
+
+# 0.1.0
+
+* Add YAML configuration
+* Add global container parameters
+* Add service as reference to another service

data/README.md

@@ -1,6 +1,216 @@
 # Dependency Injection for Ruby
 [![Build Status](https://travis-ci.org/kdisneur/dependency_injection-ruby.png?branch=master)](https://travis-ci.org/kdisneur/dependency_injection-ruby) [![Coverage Status](https://coveralls.io/repos/kdisneur/dependency_injection-ruby/badge.png?branch=master)](https://coveralls.io/r/kdisneur/dependency_injection-ruby?branch=master) [![Code Climate](https://codeclimate.com/github/kdisneur/dependency_injection-ruby.png)](https://codeclimate.com/github/kdisneur/dependency_injection-ruby)
 
-It's a WIP for now.
+## Foreword
 
-You can find some examples in the [examples folder](https://github.com/kdisneur/dependency_injection-ruby/tree/master/examples)
+This gem is heavily inspired from The Symfony Framework [Container Service](http://symfony.com/doc/current/book/service_container.html). Here's the description they give to explain the concept:
+
+> It helps you instantiate, organize and retrieve the many objects of your application. This object, called a service container, will allow you to standardize and centralize the way objects are constructed in your application. The container makes your life easier, is super fast, and emphasizes an architecture that promotes reusable and decoupled code.
+
+You can learn more about everything this gem does by looking at the [examples](https://github.com/kdisneur/dependency_injection-ruby/tree/master/examples) directory. See [Usage](#usage) for a detailed explanation.
+
+## Description
+
+### Installation
+
+Just add the gem to your Gemfile:
+
+```ruby
+gem 'dependency_injection'
+```
+
+Or simply install it using rubygems:
+
+```shell
+gem install dependency_injection
+```
+
+### Example
+
+#### Without using Dependency Injection
+
+In this example, we'll consider a simple application that needs to send emails for a newsletter.
+
+We have the two following classes:
+
+```ruby
+# mailer.rb
+class Mailer
+  attr_accessor :transporter
+
+  def initialize
+    puts 'mailer initialized'
+  end
+
+  def send_mail(message, recipient)
+    puts "mail sent via #{self.transporter}: #{message}"
+  end
+end
+```
+
+```ruby
+# newsletter_manager.rb
+class NewsletterManager
+  def initialize(mailer)
+    @mailer = mailer
+  end
+
+  def send_newsletter(message, recipients)
+    puts 'newsletter #{message} send to #{recipients}'
+    recipients.each { |recipient| @mailer.send_mail(message, recipient) }
+  end
+end
+```
+
+A `Mailer` class that handles email sending, through a given transporter, for a recipient.
+
+A `NewsletterManager` class that sends a newsletter (message) to a list of recipients.
+
+Without __DependencyInjection__, we would need to do the following to achieve our goal:
+
+```ruby
+# send_newsletter.rb
+mailer = Mailer.new
+mailer.transporter = :smtp
+
+recipients = %w(john@doe.com david@heinemeier-hansson.com)
+message    = 'I love dependency injection and think this is the future!'
+
+newsletter_manager = NewsletterManager.new(mailer)
+newsletter_manager.send_newsletter(message, recipients)
+```
+
+You have a working application but this code is thightly coupled and might be, in a real life, hard to refactor.
+
+Another big drawback is that you have to instantiate as many objects as you have emails and newsletters to send.
+
+#### Now with Dependency Injection
+
+Our two classes stay untouched, the only thing you have to do is to add a configuration file.
+
+```yaml
+# services.yml
+parameters:
+  mailer.transporter: 'smtp'
+services:
+  mailer:
+    class: 'Mailer'
+    calls:
+      - ['transporter=', '%mailer.transporter%']
+  newsletter_manager:
+    class: 'NewsletterManager'
+    arguments:
+      - '@mailer'
+```
+
+We now need to require __DependencyInjection__ and declare our __Container__.
+
+Please note that the following code only needs to be declared once as long as the `container` value is accessible throughout your whole application.
+
+```ruby
+# initialize.rb
+require 'dependency_injection/container'
+require 'dependency_injection/loaders/yaml'
+
+container = DependencyInjection::Container.new
+loader    = DependencyInjection::Loaders::Yaml.new(container)
+loader.load(File.join(File.dirname(File.expand_path(__FILE__)), 'services.yml'))
+```
+
+We can now do the same as the previous example with the following.
+
+```ruby
+# send_newsletter.rb
+recipients = %w(john@doe.com david@heinemeier-hansson.com)
+message    = 'I love dependency injection and think this is the future!'
+
+container.get('newsletter_manager').send_newsletter(message, recipients)
+```
+
+Now your code is no longer tightly coupled and can be a lot more easily refactored. Moreover, the `Mailer` and `NewsletterManager` classes are only instantiated once during your application's lifecycle.
+
+### Usage
+
+Before diving into the details of __DependencyInjection__, here are some keywords that you need to be acquainted with:
+
+* __Container__ object must be declared to be used by your application during it's whole lifecycle. The Container job is to register and retrieve Services.
+
+* __Service__ is a Plain Old Ruby Object (Poro o/) that contains your own logic. The __DependencyInjection__ gem doesn't need to know anything about it and won't force your to add/inherit any specific method.
+
+* __Configurator__ is a standard Ruby Class that shares a callable to be used by different objects (like Services) to configure them after their instantiation.
+
+#### Configuration
+
+__DependencyInjection__ needs to be configured, using a yaml file, in order to map your services with your existing classes and their dependencies. There's also some other options that we'll list below.
+
+Here's a configuration file example using almost everything __DependencyInjection__ has to offer:
+
+```yaml
+parameters:
+  mailer.transport: smtp
+services:
+  mailer:
+    class: Mailer
+    calls:
+      - ['transport=', '%mailer.transport%']
+    lazy: true
+  newsletter:
+    class: NewsletterManager
+    arguments:
+      - '@mailer'
+```
+
+And here's some more details about each keyword:
+
+* `parameters`: Based on a basic key/value scheme. This can later be used throughout your services by calling `%parameter_name%`.
+
+* `services`: The services name must be used as the first indentation tier.
+
+* `class`: A string containing the class name of your service.
+
+* `arguments`: An array containing the parameters used by your class `intialize` method.
+
+* `calls`: An array containing an array of each instance method and its parameters. Note that you only need to define the methods during your class instantiation.
+
+* `lazy`: Returns a Proxy Object if true. The _real_ object will only be instantiated at the first method call.
+
+* `alias`: A string containing the target service name.
+
+* `scope`: A string containing one of two possibles values to handle the service initialization scope:
+  * `container`: a service is initialized only once throughout the container life (default)
+  * `prototype`: a new service is initialized each time you call the container
+
+  Note that the usage of a `prototype` service inside a `container` service raises a `ScopeWideningInjectionError`
+
+__Please note:__
+* You can reference a variable in the configuration with the following syntax: `%variable%`.
+* You can reference declared services by prefixing it with an `@` sign.
+* If you declare a service as an alias, the target service configuration will be used. Your own service configuration will be ignored.
+
+### Tests
+
+__DependencyInjection__ is covered by tests at 100%, see [coveralls.io](https://coveralls.io/r/kdisneur/dependency_injection-ruby) service.
+
+If you want to launch the tests by yourself:
+* Clone this repository by running `git clone git@github.com:kdisneur/dependency_injection-ruby`
+* Run `bundle install`
+* Run `rake test`
+
+## Contribute
+
+This is Github folks!
+
+If you find a *bug*, open an [Issue](https://github.com/kdisneur/dependency_injection-ruby/issues).
+
+It's OK to open an issue to ask us what we think about a change you'd like to make, so you don't work for nothing :)
+
+If you want to add/change/hack/fix/improve/whatever something, make a [Pull Request](https://github.com/kdisneur/dependency_injection-ruby/pulls):
+
+* Fork this repository
+* Create a feature branch on your fork, we just love [git-flow](http://nvie.com/posts/a-successful-git-branching-model/)
+* Do your stuff and pay attention to the following:
+ * Your code should be documented using [Tomdoc](http://tomdoc.org)
+ * You should follow [Github's Ruby Styleguide](https://github.com/styleguide/ruby)
+ * If needed, squash your commits to group them logically
+ * Update the CHANGELOG accordingly
+* Make a Pull Request, we will *always* respond, and try to do it fast.

data/examples/scoped_services.rb

@@ -0,0 +1,28 @@
+require 'dependency_injection/container'
+require 'dependency_injection/loaders/yaml'
+
+c = DependencyInjection::Container.new
+loader = DependencyInjection::Loaders::Yaml.new(c)
+loader.load(File.join(File.dirname(File.expand_path(__FILE__)), 'scoped_services.yml'))
+
+class ContainerScopedService
+  def initialize
+    puts 'Container scoped initialization'
+  end
+end
+
+class PrototypeScopedService
+  def initialize
+    puts 'Prorotype scoped initialization'
+  end
+end
+
+c.get('my.container.scoped.service')
+# => Container scoped initialization
+c.get('my.container.scoped.service')
+# =>
+
+c.get('my.prototype.scoped.service')
+# => Prorotype scoped initialization
+c.get('my.prototype.scoped.service')
+# => Prorotype scoped initialization

data/examples/scoped_services.yml

@@ -0,0 +1,6 @@
+services:
+  my.container.scoped.service:
+    class: 'ContainerScopedService'
+  my.prototype.scoped.service:
+    class: 'PrototypeScopedService'
+    scope: 'prototype'

data/lib/dependency_injection/container.rb

@@ -23,7 +23,7 @@ module DependencyInjection
 
     def register(name, klass_name, lazy=false)
       definition = lazy ? LazyDefinition.new(klass_name, self) : Definition.new(klass_name, self)
-      @definitions[name] =definition
+      @definitions[name] = definition
     end
 
     def register_alias(name, alias_definition_name)

data/lib/dependency_injection/definition.rb

@@ -1,14 +1,16 @@
 require 'active_support/core_ext/string/inflections'
+require 'dependency_injection/scope_widening_injection_error'
 
 module DependencyInjection
   class Definition
-    attr_accessor :arguments, :configurator, :klass_name, :method_calls
+    attr_accessor :arguments, :configurator, :klass_name, :method_calls, :scope
 
     def initialize(klass_name, container)
       @container        = container
       self.arguments    = []
       self.klass_name   = klass_name
       self.method_calls = {}
+      self.scope        = :container
     end
 
     def add_argument(argument)
@@ -38,20 +40,30 @@ module DependencyInjection
     end
 
     def object
-      return @object if @object
+      self.send("#{self.scope}_scoped_object")
+    end
+
+  private
+
+    def container_scoped_object
+      @object ||= initialize_object
+    end
 
-      @object = self.klass.new(*resolve(self.arguments))
-      self.method_calls.each { |method_name, arguments| @object.send(method_name, *resolve(arguments)) }
+    def initialize_object
+      object = self.klass.new(*resolve(self.arguments))
+      self.method_calls.each { |method_name, arguments| object.send(method_name, *resolve(arguments)) }
       if self.configurator
         name, method_name   = self.configurator
         configurator_object = resolve([name]).first
-        configurator_object.send(method_name, @object)
+        configurator_object.send(method_name, object)
       end
 
-      @object
+      object
     end
 
-  private
+    def prototype_scoped_object
+      initialize_object
+    end
 
     def resolve(arguments)
       resolve_references(resolve_container_parameters(arguments))
@@ -70,7 +82,10 @@ module DependencyInjection
     def resolve_references(arguments)
       arguments.map do |argument|
         if /^@(?<reference_name>.*)/ =~ argument
-          @container.get(reference_name)
+          reference = @container.get(reference_name)
+          raise ScopeWideningInjectionError if reference.scope == :prototype && scope == :container
+
+          reference
         else
           argument
         end

data/lib/dependency_injection/loaders/yaml.rb

@@ -38,6 +38,7 @@ module DependencyInjection
       def add_standard_service(name, parameters)
         lazy_load  = parameters['lazy'] || false
         definition = @container.register(name, parameters['class'], lazy_load)
+        definition.scope = parameters['scope'] if parameters['scope']
         definition.add_arguments(*parameters['arguments']) if parameters['arguments']
         if (configurator = parameters['configurator'])
           definition.add_configurator(configurator[0], configurator[1])

data/lib/dependency_injection/scope_widening_injection_error.rb

@@ -0,0 +1,2 @@
+class ScopeWideningInjectionError < Exception
+end

data/lib/dependency_injection/version.rb

@@ -1,3 +1,3 @@
 module DependencyInjection
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/test/dependency_injection/loaders/test_yaml.rb

@@ -70,6 +70,22 @@ class TestYaml < Minitest::Test
     @yaml_loader.send(:add_service, 'my_alias', { 'alias' => 'my_definition' })
   end
 
+  def test_adding_service_without_defined_scope
+    definition = mock
+    @container.stubs(:register).with('key_1', 'MyKlass', false).returns(definition)
+
+    definition.expects(:scope=).never
+    @yaml_loader.send(:add_service, 'key_1', { 'class' => 'MyKlass' })
+  end
+
+  def test_adding_service_with_defined_scope
+    definition = mock
+    @container.stubs(:register).with('key_1', 'MyKlass', false).returns(definition)
+
+    definition.expects(:scope=).with('awesome_scope')
+    @yaml_loader.send(:add_service, 'key_1', { 'class' => 'MyKlass', 'scope' => 'awesome_scope' })
+  end
+
   def test_adding_standard_service_as_lazy
     @container.expects(:register).with('my_lazy_definition', 'MyLazyDefinition', true)
     @yaml_loader.send(:add_standard_service, 'my_lazy_definition', { 'class' => 'MyLazyDefinition', 'lazy' => true })

data/test/dependency_injection/test_definition.rb

@@ -130,6 +130,32 @@ class TestDefinition < Minitest::Test
     @definition.object
   end
 
+  def test_getting_container_scoped_object
+    @definition.scope = :container
+    @definition.expects(:send).with('container_scoped_object')
+    @definition.object
+  end
+
+  def test_getting_container_scoped_object_multiple_times
+    @definition.stubs(:initialize_object).returns(:object_1, :object_2)
+    @definition.scope = :container
+    assert_equal(:object_1, @definition.object)
+    assert_equal(:object_1, @definition.object)
+  end
+
+  def test_getting_prototype_scoped_object
+    @definition.scope = :prototype
+    @definition.expects(:send).with('prototype_scoped_object')
+    @definition.object
+  end
+
+  def test_getting_prototype_scoped_object_multiple_times
+    @definition.stubs(:initialize_object).returns(:object_1, :object_2)
+    @definition.scope = :prototype
+    assert_equal(:object_1, @definition.object)
+    assert_equal(:object_2, @definition.object)
+  end
+
   def test_resolving_first_container_parameters
     changed_arguments = mock
     arguments         = mock
@@ -162,10 +188,39 @@ class TestDefinition < Minitest::Test
     assert_equal(%w(first second), @definition.send(:resolve_references, %w(first second)))
   end
 
-  def test_resolving_references_with_references
+  def test_resolving_references_with_defintion_and_referenced_object_in_container_scope
     referenced_object = mock
+    referenced_object.stubs(:scope).returns(:container)
+    @definition.scope= :container
     @container.stubs(:get).with('reference.name').returns(referenced_object)
 
     assert_equal(['first', referenced_object], @definition.send(:resolve_references, %w(first @reference.name)))
   end
+
+  def test_resolving_references_with_defintion_and_referenced_object_in_prototype_scope
+    referenced_object = mock
+    referenced_object.stubs(:scope).returns(:prototype)
+    @definition.scope= :prototype
+    @container.stubs(:get).with('reference.name').returns(referenced_object)
+
+    assert_equal(['first', referenced_object], @definition.send(:resolve_references, %w(first @reference.name)))
+  end
+
+  def test_resolving_references_with_defintion_in_prototype_scope_and_referenced_object_in_container_scope
+    referenced_object = mock
+    referenced_object.stubs(:scope).returns(:container)
+    @definition.scope= :prototype
+    @container.stubs(:get).with('reference.name').returns(referenced_object)
+
+    assert_equal(['first', referenced_object], @definition.send(:resolve_references, %w(first @reference.name)))
+  end
+
+  def test_resolving_references_with_defintion_in_container_scope_and_referenced_object_in_prototype_scope
+    referenced_object = mock
+    referenced_object.stubs(:scope).returns(:prototype)
+    @definition.scope= :container
+    @container.stubs(:get).with('reference.name').returns(referenced_object)
+
+    assert_raises(ScopeWideningInjectionError) { @definition.send(:resolve_references, %w(first @reference.name)) }
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dependency_injection
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kevin Disneur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-05 00:00:00.000000000 Z
+date: 2013-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -34,6 +34,7 @@ files:
 - .ruby-gemset
 - .ruby-version
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -48,6 +49,8 @@ files:
 - examples/inject_a_reference_to_another_dependency.rb
 - examples/lazy_load_object.rb
 - examples/lazy_load_object.yml
+- examples/scoped_services.rb
+- examples/scoped_services.yml
 - examples/yaml_configuration_file.rb
 - examples/yaml_configuration_file.yml
 - lib/dependency_injection/alias_definition.rb
@@ -56,6 +59,7 @@ files:
 - lib/dependency_injection/lazy_definition.rb
 - lib/dependency_injection/loaders/yaml.rb
 - lib/dependency_injection/proxy_object.rb
+- lib/dependency_injection/scope_widening_injection_error.rb
 - lib/dependency_injection/version.rb
 - test/dependency_injection/loaders/test_yaml.rb
 - test/dependency_injection/test_alias_definition.rb