scorpion-ioc 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ec2ff4bcf7bacc05263624d567a42ffa57d614c
-  data.tar.gz: 1f52f7c0031504a0b0e926ff507d49af659fa717
+  metadata.gz: d9f9e729630d83f9132e46118f0a74a9bcc9946f
+  data.tar.gz: 40a34e024069aaf348ce03b37065d83098920e40
 SHA512:
-  metadata.gz: 6b6e3b77742c496ff2b3ceee4484bcd8e8eb69d63029e1d232453c34775135c1c0088a144df31528724866c2e84209cd17f2bcb3cf47cbf90b2840315aa99c12
-  data.tar.gz: b55c22cd4c397caf6c9ea10bfde2f892dc083f6eae906c54b7b724103f6b88fb627ee2ff8638667df68f538fbb503b4bd7a5a1a5048062c77ebab0e978e7475b
+  metadata.gz: 32a04845861b9ea89cd5dcd19c667a0a339a424513c7b610f9909c3995e37d45707f837f3b10c8ce2d844ef12698268ffaa50c2afde083f54cd3161c4877d792
+  data.tar.gz: 435e3fbc679d5ad65fc7f5d2cce00adb802b5c73b91d1995f15c9012f6b0a8a99cee97c70cf7907b391d71fe831b8f8b38958249ef89ced063a9b0654a5f2f2e

data/.gitignore

@@ -20,4 +20,5 @@ tmp
 *.o
 *.a
 mkmf.log
-.env
+.env
+*.sqlite

data/.rspec

@@ -1,2 +1,3 @@
 --color
---format Fuubar
+--format Fuubar
+

data/README.md

