scorpion-ioc 0.3.1 → 0.4.0

data/lib/scorpion/{king.rb → object.rb}

@@ -1,17 +1,18 @@
 require 'scorpion/attribute_set'
 
 module Scorpion
-  # Identifies objects that are served by {Scorpion scorpions} that feed on
-  # {Scorpion#hunt hunted} prey.
-  module King
+  # Identifies objects that are injected by {Scorpion scorpions} that inject
+  # {Scorpion#hunt hunted} dependencies.
+  module Object
 
     # ============================================================================
     # @!group Attributes
     #
 
     # @!attribute
-    # @return [Scorpion] the scorpion used to hunt down prey.
-      attr_reader :scorpion
+    # @return [Scorpion] the scorpion used to hunt down dependencies.
+      attr_accessor :scorpion
+      private :scorpion=
 
     # @!attribute
     # @return [Scorpion::AttributeSet] the set of injected attributes and their
@@ -23,74 +24,68 @@ module Scorpion
     #
     # @!endgroup Attributes
 
-    # Feeds one of the {#injected_attributes} to the object.
+    # Injects one of the {#injected_attributes} into the object.
     # @param [Scorpion::Attribute] attribute to be fed.
-    # @param [Object] food the value of the attribute
+    # @param [Object] dependency the value of the attribute
     # @visibility private
     #
-    # This method is used by the {#scorpion} to feed the king. Do not call it
+    # This method is used by the {#scorpion} to feed the object. Do not call it
     # directly.
-    def feed( attribute, food )
-      send "#{ attribute.name }=", food
+    def inject( attribute, dependency )
+      send "#{ attribute.name }=", dependency
     end
 
-    # Crown the object as a king and prepare it to be fed.
+    # Crown the object as a object and prepare it to be fed.
     def self.crown( base )
-      base.extend Scorpion::King::ClassMethods
+      base.extend Scorpion::Object::ClassMethods
       if base.is_a? Class
         base.class_exec do
 
-          # Span a new instance of this class with all non-lazy dependencies
+          # Create 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
+          # @param [Hunt] hunt that this instance will be used to satisfy.
+          def self.spawn( hunt, *args, &block )
+            new( *args, &block ).tap do |object|
+              object.send :scorpion=, hunt.scorpion
+
               # Go hunt for dependencies that are not lazy and initialize the
               # references.
-              scorpion.feed king
-              king.send :on_fed
+              hunt.inject object
+              object.send :on_injected
             end
           end
+
+        end
+
+        base.subclasses.each do |sub|
+          crown( sub ) unless sub < Scorpion::Object
         end
       end
     end
 
-      def self.included( base )
-        crown( base )
-        super
-      end
+    def self.included( base )
+      crown( base )
+      super
+    end
 
