jerry 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b5cd829b2996185f8ef423ab36069d638754a23
-  data.tar.gz: 341a9a49bcc3a33149320ecd0ac003264a31e03f
+  metadata.gz: 0d97c357a390c069b18e9516ad1e5dac1fcdfea5
+  data.tar.gz: b33040e60cc83f2a481d0181c809e7b045ca96ec
 SHA512:
-  metadata.gz: 233d001c305c8f4b57a2b2fa850b32459aacb3d86ab8a071079653b886b3691b4b048017d66e7b61a923e959ae8aed47eba4867af491246f6b2e5e54da277365
-  data.tar.gz: 22afec9ff0c750bc7838a140aa356cc92df22a0d0cb0a8654628ffc9d7d91fe90e949974dc59674ff72707f0595acfd9448add6b05f42854d018d4309f303938
+  metadata.gz: eae3155f70ebb6bfd88cd878f2e4dfbe95f042a23439504d185717dd4f20583ffe3ad209e65511d922be4a5e403af7a836ef1969cdd45bff8241685e064838b0
+  data.tar.gz: f4cb19e8c591ae15611d0d02e1d7c6a46ea9fb1071ef37a83e454d48622565f537f59b44f7d67bc7be13ef9c13453cb8010d0a5fc66d4639000863f817f394d8

data/.gitignore

@@ -20,7 +20,7 @@ build/
 ## Documentation cache and generated files:
 /.yardoc/
 /_yardoc/
-/doc/
+/html-doc/
 /rdoc/
 
 ## Environment normalisation:
@@ -35,4 +35,3 @@ Gemfile.lock
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
-

data/.reek

@@ -0,0 +1,2 @@
+IrresponsibleModule:
+  enabled: false

data/.rubocop.yml

