scorpion-ioc 0.3.1 → 0.4.0

data/lib/scorpion/dependency.rb

@@ -0,0 +1,137 @@
+module Scorpion
+  # Dependency that can be injected into a {Scorpion::Object} by a {Scorpion}.
+  class Dependency
+
+    require 'scorpion/dependency/captured_dependency'
+    require 'scorpion/dependency/class_dependency'
+    require 'scorpion/dependency/module_dependency'
+    require 'scorpion/dependency/builder_dependency'
+    require 'scorpion/dependency/argument_dependency'
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @!attribute
+    # @return [Class,Module,Symbol] contract describing the desired behavior of the dependency.
+      attr_reader :contract
+
+    # @!attribute
+    # @return [Array<Symbol>] the traits available on the dependency.
+      attr_reader :traits
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( contract, traits = nil )
+      @contract = contract
+      @traits   = Set.new( Array( traits ) )
+    end
+
+    # @return [Boolean] if the dependency satisfies the required contract and traits.
+    def satisfies?( contract, traits = nil )
+      satisfies_contract?( contract ) && satisfies_traits?( traits )
+    end
+
+    # Fetch an instance of the dependency.
+    # @param [Hunt] the hunting context.
+    # @return [Object] the hunted dependency.
+    def fetch( hunt )
+      fail "Not Implemented"
+    end
+
+    # Release the dependency, freeing up any long held resources.
+    def release
+    end
+
+    # Replicate the Dependency.
+    # @return [Dependency] a replication of the dependency.
+    def replicate
+      dup
+    end
+
+    def ==( other )
+      return unless other
+      self.class == other.class &&
+      contract   == other.contract &&
+      traits     == other.traits
+    end
+    alias_method :eql?, :==
+
+    def hash
+      self.class.hash ^
+      contract.hash ^
+      traits.hash
+    end
+
+    private
+
+      # @return [Boolean] true if the pray satisfies the given contract.
+      def satisfies_contract?( contract )
+        if self.contract.is_a? Symbol
+          self.contract == contract
+        else
+          self.contract <= contract
+        end
+      end
+
+      # @return [Boolean] true if the pray satisfies the given contract.
+      def satisfies_traits?( traits )
+        return true if traits.blank?
+
+        Array( traits ).all? do |trait|
+          case trait
+          when Symbol then self.traits.include? trait
+          when Module then self.contract <= trait
+          else fail ArgumentError, "Unsupported trait"
+          end
+        end
+      end
+
+    class << self
+
+      # Define dependency based on the desired contract and traits.
+      # @return [Dependency] the defined dependency.
+      def define( contract, traits = nil , &builder )
+        options, traits = extract_options!( traits )
+
+        if options.key?( :return )
+          Scorpion::Dependency::BuilderDependency.new( contract, traits ) do
+            options[:return]
+          end
+        elsif with = options[:with]
+          Scorpion::Dependency::BuilderDependency.new( contract, traits, with )
+        elsif block_given?
+          Scorpion::Dependency::BuilderDependency.new( contract, traits, builder )
+        elsif contract.respond_to?( :create )
+          Scorpion::Dependency::BuilderDependency.new( contract, traits ) do |scorpion,*args,&block|
+            contract.create scorpion, *args, &block
+          end
+        else
+          dependency_class( contract ).new( contract, traits, &builder )
+        end
+      end
+
+      private
+        def extract_options!( traits )
+          case traits
+          when Hash then return [ traits, nil ]
+          when Array then
+            if traits.last.is_a? Hash
+              return [ traits.pop, traits ]
+            end
+          end
+
+          [ {}, traits]
+        end
+
+        def dependency_class( contract, &builder )
+          return Scorpion::Dependency::ClassDependency   if contract.is_a? Class
+          return Scorpion::Dependency::ModuleDependency  if contract.is_a? Module
+
+          raise Scorpion::BuilderRequiredError
+        end
+    end
+
+  end
+end

data/lib/scorpion/dependency_map.rb