@@ -8,15 +8,13 @@
 
 Add IoC to rails with minimal fuss and ceremony.
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
+<!-- MarkdownTOC depth=4 -->
 
 - [Dependency Injection](#dependency-injection)
   - [Why might you _Want_ a DI FRamework?](#why-might-you-_want_-a-di-framework)
     - [Using a Framework...like Scorpion](#using-a-frameworklike-scorpion)
 - [Using Scorpion](#using-scorpion)
-  - [Kings](#kings)
+  - [Objects](#objects)
   - [Configuration](#configuration)
     - [Classes](#classes)
     - [Modules](#modules)
@@ -26,10 +24,13 @@ Add IoC to rails with minimal fuss and ceremony.
     - [Singletons](#singletons)
   - [Nests](#nests)
   - [Rails](#rails)
+    - [ActionController](#actioncontroller)
+    - [ActiveJob](#activejob)
+    - [ActiveRecord](#activerecord)
 - [Contributing](#contributing)
 - [License](#license)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- /MarkdownTOC -->
 
 ## Dependency Injection
 
@@ -145,7 +146,7 @@ and setting the weapon. When a Hunter is created it's dependencies are also
 created - and any of their dependencies and so on. Usage is equally simple
 
 ```ruby
-hunter = scorpion.hunt Hunter
+hunter = scorpion.fetch Hunter
 hunter.weapon   # => a Weapon
 ```
 
@@ -158,7 +159,7 @@ scorpion.prepare do
   hunt_for Axe
 end
 
-hunter = scorpion.hunt Hunter
+hunter = scorpion.fetch Hunter
 hunter.weapon # => an Axe
 ```
 
@@ -173,7 +174,7 @@ Overriding hunters!
     hunt_for Axe
   end
 
-  hunter = scorpion.hunt Hunter
+  hunter = scorpion.fetch Hunter
   hunter        # => Predator
   hunter.weapon # => an Axe
 ```
@@ -185,49 +186,49 @@ Out of the box Scorpion does not need any configuration and will work
 immediately. You can hunt for any Class even if it hasn't been configured.
 
 ```ruby
-  hash = Scorpion.instance.hunt Hash
+  hash = Scorpion.instance.fetch Hash
   hash # => {}
 ```
 
-### Kings
+### Objects
 
-Scorpions feed their [Scorpion Kings](lib/scorpion/king.rb) - any object that
+Scorpions feed their [Scorpion Objects](lib/scorpion/object.rb) - any object that
 should be fed its dependencies when it is created. Simply include the
-Scorpion::King module into your class to benefit from Scorpion injections.
+Scorpion::Object module into your class to benefit from Scorpion injections.
 
 ```ruby
 class Keeper
-  include Scorpion::King
+  include Scorpion::Object
 
-  feed_on do
+  depend_on do
     lunch FastFood
   end
 end
 
 class Zoo
-  include Scorpion::King
+  include Scorpion::Object
 
-  feed_on do # or #depend_on if you like
+  depend_on do # or #depend_on if you like
     keeper Zoo::Keeper
     vet Zoo::Vet, lazy: true
   end
 end
 
-zoo = scorpion.hunt Zoo
+zoo = scorpion.fetch Zoo
 zoo.keeper       # => an instance of a Zoo::Keeper
 zoo.vet?         # => false it hasn't been hunted down yet
 zoo.vet          # => an instnace of a Zoo::Vet
 zoo.keeper.lunch # => an instance of FastFood
 ```
 
-All of your classes should be kings! And any dependency that is also a King will
+All of your classes should be objects! And any dependency that is also a Object will
 be fed.
 
 ### Configuration
 
 A good scorpion should be prepared to hunt. An effort that describes what the
 scorpion hunts for and how it should be found. Scorpion uses Classes and Modules
-as the primary means of identifying prey in favor of opaque labels or strings.
+as the primary means of identifying dependency in favor of opaque labels or strings.
 This serves two benefits:
 
 1. The type of object expected by the dependency is clearly identified making it
@@ -242,13 +243,13 @@ derived class). In the absence of any configuration, Scorpion will simply create
 an instance of the specific class requested.
 
 ```ruby
-scorpion.hunt Hash   # => Hash.new
+scorpion.fetch Hash   # => Hash.new
 
 scorpion.prepare do
   hunt_for Object::HashWithIndifferentAccess
 end
 
-scorpion.hunt Hash   # => Object::HashWithIndifferentAccess.new
+scorpion.fetch Hash   # => Object::HashWithIndifferentAccess.new
 ```
 
 #### Modules
@@ -269,21 +270,21 @@ class Sword
   include Sharp
 end
 
-poker = scorpion.hunt Sharp
+poker = scorpion.fetch Sharp
 poker.poke     # => "Module"
 
 scorpion.prepare do
   hunt_for Sword
 end
 
-poker = scorpion.hunt Sharp
+poker = scorpion.fetch Sharp
 poker.poke     # => "Sword"
 ```
 
 #### Traits
 
-Traits can be used to distinguish between prey of the same type. For example
-a scorpion may be prepare to hunt for several weapons and the king needs a
+Traits can be used to distinguish between dependency of the same type. For example
+a scorpion may be prepare to hunt for several weapons and the object needs a
 blunt weapon.
 
 ```ruby
@@ -298,13 +299,13 @@ scorpion.prepare do
   hunt_for Mace, :blunt, :sharp
 end
 
-scorpion.hunt Weapon, :blunt # => Hammer.new
-scorpion.hunt Weapon, :sharp # => Sword.new
-scorpion.hunt Weapon, :sharp, :blunt # => Mace.new
+scorpion.fetch Weapon, :blunt # => Hammer.new
+scorpion.fetch Weapon, :sharp # => Sword.new
+scorpion.fetch Weapon, :sharp, :blunt # => Mace.new
 ```
 
 Modules can also be used to identify specific traits desired from the hunted
-prey.
+dependency.
 
 ```ruby
 module Color; end
@@ -322,14 +323,14 @@ scorpion.prepare do
   hunt_for SysLog
 end
 
-scorpion.hunt Logger, Color      # => Console.new
-scorpion.hunt Logger, Streaming  # => SysLog.new
+scorpion.fetch Logger, Color      # => Console.new
+scorpion.fetch Logger, Streaming  # => SysLog.new
 ```
 
 #### Builders
 
 Sometimes resolving the correct dependencies is a bit more dynamic. In those
-cases you can use a builder block to hunt for prey.
+cases you can use a builder block to hunt for dependency.
 
 ```ruby
 class Samurai < Sword; end
@@ -342,11 +343,36 @@ scorpion.prepare do
 end
 ```
 
+Objects may also define their own .create methods that receive a scorpion and
+arguments.
+
+```ruby
+class City
+  def self.create( scorpion, name )
+    klass = if name == "New York"
+      BigCity
+    else
+      SmallCity
+    end
+
+    klass.new name
+  end
+
+  def initialize( name )
+    @name = name
+  end
+end
+
+class BigCity < City; end
+class SmallCity < City; end
+
+```
+
 #### Hunting Delegates
 
 For really complex dependencies you may want to delegate the effort to retrieve
 the dependencies to another type - a factory module for example. Scorpion
-allows you to delegate hunting prey using the `:with` option.
+allows you to delegate hunting dependency using the `:with` option.
 
 ```ruby
 module ChocolateFactory
@@ -365,7 +391,7 @@ scorpion.prepare do
   hunt_for Candy, with: ChocolateFactory
 end
 
-scorpion.hunt Candy, Nuget.new  #=> Snickers.new Nugget.new
+scorpion.fetch Candy, Nuget.new  #=> Snickers.new Nugget.new
 ```
 
 Any object that responds to `#call( scorpion, *args, &block )` can be used as
@@ -373,11 +399,11 @@ a hunting delegate.
 
 #### Singletons
 
-Scorpion allows you to capture prey and feed the same instance to everyone that
+Scorpion allows you to capture dependency and feed the same instance to everyone that
 asks for a matching dependency.
 
 DI singletons are different then global singletons in that each scorpion can
-have a unique instance of the class that it shares with all of it's kings. This
+have a unique instance of the class that it shares with all of it's objects. This
 allows, for example, global variable like support per-request without polluting
 the global namespace or dealing with thread concurrency issues.
 
@@ -389,12 +415,12 @@ scorpion.prepare do
   capture Logger
 end
 
-scorpion.hunt Logger  # => Logger.new
-scorpion.hunt Logger  # => Previously captured logger
+scorpion.fetch Logger  # => Logger.new
+scorpion.fetch Logger  # => Previously captured logger
 ```
 
 Captured dependencies are not shared with child scorpions (for example when
-conceiving scorpions from a [Nest](Nests)). To share captured prey with children
+conceiving scorpions from a [Nest](Nests)). To share captured dependency with children
 use `share`.
 
 ### Nests
@@ -412,11 +438,13 @@ nest.prepare do
 end
 
 scorpion = nest.conceive
-scorpion.hunt Logger  # => Logger.new
+scorpion.fetch Logger  # => Logger.new
 ```
 
 ### Rails
 
+#### ActionController
+
 Scorpion provides simple integration into for rails controllers to establish
 a scorpion for each request.
 
@@ -441,12 +469,9 @@ end
 require 'scorpion'
 
 class ApplicationController < ActionController::Base
-  include Scorpion::Rails::Controller
-
-  feed_on do
+  depend_on do
     users UserService, lazy: true
   end
-
 end
 
 # users_controller.rb
@@ -458,6 +483,48 @@ class UsersController < ApplicationController
 end
 ```
 
+#### ActiveJob
+
+Simliar to support for controllers, Scorpion provides support for dependency
+injection into ActiveJob objects.
+
+```ruby
+
+# avatar_job.rb
+class AvatarJob < ActiveJob::Base
+  def perform( id )
+    user = users.find( id )
+    logger.write "Found a user: #{ user }"
+  end
+end
+```
+
+#### ActiveRecord
+
+Scorpion enhances ActiveRecord models to support resolving dependencies from
+a scorpion and sharing that scorpion with all associations.
+
+```ruby
+class User < ActiveRecord::Base
+  depend_on do
+    credentials Service::Auth::Credentials
+  end
+
+  def check_password( password )
+    credentials.check encoded_password, password
+  end
+end
+
+class SessionsController < ActionController::Base
+
+  def create
+    user = User.with_scorpion( scorpion ).find params[:id]
+    sign_in if user.check_password( params[:password] )
+  end
+end
+```
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/phallguy/scorpion/fork )

data/lib/scorpion/attribute.rb

@@ -32,7 +32,6 @@ module Scorpion
     # @return [Boolean] true if the attribute should have a public writer.
       def private?; @private end
 
-
     #
     # @!endgroup Attributes
 

data/lib/scorpion/attribute_set.rb

@@ -35,7 +35,7 @@ module Scorpion
       attributes.key? name
     end
 
-    # Defines the food that {Scorpion::King} will feed on. A food is defined by
+    # Defines the food that {Scorpion::Object} will feed on. A food is defined by
     # invoking a method with the desired name passing the contract and traits
     # desired. AttributeSet uses method_missing to dynamically define
     # attributes.
@@ -70,18 +70,26 @@ module Scorpion
       @defining_attributes = false
     end
 
+    # Define a single attribute with the given name that expects food that will
+    # satisfy the contract and traits.
+    # @param [String] name of the attribute.
+    # @param [Class,Module,Symbol] contract that describes the desired behavior
+    #   of the injected object.
+    # @param [Array<Symbol>] traits that must match on instances of the {#contract}
+    # @return [Attribute] the attribute that was created.
+    def define_attribute( name, contract, *traits )
+      options = traits.pop if traits.last.is_a? Hash
+      options ||= {}
+      attributes[name.to_sym] = Attribute.new name, contract, traits, options
+    end
+
+
     protected
 
       attr_reader :attributes
 
     private
 
-      def define_attribute( name, contract, *traits )
-        options = traits.pop if traits.last.is_a? Hash
-        options ||= {}
-        attributes[name.to_sym] = Attribute.new name, contract, traits, options
-      end
-
       def method_missing( name, *args )
         return super unless @defining_attributes
 

data/lib/scorpion/dependency/argument_dependency.rb

@@ -0,0 +1,25 @@
+require 'scorpion/dependency'
+
+module Scorpion
+  class Dependency
+    # {Dependency} for an captured argument.
+    # @see {Scorpion#argument}.
+    class ArgumentDependency < Scorpion::Dependency
+
+      attr_reader :argument
+
+      def initialize( argument )
+        @argument = argument
+      end
+
+      def fetch( *args )
+        argument
+      end
+
+      def satisfies?( contract, traits = nil )
+        contract === argument && traits.blank?
+      end
+
+    end
+  end
+end

data/lib/scorpion/{prey/builder_prey.rb → dependency/builder_dependency.rb}

@@ -1,17 +1,17 @@
-require 'scorpion/prey'
+require 'scorpion/dependency'
 
 module Scorpion
-  class Prey
-    # {Prey} that delegates to another object that implements
+  class Dependency
+    # {Dependency} that delegates to another object that implements
     # #call( scorpion, *args, &block ).
-    class BuilderPrey < Scorpion::Prey
+    class BuilderDependency < Scorpion::Dependency
 
       # ============================================================================
       # @!group Attributes
       #
 
       # @!attribute
-      # @return [#call(scorpion,*args,&block)] the builder to use to fetch instances of the prey.
+      # @return [#call(scorpion,*args,&block)] the builder to use to fetch instances of the dependency.
         attr_reader :builder
 
       #
@@ -22,9 +22,9 @@ module Scorpion
         super contract, traits
       end
 
-      # @see Scorpion::Prey#fetch
-      def fetch( scorpion, *args, &block )
-        builder.call( scorpion, *args, &block )
+      # @see Scorpion::Dependency#fetch
+      def fetch( hunt )
+        builder.call( hunt, *hunt.arguments, &hunt.block )
       end
 
     end

data/lib/scorpion/dependency/captured_dependency.rb

@@ -0,0 +1,44 @@
+require 'scorpion/dependency'
+
+module Scorpion
+  class Dependency
+    class CapturedDependency < Scorpion::Dependency
+      extend Forwardable
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Object] the instance that was captured.
+        attr_reader :instance
+
+      # @!attribute
+      # @return [Scorpion::Dependency] the actual dependency to hunt. Used to fetch the
+      #   single {#instance}.
+        attr_reader :specific_dependency
+        private :specific_dependency
+
+
+      delegate [:contract,:traits,:satisfies?] => :specific_dependency
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( specific_dependency )
+        @specific_dependency = specific_dependency
+      end
+
+      # @see Dependency#fetch
+      def fetch( hunt )
+        @instance ||= specific_dependency.fetch( hunt )
+      end
+
+      # @see Dependency#release
+      def release
+        @instance = nil
+      end
+
+    end
+  end
+end

data/lib/scorpion/dependency/class_dependency.rb

@@ -0,0 +1,25 @@
+require 'scorpion/dependency'
+
+module Scorpion
+  class Dependency
+    # {Dependency} for a {Class} contract
+    class ClassDependency < Scorpion::Dependency
+
+      def fetch( hunt )
+        hunt.scorpion.spawn hunt, hunt.contract, *resolve_arguments( hunt ), &hunt.block
+      end
+
+      private
+
+        def resolve_arguments( hunt )
+          arguments = hunt.arguments
+          return arguments unless arguments.blank? && hunt.contract < Scorpion::Object
+
+          hunt.contract.initializer_injections.each_with_object([]) do |attr,args|
+            args << hunt.fetch_by_traits( attr.contract, attr.traits )
+          end
+
+        end
+    end
+  end
+end

data/lib/scorpion/dependency/module_dependency.rb

@@ -0,0 +1,14 @@
+require 'scorpion/dependency'
+
+module Scorpion
+  class Dependency
+    # {Dependency} for a {Module} contract
+    class ModuleDependency < Scorpion::Dependency
+
+      def fetch( *args )
+        contract
+      end
+
+    end
+  end
+end