@@ -0,0 +1,4 @@
+Documentation:
+  Exclude:
+    - lib/jerry/version.rb
+    - spec/fixtures/*.rb

data/.travis.yml

@@ -1,6 +1,15 @@
 language: ruby
+sudo: false
+cache: bundler
 rvm:
-  - 2.1.2
+  - 2.2
+  - 2.1
+  - 2.0.0
   - 1.9.3
   - jruby-19mode
-  - rbx-2
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/.yardopts

@@ -1,2 +1,9 @@
 --protected
---no-private
+--no-private
+-r README.md
+lib/jerry.rb
+lib/**/*.rb
+-o html-doc
+-
+LICENSE.txt
+doc/*.md

data/Gemfile

@@ -1,5 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-gem 'coveralls', require: false

data/Guardfile

@@ -0,0 +1,16 @@
+guard 'rake', task: 'default' do
+  watch 'Rakefile'
+  watch '.rspec'
+  watch '.rubocop.yml'
+  watch '.reek'
+  watch %r{^lib/}
+  watch %r{^spec/}
+end
+
+guard 'rake', task: 'doc' do
+  watch '.yardopts'
+  watch 'LICENSE.txt'
+  watch(/.+\.(md|markdown)/)
+  watch %r{^lib/}
+  watch %r{^doc/}
+end

data/README.md

@@ -4,114 +4,129 @@ Jerry
 [![Build Status](https://travis-ci.org/beraboris/jerry.svg?branch=master)](https://travis-ci.org/beraboris/jerry)
 [![Coverage Status](https://coveralls.io/repos/beraboris/jerry/badge.png)](https://coveralls.io/r/beraboris/jerry)
 
-Jerry rigs your application together. It's an [Inversion of Control](https://en.wikipedia.org/wiki/Inversion_of_control)
-container for ruby. Just tell Jerry how to build your application and it will set it all up for you.
+Jerry is a Ruby
+[Inversion of Control](https://en.wikipedia.org/wiki/Inversion_of_control)
+container. You tell it how your classes depend on one another and it will create
+your application and wire all the dependencies correctly.
 
-Installation
-============
+Jerry aims to be simple and straight forward. It also aims to be out of your
+way. Your classes don't need to know anything about jerry.
 
-The usual stuff. Either
+Why?
+----
 
-```ruby
-gem 'jerry'
-```
+[Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) is a
+great pattern for building loosely coupled applications. It allows you to build
+isolated components that can be swapped around.
 
-then
+The problem with this pattern is that it leaves you with a bunch of classes that
+you have to build and wire together yourself. Jerry does that for you.
 
-    $ bundle install
+Getting started
+---------------
 
-or
-
-    $ gem install jerry
+### Important note
 
-Usage
-=====
+Currently jerry only supports constructor injection. If you're hoping to use
+setter injection, you're out of luck. You're going to need to switch to
+constructor injection.
 
-Let's say you have the following code:
+### Install it
 
-```ruby
-class Window; end
-class Door; end
-
-class House
-  attr_reader :window, :door
-  
-  def initialize(window, door)
-    @window = window
-    @door = door
-  end
-end
-```
+You have 3 options:
 
-First, require jerry:
+Options 1: Add jerry to your `Gemfile`
 
 ```ruby
-require 'jerry'
+gem 'jerry', '~> 2.0'
 ```
-    
-Then, define a config class. This class tells jerry how to construct your application.
+
+Option 2: Add jerry to your `*.gemspec`
 
 ```ruby
-class MyConfig < Jerry::Config
-  component(:window) { Window.new }
-  component(:door) { Door.new }
-  component(:house) { House.new rig(:window), rig(:door) }
+Gem::Specification.new do |spec|
+  # ...
+  spec.add_dependency 'jerry', '~> 2.0'
 end
 ```
 
-The `component` method defines a component. Usually you'll want a component per class. The `rig` method tells jerry to
-build a component.
+Option 3: Just install it
 
-Finally, when you want to build your application, ask jerry to do it for you.
+    $ gem install jerry
+
+### Create a configuration class
 
 ```ruby
-jerry = Jerry.new MyConfig.new
-house = jerry.rig :house
-```
+require 'jerry'
 
-Scopes
-------
+class MyConfig < Jerry::Config
+  def initialize(foo_db_url, bar_db_url)
+    @foo_db_url = foo_db_url
+    @bar_db_url = bar_db_url
+  end
 
-The `component` method lets you specify a scope. The scope can either be `:single` or `:instance` and the default is
-`:single`. If you set the scope to `:single` only one instance of the component will be created. If you set it to
-`:instance`, a new instance of the component will be created each time you call `rig`.
+  bind Application, [FooService, BarService]
 
-```ruby
-class MyConfig < Jerry::Config
-  component(:window, scope: :instance) { Window.new }
-  component(:door, scope: :single) { Door.new }
+  singleton bind FooService, [BarService, :foo_db]
+  singleton bind BarService, [:bar_db]
+
+  named_bind :foo_db Database [proc { @foo_db_url }]
+  named_bind :bar_db Database [proc { @bar_db_url }]
 end
-jerry = Jerry.new MyConfig.new
+```
 
-window_a = jerry.rig :window
-window_b = jerry.rig :window
-window_a.object_id == window_b.object_id
-#=> false
+Let's go over what's going on in this configuration class.
+
+First, we define a constructor. It takes two database urls and stores them as
+instance variables. We'll go over what these urls are used for later. You should
+note that this constructor has no special meaning to jerry. It's entirely
+specific to this configuration class.
+
+Second, we use `bind` to tell jerry how to wire the `Application` class. `bind`
+takes two arguments. The first is the class we're telling jerry about and the
+second is an array that tells jerry what constructor arguments to pass to the
+class. Here you can notice that `Application` takes an instance of `FooService`
+and an instance of `BarService` in its constructor.
+
+Third, we tell jerry how to build `FooService` and `BarService`. Note that we're
+calling `singleton bind` instead of `bind` here. `singleton` is used to tell
+jerry that we want it to only instantiate the class we just described only once.
+When we use `singleton` jerry will always pass the same instance of the given
+class as a constructor argument. This is useful when some of your classes have
+a persistent state. In this case, the `BarService` instance passed to both
+`Application` and `FooService` will be the exact same instance.
+
+Finally, we tell jerry how to build two instances of the `Database` class. The
+first instance is named `:foo_db` and the second is named `:bar_db`. We
+reference these instances when telling jerry about `FooService` and
+`BarService`. This is what `named_bind` is for. We should also note that the
+last arguments of the `named_bind` calls each contain a proc. In this case, the
+procs are used to inject the database urls for each database. In a more general
+sense, the procs are used to pass settings to various classes.
+
+### Create your application
 
-door_a = jerry.rig :door
-door_b = jerry.rig :door
-door_a.object_id == door_b.object_id
-#=> true
+```ruby
+require 'jerry'
+
+jerry = Jerry.new MyConfig.new('db://localhost/foo', 'db://localhost/bar')
+app = jerry[Application]
 ```
 
-Multiple configs
-----------------
+Let's look at what's going on here.
 
-Jerry lets you use multiple configs. This way you can organize your configs however you want. You can pass multiple
-configs to `Jerry.new` or you can use `jerry << SomeConfig.new` to add configs to jerry.
+First, we create an instance of our configuration class. We pass the urls for
+our two databases to the constructor.
 
-If two configs define the same component, the config that was inserted last will have priority. With `Jerry.new`, the
-later arguments have priority.
+Second, we create an instance of `Jerry` passing in the instance of our
+configuration class.
 
-```ruby
-class ConfA < Jerry::Config
-  component(:thing) { "from a" }
-end
-class ConfB < Jerry::Config
-  component(:thing) { "from b" }
-end
-jerry = Jerry.new ConfA.new, ConfB.new
+Finally, we use the square bracket operator (`[]`) to create an instance of our
+application. Of course our application is wired properly.
 
-jerry.rig :thing
-#=> "from b"
-```
+Learn more
+----------
+
+If you'd like to learn more, here's some more documentation:
+
+- [Multiple configurations](doc/multiple-configurations.md)

data/Rakefile

@@ -1,5 +1,24 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
+require 'rubocop/rake_task'
+require 'reek/rake/task'
+
+task default: [:spec, :lint]
 
 RSpec::Core::RakeTask.new :spec
-task :default => :spec
+YARD::Rake::YardocTask.new :doc
+
+task lint: [:reek, :rubocop]
+
+desc 'Run rubocop linter on lib/**/*.rb and spec/**/*.rb'
+RuboCop::RakeTask.new :rubocop do |t|
+  t.patterns = ['lib/**/*.rb', 'spec/**/*.rb']
+  t.fail_on_error = false
+end
+
+desc 'Run reek linter on lib/**/*.rb'
+Reek::Rake::Task.new :reek do |t|
+  t.source_files = 'lib/**/*.rb'
+  t.fail_on_error = false
+end

