carb-container 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 95c46b2436f16825eb22774536485297b23ad8ba
+  data.tar.gz: 60f675251e578ea250cae6f2f47e16e8194714d0
+SHA512:
+  metadata.gz: aa4c49159f53467cff172a8dd54214c702ebaa4b7987f9d015c611c3483f09dc60775debe3406ce22099b54fb4edcef58d0c86c3ba5ed8d7b3a9224bedeb1418
+  data.tar.gz: c32e3f6ef95c1ca332e58a802aeb67415f1631a31b5800c98f73b922117e94dc8bfa1f6a0f12a917d35672df056e9907c2c67acbe59641bd940d293600b82a46

data/.gitignore

@@ -0,0 +1,41 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.project
+.directory
+*.swp
+*~
+.DS_Store
+.idea
+.envrc
+.nvmrc
+.ruby-gemset
+.ruby-version
+.rspec-local
+public
+*.backup
+npm-debug.log
+.rspec_status
+
+# Ignore bundler config
+/.bundle
+/vendor/bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp
+/binstubs/
+
+# Ignore user import data
+/data
+
+# YARD
+.yardoc
+

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in carb-container.gemspec
+gemspec

data/README.md

@@ -0,0 +1,152 @@
+# Carb::Container
+
+A set of simple container objects to store dependencies. Can be used in
+conjuction with [carb-inject](https://github.com/Carburetor/carb-inject) as
+an IoC container.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'carb-container'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install carb-container
+
+## Usage
+
+There are 3 containers available, one interface to create custom containers and
+a utility class that helps you register classes inside the container.
+
+### Carb::Container::Base
+
+This is a simple module that is an interface. Has two methods which must both
+be provided by the developer:
+
+- `[](name)` which is the method used to get dependencies. If you need to raise
+  an error because dependency is missing, you can use
+  `Carb::Container::DependencyMissingError` which accepts the dependency name
+  in the constructor (to improve the error message)
+- `has_key?(name)` which is the method used to check if the key exists on a
+  given container
+
+### Carb::Container::RegistryContainer
+
+This is the main container and probably the only one you will be using. It
+respects the `Carb::Container::Base` interface.
+It stores dependencies (with some utilities) in a hashmap and can be fetched
+back with `#[]` which raises `Carb::Container::DependencyMissingError` in
+case no dependency is found. To register a dependency you simply call
+`#register(name, dependency_enclosed_in_proc)` and it will be stored inside.
+
+```ruby
+class MyClass
+  def hello
+    puts "hi"
+  end
+end
+
+container = Carb::Container::RegistryContainer.new
+container.register(:my_class, -> { MyClass })
+
+container[:my_class].new.hello
+```
+
+### Carb::Container::RegistrationGlue
+
+A utility class that allows you to create a class method inside `Class` so that
+you can easily register any newly created class. This is entirely optional, for
+people who don't like monkey patching, can be skipped.
+
+```ruby
+MyContainer = Carb::Container::RegistryContainer.new
+Carb::Container::RegistrationGlue.call(MyContainer)
+
+module My
+  class Person
+    carb_container
+
+    def greet
+      puts "hi"
+    end
+  end
+end
+
+class Dog
+  carb_container as: :special_dog
+
+  def bark
+    puts "woff"
+  end
+end
+
+person = MyContainer[:my_person].new
+dog    = MyContainer[:special_dog].new
+
+person.greet
+person.bark
+```
+
+### Carb::Container::DelegateContainer
+
+Special container which allows chaining containers together so that a
+dependency not found in the first one, is searched in the subsequent ones. If
+no dependency is found, `Carb::Container::DependencyMissingError` is raised.
+
+```ruby
+Container1 = Carb::Container::RegistryContainer.new
+Container2 = Carb::Container::RegistryContainer.new
+Delegate = Carb::Container::DelegateContainer.new([Container1, Container2])
+
+class Person
+  def greet
+    puts "hello"
+  end
+end
+
+class Dog
+  def bark
+    puts "woff"
+  end
+end
+
+Container1.register(:person, -> { Person })
+Container2.register(:dog, -> { Dog })
+
+Delegate[:dog] == Dog # => true
+Delegate[:person] == Person # => true
+
+Delegate[:foo] # raises DependencyMissingError
+```
+
+### Carb::Container::ErrorContainer
+
+Special container which doesn't allow to register any dependency, always
+raises `Carb::Container::DependencyMissingError` and always returns `false`
+for `has_key?` method. It's only useful within the DelegateContainer or as a
+null object (as in null object pattern).
+
+```ruby
+container = Carb::Container::ErrorContainer.new
+
+container[:foo] # raises DependencyMissingError
+container.has_key?(:bar) # => false
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Carburetor/carb-container.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "carb/container"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/carb-container.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "carb/container/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "carb-container"
+  spec.version       = Carb::Container::VERSION
+  spec.authors       = ["Fire-Dragon-DoL"]
+  spec.email         = ["francesco.belladonna@gmail.com"]
+
+  spec.summary       = %q{Set of IoC containers for carb-inject}
+  spec.description   = %q{Set of IoC containers for carb-inject}
+  spec.homepage      = "https://github.com/Carburetor/carb-container"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "carb-core", ">= 1.0.0"
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake",    "~> 11.0"
+  spec.add_development_dependency "rspec",   "~> 3.0"
+  spec.add_development_dependency "activesupport"
+  spec.add_development_dependency "pry-byebug"
+end

data/lib/carb-container.rb

@@ -0,0 +1 @@
+require "carb/container"

data/lib/carb/container.rb

@@ -0,0 +1,15 @@
+require "carb/container/version"
+require "carb/container/base"
+require "carb/container/already_registered_error"
+require "carb/container/dependency_missing_error"
+require "carb/container/container_validator"
+require "carb/container/registry_container"
+require "carb/container/error_container"
+require "carb/container/delegate_container"
+require "carb/container/registerer"
+require "carb/container/registration_glue"
+
+module Carb
+  module Container
+  end
+end

data/lib/carb/container/already_registered_error.rb

@@ -0,0 +1,14 @@
+require "carb"
+
+module Carb::Container
+  # Error when a dependency with same name already exists
+  class AlreadyRegisteredError < StandardError
+    MESSAGE = "Dependency %s already exists, registered at:\n%s".freeze
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+    end
+  end
+end

data/lib/carb/container/base.rb

@@ -0,0 +1,14 @@
+require "carb"
+
+module Carb::Container
+  # Interface for container definition
+  module Base
+    def [](name)
+      raise NotImplementedError, "#[] not implemented"
+    end
+
+    def has_key?(name)
+      raise NotImplementedError, "#has_key? not implemented"
+    end
+  end
+end

data/lib/carb/container/class_name_to_method_name.rb

@@ -0,0 +1,29 @@
+require "carb"
+
+module Carb::Container
+  # Converts a fully qualified class name to a valid method name. Uses
+  # activesupport if available, otherwise just replaces / with _
+  class ClassNameToMethodName
+    def call(text)
+      snaked = maybe_snake_case(text)
+      snaked = snaked.gsub("/", "_")
+    end
+
+    private
+
+    def maybe_snake_case(text)
+      return text unless maybe_require_activesupport
+      return text unless defined?(::ActiveSupport)
+      return text.underscore if text.respond_to?(:underscore)
+
+      ActiveSupport::Inflector.underscore(text)
+    end
+
+    def maybe_require_activesupport
+      require "active_support/inflector/methods"
+      true
+    rescue
+      false
+    end
+  end
+end

data/lib/carb/container/container_validator.rb

@@ -0,0 +1,21 @@
+require "carb"
+
+module Carb::Container
+  # Checks if object is a valid container
+  class ContainerValidator
+    # @param container [Object]
+    # @return [Boolean] true if object is a container, false otherwise
+    def call(container)
+      is_container   = container.respond_to?(:[])
+      is_container &&= container.respond_to?(:has_key?)
+
+      is_container
+    end
+
+    # @param container [Object]
+    # @return [Boolean] true if object is a container, false otherwise
+    def self.call(container)
+      new.call(container)
+    end
+  end
+end

data/lib/carb/container/delegate_container.rb

@@ -0,0 +1,75 @@
+require "carb"
+require "carb/container/base"
+require "carb/container/dependency_missing_error"
+require "carb/container/container_validator"
+
+module Carb::Container
+  # Container which requests dependency in sequence to a list of containers
+  # otherwise and if none returns, it raises
+  class DelegateContainer
+    include ::Carb::Container::Base
+
+    private
+
+    attr_reader :containers
+    attr_reader :dependencies
+
+    public
+
+    # @param containers [Array] an array of container objects. Must have at
+    #   least one container
+    # @raise [ArgumentError] unless at least one container is supplied
+    def initialize(containers, **dependencies)
+      @containers   = containers
+      @dependencies = dependencies
+      dependencies[:container_validator] ||= ContainerValidator.new
+
+      ensure_at_least_one_container!(containers)
+      ensure_all_are_containers!(containers)
+    end
+
+    # @param name [Object] dependency name
+    # @return [Object] dependency for given name if present in any container
+    #   (only the first in sequence is returned), otherwise raises
+    # @raise [DependencyMissingError]
+    def [](name)
+      containers.each do |container|
+        return container[name] if container.has_key?(name)
+      end
+
+      error_class = ::Carb::Container::DependencyMissingError
+      raise error_class.new(name), format(error_class::MESSAGE, name.to_s)
+    end
+
+    # @param name [Object] dependency name
+    # @return [Boolean] true if dependency is present in any container, false
+    #   otherwise
+    def has_key?(name)
+      containers.any? { |container| container.has_key?(name) }
+    end
+
+    private
+
+    def ensure_at_least_one_container!(containers)
+      return if containers.size > 0
+
+      raise ArgumentError, "At least one container is required"
+    end
+
+    def ensure_object_is_container!(container, index)
+      return if container_validator.(container)
+
+      raise TypeError, "Container at index #{index} is not valid"
+    end
+
+    def ensure_all_are_containers!(containers)
+      containers.each_with_index do |container, index|
+        ensure_object_is_container!(container, index)
+      end
+    end
+
+    def container_validator
+      dependencies[:container_validator]
+    end
+  end
+end

data/lib/carb/container/dependency_missing_error.rb

@@ -0,0 +1,15 @@
+require "carb"
+
+module Carb::Container
+  # Error when trying to fetch a dependency which doesn't exist
+  class DependencyMissingError < StandardError
+    MESSAGE = "Dependency \"%s\" doesn't exist " \
+              "in this container".freeze
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+    end
+  end
+end

data/lib/carb/container/error_container.rb

@@ -0,0 +1,26 @@
+require "carb"
+require "carb/container/base"
+require "carb/container/dependency_missing_error"
+
+module Carb::Container
+  # Container which holds no dependency and will raise every time
+  # one is being fetched
+  class ErrorContainer
+    include ::Carb::Container::Base
+
+    # This method will always raise an error
+    # @param name [Object] dependency name
+    # @raise [::Carb::Container::DependencyMissingError] raised
+    #   whenever a dependency is being fetched from this container
+    def [](name)
+      error_class = ::Carb::Container::DependencyMissingError
+      raise error_class.new(name), format(error_class::MESSAGE, name.to_s)
+    end
+
+    # @param name [Object] dependency name
+    # @return [false]
+    def has_key?(name)
+      false
+    end
+  end
+end

data/lib/carb/container/registerer.rb

@@ -0,0 +1,34 @@
+require "carb"
+require "carb/container/class_name_to_method_name"
+
+module Carb::Container
+  # Provides a class method to register classes globally
+  class Registerer < Module
+    private
+
+    attr_reader :container
+    attr_reader :converter
+
+    # @param container [#register] object which will be used to register
+    #   dependencies as {::Proc}
+    # @param converter [#call] object which accepts a string and converts it
+    #   into a valid method name. It's used to convert class name to a method
+    #   name. By default it uses an instance of {ClassNameToMethodName}
+    def initialize(container, converter: ClassNameToMethodName.new)
+      @container = container
+      @converter = converter
+    end
+
+    def included(klass)
+      # Required for scope purposes
+      kontainer = container
+      convert   = converter
+
+      klass.define_singleton_method(:carb_container) do |as: nil|
+        as ||= convert.call(self.name.to_s)
+        as   = as.to_sym
+        kontainer.register(as, -> { self })
+      end
+    end
+  end
+end

data/lib/carb/container/registration_glue.rb

@@ -0,0 +1,36 @@
+require "carb"
+require "carb/container/registerer"
+require "forwardable"
+
+module Carb::Container
+  # Provides a method hook in all classes to register them as injectable
+  class RegistrationGlue
+    # Creates a new class method {Class#carb_container} which can be used as
+    # a macro to easily register objects into the supplied container
+    # @param container [#register] a generic object, usually a
+    #   {RegistryContainer} which responds to `#register(name, dependency)`,
+    #   it's the only required argument
+    # @param target [Object] class where you want to add the class method
+    #   `carb_container`. Usually it's {::Class} itself
+    # @param registerer [Module] subclass of a module which can be included.
+    #   Usually it's {Registerer} which is an internal module used to store
+    #   objects inside a container which responds to `#register`
+    # @param converter [#call] object which accepts a string and converts it
+    #   into a valid method name. It's used to convert class name to a method
+    #   name. By default it uses an instance of {ClassNameToMethodName}
+    def call(
+      container,
+      target:     Class,
+      registerer: Registerer,
+      converter:  ClassNameToMethodName.new
+    )
+      target.send(:include, registerer.new(container, converter: converter))
+    end
+
+    class << self
+      extend Forwardable
+
+      def_delegators :new, :call
+    end
+  end
+end

data/lib/carb/container/registry_container.rb

@@ -0,0 +1,98 @@
+require "carb"
+require "carb/container/base"
+require "carb/container/already_registered_error"
+require "carb/container/dependency_missing_error"
+
+module Carb::Container
+  include ::Carb::Container::Base
+
+  # Simple {Hash} based container for dependency resolution based on name, with
+  # further registration capabilities
+  class RegistryContainer
+    include ::Carb::Container::Base
+
+    Record = Struct.new(:dependency, :registerer)
+
+    private
+
+    attr_reader :dependencies
+
+    public
+
+    # @param dependencies [Hash{Object => Proc}] dependency name with proc
+    #   as value, which will be `call`ed to extract the dependency object
+    def initialize(dependencies = {})
+      @dependencies = {}
+      dependencies.each do |name, dep|
+        register_with_caller(name, dep, caller_locations[0])
+      end
+    end
+
+    # @param name [Object] name used to fetch back the dependency
+    # @param dependency [Proc] dependency to be stored, must be wrapped within
+    #   a lambda
+    # @raise [TypeError] raised if dependency is not a {Proc}
+    # @raise [AlreadyRegisteredError] raise when a dependency with same name
+    #   already exists
+    # @return [RegistryContainer] self (for chaining purposes)
+    def register(name, dependency)
+      register_with_caller(name, dependency, caller_locations[0])
+      self
+    end
+
+    # Gets a dependency
+    # @param name [Object] dependency name with which it was registered
+    # @return [nil, Object] nil if dependency is missing, otherwise the
+    #   dependency, unwrapped from proc
+    def [](name)
+      ensure_dependency_present!(name)
+
+      dependencies[name].dependency.()
+    end
+
+    # Checks if the dependency exists within the container
+    # @param name [Object] dependency name with which it was registered
+    # @return [Boolean] true if the dependency exists within the container,
+    #   false otherwise
+    def has_key?(name)
+      dependencies.has_key?(name)
+    end
+
+    private
+
+    def register_with_caller(name, dependency, registerer)
+      ensure_dependency_type!(dependency)
+      ensure_dependency_uniqueness!(name)
+
+      dependencies[name] = Record.new(dependency, registerer)
+    end
+
+    def ensure_dependency_present!(name)
+      return if has_key?(name)
+
+      raise DependencyMissingError.new(name), missing(name)
+    end
+
+    def ensure_dependency_type!(dependency)
+      return if dependency.respond_to?(:call)
+
+      raise TypeError, "dependency must be a Proc"
+    end
+
+    def ensure_dependency_uniqueness!(name)
+      return unless dependencies.has_key?(name)
+
+      record = dependencies.fetch(name)
+      raise AlreadyRegisteredError.new(name), registered(name, record)
+    end
+
+    def registered(name, record)
+      registerer = record.registerer
+      format(AlreadyRegisteredError::MESSAGE, name.to_s, registerer.to_s)
+    end
+
+    def missing(name)
+      format(DependencyMissingError::MESSAGE, name.to_s)
+    end
+  end
+end

data/lib/carb/container/version.rb

@@ -0,0 +1,5 @@
+module Carb
+  module Container
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: carb-container
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fire-Dragon-DoL
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-05-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: carb-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Set of IoC containers for carb-inject
+email:
+- francesco.belladonna@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- carb-container.gemspec
+- lib/carb-container.rb
+- lib/carb/container.rb
+- lib/carb/container/already_registered_error.rb
+- lib/carb/container/base.rb
+- lib/carb/container/class_name_to_method_name.rb
+- lib/carb/container/container_validator.rb
+- lib/carb/container/delegate_container.rb
+- lib/carb/container/dependency_missing_error.rb
+- lib/carb/container/error_container.rb
+- lib/carb/container/registerer.rb
+- lib/carb/container/registration_glue.rb
+- lib/carb/container/registry_container.rb
+- lib/carb/container/version.rb
+homepage: https://github.com/Carburetor/carb-container
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Set of IoC containers for carb-inject
+test_files: []