conject 0.0.1

data/lib/conject/class_ext_construct_with.rb

@@ -0,0 +1,123 @@
+
+class Class
+
+  def construct_with(*syms)
+    klass = self
+
+    object_def = Conject::ObjectDefinition.new(:owner => klass, :component_names => syms)
+    klass.meta_def :object_definition do
+      object_def
+    end
+
+
+    klass.class_def_private :components do 
+      @_components ||= {}
+    end
+
+    syms.each do |object_name|
+      class_def_private object_name do
+        components[object_name]
+      end
+    end
+
+    klass.class_def_private :set_components do |component_map|
+      required = object_def.component_names
+      provided = component_map.keys
+      if required.to_set != provided.to_set
+        raise Conject::CompositionError.new(
+          :object_definition => object_def,
+          :required => required, 
+          :provided => provided)
+      end
+
+      components.clear.merge! component_map
+
+    end
+
+    # Tidbits of state that our dynamically-defined functions herein
+    # will close over.
+    object_context_prep = {
+      :initialize_has_been_wrapped => false,  # keep track of when a class's :initialize method has been wrapped
+    }
+    
+    # Alias :new such that we can wrap and invoke it later
+    klass.meta_eval do 
+      alias_method :actual_new, :new
+    end
+
+    # Override default :new behavior for this class.
+    #
+    # The .new method is rewritten to accept a single argument:
+    #   component_map: a Hash containing all required objects to construct a new instance.
+    #                  Keys are expected to be symbols.
+    # 
+    # If user defines their own #initialize method, all components sent into .new
+    # will be installed BEFORE the user-defined #initialize, and it may accept arguments thusly:
+    # * zero args.  Nothing will be passed to #initialize
+    # * single arg. The component_map will be passed.
+    # * var args (eg, def initialize(*args)).  args[0] will be the component map.  NO OTHER ARGS WILL BE PASSED. See Footnote a)
+    #
+    klass.meta_def :new do |component_map|
+
+      # We only want to do the following one time, but we've waited until now
+      # in order to make sure our metaprogramming didn't get ahead of the user's
+      # own definition of initialize:
+      unless object_context_prep[:initialize_has_been_wrapped]
+        # Define a new wrapper'd version of initialize that accepts and uses a component map
+        alias_method :actual_initialize, :initialize
+        class_def :initialize do |component_map|
+          # Apply the given components
+          set_components component_map
+
+          # Invoke the normal initialize method.
+          # User-defined initialize method may accept 0 args, or it may accept a single arg
+          # which will be the component map.
+          arg_count = method(:actual_initialize).arity
+          case arg_count
+          when 0
+            actual_initialize
+          when 1, -1  # See Footnote a) at the bottom of this file
+
+            actual_initialize component_map
+
+          else
+            # We're not equipped to handle this
+            raise "User-defined initialize method defined with #{arg_count} parameters; must either be 0, other wise 1 or -1 (varargs) to receive the component map."
+          end
+        end
+        # Make a note that the initialize wrapper has been applied
+        object_context_prep[:initialize_has_been_wrapped] = true
+      end
+
+      # Instantiate an instance
+      actual_new component_map 
+    end
+  end
+
+  def has_object_definition?
+    respond_to?(:object_definition) and !object_definition.nil?
+  end
+
+end
+
+
+# Footnote a) - Object#initialize arity funny business
+#
+# Before Ruby 1.9.3, Object#initialize has -1 arity by default and accepts 0 or
+# more args.  1.9.3 changes Object#initialize to default to 0 args.  This is
+# deliberate (and in my opinion a long-overdue correction) but a mild problem
+# -- I have no idea how I would determine in 1.9.2 or earlier if a user has
+# defined NO constructor at all.  However, passing component_map to an
+# otherwise undefined initialize method won't hurt, so let's just do it.
+#
+# If in 1.9.3 a user really HAS defined a varargs #initialize, then let's
+# expect that initialize method to conform to the same rules we're laying out
+# for other cases: If you accept args at all, the first one will be the
+# component_map.  In this case NO ADDITIONAL ARGS WILL BE PASSED.  (Who would send them in, anyway?)
+# The idea here is that people using construct_with are not intending to construct
+# new instances using some other input.
+#
+# Found this when struggling:
+#   http://bugs.ruby-lang.org/issues/5542 - Bug #5542: Ruby 1.9.3-p0 changed arity on default initialization method
+#
+# crosby 2012-01-07

data/lib/conject/class_finder.rb

@@ -0,0 +1,11 @@
+
+class Conject::ClassFinder
+  def find_class(name)
+    cname = name.to_s.camelize
+    if Object.const_defined?(cname)
+      Object.const_get(cname)
+    else
+      raise "Could not find class for #{name}"
+    end
+  end
+end

data/lib/conject/composition_error.rb

