scorpion-ioc 0.0.1 → 0.1.0

data/circle.yml

@@ -0,0 +1,5 @@
+database:
+  override:
+    # We don't actually use a DB but it is included in the internal rails app
+    # for specs. So override default behavior to do nothing
+    - echo "Skip DB"

data/config.ru

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/lib/scorpion.rb

@@ -1,4 +1,91 @@
+require 'i18n'
+
+I18n.load_path += Dir[ File.expand_path( '../scorpion/locale/*.yml', __FILE__ ) ]
+
 module Scorpion
   require 'scorpion/version'
+  require 'scorpion/error'
+  require 'scorpion/king'
+  require 'scorpion/attribute_set'
+  require 'scorpion/hunter'
+  require 'scorpion/hunting_map'
+  require 'scorpion/prey'
+  require 'scorpion/nest'
   require 'scorpion/rails'
+
+  # @return [Scorpion] main scorpion for the app.
+  def self.instance
+    @instance
+  end
+  @instance = Scorpion::Hunter.new
+
+  # Prepare the {#instance} for hunting.
+  def self.prepare( &block )
+    instance.prepare &block
+  end
+
+  # Hunts for an object that satisfies the requested `contract` and `traits`.
+  # @param [Class,Module,Symbol] contract describing the desired behavior of the prey.
+  # @param [Array<Symbol>] traits required of the prey
+  # @return [Object] an object that matches the requirements defined in `attribute`.
+  # @raise [UnsuccessfulHunt] if a matching object cannot be found.
+  def hunt_by_traits!( contract, traits, *args, &block )
+    fail "Not implemented"
+  end
+  alias_method :fetch_by_traits!, :hunt_by_traits!
+
+  # Hunts for an object that satisfies the requested `contract` regardless of
+  # traits.
+  # @see #hunt_by_traits!
+  def hunt!( contract, *args, &block )
+    hunt_by_traits!( contract, nil, *args, &block )
+  end
+  alias_method :fetch!, :hunt!
+
+  # Populate given `king` with its expected attributes.
+  # @param [Scorpion::King] king to be fed.
+  # @return [Scorpion::King] the populated king.
+  def feed!( king )
+    king.injected_attributes.each do |attr|
+      king.send :feed, attr, hunt_by_traits!( attr.contract, attr.traits )
+    end
+  end
+
+  # Creates a new king and feeds it it's dependencies.
+  # @param [Class] king_class a class that includes {Scorpion::King}.
+  # @param [Array<Object>] args to pass to the constructor.
+  # @param [#call] block to pass to the constructor.
+  # @return [Scorpion::King] the spawned king.
+  def spawn( king_class, *args, &block )
+    if king_class < Scorpion::King
+      king_class.spawn self, *args, &block
+    else
+      king_class.new *args, &block
+    end
+  end
+
+  # Creates a new {Scorpion} copying the current configuration any any currently
+  # captured prey.
+  # @return [Scorpion] the replicated scorpion.
+  def replicate( &block )
+    fail "Not implemented"
+  end
+
+  # Free up any captured prey and release any long-held resources.
+  def destroy
+  end
+
+  # @return [Scorpion::Nest] a nest that uses this scorpion as the mother.
+  def build_nest
+    Scorpion::Nest.new( self )
+  end
+
+  private
+
+    # Used by concrete scorpions to notify the caller that the hunt was
+    # unsuccessful.
+    def unsuccessful_hunt!( contract, traits )
+      fail UnsuccessfulHunt.new contract, traits
+    end
+
 end

data/lib/scorpion/attribute.rb