@@ -0,0 +1,135 @@
+module Scorpion
+  # {#chart} available {Dependency} and {#find} them based on desired
+  # {Scorpion::Attribute attributes}.
+  class DependencyMap
+    include Enumerable
+    extend Forwardable
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @return [Scorpion] the scorpion that created the map.
+      attr_reader :scorpion
+
+    # @return [Set] the set of dependency charted on this map.
+      attr_reader :dependency_set
+      private :dependency_set
+
+    # @return [Set] the set of dependencies charted on this map that is shared
+    #   with all child dependencies.
+      attr_reader :shared_dependency_set
+      private :shared_dependency_set
+
+    # @return [Set] the active dependency set either {#dependency_set} or {#shared_dependency_set}
+      attr_reader :active_dependency_set
+      private :active_dependency_set
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( scorpion )
+      @scorpion              = scorpion
+      @dependency_set        = @active_dependency_set = []
+      @shared_dependency_set = []
+    end
+
+    # Find {Dependency} that matches the requested `contract` and `traits`.
+    # @param [Class,Module,Symbol] contract describing the desired behavior of the dependency.
+    # @param [Array<Symbol>] traits found on the {Dependency}.
+    # @return [Dependency] the dependency matching the attribute.
+    def find( contract, traits = nil )
+      dependency_set.find{ |p| p.satisfies?( contract, traits ) } ||
+      shared_dependency_set.find{ |p| p.satisfies?( contract, traits ) }
+    end
+
+    # Chart the {Dependency} that this hunting map can {#find}.
+    #
+    # The block is executed in the context of DependencyMap if the block does not
+    # accept any arguments so that {#hunt_for}, {#capture} and {#share} can be
+    # called as methods.
+    #
+    # @example
+    #
+    #   cache = {}
+    #   chart do
+    #     self #=> DependencyMap
+    #     hunt_for Repository
+    #     capture  Cache, return: cache # => NoMethodError
+    #   end
+    #
+    #   chart do |map|
+    #     map.hunt_for Repository
+    #     map.capture  Cache, return: cache # => No problem
+    #   end
+    #
+    # @return [self]
+    def chart( &block )
+      return unless block_given?
+
+      if block.arity == 1
+        yield self
+      else
+        instance_eval &block
+      end
+
+      self
+    end
+
+    # Define {Dependency} that can be found on this map by `contract` and `traits`.
+    #
+    # If a block is given, it will be used build the actual instances of the
+    # dependency for the {Scorpion}.
+    #
+    # @param [Class,Module,Symbol] contract describing the desired behavior of the dependency.
+    # @param [Array<Symbol>] traits found on the {Dependency}.
+    # @return [Dependency] the dependency to be hunted for.
+    def hunt_for( contract, traits = nil, &builder )
+      active_dependency_set.unshift define_dependency( contract, traits, &builder )
+    end
+
+    # Captures a single dependency and returns the same instance fore each request
+    # for the resource.
+    # @see #hunt_for
+    # @return [Dependency] the dependency to be hunted for.
+    def capture( contract, traits = nil, &builder )
+      active_dependency_set.unshift Dependency::CapturedDependency.new( define_dependency( contract, traits, &builder ) )
+    end
+    alias_method :singleton, :capture
+
+    # Share dependencies defined within the block with all child scorpions.
+    # @return [Dependency] the dependency to be hunted for.
+    def share( &block )
+      old_set = active_dependency_set
+      @active_dependency_set = shared_dependency_set
+      yield
+    ensure
+      @active_dependency_set = old_set
+    end
+
+    # @visibility private
+    def each( &block )
+      dependency_set.each &block
+    end
+    delegate [ :empty?, :blank?, :present? ] => :dependency_set
+
+    # Replicates the dependency in `other_map` into this map.
+    # @param [Scorpion::DependencyMap] other_map to replicate from.
+    # @return [self]
+    def replicate_from( other_map )
+      other_map.each do |dependency|
+        if replica = dependency.replicate
+          dependency_set << replica
+        end
+      end
+
+      self
+    end
+
+    private
+
+      def define_dependency( contract, traits, &builder )
+        Dependency.define contract, traits, &builder
+      end
+  end
+end

data/lib/scorpion/hunt.rb

@@ -0,0 +1,158 @@
+module Scorpion
+  # Captures state for a specific hunt so that constructor arguments can be
+  # shared with child dependencies.
+  #
+  # @example
+  #
+  #   class Service
+  #     depend_on do
+  #       options UserOptions
+  #     end
+  #
+  #     def initialize( user )
+  #     end
+  #   end
+  #
+  #   class UserOptions
+  #
+  #     depend_on do
+  #       user User
+  #     end
+  #   end
+  #
+  #   user    = User.find 123
+  #   service = scorpion.fetch Service, user
+  #   service.options.user # => user
+  class Hunt
+    extend Forwardable
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @!attribute
+    # @return [Scorpion] scorpion used to fetch uncaptured dependency.
+      attr_reader :scorpion
+
+    # @!attribute
+    # @return [Array<Array>] the stack of trips conducted by the hunt to help
+    #   resolve child dependencies.
+      attr_reader :trips
+      private :trips
+
+    # @!attribute
+    # @return [Trip] the current hunting trip.
+      attr_reader :trip
+      private :trip
+
+      delegate [:contract, :traits, :arguments, :block] => :trip
+
+    # @!attribute contract
+    # @return [Class,Module,Symbol] contract being hunted for.
+
+    # @!attribute traits
+    # @return [Array<Symbol>] traits being hunted for.
+
+    # @!attribute [r] arguments
+    # @return [Array<Dependency>] dependency to pass to initializer of contract when found.
+
+    # @!attribute block
+    # @return [#call] block to pass to constructor of contract when found.
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( scorpion, contract, traits, *arguments, &block )
+      @scorpion  = scorpion
+      @trips     = []
+      @trip      = Trip.new contract, traits, arguments, block
+    end
+
+    # Hunt for additional dependency to satisfy the main hunt's contract and traits.
+    # @see Scorpion#hunt
+    def fetch( contract, *arguments, &block )
+      fetch_by_traits( contract, nil, *arguments, &block )
+    end
+
+    # Hunt for additional dependency to satisfy the main hunt's contract and traits.
+    # @see Scorpion#hunt
+    def fetch_by_traits( contract, traits, *arguments, &block )
+      push contract, traits, arguments, block
+      execute
+    ensure
+      pop
+    end
+
+    # Inject given `object` with its expected dependencies.
+    # @param [Scorpion::Object] object to be injected.
+    # @return [Scorpion::Object] the injected object.
+    def inject( object )
+      trip.object = object
+      object.injected_attributes.each do |attr|
+        next if object.send "#{ attr.name }?"
+        next if attr.lazy?
+
+        object.send :inject, attr, fetch_by_traits( attr.contract, attr.traits )
+      end
+
+      object
+    end
+
+    # Allow the hunt to spawn objects.
+    # @see Scorpion#spawn
+    def spawn( klass, *arguments, &block )
+      scorpion.spawn( self, klass, *arguments, &block )
+    end
+
+    private
+
+      def execute
+        execute_from_trips || execute_from_scorpion
+      end
+
+      def execute_from_trips
+        return if arguments.any?
+
+        trips.each do |trip|
+          return trip.object if contract === trip.object
+          trip.arguments.each do |arg|
+            return arg if contract === arg
+          end
+        end
+
+        nil
+      end
+
+      def execute_from_scorpion
+        scorpion.execute self
+      end
+
+      def push( contract, traits, arguments, block )
+        trips.push trip
+
+        @trip = Trip.new contract, traits, arguments, block
+      end
+
+      def pop
+        @trip = trips.pop
+      end
+
+      class Trip
+        attr_reader :contract
+        attr_reader :traits
+        attr_reader :arguments
+        attr_reader :block
+
+        attr_accessor :object
+
+        def initialize( contract, traits, arguments, block )
+          @contract  = contract
+          @traits    = traits
+          @arguments = arguments
+          @block     = block
+        end
+      end
+
+      class InitializerTrip < Trip; end
+  end
+end