@@ -0,0 +1,33 @@
+require 'set'
+
+class Conject::CompositionError < ArgumentError
+  def initialize(opts=nil)
+    opts ||= {}
+    object_def = opts[:object_definition]
+    required = nil
+    required = object_def.component_names if object_def
+    provided = opts[:provided] || []
+
+    msg = "Unexpected CompositionError"
+
+    if object_def.nil?
+      msg = "Failed to construct... something."
+      if provided and !provided.empty? 
+        msg << " Provided objects were: #{provided.inspect}"
+      end
+
+    elsif object_def and required and provided
+      owner = object_def.owner || "object"
+      msg = "Wrong components when building new #{owner}."
+
+      missing = required - provided
+      msg << " Missing required object(s) #{missing.to_a.inspect}." unless missing.empty?
+
+      unexpected = provided - required
+      msg << " Unexpected object(s) provided #{unexpected.to_a.inspect}." unless unexpected.empty?
+
+    end
+
+    super msg
+  end
+end

data/lib/conject/dependency_resolver.rb

@@ -0,0 +1,16 @@
+class Conject::DependencyResolver
+  #
+  # Given a Class, generate a map of dependencies needed to construct a new
+  # instance of that class. Dependencies are looked up (and/or instantiated, as
+  # determined within the ObjectContext) via the provided ObjectContext.
+  #
+  # This method assumes the Class has_object_defintion?  (Client code should
+  # determine that before invoking this method.)
+  #
+  def resolve_for_class(klass, object_context)
+    klass.object_definition.component_names.inject({}) do |obj_map, name|
+      obj_map[name] = object_context.get(name)
+      obj_map
+    end
+  end
+end

data/lib/conject/extended_metaid.rb

@@ -0,0 +1,33 @@
+# Metaid == a few simple metaclass helper
+# (See http://whytheluckystiff.net/articles/seeingMetaclassesClearly.html.)
+#
+# 2012-01-03 crosby: Added module_def_private and class_def_private
+#
+class Object
+  # The hidden singleton lurks behind everyone
+  def metaclass; class << self; self; end; end
+  def meta_eval &blk; metaclass.instance_eval &blk; end
+
+  # Adds methods to a metaclass
+  def meta_def name, &blk
+    meta_eval { define_method name, &blk }
+  end
+end
+
+class Module
+  # Defines an instance method within a module
+  def module_def name, &blk
+    module_eval { define_method name, &blk }
+  end
+
+  # Same as module_def then makes the method private
+  def module_def_private name, &blk
+    module_def name, &blk
+    private name
+  end
+end
+
+class Class
+  alias class_def module_def
+  alias class_def_private module_def_private
+end

data/lib/conject/object_context.rb

@@ -0,0 +1,61 @@
+class Conject::ObjectContext
+
+  construct_with :parent_context, :object_factory
+
+  def initialize
+    @cache = {}
+  end
+
+  # Inject a named object into this context
+  def put(name, object)
+    @cache[name.to_sym] = object
+  end
+
+  alias_method :[]=, :put
+
+  # Retrieve a named object from this context.
+  #   If the object is already existant in this context, return it.
+  #   If we have a parent context and it contains the requested object, get and return object from parent context. (Recursive upward search)
+  #   If the object exists nowhere in this or a super context: construct, cache and return a new instance of the requested object using the object factory.
+  def get(name)
+    name = name.to_sym
+    object = @cache[name]
+    return @cache[name] if @cache.keys.include?(name)
+    
+    if parent_context and parent_context.has?(name)
+      return parent_context.get(name)
+    else
+      object = object_factory.construct_new(name,self)
+      @cache[name] = object
+      return object
+    end
+  end
+
+  alias_method :[], :get
+
+  # Indicates if this context, or any parent context, contains the requested object in its cache.
+  def has?(name)
+    return true if directly_has?(name)
+
+    # Ask parent (if i have a parent) if I don't have the object:
+    if !parent_context.nil?
+      return parent_context.has?(name)
+    else
+      # I don't have it, and neither do my ancestors.
+      return false
+    end
+  end
+  
+  # Indicates if this context has the requested object in its own personal cache.
+  # (Does not consult any parent contexts.)
+  def directly_has?(name)
+    @cache.keys.include?(name.to_sym)
+  end
+
+  def in_subcontext
+    yield Conject.create_object_context(self) if block_given?
+  end
+
+end
+
+

data/lib/conject/object_definition.rb

@@ -0,0 +1,10 @@
+
+class Conject::ObjectDefinition
+  attr_reader :component_names, :owner 
+
+  def initialize(opts={})
+    @owner = opts[:owner]
+    @component_names = opts[:component_names] || []
+  end
+end
+

data/lib/conject/object_factory.rb

