ruse 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eea82ddd26c784db349a59f881be20f9137061bc
-  data.tar.gz: a9612d3e8d4802eb5291a2615b2ebba9d8f76343
+  metadata.gz: d095e3c4fbabc172f422463a08a3509906cd45cd
+  data.tar.gz: 511b955cccf7a731dec5b94f2fdda97ad6bdd6a1
 SHA512:
-  metadata.gz: ba15491b3261228c622116eb269594b9bd77b5e1910e9146fc8821ddff10eff6c05c7a8fd691098b3952a5bc4e9894d0b6b7fd2018027e6124aade947fe29a5c
-  data.tar.gz: d6a1d5057fe6ffa7a144d5998402b92a53b5d487b51b19745c72730517243b5e0e3d7b8452ffb5b0022f204db2a5286f5402991c1a379f9a4db333b80b3a5558
+  metadata.gz: 8c12916ebcd87eb57c84f6ab9f965323942fea70b3fbc49b69c184d3e7b5af957312908dedc8f0d4914391593ebe6c9be20745298d057381e22b15de0c0876b7
+  data.tar.gz: 37ffdd78470a69c001b778688a94dabec4d6229c28306a7c977107b4cab8380eba569347f83d23f1bc9e7ad06d3085dff9d5b6f12a3d0e63a5dfc540c0cd9863

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+rvm:
+- 1.9.3
+- 2.0
+- 2.1

data/README.md

@@ -82,19 +82,86 @@ all the way down the object graph.
 
 ## Instance Resolution
 
-Dependencies are determined by the identifiers used in constructure parameters.
+Dependencies are determined by the identifiers used in constructor parameters.
 This was lifted directly from angular.js, and I believe may be the key to
 reducing the overhead in using a tool like this. Your dependency consuming
 classes do not have to be annotated or registered in any way.
 
-In this early alpha state, identifiers are resolved to types through simple
+By default, identifiers are resolved to types through simple
 string manipulation (similiar to ActiveSupport's `classify` and `constantize`).
 That means you can get an instance of `SomeService` by requesting
-`"SomeService"`, `"some_service"` or `:some_service`.
+`"SomeService"`, `"some_service"` or `:some_service`. The type is then
+instantiated (populating all of *its* dependencies using the same mechanism)
+and passed in to the constructor.
 
-In the future, I can imagine a simple configuration mechanism that lets you
-resolve an identifier to some other type, so `"notifier"` resolves to
-`EmailNotifier`.
+However, you can configure the injector to use types that differ from the
+parameter name, or return existing objects.
+
+## Instance Lifecycle
+
+Currently, all objects retrieved from the injector are treated as singletons.
+This means that any time you ask a given injector for an instance of a
+service, you will always get the same exact instance. If you want a new
+instance, you need to use a new instance of the injector. In the future,
+the lifecycle may be configurable, but I haven't needed it yet.
+
+## Configuration
+
+Currently, you configure the injector by passing an options `Hash` to
+`Ruse.create_injector` or to the `#configure` method of an `Injector` instance.
+You can call the `#configure` method multiple times, and each time the options
+will be merged into the existing options.
+
+Eventually there may be an API or DSL for building the options `Hash`, but for
+now, you need to know the specific keys that are understood internally.
+
+### Aliases
+
+Aliases are the most common configuration. They allow you to specify the type
+that should be injected for a given parameter name. In the example above,
+the `CreateOrderCommand` relies on a `:notifier`. By default, Ruse will
+attempt to inject an instance of `Notifier`. However, you may have two services
+that can act as a `notifier`: `EmailNotifier` or `FileSystemNotifier`.
+
+In production, you want real emails to be sent, so you would configure the
+injector to use `EmailNotifier`:
+
+```ruby
+Ruse.create_injector aliases: {notifier: "EmailNotifier"}
+```
+
+However, in testing, you just want to record notifications in the filesystem:
+
+```ruby
+Ruse.create_injector aliases: {notifier: "FileSystemNotifier"}
+```
+
+### Values
+
+Sometimes you want to inject a specific value, or existing object instance,
+instead of relying on the injector to create the instance.
+
+```ruby
+Ruse.create_injector values: {max_uploads: 42, file_system: File}
+```
+
+You could now create a class that depends on `file_system` and send messages
+exposed by `File`, without an explicit dependency on `File` (making it easy
+to pass in a stub file system during tests).
+
+### Factories / Procs / Delayed Evaluation
+
+Factories are similar to `values`, but allow you to delay the creation of the
+object until it is requested. For example, you might want to inject a
+connection to a 3rd party service, but you don't want to create the connection
+at configuration time - you want to wait until it is used.
+
+```ruby
+Ruse.create_injector factories: {
+  s3_connection:
+    ->{ AWS::S3.new(config).buckets["my_files"] }
+}
+```
 
 ## Installation
 

data/lib/ruse/injector.rb

@@ -1,6 +1,12 @@
+require 'ruse/proc_resolver'
+require 'ruse/type_resolver'
+require 'ruse/value_resolver'
+require 'ruse/object_factory'
+
 module Ruse
   class Injector
     def get(identifier)
+      ensure_valid_identifier! identifier
       identifier = aliases[identifier] || identifier
       cache_fetch(identifier) do
         resolver = find_resolver identifier
@@ -10,11 +16,32 @@ module Ruse
     end
 
     def configure(settings)
-      configuration.merge! settings
+      configuration.each do |key, hsh|
+        hsh.merge!(settings[key] || {})
+      end
+    end
+
+    def can_resolve?(identifier)
+      return false if invalid_identifier?(identifier)
+      find_resolver(identifier) ? true : false
     end
 
     private
 
+    def ensure_valid_identifier!(identifier)
+      if invalid_identifier? identifier
+        raise InvalidServiceName.new("<#{identifier.inspect}>")
+      end
+    end
+
+    def invalid_identifier?(identifier)
+      identifier.nil? || empty_string?(identifier)
+    end
+
+    def empty_string?(s)
+      s.is_a?(String) && s !~ /[^[:space:]]/
+    end
+
     def cache_fetch(identifier, &block)
       return cache[identifier] if cache.key?(identifier)
       cache[identifier] = block.call
@@ -32,6 +59,17 @@ module Ruse
       }
     end
 
