scorpion-ioc 0.0.1 → 0.1.0

data/lib/scorpion/king.rb

@@ -0,0 +1,150 @@
+require 'scorpion/attribute_set'
+
+module Scorpion
+  # Identifies objects that are served by {Scorpion scorpions} that feed on
+  # {Scorpion#hunt! hunted} prey.
+  module King
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @!attribute
+    # @return [Scorpion] the scorpion used to hunt down prey.
+      attr_reader :scorpion
+
+    # @!attribute
+    # @return [Scorpion::AttributeSet] the set of injected attributes and their
+    #   settings.
+      def injected_attributes
+        self.class.injected_attributes
+      end
+
+    #
+    # @!endgroup Attributes
+
+    # Feeds one of the {#injected_attributes} to the object.
+    # @param [Scorpion::Attribute] attribute to be fed.
+    # @param [Object] food the value of the attribute
+    # @visibility private
+    #
+    # This method is used by the {#scorpion} to feed the king. Do not call it
+    # directly.
+    def feed( attribute, food )
+      send "#{ attribute.name }=", food
+    end
+
+    # Crown the object as a king and prepare it to be fed.
+    def self.crown( base )
+      base.extend Scorpion::King::ClassMethods
+      if base.is_a? Class
+        base.class_exec do
+
+          # Span a new instance of this class with all non-lazy dependencies
+          # satisfied.
+          # @param [Scorpion] scorpion that will hunt for dependencies.
+          def self.spawn( scorpion, *args, &block )
+            new( *args, &block ).tap do |king|
+              king.instance_variable_set :@scorpion, scorpion
+              # Go hunt for dependencies that are not lazy and initialize the
+              # references.
+              scorpion.feed! king
+              king.send :on_fed
+            end
+          end
+        end
+      end
+    end
+
+      def self.included( base )
+        crown( base )
+        super
+      end
+
+      def self.prepended( base )
+        crown( base )
+        super
+      end
+
+
+    private
+
+      # Called after the king has been initialized and feed all its required
+      # dependencies. It should be used in place of #initialize when the
+      # constructor needs access to injected attributes.
+      def on_fed
+      end
+
+      # Convenience method to ask the {#scorpion} to hunt for an object.
+      # @see Scorpion#hunt!
+      def hunt!( contract, *args, &block )
+        scorpion.hunt! contract, *args, &block
+      end
+
+      # Convenience method to ask the {#scorpion} to hunt for an object.
+      # @see Scorpion#hunt_by_traits!
+      def hunt_by_traits!( contract, traits, *args, &block )
+        scorpion.hunt_by_traits! contract, *args, &block
+      end
+
+    module ClassMethods
+
+      # Tells a {Scorpion} what to inject into the class when it is constructed
+      # @return [nil]
+      # @see AttributeSet#define
+      def feed_on( &block )
+        injected_attributes.define &block
+        build_injected_attributes
+      end
+      alias_method :inject, :feed_on
+      alias_method :depend_on, :feed_on
+
+      # @!attribute
+      # @return [Scorpion::AttributeSet] the set of injected attriutes.
+      def injected_attributes
+        @injected_attributes ||= begin
+          attr = AttributeSet.new
+          attr.inherit! superclass.injected_attributes if superclass.respond_to? :injected_attributes
+          attr
+        end
+      end
+
+      private
+
+        def build_injected_attributes
+          injected_attributes.each do |attr|
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{ attr.name }
+                @#{ attr.name } ||= begin
+                  attr = injected_attributes[ :#{ attr.name } ]
+                  scorpion.hunt!( attr.contract, attr.traits )
+                end
+              end
+
+              def #{ attr.name }=( value )
+                @#{ attr.name } = value
+              end
+
+              def #{ attr.name }?
+                !!@#{ attr.name }
+              end
+            RUBY
+
+            unless attr.public?
+              class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                private :#{ attr.name }=
+                private :#{ attr.name }?
+              RUBY
+            end
+
+            if attr.private?
+              class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                private :#{ attr.name }
+              RUBY
+            end
+
+          end
+        end
+    end
+  end
+end

data/lib/scorpion/locale/en.yml

@@ -0,0 +1,5 @@
+en:
+  scorpion:
+    errors:
+      messages:
+        unsuccessful_hunt: "Couldn't find a %{contract} builder with traits '%{traits}'"

data/lib/scorpion/nest.rb

@@ -0,0 +1,37 @@
+module Scorpion
+  # A scorpion factory
+  class Nest
+
+    # ============================================================================
+    # @!group Associations
+    #
+
+    # @!attribute
+    # @return [Scorpion] the mother scorpion that that will {#conceive} new
+    #   scorpions for each request.
+      attr_reader :mother
+
+    #
+    # @!endgroup Associations
+
+    def initialize( mother = nil )
+      @mother = mother || Scorpion::Hunter.new
+    end
+
+    def prepare( &block )
+      mother.prepare &block
+    end
+
+    # @return [Scorpion] a new scorpion used to hunt for dependencies.
+    def conceive
+      mother.replicate
+    end
+
+    # Free up any persistent resources
+    def destroy
+      mother.destroy
+      @mother = nil
+    end
+
+  end
+end

data/lib/scorpion/prey.rb

@@ -0,0 +1,94 @@
+module Scorpion
+  # Prey that can be fed to a {Scorpion::King} by a {Scorpion}.
+  class Prey
+
+    require 'scorpion/prey/captured_prey'
+    require 'scorpion/prey/class_prey'
+    require 'scorpion/prey/module_prey'
+    require 'scorpion/prey/builder_prey'
+    require 'scorpion/prey/hunted_prey'
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @!attribute
+    # @return [Class,Module,Symbol] contract describing the desired behavior of the prey.
+      attr_reader :contract
+
+    # @!attribute
+    # @return [Array<Symbol>] the traits available on the prey.
+      attr_reader :traits
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( contract, traits = nil )
+      @contract = contract
+      @traits   = Set.new( Array( traits ) )
+    end
+
+    # @return [Boolean] if the prey satisfies the required contract and traits.
+    def satisfies?( contract, traits = nil )
+      satisfies_contract?( contract ) && satisfies_traits?( traits )
+    end
+
+    # Fetch an instance of the prey.
+    # @param [Scorpion] scorpion hunting for the prey.
+    # @param [Array<Object>] arguments to the consructor of the prey.
+    # @param [#call] block to pass to constructor.
+    # @return [Object] the hunted prey.
+    def fetch( scorpion, *args, &block )
+      fail "Not Implemented"
+    end
+
+    # Release the prey, freeing up any long held resources.
+    def release
+    end
+
+    # Replicate the Prey.
+    # @return [Prey] a replication of the prey.
+    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
+
+  end
+end

data/lib/scorpion/prey/builder_prey.rb

@@ -0,0 +1,32 @@
+require 'scorpion/prey'
+
+module Scorpion
+  class Prey
+    # {Prey} for an explicit builder block
+    class BuilderPrey < Scorpion::Prey
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [#call(scorpion)] the builder to use to fetch instances of the prey.
+        attr_reader :builder
+
+      #
+      # @!endgroup Attributes
+
+
+      def initialize( contract, traits = nil, &builder )
+        @builder = builder
+        super
+      end
+
+      # @see Scorpion::Prey#fetch
+      def fetch( scorpion, *args, &block )
+        builder.call( scorpion, *args, &block )
+      end
+
+    end
+  end
+end

data/lib/scorpion/prey/captured_prey.rb

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

data/lib/scorpion/prey/class_prey.rb

@@ -0,0 +1,13 @@
+require 'scorpion/prey'
+
+module Scorpion
+  class Prey
+    # {Prey} for a {Class} contract
+    class ClassPrey < Scorpion::Prey
+
+      def fetch( scorpion, *args, &block )
+        scorpion.spawn contract, *args, &block
+      end
+    end
+  end
+end

data/lib/scorpion/prey/hunted_prey.rb

@@ -0,0 +1,14 @@
+require 'scorpion/prey'
+
+module Scorpion
+  class Prey
+    # {Prey} for a contract that implements #hunt
+    class HuntedPrey < Scorpion::Prey
+
+      # @see Scorpion::Prey#fetch
+      def fetch( scorpion, *args, &block )
+        contract.hunt( scorpion, *args, &block )
+      end
+    end
+  end
+end

data/lib/scorpion/prey/module_prey.rb

@@ -0,0 +1,14 @@
+require 'scorpion/prey'
+
+module Scorpion
+  class Prey
+    # {Prey} for a {Module} contract
+    class ModulePrey < Scorpion::Prey
+
+      def fetch( scorpion, *args, &block )
+        contract
+      end
+
+    end
+  end
+end

data/lib/scorpion/rails.rb

@@ -1,5 +1,5 @@
 module Scorpion
   module Rails
-    require 'scorpion/rails/railtie'
+    require 'scorpion/rails/controller'
   end
 end

data/lib/scorpion/rails/controller.rb

@@ -0,0 +1,89 @@
+require 'scorpion/nest'
+require 'active_support/core_ext/class/attribute'
+
+module Scorpion
+  module Rails
+    # Adds a scorpion nest to rails controllers to automatically support
+    # injection into rails controllers.
+    module Controller
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Scorpion] the scorpion used to fetch dependencies.
+        attr_reader :scorpion
+        private :scorpion
+
+      # @!attribute
+      # @return [Scorpion::Nest] the nest used to conceive scorpions.
+        def nest
+          self.class.nest
+        end
+        private :nest
+
+      #
+      # @!endgroup Attributes
+
+
+      def self.included( base )
+        # Setup dependency injection
+        base.send :include, Scorpion::King
+        base.around_action :with_scorpion
+
+        # @!attribute [rw]
+        # @return [Scorpion::Nest] the singleton nest used by controllers.
+        base.class_attribute :nest_instance
+        base.class_exec do
+
+          # @!attribute
+          # @return [Scorpion::Nest] the nest used to conceive scorpions to
+          #   hunt for objects on each request.
+          def self.nest
+            nest_instance
+          end
+          def self.nest=( value )
+            nest_instance.destroy if nest_instance
+            self.nest_instance = value
+          end
+
+          # Prepare the nest for conceiving scorpions.
+          # @see HuntingMap#chart
+          def self.scorpion_nest( &block )
+            nest.prepare &block
+          end
+        end
+        base.nest ||= Scorpion.instance.build_nest
+
+        super
+      end
+
+      private
+
+        # Fetch a scorpion and feed the controller it's dependencies
+        def with_scorpion( &block )
+          @scorpion = nest.conceive
+
+          @scorpion.prepare do |hunter|
+            hunter.hunt_for AbstractController::Base do
+              self
+            end
+            # Allow dependencies to access the current request/response
+            hunter.hunt_for ActionDispatch::Request do |hunter|
+              hunter.hunt!( AbstractController::Base ).request
+            end
+            hunter.hunt_for ActionDispatch::Response do |hunter|
+              hunter.hunt!( AbstractController::Base ).response
+            end
+          end
+
+          @scorpion.feed! self
+
+          yield
+        ensure
+          @scorpion = nil
+        end
+    end
+  end
+end