-      def self.prepended( 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
+      # Called after the object 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
+      def on_injected
       end
 
       # Feed dependencies from a hash into their associated attributes.
       # @param [Hash] dependencies hash describing attributes to inject.
       # @param [Boolean] overwrite existing attributes with values in in the hash.
-      def feast_on( dependencies, overwrite = false )
+      def inject_from( dependencies, overwrite = false )
         injected_attributes.each do |attr|
           next unless dependencies.key? attr.name
 
@@ -101,11 +96,10 @@ module Scorpion
 
         dependencies
       end
-      alias_method :inject_from, :feast_on
 
       # Injects dependenices from the hash and removes them from the hash.
-      # @see #feast_on
-      def feast_on!( dependencies, overwrite = false )
+      # @see #inject_from
+      def inject_from!( dependencies, overwrite = false )
         injected_attributes.each do |attr|
           next unless dependencies.key? attr.name
           val = dependencies.delete( attr.name )
@@ -117,27 +111,52 @@ module Scorpion
 
         dependencies
       end
-      alias_method :inject_from!, :feast_on!
 
     module ClassMethods
 
+      # Define an initializer that accepts injections.
+      # @param [Hash] arguments to accept in the initializer.
+      # @yield to initialize itself.
+      def initialize( arguments, &block )
+        Scorpion::ObjectConstructor.new( self, arguments, &block ).define
+      end
+
       # Tells a {Scorpion} what to inject into the class when it is constructed
       # @return [nil]
       # @see AttributeSet#define
-      def feed_on( &block )
+      def depend_on( &block )
         injected_attributes.define &block
         build_injected_attributes
       end
-      alias_method :inject, :feed_on
-      alias_method :depend_on, :feed_on
+      alias_method :inject, :depend_on
+      alias_method :depend_on, :depend_on
+
+      # Define a single dependency and accessor.
+      # @param [Symbol] name of the dependency.
+      # @param [Class,Module,Symbol] contract describing the desired behavior of the dependency.
+      # @param [Array<Symbol>] traits found on the {Dependency}.
+      def attr_dependency( name, contract, *traits, &block )
+        attr = injected_attributes.define_attribute name, contract, *traits, &block
+        build_injected_attribute attr
+        set_injected_attribute_visibility attr
+      end
 
       # @!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
+          attrs = AttributeSet.new
+          attrs.inherit! superclass.injected_attributes if superclass.respond_to? :injected_attributes
+          attrs
+        end
+      end
+
+      # @!attribute
+      # @return [Scorpion::AttributeSet] the set of injected attriutes.
+      def initializer_injections
+        @initializer_injections ||= begin
+          attrs = AttributeSet.new
+          attrs
         end
       end
 
@@ -155,7 +174,7 @@ module Scorpion
             def #{ attr.name }
               @#{ attr.name } ||= begin
                 attr = injected_attributes[ :#{ attr.name } ]
-                scorpion.hunt( attr.contract, attr.traits )
+                scorpion.fetch( attr.contract, attr.traits )
               end
             end
 

data/lib/scorpion/object_constructor.rb

@@ -0,0 +1,55 @@
+module Scorpion
+  # Builds an injectable constructor for a Scorpion::Object.
+  class ObjectConstructor
+
+    def initialize( base, arguments, &block )
+      @base      = base
+      @arguments = arguments
+      @block     = block
+    end
+
+    def define
+      @signature = []
+      @body      = ""
+
+      build_signature
+      build_body
+
+      add_initialize_block
+      assemble
+    end
+
+    private
+      attr_reader :base, :arguments, :block, :body, :signature
+
+      def build_signature
+        arguments.each do |key,expectation|
+          signature << key
+
+          base.initializer_injections.define_attribute key, *Array( expectation )
+          base.attr_dependency key, *Array( expectation )
+        end
+      end
+
+      def build_body
+        arguments.each do |key,expectation|
+          body << "@#{ key } = #{ key };"
+        end
+      end
+
+      def add_initialize_block
+        if block
+          body << "__initialize_with_block( &block )"
+          base.send :define_method, :__initialize_with_block, &block
+        end
+      end
+
+      def assemble
+        base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def initialize( #{ signature.join( ', ' ) }, &block )
+            #{ body }
+          end
+        RUBY
+      end
+  end
+end

data/lib/scorpion/rails/active_record/association.rb

@@ -0,0 +1,65 @@
+module Scorpion
+  module Rails
+    module ActiveRecord
+
+      # Adds dependency injection to ActiveRecord::Base model associations.
+      module Association
+        include Scorpion::Stinger
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute
+        # @return [Scorpion] the scorpion serving the association.
+          attr_accessor :scorpion
+          def scorpion
+            @scorpion || owner.scorpion
+          end
+
+        #
+        # @!endgroup Attributes
+
+
+        # Make sure we override the methods of child classes as well.
+        def self.prepended( base )
+          infect base
+          super
+        end
+
+        # Propagate the module inheritance to all derived classes so that we can
+        # always overlay our interception methods on the top-most overriden
+        # method.
+        def self.infect( klass )
+          klass.class_exec do
+            def self.inherited( from )
+              Scorpion::Rails::ActiveRecord::Association.infect( from )
+
+              super
+            end
+          end
+          overlay( klass )
+        end
+
+        # Overlay interception methods on the klass.
+        def self.overlay( klass )
+          [ :load_target, :target, :reader, :writer, :scope ].each do |method|
+            next unless klass.instance_methods.include? method
+
+            mod = Module.new do
+              module_eval <<-EOS, __FILE__, __LINE__ + 1
+                def #{ method }( *args, &block )
+                  sting! super
+                end
+              EOS
+            end
+
+            klass.prepend mod
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/scorpion/rails/active_record/model.rb

@@ -0,0 +1,28 @@
+module Scorpion
+  module Rails
+    module ActiveRecord
+
+      # Adds dependency injection to ActiveRecord::Base models.
+      module Model
+        include Scorpion::Stinger
+
+        def self.prepended( base )
+          # Setup dependency injection
+          base.send :include, Scorpion::Object
+          base.send :extend, ClassMethods
+          super
+        end
+
+        module ClassMethods
+          delegate :with_scorpion, to: :all
+        end
+
+        def association( *args, &block )
+          sting! super
+        end
+
+      end
+
+    end
+  end
+end

data/lib/scorpion/rails/active_record/relation.rb

@@ -0,0 +1,66 @@
+module Scorpion
+  module Rails
+    module ActiveRecord
+
+      # Make sure that all models return by the relation inherit the relation's
+      # scorpion.
+      module Relation
+        include Scorpion::Stinger
+
+        # ============================================================================
+        # @!group Attributes
+        #
+
+        # @!attribute
+        # @return [Scorpion] the scorpion serving the relation.
+          attr_accessor :scorpion
+
+        #
+        # @!endgroup Attributes
+
+        # Elect to use a specific scorpion for all further operations in the
+        # chain.
+        #
+        # @example
+        #
+        #   User.all.with_scorpion( scorpion ).where( ... )
+        #   User.with_scorpion( scorpion ).where( ... )
+        def with_scorpion( scorpion )
+          spawn.tap do |other|
+            other.scorpion = scorpion
+          end
+        end
+
+
+        # from ActiveRecord::Relation
+        [ :new, :build, :create, :create! ].each do |method|
+          class_eval <<-EOS, __FILE__, __LINE__ + 1
+            def #{ method }( *args, &block )
+              super *args do |*block_args|
+                sting!( block_args )
+                yield *block_args if block_given?
+              end
+            end
+          EOS
+        end
+
+        # from ActiveRecord::SpawnMethods
+        def spawn
+          sting!( super )
+        end
+
+        private
+          # from ActiveRecord::Relation
+          def exec_queries( *args, &block )
+            sting!( super )
+          end
+
+          # from ActiveRecord::SpawnMethods
+          def relation_with( *args )
+            sting!( super )
+          end
+
+      end
+    end
+  end
+end

data/lib/scorpion/rails/active_record.rb

@@ -0,0 +1,21 @@
+module Scorpion
+  module Rails
+    module ActiveRecord
+      require 'scorpion/rails/active_record/model'
+      require 'scorpion/rails/active_record/relation'
+      require 'scorpion/rails/active_record/association'
+
+      # Setup scorpion support for activerecord
+      def self.install!
+        return unless defined? ::ActiveRecord
+
+        ::ActiveRecord::Base.send :prepend, Scorpion::Rails::ActiveRecord::Model
+        ::ActiveRecord::Relation.send :prepend, Scorpion::Rails::ActiveRecord::Relation
+        ::ActiveRecord::Associations::Association.send :prepend, Scorpion::Rails::ActiveRecord::Association
+
+        # TODO extend Scorpion::Hunter to support AR
+      end
+    end
+  end
+end
+

data/lib/scorpion/rails/controller.rb

@@ -1,89 +1,49 @@
 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
+    # Adds a scorpion nest to support injection into rails controllers.
+    module Controller
 
-      #
-      # @!endgroup Attributes
+      ENV_KEY = 'scorpion.instance'.freeze
 
+      def scorpion
+        env[ENV_KEY]
+      end
 
       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
-
+        base.send :include, Scorpion::Rails::Nest
+        base.around_filter :with_scorpion
         super
       end
 
       private
 
         # Fetch a scorpion and feed the controller it's dependencies
-        def with_scorpion( &block )
-          @scorpion = nest.conceive
+        def prepare_scorpion( scorpion )
+          scorpion.prepare do |hunter|
+            # Allow dependencies to access the controller
+            hunter.hunt_for AbstractController::Base, return: self
 
-          @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
+            hunter.hunt_for ActionDispatch::Request do |hunt|
+              hunt.fetch( AbstractController::Base ).request
             end
-            hunter.hunt_for ActionDispatch::Response do |hunter|
-              hunter.hunt( AbstractController::Base ).response
+            hunter.hunt_for ActionDispatch::Response do |hunt|
+              hunt.fetch( AbstractController::Base ).response
             end
           end
+        end
 
-          @scorpion.feed self
+        def assign_scorpion( scorpion )
+          env[ENV_KEY] = scorpion
+        end
 
-          yield
-        ensure
-          @scorpion = nil
+        def free_scorpion
         end
+
     end
   end
 end

data/lib/scorpion/rails/job.rb

@@ -0,0 +1,30 @@
+require 'scorpion/nest'
+
+module Scorpion
+  module Rails
+
+    # Adds a scorpion nest to support injection into rails background worker jobs.
+    module Job
+
+      def self.included( base )
+        # Setup dependency injection
+        base.send :include, Scorpion::Rails::Nest
+        base.send :around_perform do |job, block|
+          job.with_scorpion &block
+        end
+
+        super
+      end
+
+      private
+
+        def prepare_scorpion( scorpion )
+          scorpion.prepare do |hunter|
+            hunter.hunt_for ActiveJob::Base do
+              self
+            end
+          end
+        end
+    end
+  end
+end

data/lib/scorpion/rails/nest.rb

@@ -0,0 +1,86 @@
+require 'scorpion/nest'
+require 'active_support/core_ext/class/attribute'
+
+module Scorpion
+  module Rails
+    # Handles building a scorpion to handle a single request and populating
+    # all the dependencies automatically.
+    module Nest
+
+      # ============================================================================
+      # @!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::Object
+
+        # @!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 DependencyMap#chart
+          def self.scorpion_nest( &block )
+            nest.prepare &block
+          end
+        end
+        base.nest ||= Scorpion.instance.build_nest
+
+        super
+      end
+
+      # Fetch a scorpion and feed the controller it's dependencies, then yield
+      # to perform the action within the context of that scorpion.
+      def with_scorpion( &block )
+        assign_scorpion( nest.conceive )
+
+        prepare_scorpion( @scorpion ) if respond_to?( :prepare_scorpion, true )
+
+        hunt = Scorpion::Hunt.new @scorpion, nil, nil
+        hunt.inject self
+
+        yield
+      ensure
+        free_scorpion
+      end
+
+      private
+
+        def assign_scorpion( scorpion )
+          @scorpion = scorpion
+        end
+
+        def free_scorpion
+          @scorpion = nil
+        end
+    end
+  end
+end

data/lib/scorpion/rails/railtie.rb

@@ -0,0 +1,16 @@
+require 'rails/railtie'
+
+module Scorpion
+  module Rails
+    class Railtie < ::Rails::Railtie
+
+      initializer "scorpion.configure" do |app|
+        ::ActionController::Base.send :include, Scorpion::Rails::Controller
+        ::ActiveJob::Base.send :include, Scorpion::Rails::Job
+
+        ::Scorpion::Rails::ActiveRecord.install!
+      end
+
+    end
+  end
+end