callme 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 22eae5e35215e5eed4a7876f1bdac5b8f8f9bcdb
+  data.tar.gz: 734e00afe63b56af60134a224acc0489ae09d481
+SHA512:
+  metadata.gz: ab1b440d21c6f30ee6ff3d95b89d5462485bf5505a468994ee1712117dc3e5c2e6b019b6e17660313f6ecbb7937f1c539e286a98a3464e0cb5d8f091f6def3cd
+  data.tar.gz: be2243ddbedb38520e29e85e652db9f2a09a168d99ae89dec6c30e2e8e57925f2e95be4e35094eb342d87f0adc93137bfdcdd008d6782c7fae096667c852d55b

data/.gitignore

@@ -0,0 +1,5 @@
+vendor/
+tags
+.bundle
+.DS_Store
+pkg

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+- 2.0.0
+script: "bundle exec rspec spec/"

data/.yardops

@@ -0,0 +1 @@
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in aggregate_builder.gemspec
+gemspec
+
+group :test do
+  gem 'rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    callme (0.5.0)
+      request_store
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rake (10.1.1)
+    request_store (1.0.5)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  callme!
+  rake
+  rspec
+
+BUNDLED WITH
+   1.14.6

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Albert Gazizov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# Callme [![Build Status](https://travis-ci.org/mindreframer/callme.png)](https://travis-ci.org/mindreframer/callme) [![Code Climate](https://codeclimate.com/github/mindreframer/callme.png)](https://codeclimate.com/github/mindreframer/callme)
+
+
+
+Callme is an Inversion of Control container for Ruby.
+It takes advantage of the dynamic nature of Ruby to provide a rich and flexible approach to injecting dependencies.
+It's inspired by SpringIoc and tries to give you the same features.
+
+## Usage
+Lets say you have a Logger which has the Appender dependency
+
+```ruby
+class Logger
+  attr_accessor :appender
+
+  def info(message)
+    # do some work with appender
+  end
+end
+
+class Appender
+end
+```
+To use Logger you need to inject the instance of Appender class, for example
+using setter injection:
+```ruby
+logger = Logger.new
+logger.appender = Appender.new
+logger.info('some message')
+```
+
+Callme eliminates the manual injection step and injects dependencies by itself.
+To use it you need to instantiate Callme::Container and pass dependency definitions(we call them beans) to it:
+```ruby
+container = Callme::Container.new do |c|
+  c.bean(:appender, class: Appender)
+  c.bean(:logger, class: Logger) do
+    attr :appender, ref: :appender
+  end
+end
+```
+Now you can get the Logger instance from container with already set dependencies and use it:
+```ruby
+logger = container[:logger]
+logger.info('some message')
+```
+
+To simplify injection Callme allows you specify dependencies inside of your class:
+```ruby
+class Logger
+  inject :appender
+
+  def info(message)
+    # do some work with appender
+  end
+end
+
+class Appender
+end
+```
+With `inject` keyword you won't need to specify class dependencies in bean definition:
+```ruby
+container = Callme::Container.new do |c|
+  c.bean(:appender, class: Appender)
+  c.bean(:logger, class: Logger)
+end
+```
+
+
+
+## Inheriting from other containers
+Quite often you will want to selectively override some parts of the system, use `Callme::Container.with_parent` to
+create a new container with all the beans copied from the parent container.
+
+```ruby
+class ContactBook
+  inject :contacts_repository
+  inject :validator, ref: :contact_validator
+end
+class ContactBookService
+  inject :contacts_repository
+  inject :validator, ref: :contact_validator
+end
+class ContactsRepository
+end
+class ContactValidator
+end
+class TestContactValidator
+end
+
+class AnotherTestContactValidator
+end
+
+parent = Callme::Container.new do |c|
+  c.bean(:contacts_repository,  class: ContactsRepository)
+  c.bean(:contact_validator,    class: ContactValidator)
+  c.bean(:contact_book,         class: ContactBook)
+  c.bean(:contact_book_service, class: "ContactBookService")
+end
+puts parent[:contact_book_service].validator.class
+#=> ContactValidator
+
+testcontainer = Callme::Container.with_parent(parent) do |c|
+  c.bean(:contact_validator,    class: TestContactValidator)
+end
+puts testcontainer[:contact_book_service].validator.class
+#=> TestContactValidator
+
+third = Callme::Container.with_parent(parent) do |c|
+  c.bean(:contact_validator,    class: AnotherTestContactValidator)
+end
+
+puts third[:contact_book_service].validator.class
+#=> AnotherTestContactValidator
+```
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'callme'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install callme
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+# TODO
+1. Constructor based injection
+2. Scope registration, refactor BeanFactory. Callme:Container.register_scope(SomeScope)
+3. Write documentation with more examples
+
+## Author
+Roman Heinrich, [@mindreframer](https://twitter.com/mindreframer)
+Albert Gazizov, [@deeper4k](https://twitter.com/deeper4k)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "callme"
+
+require "irb"
+IRB.start(__FILE__)

data/callme.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'callme/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "callme"
+  spec.version       = Callme::VERSION
+  spec.authors       = ["Roman Heinrich", "Albert Gazizov"]
+  spec.email         = ["roman.heinrich@gmail.com"]
+  spec.description   = %q{Callme: Simple depencency injection lib}
+  spec.summary       = %q{Callme: Simple depencency injection lib}
+  spec.homepage      = "http://github.com/mindreframer/callme"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "request_store"
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/callme/args_validator.rb

@@ -0,0 +1,49 @@
+# Helper class for arguments validation
+module Callme::ArgsValidator
+  class << self
+
+    # Checks that specifid +obj+ is a symbol
+    # @param obj some object
+    # @param obj_name object's name, used to clarify error causer in exception
+    def is_symbol!(obj, obj_name)
+      unless obj.is_a?(Symbol)
+        raise ArgumentError, "#{obj_name} should be a Symbol"
+      end
+    end
+
+    # Checks that specifid +obj+ is an Array
+    # @param obj some object
+    # @param obj_name object's name, used to clarify error causer in exception
+    def is_array!(obj, obj_name)
+      unless obj.is_a?(Array)
+        raise ArgumentError, "#{obj_name} should be an Array"
+      end
+    end
+
+    # Checks that specifid +obj+ is a Hash
+    # @param obj some object
+    # @param obj_name object's name, used to clarify error causer in exception
+    def is_hash!(obj, obj_name)
+      unless obj.is_a?(Hash)
+        raise ArgumentError, "#{obj_name} should be a Hash"
+      end
+    end
+
+    # Checks that specifid +hash+ has a specified +key+
+    # @param hash some hash
+    # @param key hash's key
+    def has_key!(hash, key)
+      unless hash.has_key?(key)
+        raise ArgumentError, "#{hash} should has #{key} key"
+      end
+    end
+
+    # Checks that specified +block+ is given
+    # @param block some block
+    def block_given!(block)
+      unless block
+        raise ArgumentError, "Block should be given"
+      end
+    end
+  end
+end

data/lib/callme/bean_factory.rb

@@ -0,0 +1,115 @@
+require 'callme/scopes'
+require 'callme/scopes/singleton_scope'
+require 'callme/scopes/prototype_scope'
+require 'callme/scopes/request_scope'
+
+# Instantiates beans according to their scopes
+class Callme::BeanFactory
+  attr_reader :const_loader
+
+  # Constructor
+  # @param beans_metadata_storage [BeansMetadataStorage] storage of bean metadatas
+  def initialize(const_loader, beans_metadata_storage)
+    @const_loader           = const_loader
+    @beans_metadata_storage = beans_metadata_storage
+    @singleton_scope        = Callme::Scopes::SingletonScope.new(self)
+    @prototype_scope        = Callme::Scopes::PrototypeScope.new(self)
+    @request_scope          = Callme::Scopes::RequestScope.new(self)
+  end
+
+  # Get bean from the container by it's +name+.
+  # According to the bean scope it will be newly created or returned already
+  # instantiated bean
+  # @param [Symbol] bean name
+  # @return bean instance
+  # @raise MissingBeanError if bean with the specified name is not found
+  def get_bean(name)
+    bean_metadata = @beans_metadata_storage.by_name(name)
+    unless bean_metadata
+      raise Callme::Errors::MissingBeanError, "Bean with name :#{name} is not defined"
+    end
+    get_bean_with_metadata(bean_metadata)
+  end
+
+  # Get bean by the specified +bean metadata+
+  # @param [BeanMetadata] bean metadata
+  # @return bean instance
+  def get_bean_with_metadata(bean_metadata)
+    get_scope_by_metadata(bean_metadata).get_bean(bean_metadata)
+  end
+
+  # Create new bean instance according
+  # to the specified +bean_metadata+
+  # @param [BeanMetadata] bean metadata
+  # @return bean instance
+  # @raise MissingBeanError if some of bean dependencies are not found
+  def create_bean_and_save(bean_metadata, beans_storage)
+    if bean_metadata.bean_class.is_a?(Class)
+      bean_class = bean_metadata.bean_class
+    else
+      bean_class = const_loader.load_const(bean_metadata.bean_class)
+      bean_metadata.fetch_attrs!(bean_class)
+    end
+    bean = bean_metadata.instance ? bean_class.new : bean_class
+    if bean_metadata.has_factory_method?
+      set_bean_dependencies(bean, bean_metadata)
+      bean = bean.send(bean_metadata.factory_method)
+      beans_storage[bean_metadata.name] = bean
+    else
+      # put to container first to prevent circular dependencies
+      beans_storage[bean_metadata.name] = bean
+      set_bean_dependencies(bean, bean_metadata)
+    end
+
+    bean
+  end
+
+  # Delete bean from the container by it's +name+.
+  # @param [Symbol] bean name
+  # @raise MissingBeanError if bean with the specified name is not found
+  def delete_bean(name)
+    bean_metadata = @beans_metadata_storage.by_name(name)
+    unless bean_metadata
+      raise Callme::Errors::MissingBeanError, "Bean with name :#{name} is not defined"
+    end
+    get_scope_by_metadata(bean_metadata).delete_bean(bean_metadata)
+  end
+
+  private
+
+  def set_bean_dependencies(bean, bean_metadata)
+    bean_metadata.attrs.each do |attr|
+      bean_metadata = @beans_metadata_storage.by_name(attr.ref)
+      unless bean_metadata
+        raise Callme::Errors::MissingBeanError, "Bean with name :#{attr.ref} is not defined, check #{bean.class}"
+      end
+      case bean_metadata.scope
+      when :singleton
+        bean.send("#{attr.name}=", get_bean(attr.ref))
+      when :prototype
+        bean.instance_variable_set(:@_callme_bean_factory, self)
+        bean.define_singleton_method(attr.name) do
+          @_callme_bean_factory.get_bean(attr.ref)
+        end
+      when :request
+        bean.instance_variable_set(:@_callme_bean_factory, self)
+        bean.define_singleton_method(attr.name) do
+          @_callme_bean_factory.get_bean(attr.ref)
+        end
+      end
+    end
+  end
+
+  def get_scope_by_metadata(bean_metadata)
+    case bean_metadata.scope
+    when :singleton
+      @singleton_scope
+    when :prototype
+      @prototype_scope
+    when :request
+      @request_scope
+    else
+      raise Callme::Errors::UnsupportedScopeError, "Bean with name :#{bean_metadata.name} has unsupported scope :#{bean_metadata.scope}"
+    end
+  end
+end

data/lib/callme/bean_metadata.rb

@@ -0,0 +1,70 @@
+# Stores bean specific data: bean class, name,
+# scope and bean dependencies
+class Callme::BeanMetadata
+  attr_reader :name, :bean_class, :scope, :instance, :factory_method, :attrs
+
+  # Constructor
+  # @param name [Symbol] bean name
+  # @params options [Hash] includes bean class and scope
+  # @params &block [Proc] bean dependencies, has the following structure:
+  #   do |c|
+  #     attr :some_dependency, ref: :dependency_name
+  #     arg  :another_dependency, ref: :another_dependency_name
+  #   end
+  # here attr means setter injection, arg means constructon injects
+  # +some_dependency+ is an attr_accessor defined in the bean class,
+  # +ref+ specifies what dependency from container to use to set the attribute
+  def initialize(name, options, &block)
+    Callme::ArgsValidator.has_key!(options, :class)
+
+    @name           = name
+    @bean_class     = options[:class]
+    @scope          = options[:scope] || :singleton
+    @instance       = options[:instance].nil? ? true : options[:instance]
+    @factory_method = options[:factory_method]
+    @attrs          = []
+
+    fetch_attrs!(@bean_class)
+
+    if block
+      Dsl.new(@attrs).instance_exec(&block)
+    end
+  end
+
+  def fetch_attrs!(klass)
+    if klass.respond_to?(:_callme_injectable_attrs)
+      klass._callme_injectable_attrs.each do |attr, options|
+        options[:ref] ||= attr
+        @attrs << Callme::BeanMetadata::Attribute.new(attr, options)
+      end
+    end
+  end
+
+  def has_factory_method?
+    !!@factory_method
+  end
+
+  class Attribute
+    attr_reader :name, :ref
+
+    def initialize(name, options)
+      Callme::ArgsValidator.has_key!(options, :ref)
+      @name = name
+      @ref  = options[:ref]
+    end
+  end
+
+  class Dsl
+    def initialize(attrs)
+      @attrs = attrs
+    end
+
+    def attr(name, options)
+      @attrs << Callme::BeanMetadata::Attribute.new(name, options)
+    end
+
+    def arg(name, options)
+      @args << Callme::BeanMetadata::Attribute.new(name, options)
+    end
+  end
+end

data/lib/callme/beans_metadata_storage.rb

@@ -0,0 +1,32 @@
+# Storage of bean metadatas
+class Callme::BeansMetadataStorage
+  def initialize(bean_metadatas = {})
+    @bean_metadatas = bean_metadatas
+  end
+
+  # Finds bean metadata in storage by it's name
+  # @param name [Symbol] bean metadata name
+  # @return bean metadata
+  def by_name(name)
+    @bean_metadatas[name]
+  end
+
+  # Saves a given +bean_metadata+ to the storage
+  # @param bean_metadata [BeanMetadata] bean metadata for saving
+  def put(bean_metadata)
+    @bean_metadatas[bean_metadata.name] = bean_metadata
+  end
+
+  def bean_classes
+    @bean_metadatas.values.map(&:bean_class)
+  end
+
+  def keys
+    @bean_metadatas.keys
+  end
+
+  # Creates an independent copy of this instance
+  def copy
+    self.class.new(@bean_metadatas.dup)
+  end
+end

data/lib/callme/const_loaders/active_support.rb

@@ -0,0 +1,7 @@
+module Callme::ConstLoaders
+  module ActiveSupport
+    def self.load_const(const_name)
+      ::ActiveSupport::Inflector.constantize(const_name)
+    end
+  end
+end

data/lib/callme/const_loaders/native.rb

@@ -0,0 +1,9 @@
+module Callme::ConstLoaders
+  module Native
+    def self.load_const(const_name)
+      const_name.split('::').inject(Object) do |mod, const_part|
+        mod.const_get(const_part)
+      end
+    end
+  end
+end

data/lib/callme/container.rb

@@ -0,0 +1,107 @@
+require 'callme/errors'
+require 'callme/args_validator'
+require 'callme/bean_metadata'
+require 'callme/beans_metadata_storage'
+require 'callme/bean_factory'
+require 'callme/const_loaders/native'
+
+module Callme
+
+  # Callme::Container is the central data store for registering objects
+  # used for dependency injection. Users register classes by
+  # providing a name and a class to create the object(we call them beans). Beans
+  # may be retrieved by asking for them by name (via the [] operator)
+  class Container
+    DEFAULT_CONST_LOADER = Callme::ConstLoaders::Native
+
+    # Constructor
+    # @param resources [Array] array of procs with container's beans definitions
+    # @param &block [Proc] optional proc with container's beans definitions
+    def initialize(const_loader = DEFAULT_CONST_LOADER, &block)
+      @const_loader           = const_loader
+      @beans_metadata_storage = Callme::BeansMetadataStorage.new
+      @bean_factory           = Callme::BeanFactory.new(const_loader, @beans_metadata_storage)
+
+      block.call(self) if block_given?
+    end
+
+    # Evaluates the given array of blocks on the container instance
+    # what adds new bean definitions to the container
+    # @param resources [Array] array of procs with container's beans definitions
+    def self.new_with_beans(resources, const_loader = DEFAULT_CONST_LOADER)
+      Callme::ArgsValidator.is_array!(resources, :resources)
+
+      self.new(const_loader).tap do |container|
+        resources.each do |resource|
+          resource.call(container)
+        end
+      end
+    end
+
+    def self.with_parent(parent_container, &block)
+      const_loader           = parent_container.instance_variable_get("@const_loader")
+      beans_metadata_storage = parent_container.instance_variable_get("@beans_metadata_storage").copy
+      container              = self.new(const_loader)
+      container.instance_eval do
+        @beans_metadata_storage = beans_metadata_storage
+        @bean_factory           = Callme::BeanFactory.new(const_loader, beans_metadata_storage)
+      end
+      block.call(container) if block_given?
+      container
+    end
+
+    # Registers new bean in container
+    # @param bean_name [Symbol] bean name
+    # @param options [Hash] includes bean class and bean scope
+    # @param &block [Proc] the block  which describes bean dependencies,
+    #                      see more in the BeanMetadata
+    def bean(bean_name, options, &block)
+      Callme::ArgsValidator.is_symbol!(bean_name, :bean_name)
+      Callme::ArgsValidator.is_hash!(options, :options)
+
+      bean = Callme::BeanMetadata.new(bean_name, options, &block)
+      @beans_metadata_storage.put(bean)
+    end
+
+    # Registers new bean in container and replace existing instance if it's instantiated
+    # @param bean_name [Symbol] bean name
+    # @param options [Hash] includes bean class and bean scope
+    # @param &block [Proc] the block  which describes bean dependencies,
+    #                      see more in the BeanMetadata
+    def replace_bean(bean_name, options, &block)
+      if @bean_factory.get_bean(bean_name)
+        @bean_factory.delete_bean(bean_name)
+      end
+      bean(bean_name, options, &block)
+    end
+
+    def reset!
+      @bean_factory = Callme::BeanFactory.new(@const_loader, @beans_metadata_storage)
+    end
+
+    # Returns bean instance from the container
+    # by the specified bean name
+    # @param name [Symbol] bean name
+    # @return bean instance
+    def [](name)
+      Callme::ArgsValidator.is_symbol!(name, :bean_name)
+      return @bean_factory.get_bean(name)
+    end
+
+    def keys
+      @beans_metadata_storage.keys
+    end
+
+    # Load defined in bean classes
+    # this is needed for production usage
+    # for eager loading
+    def eager_load_bean_classes
+      @beans_metadata_storage.bean_classes.each do |bean_class|
+        if !bean_class.is_a?(Class)
+          @const_loader.load_const(bean_class)
+        end
+      end
+    end
+
+  end
+end

data/lib/callme/errors.rb

@@ -0,0 +1,10 @@
+module Callme::Errors
+  # Thrown when a service cannot be located by name.
+  class MissingBeanError < StandardError; end
+
+  # Thrown when a duplicate service is registered.
+  class DuplicateBeanError < StandardError; end
+
+  # Thrown when an unsupported bean scope is specified.
+  class UnsupportedScopeError < StandardError; end
+end