@@ -0,0 +1,28 @@
+
+class Conject::ObjectFactory
+  construct_with :class_finder, :dependency_resolver
+
+  def construct_new(name, object_context)
+
+    #
+    # This implementation is what I'm loosely calling "type 1" or "regular" object creation:
+    #  - Assume we're looking for a class to create an instance with
+    #  - it may or may not have a declared list of named objects it needs to be constructed with
+    #
+
+    klass = class_finder.find_class(name)
+
+    if klass.has_object_definition?
+      object_map = dependency_resolver.resolve_for_class(klass, object_context)
+      return klass.new(object_map)
+
+    elsif Conject::Utilities.has_zero_arg_constructor?(klass)
+      # Default construction
+      return klass.new
+    else
+      # Oops, out of ideas on how to build.
+      raise ArgumentError.new("Class #{klass} has no special component needs, but neither does it have a zero-argument constructor.");
+    end
+
+  end
+end

data/lib/conject/utilities.rb

@@ -0,0 +1,8 @@
+module Conject::Utilities 
+  class << self
+    def has_zero_arg_constructor?(klass)
+      init_arity = klass.instance_method(:initialize).arity
+      init_arity == 0 or (RUBY_VERSION <= "1.9.2" and init_arity == -1)
+    end
+  end
+end

data/lib/conject/version.rb

@@ -0,0 +1,3 @@
+module Conject
+  VERSION = "0.0.1"
+end

data/rake_tasks/rspec.rake

@@ -0,0 +1,25 @@
+begin
+require 'rspec/core/rake_task'
+rescue Exception => e
+  "RSpec is not available.  'spec' task will not be defined."
+end
+
+begin # protect from missing rspec
+  desc "Run specs"
+  RSpec::Core::RakeTask.new do |t|
+    if ENV["file"]
+      t.pattern = ENV["file"]
+    end
+    t.rspec_opts = "--color --format documentation" # --tty
+  end
+  
+  desc "Run individual spec"
+  task "spec:just" do
+    RSpec::Core::RakeTask.new("_tmp_rspec") do |t|
+      t.pattern = ENV["file"] || raise("Please supply 'file' argument")
+      t.rspec_opts = "--color"
+    end
+    Rake::Task["_tmp_rspec"].invoke
+  end
+rescue Exception => e
+end

data/spec/acceptance/dev/README

@@ -0,0 +1,7 @@
+Developing Acceptance Tests
+
+This suite contains acceptance tests for features that are
+UNDER DEVELOPMENT.
+
+Once the features are complete, the test must be moved
+into the "regression" peer directory.

data/spec/acceptance/regression/README

@@ -0,0 +1,12 @@
+Regression Acceptance Tests
+
+This suite ensures that all defined features remain functional.  Only
+acceptance tests that are expected to ALWAYS PASS should live here.
+
+Tests that are NOT FINISHED, or are failing because their targeted
+features are UNDER DEVELOPMENT, go in the "dev" directory parallel to
+this "regression" dir.
+
+This applies to acceptance tests that are being redressed, or
+whose target features are back under actual development.
+

data/spec/acceptance/regression/basic_composition_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + "/../../spec_helper")
+
+describe "basic object composition" do
+  subject { Conject.default_object_context }
+
+  before do
+    append_test_load_path "basic_composition"
+    require 'fence'
+    require 'wood'
+    require 'nails'
+  end
+
+  after do
+    restore_load_path
+  end
+
+  it "constructs objects by providing necessary object components" do
+    fence = subject.get('fence')
+    fence.should_not be_nil
+
+    fence.wood.should_not be_nil
+    fence.wood.object_id.should == subject.get('wood').object_id
+
+    fence.nails.should_not be_nil
+    fence.nails.object_id.should == subject.get('nails').object_id
+  end
+
+end
+

data/spec/acceptance/regression/basic_object_creation_spec.rb

@@ -0,0 +1,42 @@
+require File.expand_path(File.dirname(__FILE__) + "/../../spec_helper")
+
+
+describe "simple object creation" do
+  subject { Conject.default_object_context }
+
+  before do
+    append_test_load_path "simple_stuff"
+    require 'some_random_class'
+  end
+
+  after do
+    restore_load_path
+  end
+
+  it "constructs simple objects" do
+    obj = subject.get('some_random_class')
+    obj.should_not be_nil
+    obj.class.should == SomeRandomClass
+  end
+
+  it "caches and returns references to same objects once built" do
+    obj = subject.get('some_random_class')
+    obj.should_not be_nil
+    obj.class.should == SomeRandomClass
+
+    obj2 = subject.get('some_random_class')
+    obj2.should_not be_nil
+    obj2.class.should == SomeRandomClass
+
+    obj.object_id.should == obj2.object_id
+  end
+
+  it "can use strings and symbols interchangeably for object keys" do
+    obj = subject.get('some_random_class')
+    obj.should_not be_nil
+    obj2 = subject.get(:some_random_class)
+    obj.object_id.should == obj2.object_id
+  end
+
+end
+