wirer 0.4.7

data/lib/wirer/dependency.rb

@@ -0,0 +1,234 @@
+# dependency :foo, Class, :features => [:feature, :feature], :optional => true
+# dependency :foo, Class, :features => [:feature, :feature], :multiple => true
+#
+# dependency :foo, Class, :optional => true
+# dependency :foo, :feature, :another_feature, :optional => true, :constructor => true
+
+module Wirer
+
+  class Dependency
+    def self.new_from_args(*args)
+      new(normalise_args(*args))
+    end
+
+    def self.new_from_arg_or_args_list(arg_or_args_list)
+      new(normalise_arg_or_args_list(arg_or_args_list))
+    end
+
+    def self.normalise_arg_or_args_list(arg_or_args_list)
+      case arg_or_args_list
+      when Hash then arg_or_args_list
+      when Array then normalise_args(*arg_or_args_list)
+      else normalise_args(arg_or_args_list)
+      end
+    end
+
+    def self.normalise_args(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      args.each do |requirement|
+        case requirement
+        when Module then options[:class] = requirement
+        else (options[:features] ||= []) << requirement
+        end
+      end
+      options
+    end
+
+    OPTION_NAMES = [:class, :module, :features, :prefer, :multiple, :optional, :factory]
+
+    # By default, dependencies will :prefer => :default.
+    # This means if you want to force one factory to be preferred over another
+    # in a given situation, you can just add (or wrap it with) a provided feature
+    # name of :default.
+    PREFER_DEFAULT = :default
+
+    def initialize(options = {})
+      required_class = options[:class] || options[:module]
+      case required_class
+      when Module
+        @required_class = required_class
+      when String
+        @required_class_name = required_class
+      when NilClass
+        @required_class = nil
+      else
+        raise ArgumentError, "required :class for a Dependency must be a Module or Class, or a String name of a Module or Class"
+      end
+      @required_features = options[:features] && [*options[:features]]
+      @multiple = options[:multiple] || false
+      @optional = options[:optional] || false
+      @factory = options[:factory] || false
+
+      if @multiple
+        raise ArgumentError, "preferred features don't make sense for a :multiple depedency" if options.has_key?(:prefer)
+      else
+        @preferred_features = [*options.fetch(:prefer, PREFER_DEFAULT) || []]
+      end
+    end
+
+    attr_reader :required_features, :preferred_features
+    def multiple?; @multiple; end
+    def optional?; @optional; end
+
+    # Specifying :factory => true on a dependency means that you won't be given an actual instance
+    # of the class you asked for, but rather you'll be given a simple factory wrapper which allows
+    # you to construct your own instance(s), with any dependencies pre-supplied.
+    # See Factory::CurriedDependencies
+    def factory?; @factory; end
+
+    # A string class name may be supplied as the :class arg to the constructor, in which case we only
+    # attempt to resolve the actual class from it the first time .required_class is requested.
+    #
+    # This helps avoid introducing undesired load order dependencies between classes using Wirer::Factory::ClassDSL.
+    def required_class
+      return @required_class if defined?(@required_class)
+      @required_class = @required_class_name.split("::").inject(Object, :const_get)
+    end
+
+    def requirements_to_s
+      [
+        begin
+          case required_class
+          when ::Class then "class #{@required_class}"
+          when ::Module then "module #{@required_class}"
+          end
+        rescue NameError
+          "class or module name #{@required_class_name} (not currently loaded!)"
+        end,
+        @required_features && "features #{@required_features.inspect}"
+      ].compact.join(" and ")
+    end
+
+    def inspect
+      description = [
+        @factory ? "factory for #{requirements_to_s}" : requirements_to_s,
+        ("optional" if @optional),
+        ("multiple" if @multiple),
+        ("preferring features #{@preferred_features.inspect}" if @preferred_features && !@preferred_features.empty?)
+      ].compact.join(', ')
+      "#<#{self.class} on #{description}>"
+    end
+
+    def match_factories(available_factories)
+      candidates = available_factories.select {|f| self === f}
+      if !@optional && candidates.length == 0
+        raise DependencyFindingError, "No available factories matching #{requirements_to_s}"
+      end
+      if @multiple
+        candidates.map! {|c| yield c} if block_given?; candidates
+      else
+        candidate = if candidates.length > 1
+          if @preferred_features.empty?
+            raise DependencyFindingError, "More than one factory available matching #{requirements_to_s}"
+          else
+            unique_preferred_factory(candidates)
+          end
+        else
+          candidates.first
+        end
+        if block_given?
+          yield candidate if candidate
+        else
+          candidate
+        end
+      end
+    end
+
+    def ===(factory)
+      factory.is_a?(Factory::Interface) && matches_required_class(factory) && matches_required_features(factory)
+    end
+
+    def check_argument(argument_name, argument, strict_type_checks=false)
+      if @multiple
+        raise ArgumentError, "expected Array for argument #{argument_name}" unless argument.is_a?(Array)
+        if argument.empty?
+          if @optional then return else
+            raise ArgumentError, "expected at least one value for argument #{argument_name}"
+          end
+        end
+        argument.each do |value|
+          if @factory
+            unless value.respond_to?(:new)
+              raise ArgumentError, "expected Array of factory-like objects which respond_to?(:new) for argument #{argument_name}"
+            end
+          elsif strict_type_checks && required_class && !value.is_a?(required_class)
+            raise ArgumentError, "expected Array of #{required_class} for argument #{argument_name}"
+          end
+        end
+      else
+        if argument.nil?
+          if @optional then return else
+            raise ArgumentError, "expected argument #{argument_name}"
+          end
+        end
+        if @factory
+          unless argument.respond_to?(:new)
+            raise ArgumentError, "expected factory-like object which respond_to?(:new) for argument #{argument_name}"
+          end
+        elsif strict_type_checks && required_class && !argument.is_a?(required_class)
+          raise ArgumentError, "expected #{required_class} for argument #{argument_name}"
+        end
+      end
+    end
+
+    # if the required_class can't be resolved (ie a class of that name doesn't even exist) then nothing will match.
+    def matches_required_class(factory)
+      begin
+        !required_class || factory.provides_class <= required_class
+      rescue NameError
+        false
+      end
+    end
+
+    def matches_required_features(factory)
+      !@required_features || @required_features.all? {|feature| factory.provides_features.include?(feature)}
+    end
+
+    def with_options(options)
+      new_options = {
+        :multiple => @multiple,
+        :optional => @optional,
+        :class    => required_class,
+        :features => @required_features,
+        :prefer   => @preferred_features
+      }
+      new_required_class = options[:class] and begin
+        if required_class && !(new_required_class <= required_class)
+          raise "Required class #{new_required_class} not compatible with existing requirement for #{required_class}"
+        end
+        new_options[:class] = new_required_class
+      end
+      new_required_features = options[:features] and begin
+        new_options[:features] ||= []
+        new_options[:features] |= [*new_required_features]
+      end
+      new_preferred_features = options[:prefer] and begin
+        new_options[:prefer] ||= []
+        new_options[:prefer] |= [*new_preferred_features]
+      end
+      self.class.new(new_options)
+    end
+
+  private
+
+    def unique_preferred_factory(candidates)
+      max_preferred_features_count = 0
+      winners = []
+      candidates.each do |candidate|
+        provided = candidate.provides_features
+        count = @preferred_features.count {|f| provided.include?(f)}
+        if count > max_preferred_features_count
+          max_preferred_features_count = count
+          winners = [candidate]
+        elsif count == max_preferred_features_count
+          winners << candidate
+        end
+      end
+      if winners.length > 1
+        raise DependencyFindingError,
+          "More than one factory available matching #{requirements_to_s}, and tie can't be resolved using preferred_features #{@preferred_features.inspect}"
+      end
+      winners.first
+    end
+  end
+end

data/lib/wirer/errors.rb

@@ -0,0 +1,30 @@
+module Wirer
+
+  # Thank you to http://rubyforge.org/projects/nestegg for the pattern
+  class Error < StandardError
+
+    attr_reader :cause
+    alias :wrapped_error :cause
+
+    def initialize(msg, cause=nil)
+      @cause = cause
+      super(msg)
+    end
+
+    def set_backtrace(bt)
+      if cause
+        bt << "cause: #{cause.class.name}: #{cause}"
+        bt.concat cause.backtrace
+      end
+      super(bt)
+    end
+
+  end
+
+  class DependencyFindingError < Error; end
+  class CyclicDependencyError < Error; end
+
+  # raised when a dependency could be found, but failed to be constructed.
+  class DependencyConstructionError < Error; end
+
+end

data/lib/wirer/factory/class_mixins.rb

@@ -0,0 +1,117 @@
+module Wirer
+  # You can extend a Class instance directly with this if you want
+  # the class itself to be usable as a factory, exposing
+  # Wirer::Factory::Interface.
+  #
+  # By default, new_from_dependencies will call new on the class
+  # with the hash of dependencies as the last argument (or merged
+  # into the last argument where this is already a Hash). If you
+  # don't like this you may want to override the new_from_dependencies
+  # class method.
+  #
+  # You'll still probably want to override some of
+  #   constructor_dependencies, provides_features, setter_dependencies;
+  # if you'd prefer to do this via a handy DSL, instead see
+  # See Wirer::Factory::ClassDSL.
+  module Factory::ClassMixin
+    include Factory::Interface
+
+    def provides_class; self; end
+
+    def new_from_dependencies(dependencies, *other_args, &block_arg)
+      if other_args.last.is_a?(Hash)
+        hash_arg = other_args.pop
+        other_args.push(hash_arg.merge(dependencies))
+      else
+        other_args.push(dependencies) unless dependencies.empty?
+      end
+      new(*other_args, &block_arg)
+    end
+  end
+
+  # A more convenient form of Wirer::Factory::ClassMixin, this additionally adds some
+  # private DSL methods which let you declare your constructor_dependencies,
+  # setter_dependencies and provides_features.
+  #
+  # The DSL works nicely with respect to subclassing, so you can add extra dependencies
+  # or features in a subclass.
+  module Factory::ClassDSL
+    include Factory::ClassMixin
+
+    def constructor_dependencies
+      @constructor_dependencies ||= (superclass.is_a?(Factory::Interface) ? superclass.constructor_dependencies.dup : {})
+    end
+
+    # the supplied implementation of setter_dependencies does not allow for them varying dependening on the
+    # instance passed; if you want to specify setter_dependencies on an instance-sensitive basis you'll need
+    # to override this yourself.
+    def setter_dependencies(instance=nil)
+      @setter_dependencies ||= (superclass.is_a?(Factory::Interface) ? superclass.setter_dependencies.dup : {})
+    end
+
+    def provides_features
+      @provides_features ||= (superclass.is_a?(Factory::Interface) ? superclass.provides_features.dup : [])
+    end
+
+  private
+
+    def provides_feature(*args)
+      provides_features.concat(args)
+    end
+
+    def add_dependency(type, arg_name, *dependency_args)
+      deps_hash = type == :setter ? setter_dependencies : constructor_dependencies
+      deps_hash[arg_name] = Dependency.new_from_args(*dependency_args)
+    end
+
+    # as a convenience, will additionally define an attr_reader for this dependency name
+    # unless you specify :getter => false. by default it will be private, but :getter => :public
+    # will make it public.
+    def constructor_dependency(name, *args)
+      getter = if args.last.is_a?(Hash) then args.last.delete(:getter) end
+      if getter != false
+        attr_reader(name)
+        getter == :public ? public(name) : private(name)
+      end
+      add_dependency(:constructor, name, *args)
+    end
+    alias :dependency :constructor_dependency
+
+    # sugar for dependency :foo, ..., :factory => true.
+    #
+    # for factory dependencies, you'll be given a factory instance responding to 'new'
+    # from which you can construct your own instances of the dependency -- as opposed
+    # to normal dependencies where the container will give you a pre-constructed instance.
+    def factory_dependency(name, *args)
+      args.push({}) unless args.last.is_a?(Hash)
+      args.last[:factory] = true
+      constructor_dependency(name, *args)
+    end
+
+    # will additionally define a attr_writer method of this name, unless :setter => false
+    # is specified. this is private by default but made public if you specify :setter => :public.
+    #
+    # and a corresponding public attr_reader too if :accessor => true if specified.
+    def setter_dependency(name, *args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      getter = options.delete(:getter)
+      setter = options.delete(:setter)
+      if setter != false
+        attr_writer(name)
+        setter == :public ? public(:"#{name}=") : private(:"#{name}=")
+      end
+      if getter != false
+        attr_reader(name)
+        getter == :public ? public(name) : private(name)
+      end
+
+      add_dependency(:setter, name, *args)
+    end
+  end
+end
+
+class Class
+  def wireable
+    extend Wirer::Factory::ClassDSL
+  end
+end

data/lib/wirer/factory/curried_dependencies.rb

@@ -0,0 +1,33 @@
+module Wirer
+  # This doesn't implement the full Factory::Interface, rather it's a simple
+  # 'curried' wrapper around the new_from_dependencies method of a factory,
+  # where the dependency arguments are pre-supplied.
+  #
+  # You can use one of these pretty much the same as a class, in that it has a
+  # 'new' method, or it also implements a Proc-like interface ('call' and 'to_proc')
+  # so you can also treat it like a block which constructs things.
+  #
+  # Factory::Interface#curry_with_dependencies is used to make these, but you'd
+  # normally get one via a Wirer::Containerm by specifying a dependency with :factory => true;
+  # the container will then give you a curried factory from which you can construct
+  # your own instances, rather than supplying a single pre-constructed instance.
+  #
+  # Note: at present only constructor dependencies can be curried in this way.
+  class Factory::CurriedDependencies
+    def initialize(factory, dependencies)
+      @factory = factory
+      @dependencies = dependencies
+    end
+
+    def new(*args, &block_arg)
+      @factory.new_from_dependencies(@dependencies, *args, &block_arg)
+    end
+
+    alias :call :new
+
+    # this allows it to be implicitly converted into a block argument, eg: instances = args.map(&factory)
+    def to_proc
+      method(:new).to_proc
+    end
+  end
+end

data/lib/wirer/factory/from_args.rb

@@ -0,0 +1,100 @@
+module Wirer
+  # This is handy if you want to create a factory instance entirely from
+  # supplied arguments, in particular from a supplied constructor block.
+  #
+  # This saves you having to create your own Factory class in almost all
+  # cases.
+  #
+  # If you specify a :class, a default implementation will be supplied
+  # for constructing instances from it, whereby dependencies are passed
+  # as the last argument to the class's new method, after any other args.
+  # (if the last arg is already a Hash, the dependencies will be merged
+  #  into it).
+  #
+  # Is also aliased for convenience from Factory.new.
+  #
+  # Factory.new(
+  #   :class => Foo,
+  #   :dependencies => {
+  #     :logger => Logger,
+  #     :bars   => {:class => Bar, :multiple => true}
+  #   }
+  # ) do |depedencies, *args, &block|
+  #   Foo.new(*args, dependencies, &block)
+  # end
+  class Factory::FromArgs
+    include Factory::Interface
+
+    OPTION_NAMES = [:class, :module, :args, :features, :dependencies, :constructor_dependencies, :setter_dependencies].freeze
+
+    def initialize(options={}, &constructor_block)
+      @provides_class = options[:class] || options[:module]
+
+      @constructor_dependencies = {}
+      (options[:constructor_dependencies] || options[:dependencies] || {}).each do |name, args|
+        @constructor_dependencies[name] = Dependency.new_from_arg_or_args_list(args)
+      end
+      @setter_dependencies = {}
+      (options[:setter_dependencies] || {}).each do |name, args|
+        @setter_dependencies[name] = Dependency.new_from_arg_or_args_list(args)
+      end
+
+      @provides_features = options[:features] || []
+      @constructor_block = constructor_block if constructor_block
+
+      case @provides_class
+      when ::Class
+        @initial_args = options[:args] if options[:args]
+      when Module
+        unless @constructor_block
+          raise ArgumentError, "when a Module is specified you need to supply a constructor block"
+        end
+      when NilClass
+        @provides_class = Object
+        unless @constructor_block
+          raise ArgumentError, "expected a :class or a constructor block or both"
+        end
+      else
+        raise TypeError, ":class / :module options only accept a Class or Module"
+      end
+    end
+
+    attr_reader :constructor_dependencies, :provides_class,
+                :provides_features, :initial_args, :wrapped_class
+
+    # Factory::FromArgs doesn't allow you to do instance-sensitive setter-dependencies;
+    # subclass or make your own factory if you want these.
+    def setter_dependencies(instance=nil); @setter_dependencies; end
+
+    def new_from_dependencies(dependencies, *other_args, &block_arg)
+      if @constructor_block
+        @constructor_block.call(dependencies, *other_args, &block_arg)
+      else
+        # The only time it allows you not to specify a constructor_block
+        # is when an actual Class is supplied for provides_class.
+        #
+        # In this case we supply a default construction method whereby
+        # dependencies are merged into a last argument:
+        if other_args.last.is_a?(Hash)
+          hash_arg = other_args.pop
+          other_args.push(hash_arg.merge(dependencies))
+        else
+          other_args.push(dependencies) unless dependencies.empty?
+        end
+        case @initial_args
+        when NilClass # forgeddit
+        when Array then other_args.unshift(*@initial_args)
+        else other_args.unshift(@initial_args)
+        end
+        @provides_class.new(*other_args, &block_arg)
+      end
+    end
+  end
+
+  module Factory
+    # delegates to Factory::FromArgs.new
+    def self.new(options, &constructor_block)
+      FromArgs.new(options, &constructor_block)
+    end
+  end
+end

data/lib/wirer/factory/from_instance.rb

@@ -0,0 +1,24 @@
+module Wirer
+  # For when you have some pre-existing instance which you want to wrap as a singleton
+  # Factory.
+  # (You wouldn't normally need to do this yourself, but rather Container uses it
+  #  under the hood if you add an existing instance to the container)
+  class Factory::FromInstance
+    include Factory::Interface
+
+    attr_reader :instance, :provides_features
+
+    def initialize(instance, *features)
+      @instance = instance
+      @provides_features = features
+    end
+
+    def provides_class
+      @instance.class
+    end
+
+    def new_from_dependencies(deps=nil)
+      @instance
+    end
+  end
+end

data/lib/wirer/factory/interface.rb

@@ -0,0 +1,114 @@
+module Wirer
+  module Factory; end
+
+  # This is the basic Factory interface around which the whole framework is built.
+  #
+  # You won't normally need to implement this interface yourself, but it's useful
+  # in terms of understanding how Wirer works.
+  #
+  # A Factory is responsible for creating some kind of object, given some dependencies
+  # and possibly some additional arguments. so new_from_dependencies is the main
+  # method here.
+  #
+  # It also comes with an interface (constructor_dependencies) telling you what
+  # the required dependencies are; this is specified via a hash of symbol argument
+  # names to Dependency objects which specify the criterea that must be satisfied
+  # for the dependency argument of that name.
+  #
+  # Wirer::Container uses this metadata to find and pass in dependencies automatically
+  # when constructing things from Factories.
+  #
+  # == Two-phase initialisation
+  #
+  # Factory can also support cases where some dependencies need to be passed in
+  # after creation time, eg when you have cyclic dependencies.
+  #
+  # This is done via specifying setter_dependencies in the same way as
+  # constructor_dependencies; the expectation is that after constructing an instance
+  # with new_from_dependencies, you must additionally fetch any setter_dependencies
+  # and 'inject' them into the instance via calling inject_dependency on the factory
+  # with the instance, dependency name and the value for that dependency.
+  #
+  # (the default implementation of inject_dependency will just call a setter method
+  #  on the instance, eg instance.logger = logger; this will work with a private setter
+  #  if you prefer to make private these things which are only a part of initialization)
+  #
+  # After a whole set of objects have been created and their setter_dependencies injected, it
+  # can be handy for them to get a notification along the lines of "hey so your whole dependency
+  # graph is now all wired up any ready". Factory#post_initialize should send this notification
+  # to an object created from the factory, where it's supported by the objects you construct.
+  #
+  # (by default it will call a :post_initialize method on the instance, if this is present;
+  #  again this can be a private method if you wish).
+  module Factory::Interface
+    # A Module or Class which all objects constructed by this factory are kind_of?.
+    # The more specific you are, the more use this will be when specifying requirements
+    # based on a Module or Class.
+    def provides_class
+      Object # not very informative by default :)
+    end
+
+    # List of arbitrary objects representing features provided by this factory,
+    # which may be compared against required features when looking for dependencies.
+    # Typically symbols are used.
+    def provides_features
+      []
+    end
+
+    # Hash of symbol argument names to Wirer::Dependency objects, representing
+    # dependencies that need to be passed as arguments to new_from_dependencies
+    def constructor_dependencies
+      {}
+    end
+
+    # Hash of symbol argument names to Wirer::Dependency objects, representing
+    # dependencies which need to be injected into instances *after* they have
+    # been constructed via new_from_dependencies
+    #
+    # if no instance is passed, should return a hash of any setter dependencies
+    # applying to all instances constructed from this factory. (which may be none)
+    #
+    # if an instance is passed, it may add to this hash any additional setter dependencies
+    # which are specific to this instance. This is useful when you have some extra set
+    # of dependencies which varies depending on the parameters to the constructor.
+    def setter_dependencies(instance=nil)
+      {}
+    end
+
+    # Will be passed a hash which has keys for all of the argument names specified
+    # in constructor_dependencies, together with values which are the constructed
+    # dependencies meeting the requirements of the corresponding Wirer::Depedency.
+    #
+    # May also be passed additional non-dependency arguments supplied directly
+    # to the factory.
+    #
+    # The following must hold:
+    #   factory.new_from_dependencies(dependencies, ...).is_a?(factory.provides_class)
+    #
+    # however the following is not required to hold:
+    #   factory.new_from_dependencies(dependencies, ...).instance_of?(factory.provides_class)
+    def new_from_dependencies(dependencies={}, *other_args, &block_arg)
+      raise NotImplementedError
+    end
+
+    # Supplies a wrapper around the factory with a set of pre-supplied dependencies.
+    # The wrapper can then be used to construct instances.
+    # See Factory::CurriedDependencies
+    def curry_with_dependencies(dependencies)
+      Factory::CurriedDependencies.new(self, dependencies)
+    end
+
+    def inject_dependency(instance, attr_name, dependency)
+      instance.send(:"#{attr_name}=", dependency)
+    end
+
+    def post_initialize(instance)
+      instance.send(:post_initialize) if instance.respond_to?(:post_initialize, true)
+    end
+
+    def wrapped_with(additional_options={}, &wrapped_constructor_block)
+      Factory::Wrapped.new(self, additional_options, &wrapped_constructor_block)
+    end
+  end
+
+end