+    def reset_configuration
+      @configuration = nil
+    end
+    # Allow #initialize_clone to reset the configuration of the cloned injector
+    protected :reset_configuration
+
+    def initialize_clone(cloned_injector)
+      cloned_injector.reset_configuration
+      cloned_injector.configure(configuration)
+    end
+
     def aliases
       configuration[:aliases]
     end
@@ -60,98 +98,5 @@ module Ruse
   end
 
   class UnknownServiceError < StandardError; end
-
-  class ProcResolver
-    attr_reader :factories
-    def initialize(factories)
-      @factories = factories
-    end
-    def can_build?(identifier)
-      factories.key? identifier
-    end
-
-    def build(identifier)
-      factory = factories.fetch(identifier)
-      factory.call
-    end
-  end
-
-  class ValueResolver
-    attr_reader :values
-
-    def initialize(values)
-      @values = values
-    end
-
-    def can_build?(identifier)
-      values.key? identifier
-    end
-
-    def build(identifier)
-      values.fetch(identifier)
-    end
-  end
-
-  class TypeResolver
-    def initialize(injector)
-      @injector = injector
-    end
-
-    def can_build?(identifier)
-      type_name = self.class.classify(identifier)
-      load_type type_name
-    end
-
-    def build(identifier)
-      type = resolve_type identifier
-      object_factory.build(type)
-    end
-
-    def self.classify(term)
-      # lifted from active_support gem: lib/active_support/inflector/methods.rb
-      string = term.to_s
-      string = string.sub(/^[a-z\d]*/) { $&.capitalize }
-      string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{ $2.capitalize}" }.gsub('/', '::')
-    end
-
-    private
-
-    def load_type(type_name)
-      type_name.split('::').reduce(Object){|ns, name|
-        if ns.const_defined? name
-          ns.const_get name
-        end
-      }
-    end
-
-    def object_factory
-      @object_factory ||= ObjectFactory.new(@injector)
-    end
-
-    def resolve_type(identifier)
-      type_name = self.class.classify(identifier)
-      load_type type_name
-    end
-  end
-
-  class ObjectFactory
-    attr_reader :injector
-
-    def initialize(injector)
-      @injector = injector
-    end
-
-    def build(type)
-      args = resolve_dependencies type
-      type.new *args
-    end
-
-    private
-
-    def resolve_dependencies(type)
-      type.instance_method(:initialize).parameters.map{|_, identifier|
-        @injector.get identifier
-      }
-    end
-  end
+  class InvalidServiceName < StandardError; end
 end

data/lib/ruse/object_factory.rb