@@ -0,0 +1,71 @@
+module Scorpion
+  # An injected attribute and it's configuration.
+  class Attribute
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @!attribute
+    # @return [Symbol] the name of the attribute.
+      attr_reader :name
+
+    # @!attribute
+    # @return [Class,Module,Symbol] contract that describes the desired behavior
+    #   of the injected object.
+      attr_reader :contract
+
+    # @!attribute
+    # @return [Array<Symbol>] traits that must match on instances of the {#contract}
+      attr_reader :traits
+
+    # @!attribute
+    # @return [Boolean] true if the attribute is not immediately required and
+    #   will be hunted down on first use.
+      def lazy?; @lazy end
+
+    # @!attribute
+    # @return [Boolean] true if the attribute should have a public writer.
+      def public?; @public end
+
+    # @!attribute
+    # @return [Boolean] true if the attribute should have a public writer.
+      def private?; @private end
+
+
+    #
+    # @!endgroup Attributes
+
+
+    def initialize( name, contract, traits = nil, options = {} )
+      @name      = name.to_sym
+      @contract  = contract
+      @traits    = Array( traits ).flatten.freeze
+      @trait_set = Set.new( @traits.map{ |t| :"#{t}?" } )
+      @lazy      = options.fetch( :lazy, false )
+      @public    = options.fetch( :public, false )
+      @private   = options.fetch( :private, false )
+    end
+
+    def respond_to?( name, include_all = false )
+      super || trait_set.include?( name )
+    end
+
+    private
+      # @return [Set] the set of traits associated with the attribute pre-processed
+      #   to include the trait names with a '?' suffix.
+        attr_reader :trait_set
+
+      def method_missing( name, *args )
+        if is_trait_method?( name )
+          trait_set.include? name
+        else
+          super
+        end
+      end
+
+      def is_trait_method?( name )
+        name[-1] == '?'
+      end
+  end
+end

data/lib/scorpion/attribute_set.rb

@@ -0,0 +1,96 @@
+require 'scorpion/attribute'
+
+module Scorpion
+  class AttributeSet
+    include Enumerable
+
+    def initialize( attributes = {} )
+      @attributes = attributes
+    end
+
+    def []( key )
+      attributes.fetch( key )
+    end
+
+    def each( &block )
+      attributes.each do |k,v|
+        yield v
+      end
+    end
+
+    # Merge two sets and create another.
+    def merge( other )
+      AttributeSet.new attributes.merge( other.attributes )
+    end
+    alias_method :|, :merge
+
+    # Inherit attribute definitions from another set.
+    def inherit!( other )
+      other.each do |attr|
+        attributes[attr.name] ||= attr
+      end
+    end
+
+    def key?( name )
+      attributes.key? name
+    end
+
+    # Defines the food that {Scorpion::King} 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.
+    #
+    # If the block takes an argument, AttributeSet will yield to the block
+    # passing itself. If no argument is provided, yield will use the
+    # AttributeSet itself as the calling context.
+    #
+    # @example With Argument
+    #
+    #   define do |set|
+    #     set.logger Rails::Logger
+    #   end
+    #
+    # @example Without Argument
+    #
+    #   define do
+    #     logger Rails::Logger, :color
+    #   end
+    def define( &block )
+      return unless block_given?
+
+      @defining_attributes = true
+      if block.arity == 1
+        yield self
+      else
+        instance_eval &block
+      end
+
+      self
+    ensure
+      @defining_attributes = false
+    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
+
+        if args.length >= 1
+          define_attribute name, *args
+        else
+          super
+        end
+      end
+
+  end
+end

data/lib/scorpion/error.rb

@@ -0,0 +1,29 @@
+require 'i18n'
+
+module Scorpion
+  class Error < StandardError
+
+    private
+      def translate( key, args = {} )
+        I18n.translate key, args.merge( scope: [:scorpion,:errors,:messages] )
+      end
+  end
+
+  class UnsuccessfulHunt < Error
+    attr_reader :contract
+    attr_reader :traits
+
+    def initialize( contract, traits = nil )
+      @contract = contract
+      @traits   = traits
+
+      super translate( :unsuccessful_hunt, contract: contract, traits: traits )
+    end
+  end
+
+  class BuilderRequiredError < Error
+    def initialize( message = nil )
+      super ( message || translate( :builder_required ) )
+    end
+  end
+end

data/lib/scorpion/hunter.rb

@@ -0,0 +1,54 @@
+module Scorpion
+  # A concrete implementation of a Scorpion used to hunt down food for a {Scorpion::King}.
+  # @see Scorpion
+  class Hunter
+    include Scorpion
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @return [Scorpion::HuntingMap] map of {Prey} and how to create instances.
+      attr_reader :hunting_map
+      protected :hunting_map
+
+    # @return [Scorpion] parent scorpion to deferr hunting to on missing prey.
+      attr_reader :parent
+      private :parent
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( parent = nil, &block )
+      @parent      = parent
+      @hunting_map = Scorpion::HuntingMap.new( self )
+
+      prepare &block if block_given?
+    end
+
+    # Prepare the scorpion for hunting.
+    # @see HuntingMap#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.nil?
+        unsuccessful_hunt!( contract, traits ) unless prey
+      end
+      prey.fetch self, *args, &block
+    end
+
+    # @see Scorpion#replicate
+    def replicate
+      replica = self.class.new self
+      replica.hunting_map.replicate_from( hunting_map )
+      replica
+    end
+
+  end
+end