data/bin/console

@@ -0,0 +1,3 @@
+#!/bin/sh
+cd "$(dirname "$0")/.."
+bundle exec pry -Ilib -rjerry "$@"

data/bin/guard

@@ -0,0 +1,3 @@
+#!/bin/sh
+cd "$(dirname "$0")/.."
+bundle exec guard "$@"

data/bin/rake

@@ -0,0 +1,3 @@
+#!/bin/sh
+cd "$(dirname "$0")/.."
+bundle exec rake "$@"

data/bin/setup

@@ -0,0 +1,3 @@
+#!/bin/sh
+cd "$(dirname "$0")/.."
+bundle install "$@"

data/doc/multiple-configurations.md

@@ -0,0 +1,51 @@
+Multiple configurations
+-----------------------
+
+Jerry allows you to define and use multiple configurations. This way you can
+separate the dependency configurations for different parts of your application.
+
+Let's look at an example. In this example, we have a simple on-line store. It
+has users, products and shopping carts. We can create separate configurations
+for user, product, and shopping cart related classed. Users, products and
+shopping carts each have a service that talks to the database and other services
+and a controller that talks to the service. Here's what it might look like:
+
+```ruby
+class DatabaseConfig < Jerry::Config
+  # database connector thingy
+  bind Database
+end
+
+class UserConfig < Jerry::Config
+  bind UserService, [Database]
+  bind UserController, [UserService]
+end
+
+class ProductConfig < Jerry::Config
+  bind ProductService, [Database]
+  bind ProductController, [ProductService]
+end
+
+class ShoppingCartConfig < Jerry::Config
+  bind ShoppingCartService, [Database, ProductService, UserService]
+  bind ShoppingCartController, [ShoppingCartService]
+end
+
+class AppConfig < Jerry::Config
+  bind Application, [UserController, ProductController, ShoppingCartController]
+end
+
+jerry = Jerry.new(
+  DatabaseConfig.new,
+  AppConfig.new,
+  UserConfig.new,
+  ProductConfig.new,
+  ShoppingCartConfig.new
+)
+
+app = jerry[Application]
+```
+
+Note that in the example above, some the configurations reference classes that
+are configured in other configurations. This is perfectly fine. When
+instantiating a class, jerry will look at all the configurations.