data/lib/scorpion/hunter.rb

@@ -1,5 +1,5 @@
 module Scorpion
-  # A concrete implementation of a Scorpion used to hunt down food for a {Scorpion::King}.
+  # A concrete implementation of a Scorpion used to hunt down food for a {Scorpion::Object}.
   # @see Scorpion
   class Hunter
     include Scorpion
@@ -8,11 +8,11 @@ module Scorpion
     # @!group Attributes
     #
 
-    # @return [Scorpion::HuntingMap] map of {Prey} and how to create instances.
-      attr_reader :hunting_map
-      protected :hunting_map
+    # @return [Scorpion::DependencyMap] map of {Dependency} and how to create instances.
+      attr_reader :dependency_map
+      protected :dependency_map
 
-    # @return [Scorpion] parent scorpion to deferr hunting to on missing prey.
+    # @return [Scorpion] parent scorpion to deferr hunting to on missing dependency.
       attr_reader :parent
       private :parent
 
@@ -21,34 +21,35 @@ module Scorpion
 
     def initialize( parent = nil, &block )
       @parent      = parent
-      @hunting_map = Scorpion::HuntingMap.new( self )
+      @dependency_map = Scorpion::DependencyMap.new( self )
 
       prepare &block if block_given?
     end
 
     # Prepare the scorpion for hunting.
-    # @see HuntingMap#chart
+    # @see DependencyMap#chart
     def prepare( &block )
-      hunting_map.chart &block
-    end
-
-    # @see Scorpion#hunt
-    def hunt_by_traits( contract, traits = nil, *args, &block  )
-      unless prey = hunting_map.find( contract, traits )
-        return parent.hunt_by_traits contract, traits if parent
-
-        prey = Scorpion::Prey::ClassPrey.new( contract, nil ) if contract.is_a?( Class ) && traits.blank?
-        unsuccessful_hunt( contract, traits ) unless prey
-      end
-      prey.fetch self, *args, &block
+      dependency_map.chart &block
     end
 
     # @see Scorpion#replicate
     def replicate
       replica = self.class.new self
-      replica.hunting_map.replicate_from( hunting_map )
+      replica.dependency_map.replicate_from( dependency_map )
       replica
     end
 
+    # @see Scorpion#hunt
+    def execute( hunt )
+      dependency   = dependency_map.find( hunt.contract, hunt.traits )
+      dependency ||= parent.dependency_map.find( hunt.contract, hunt.traits ) if parent
+      dependency ||= Dependency.define( hunt.contract ) if hunt.traits.blank?
+
+      unsuccessful_hunt( hunt.contract, hunt.traits ) unless dependency
+
+      dependency.fetch hunt
+    end
+
+
   end
 end

data/lib/scorpion/locale/en.yml

@@ -2,4 +2,8 @@ en:
   scorpion:
     errors:
       messages:
-        unsuccessful_hunt: "Couldn't find a %{contract} builder with traits '%{traits}'"
+        unsuccessful_hunt: "Couldn't find a %{contract} builder with traits '%{traits}'"
+        builder_required: A custom builder must be provided to resolve this dependency
+    warnings:
+      messages:
+        mixed_scorpions: A scorpion has already been assigned. Mixing scorpions can result in unexpected results.