@@ -0,0 +1,94 @@
+module Ruse
+  class ObjectFactory
+    attr_reader :injector
+
+    def initialize(injector)
+      @injector = injector
+    end
+
+    def build(type)
+      initializer = Initializer.new @injector, type.instance_method(:initialize)
+      initializer.resolve_dependencies!
+      type.new *initializer.args
+    end
+
+    class Initializer
+      attr_reader :positional_args, :keyword_args
+
+      def initialize(injector, initialize_method)
+        @injector          = injector
+        @initialize_method = initialize_method
+        @positional_args   = []
+        @keyword_args      = {}
+      end
+
+      def args
+        [*positional_args, keyword_args].tap do |list|
+          list.pop if list.last.empty?
+        end
+      end
+
+      def resolve_dependencies!
+        @initialize_method.parameters.each do |arg_type, identifier|
+          MethodArgument.build(arg_type, identifier, @injector).resolve(self)
+        end
+      end
+
+      MethodArgument = Struct.new :arg_type, :identifier, :injector do
+        def self.build(arg_type, *args)
+          [PositionalArgument, KeywordArgument].each do |klass|
+            return klass.new(arg_type, *args) if klass.match?(arg_type)
+          end
+          UnhandleableArgument
+        end
+
+        def build_dependency
+          injector.get identifier
+        end
+
+        def must_resolve?
+          required? || injector.can_resolve?(identifier)
+        end
+
+        def resolve(initializer)
+          resolve!(initializer) if must_resolve?
+        end
+      end
+
+      class PositionalArgument < MethodArgument
+        def self.match?(arg_type)
+          [:req, :opt].include? arg_type
+        end
+
+        def required?
+          arg_type == :req
+        end
+
+        def resolve!(initializer)
+          initializer.positional_args << build_dependency
+        end
+      end
+
+      class KeywordArgument < MethodArgument
+        def self.match?(arg_type)
+          [:key, :keyreq].include? arg_type
+        end
+
+        def required?
+          arg_type == :keyreq
+        end
+
+        def resolve!(initializer)
+          initializer.keyword_args[identifier] = build_dependency
+        end
+      end
+
+      # Singleton object that be substituted for the other MethodArgument
+      # subclasses when we don't want to try resolving the argument.
+      module UnhandleableArgument
+        extend self
+        def resolve(*) end
+      end
+    end
+  end
+end

data/lib/ruse/proc_resolver.rb

@@ -0,0 +1,14 @@
+class ProcResolver
+  attr_reader :factories
+  def initialize(factories)
+    @factories = factories
+  end
+  def can_build?(identifier)
+    factories.key? identifier
+  end
+
+  def build(identifier)
+    factory = factories.fetch(identifier)
+    factory.call
+  end
+end

data/lib/ruse/type_resolver.rb

@@ -0,0 +1,47 @@
+module Ruse
+  class TypeResolver
+    def initialize(injector)
+      @injector = injector
+    end
+
+    def can_build?(identifier)
+      type_name = self.class.classify(identifier)
+      load_type type_name
+    end
+
+    def build(identifier)
+      type = resolve_type identifier
+      object_factory.build(type)
+    end
+
+    def self.classify(term)
+      # lifted from active_support gem: lib/active_support/inflector/methods.rb
+      string = term.to_s
+      string = string.sub(/^[a-z\d]*/) { $&.capitalize }
+      string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{ $2.capitalize}" }.gsub('/', '::')
+    end
+
+    private
+
+    def base_module
+      Object
+    end
+
+    def load_type(type_name)
+      type_name.split('::').reduce(base_module){|ns, name|
+        if ns.const_defined? name
+          ns.const_get name
+        end
+      }
+    end
+
+    def object_factory
+      @object_factory ||= ObjectFactory.new(@injector)
+    end
+
+    def resolve_type(identifier)
+      type_name = self.class.classify(identifier)
+      load_type type_name
+    end
+  end
+end

data/lib/ruse/value_resolver.rb

@@ -0,0 +1,17 @@
+module Ruse
+  class ValueResolver
+    attr_reader :values
+
+    def initialize(values)
+      @values = values
+    end
+
+    def can_build?(identifier)
+      values.key? identifier
+    end
+
+    def build(identifier)
+      values.fetch(identifier)
+    end
+  end
+end

data/lib/ruse/version.rb

@@ -1,3 +1,3 @@
 module Ruse
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/ruse.gemspec

@@ -18,6 +18,6 @@ Gem::Specification.new do |spec|
   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 "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
 end

data/specs/injector_keyword_args_spec.rb