data/jerry.gemspec

@@ -14,12 +14,17 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec', '~> 3.0.0'
-  spec.add_development_dependency 'yard', '~> 0.8.7.4'
+  spec.add_development_dependency 'guard'
+  spec.add_development_dependency 'guard-rake'
+  spec.add_development_dependency 'rspec', '~> 3.3'
+  spec.add_development_dependency 'coveralls', '~> 0.8'
+  spec.add_development_dependency 'yard', '~> 0.8.7'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rubocop', '~> 0.32'
+  spec.add_development_dependency 'reek', '~> 2.2'
 end

data/lib/jerry/class_provider.rb

@@ -0,0 +1,30 @@
+class Jerry
+  # A provider that instanciates a given class by collecting constructor
+  # arguments through a given jerry instance.
+  class ClassProvider
+    # @param klass [Class] class to be instanciated
+    # @param args_spec [Array<Clsss, Symbol, Proc>] specification for the
+    #   constructor arguments. Classes and Symbols are used to collect the
+    #   arguments from the jerry instance. Procs are called to generate
+    #   arguments.
+    def initialize(klass, args_spec)
+      @klass = klass
+      @args_spec = args_spec
+    end
+
+    # @param jerry [Jerry] a jerry instance
+    # @param config [Jerry::Config] the config holding the provider
+    # @return An instance of the class given in the constructor
+    def call(jerry, config)
+      args = @args_spec.map do |spec|
+        if spec.respond_to? :call
+          config.instance_exec(jerry, config, &spec)
+        else
+          jerry[spec]
+        end
+      end
+
+      @klass.new(*args)
+    end
+  end
+end

data/lib/jerry/config.rb

@@ -1,85 +1,88 @@
-class Jerry
-  # Indicated that an error occurred when defining a component
-  class ComponentError < StandardError; end
+require 'jerry/class_provider'
+require 'jerry/errors'
 
-  # Base class for all jerry configs.
+class Jerry
+  # A configuration specifies how to wire parts of an application
+  #
+  # @abstract Subclass this class in order to create a configuration
+  # @example Basic usage
+  #   class Door; end
+  #   class Window; end
   #
-  # A config is a class that tells jerry about a set of available
-  # components and how those should be created
+  #   class House
+  #     def initialize(door, window)
+  #       # ...
+  #     end
+  #   end
   #
-  # @abstract Subclass to define a config
-  # @example
   #   class MyConfig < Jerry::Config
-  #     component(:service) { MyService.new }
-  #     component(:app) { MyApp.new rig(:service) }
+  #     bind House, [Door, Window]
+  #     bind Door
+  #     bind Window
   #   end
   class Config
     class << self
-      # @return [Array<Symbol>] list of the components defined by the config
-      def components
-        @components ||= []
+      # Specify how to wire the dependencies of a given class
+      #
+      # @param klass [Class] The class to wire the dependencies for
+      # @param ctor_args [Array<Class, Symbol, Proc>] specifies the arguments to
+      #   be given to the constructor
+      # @return [Class] the class that will be instanciated
+      def bind(klass, ctor_args = [])
+        named_bind klass, klass, ctor_args
       end
 