data/lib/scorpion/hunting_map.rb

@@ -0,0 +1,115 @@
+module Scorpion
+  # {#chart} available {Prey} and {#find} them based on desired
+  # {#{Scorpion::Attribute attributes}.
+  class HuntingMap
+    include Enumerable
+    extend Forwardable
+
+    # ============================================================================
+    # @!group Attributes
+    #
+
+    # @return [Scorpion] the scorpion that created the map.
+      attr_reader :scorpion
+
+    # @return [Set] the set of prey charted on this map.
+      attr_reader :prey_set
+      private :prey_set
+
+    # @return [Set] the set of prey charted on this map that is shared with all
+    #   child prey.
+      attr_reader :shared_prey_set
+      private :shared_prey_set
+
+
+    # @return [Set] the active prey set either {#prey_set} or {#shared_prey_set}
+      attr_reader :active_prey_set
+      private :active_prey_set
+
+    #
+    # @!endgroup Attributes
+
+    def initialize( scorpion )
+      @scorpion = scorpion
+      @prey_set = @active_prey_set = Set.new
+      @shared_prey_set = Set.new
+    end
+
+    # Find {Prey} that matches the requested `contract` and `traits`.
+    # @param [Class,Module,Symbol] contract describing the desired behavior of the prey.
+    # @param [Array<Symbol>] traits found on the {Prey}.
+    # @return [Prey] the prey matching the attribute.
+    def find( contract, traits = nil )
+      prey_set.find{ |p| p.satisfies?( contract, traits ) } ||
+      shared_prey_set.find{ |p| p.satisfies?( contract, traits ) }
+    end
+
+    # Chart the {Prey} that this hunting map can {#find}.
+    def chart( &block )
+      return unless block_given?
+
+      if block.arity == 1
+        yield self
+      else
+        instance_eval &block
+      end
+
+      self
+    end
+
+    # Define {Prey} 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
+    # prey for the {Scorpion}.
+    #
+    # @param [Class,Module,Symbol] contract describing the desired behavior of the prey.
+    # @param [Array<Symbol>] traits found on the {Prey}.
+    # @return [Scorpion::Prey] the prey to be hunted for.
+    def hunt_for( contract, traits = nil, &builder )
+      active_prey_set << prey_class( contract, &builder ).new( contract, traits, &builder )
+    end
+    alias_method :offer, :hunt_for
+
+    # Captures a single prey and returns the same instance fore each request
+    # for the resource.
+    # @see #hunt_for
+    def capture( contract, traits = nil, &builder )
+      active_prey_set << Scorpion::Prey::CapturedPrey.new( prey_class( contract, &builder ).new( contract, traits, &builder ) )
+    end
+    alias_method :singleton, :capture
+
+    # Share captured prey defined within the block with all child scorpions.
+    def share( &block )
+      old_set = active_prey_set
+      @active_prey_set = shared_prey_set
+      yield
+    ensure
+      @active_prey_set = old_set
+    end
+
+    def each( &block )
+      prey_set.each &block
+    end
+    delegate [ :empty?, :blank?, :present? ] => :prey_set
+
+    # Replicates the prey in `other_map` into this map.
+    # @param [Scorpion::HuntingMap] other_map to replicate from.
+    def replicate_from( other_map )
+      other_map.each do |prey|
+        if replica = prey.replicate
+          prey_set << replica
+        end
+      end
+    end
+
+    private
+      def prey_class( contract, &builder )
+        return Scorpion::Prey::BuilderPrey if block_given?
+        return Scorpion::Prey::HuntedPrey  if contract.respond_to? :hunt
+        return Scorpion::Prey::ClassPrey   if contract.is_a? Class
+        return Scorpion::Prey::ClassPrey   if contract.is_a? Module
+
+        raise Scorpion::BuilderRequiredError
+      end
+  end
+end