@@ -0,0 +1,75 @@
+require 'minitest/spec'
+require 'minitest/autorun'
+require 'ruse/injector'
+
+describe Ruse::Injector do
+  def injector
+    @injector ||= Ruse::Injector.new
+  end
+
+  it "injects keyword arguments it can resolve, delegating to defaults when it can't" do
+    skip("No keyword argument support before Ruby 2.0") unless RUBY_VERSION >= "2.0"
+    object = injector.get("HasKeywordArguments")
+    object.a.must_be_kind_of ServiceA
+    object.z.must_equal :z
+  end
+
+  it "injects optional parameters it can resolve, delegating to defaults when it can't" do
+    skip("No keyword argument support before Ruby 2.0") unless RUBY_VERSION >= "2.0"
+    object = injector.get("HasOptionalParameters")
+    object.a.must_be_kind_of ServiceA
+    object.z.must_equal :z
+  end
+
+  it "injects required keyword arguments" do
+    skip("No required keyword argument support before Ruby 2.1") unless RUBY_VERSION >= "2.1"
+    object = injector.get("HasRequiredKeywordArguments")
+    object.a.must_be_kind_of ServiceA
+  end
+
+  it "exceptions when a required keyword argument can't resolve" do
+    skip("No required keyword argument support before Ruby 2.1") unless RUBY_VERSION >= "2.1"
+    -> {
+      injector.get("HasUnresolvableRequiredKeywordArguments")
+    }.must_raise Ruse::UnknownServiceError
+  end
+
+  class ServiceA; end
+
+  if RUBY_VERSION >= "2.0"
+    class HasOptionalParameters
+      attr_reader :a, :z
+      class_eval <<-EVAL, __FILE__, __LINE__
+    def initialize(service_a = :a, service_z = :z)
+      @a = service_a
+      @z = service_z
+    end
+      EVAL
+    end
+
+    class HasKeywordArguments
+      attr_reader :a, :z
+      class_eval <<-EVAL, __FILE__, __LINE__
+    def initialize(service_a: :a, service_z: :z)
+      @a = service_a
+      @z = service_z
+    end
+      EVAL
+    end
+  end
+  if RUBY_VERSION >= "2.1"
+    class HasRequiredKeywordArguments
+      attr_reader :a
+      class_eval <<-EVAL, __FILE__, __LINE__
+      def initialize(service_a:)
+        @a = service_a
+      end
+      EVAL
+    end
+    class HasUnresolvableRequiredKeywordArguments
+      class_eval <<-EVAL, __FILE__, __LINE__
+      def initialize(service_z:) end
+      EVAL
+    end
+  end
+end

data/specs/injector_spec.rb

@@ -26,6 +26,27 @@ describe Ruse::Injector do
     }.must_raise(Ruse::UnknownServiceError)
   end
 
+  it "raises InvalidServiceName when identifier is nil" do
+    ->{
+      injector.get(nil)
+    }.must_raise(Ruse::InvalidServiceName)
+  end
+
+  it "raises InvalidServiceName when identifier is blank string" do
+    ->{
+      injector.get(" ")
+    }.must_raise(Ruse::InvalidServiceName)
+  end
+
+  it "cannot resolve a nil identifier" do
+    refute injector.can_resolve?(nil)
+  end
+
+  it "cannot resolve a blank string identifier" do
+    refute injector.can_resolve?(" ")
+  end
+
+
   it "populates dependencies for the instance it retrieves" do
     instance = injector.get("ConsumerA")
     instance.must_be_instance_of(ConsumerA)
@@ -70,6 +91,29 @@ describe Ruse::Injector do
     instance.value.must_equal(88)
   end
 
+  it "skips over splats" do
+    injector.get("HasSplatInInitializer").must_be_kind_of HasSplatInInitializer
+    injector.get("Array").must_equal []
+  end
+
+  it "can be reconfigured" do
+    injector.configure(values: { service_a: 'foo' })
+    injector.configure(values: { service_b: 'bar' })
+    object = injector.get(:consumer_a)
+    object.a.must_equal 'foo'
+    object.b.must_equal 'bar'
+  end
+
+  it "duplicates configuration on cloning" do
+    injector.configure(values: { service_a: 'foo', service_b: 'bar' })
+    child_injector = injector.clone
+    child_injector.configure(values: { service_a: 'FOO' })
+    child_object = child_injector.get(:consumer_a)
+    parent_object = injector.get(:consumer_a)
+
+    child_object.a.must_equal 'FOO'
+    parent_object.a.must_equal 'foo'
+  end
 
   class ServiceA; end
   class ServiceB; end
@@ -111,6 +155,10 @@ describe Ruse::Injector do
     end
   end
 
+  class HasSplatInInitializer
+    def initialize(*args)
+    end
+  end
 end
 
 describe "classify" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruse
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Joshua Flanagan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-28 00:00:00.000000000 Z
+date: 2014-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -17,13 +17,13 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.5'
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   type: :development
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -53,8 +54,13 @@ files:
 - lib/ruse.rb
 - lib/ruse/activesupport.rb
 - lib/ruse/injector.rb
+- lib/ruse/object_factory.rb
+- lib/ruse/proc_resolver.rb
+- lib/ruse/type_resolver.rb
+- lib/ruse/value_resolver.rb
 - lib/ruse/version.rb
 - ruse.gemspec
+- specs/injector_keyword_args_spec.rb
 - specs/injector_spec.rb
 - specs/ruse_spec.rb
 homepage: https://github.com/joshuaflanagan/ruse