-      # Defines a component
+      # Specify how to wire the dependencies of a given class giving it a name
       #
-      # @param [Symbol] name name of the component
-      # @param [Hash] options options hash see supported options
-      # @option options [Symbol] (:single) The scope of the component. Can be either :single or :instance.
-      #   When the scope is :single, only one instance of the component will be created and every call
-      #   to Jerry#rig will return the same instance. When the scope is :instance, every call to Jerry#rig
-      #   will return a new instance.
-      # @yield Block used to instantiate the component. This block in only called when Jerry#rig is called.
-      # @raise [Jerry::ComponentError] when the block is missing or the scope is invalid
-      def component(name, options={}, &block)
-        raise Jerry::ComponentError, "could not define component #{name}, block is missing" if block.nil?
+      # @param name [Symbol] The name used to identify this way of building the
+      #   given class
+      # @param klass [Class] The class to wire the dependencies for
+      # @param ctor_args [Array<Class, Symbol, Proc>] specifies the arguments to
+      #   be given to the constructor
+      # @return [Symbol] the name of the class that will be instanciated
+      def named_bind(name, klass, ctor_args = [])
+        providers[name] = ClassProvider.new klass, ctor_args
+        name
+      end
 
-        scope = options[:scope] || :single
-        unless [:single, :instance].include? scope
-          raise Jerry::ComponentError, "could not define component #{name}, scope #{scope} is unknown"
-        end
+      # Specifies that a class should only be instanciated once
+      #
+      # @param key [Class, Symbol] the class or the name of the class that
+      #   should only be instanciated once
+      def singleton(key)
+        return unless providers.key? key
 
-        define_method name do
-          case scope
-            when :single
-              cache[name] ||= instance_eval(&block)
-            when :instance
-              instance_eval(&block)
-          end
-        end
+        provider = providers[key]
 
-        components << name
+        instance = nil
+        providers[key] = ->(*args) { instance ||= provider.call(*args) }
       end
-    end
 
-    # @return [Array<Symbol>] list of components defined by the config
-    def components
-      self.class.components
+      def providers
+        @providers ||= {}
+      end
     end
 
-    # Jerry instance the config is part of
-    #
-    # This gets set by Jerry when it loads a config
+    # The jerry instance this config is part of
     attr_writer :jerry
 
-    protected
+    # @return an instance of an object wired by the config
+    def [](key)
+      provider = self.class.providers[key]
 
-    # Creates a component
-    #
-    # This should be used inside the block passed to Config::component
-    def rig(component)
-      @jerry.rig component
-    end
-
-    # Check if given component exists
-    #
-    # This should be used inside the block passed to Config::component
-    def knows?(component)
-      @jerry.knows? component
+      if provider
+        provider.call @jerry, self
+      else
+        fail InstantiationError,
+             "Failed to instanciate #{key}. Can't find provider for it"
+      end
+    rescue RuntimeError
+      raise InstantiationError, "Provider for #{key} raised an error"
     end
 
-    # Used internally to cache single instance components
-    def cache
-      @cache ||= {}
+    # @return true if this config can provide the given key, false otherwise
+    def knows?(key)
+      self.class.providers.key? key
     end
   end
-end
+end

data/lib/jerry/errors.rb

@@ -0,0 +1,16 @@
+require 'English'
+
+class Jerry
+  # Base error class for Jerry that allows recording causing exceptions
+  class Error < RuntimeError
+    attr_reader :cause
+
+    def initialize(message = nil)
+      super
+      @cause = $ERROR_INFO
+    end
+  end
+
+  # Failed to instanciate a class
+  class InstantiationError < Jerry::Error; end
+end

data/lib/jerry/version.rb

@@ -1,3 +1,3 @@
 class Jerry
-  VERSION = '1.0.1'
+  VERSION = '2.0.0'
 end