needle 0.6.0 → 0.9.0

data/lib/needle/container.rb

@@ -41,7 +41,7 @@ module Needle
         protected_instance_methods +
         public_instance_methods -
         [ "instance_eval", "__id__", "__send__", "initialize", "remove_const",
-          "method_missing", "inspect" ]
+          "method_missing", "method", "class", "inspect", "to_s", "instance_variables" ]
       ).
       each { |m| undef_method m }
 
@@ -63,11 +63,9 @@ module Needle
         @container.intercept( name )
       end
 
-      # Delegate to Container#namespace. Instead of passing the container to
-      # the new namespace, however, pass the definition context for the new
-      # container.
+      # Delegate to Container#namespace.
       def namespace( *parms, &block )
-        @container.namespace( *parms ) { |ns| block.call( ns.builder ) }
+        @container.namespace( *parms, &block )
       end
 
       # Delegate to Container#namespace!.
@@ -75,6 +73,11 @@ module Needle
         @container.namespace!( *parms, &block )
       end
 
+      # Delegate to Container#define on the new namespace.
+      def namespace_define( *parms, &block )
+        @container.namespace( *parms ) { |ns| ns.define( &block ) }
+      end
+
       # Any method invocation with no block and no parameters is interpreted to
       # be a service reference on the wrapped container, and delegates to
       # Container#[]. If the block is not given but the args are not empty, a
@@ -125,8 +128,9 @@ module Needle
     # container's name and all parent's names up to the root container,
     # catenated together with dot characters, i.e., "one.two.three".
     def fullname
-      return @name.to_s unless @parent
-      "#{@parent.fullname}.#{@name}"
+      parent_name = ( @parent ? @parent.fullname : nil )
+      return @name.to_s unless parent_name
+      "#{parent_name}.#{@name}"
     end
 
     # Returns the DefinitionContext instance that can be used to "build"
@@ -173,6 +177,8 @@ module Needle
     # requested (with Container#[]), the associated callback will be used
     # to construct it.
     #
+    # This returns the registry that was used to register the service.
+    #
     # Usage:
     #
     #   container.register( :calc, :model=>:prototype ) do |c|
@@ -184,6 +190,8 @@ module Needle
       name = name.to_s.intern unless name.is_a?( Symbol )
       @service_points[ name ] =
         ServicePoint.new( self, name, opts, &callback )
+
+      self
     end
 
     # Create a new namespace within the container, with the given name. If a
@@ -198,7 +206,7 @@ module Needle
     #
     # Note that this means that namespaces may be singletons or prototypes, or
     # have immediate or deferred instantiation, and so forth. (The default of
-    # immediately, singleton instantiation is sufficient for 99% of the things
+    # immediate, singleton instantiation is sufficient for 99% of the things
     # you'll use namespaces for.)
     #
     # Usage:
@@ -209,6 +217,11 @@ module Needle
     #   end
     #
     #   adder = container.calc.operations.add
+    #
+    # *Note*: the block is not invoked until the namespace is created, which
+    # is not until it is first referenced. If you need the namespace to be
+    # created immediately, either use #namespace_define or reference the
+    # namespace as soon as you've created it.
     def namespace( name, opts={}, &block )
       register( name, opts ) do |c,p|
         ns = Container.new( c, name )
@@ -229,20 +242,64 @@ module Needle
     #
     # Note that this means that namespaces may be singletons or prototypes, or
     # have immediate or deferred instantiation, and so forth. (The default of
-    # immediately, singleton instantiation is sufficient for 99% of the things
+    # immediate, singleton instantiation is sufficient for 99% of the things
     # you'll use namespaces for.)
     #
     # Usage:
     #
-    #   container.namespace!( :operations ) do
+    #   container.namespace_define!( :operations ) do
     #     add { Adder.new }
     #     ...
     #   end
     #
     #   adder = container.calc.operations.add
-    def namespace!( name, opts={}, &block )
+    #
+    # *Note*: this method will immediately instantiate the new namespace,
+    # unlike #namespace. If you want instantiation of the namespace to be
+    # deferred, either use a deferring service model
+    # (like <tt>:singleton_deferred</tt>) or create the namespace via
+    # #namespace.
+    def namespace_define!( name, opts={}, &block )
       raise ArgumentError, "block expected" unless block
       namespace( name, opts ) { |ns| ns.define!( &block ) }
+      self[name]
+    end
+
+    alias :namespace! :namespace_define!
+
+    # Create a new namespace within the container, with the given name.
+    # The block (which is required) will be passed to Container#define on
+    # the new namespace.
+    #
+    # For the curious, namespaces are simply services that are implemented
+    # by Container.  The two statements are really identical:
+    #
+    #   container.namespace( :calc )
+    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #
+    # Note that this means that namespaces may be singletons or prototypes, or
+    # have immediate or deferred instantiation, and so forth. (The default of
+    # immediate, singleton instantiation is sufficient for 99% of the things
+    # you'll use namespaces for.)
+    #
+    # Usage:
+    #
+    #   container.define_namespace( :operations ) do |b|
+    #     b.add { Adder.new }
+    #     ...
+    #   end
+    #
+    #   adder = container.calc.operations.add
+    #
+    # *Note*: this method will immediately instantiate the new namespace,
+    # unlike #namespace. If you want instantiation of the namespace to be
+    # deferred, either use a deferring service model
+    # (like <tt>:singleton_deferred</tt>) or create the namespace via
+    # #namespace.
+    def namespace_define( name, opts={}, &block )
+      raise ArgumentError, "block expected" unless block
+      namespace( name, opts ) { |ns| ns.define( &block ) }
+      self[name]
     end
 
     # Describe a new interceptor to use that will intercept method calls

data/lib/needle/registry.rb

@@ -28,7 +28,7 @@ module Needle
 
   # Registry is a specialization of Container, with additional functionality
   # for bootstrapping basic services into a new registry. It also supports a
-  # #new! method for easily registering new services.
+  # #define! method for easily registering new services.
   #
   # Usage:
   #
@@ -41,34 +41,41 @@ module Needle
   #   bar = registry.bar
   class Registry < Container
 
-    # This is the default name given to a registry. If you have multiple
-    # independent registries in the same application, it can help to given them
-    # each names. By default, the name is empty.
-    DEFAULT_REGISTRY_NAME = ""
-
     # Instantiate a new Registry (via #new) and immediately invoke #define!
     # using the given block.
     #
     # Usage:
     #
-    #   registry = Needle::Registry.new! do
+    #   registry = Needle::Registry.define! do
     #     add { Adder.new }
     #     ...
     #   end
     #
     #   adder = registry.add
-    def self.new!( *parms, &block )
+    def self.define!( *parms, &block )
       raise NeedleError, "needs a block" if block.nil?
       new( *parms ) { |reg| reg.define!( &block ) }
     end
 
-    # Instantiate a new Registry. If the first parameter is a string, it will
-    # be used as the name of this registry. If the next parameter is a Hash,
-    # it will be used as the options to use when bootstrapping the registry.
+    # Instantiate a new Registry (via #new) and immediately invoke #define
+    # using the given block.
+    #
+    # Usage:
+    #
+    #   registry = Needle::Registry.define do |b|
+    #     b.add { Adder.new }
+    #     ...
+    #   end
     #
-    # The options hash may include options used to initialize the logger
-    # factory. The logger factory options should be in another hash, keyed
-    # by the value <tt>:logs</tt>.
+    #   adder = registry.add
+    def self.define( *parms, &block )
+      raise NeedleError, "needs a block" if block.nil?
+      new( *parms ) { |reg| reg.define( &block ) }
+    end
+
+    # Instantiate a new Registry. The options hash may include options
+    # used to initialize the logger factory. The logger factory options
+    # should be in another hash, keyed by the value <tt>:logs</tt>.
     #
     # If a block is given, the constructed registry instance is yielded to it.
     #
@@ -87,25 +94,15 @@ module Needle
     #   registry = Needle::Registry.new(
     #     :logs => { :filename => "/dev/null" }
     #   )
-    def initialize( *parms )
-      raise ArgumentError, "expected <= 2 arguments" if parms.length > 2
-      name = ( parms.first.is_a?( String ) ? parms.shift :
-        DEFAULT_REGISTRY_NAME )
-      opts = ( parms.first.is_a?( Hash ) ? parms.shift : {} )
-
-      if parms.length > 0
-        raise ArgumentError, "invalid parameter(s): #{parms.inspect}"
-      end
-
-      super( nil, name )
+    def initialize( opts={} )
+      super( nil, nil )
       bootstrap( opts )
-
       yield( self ) if block_given?
     end
 
-    # Return the name of this registry, enclosed in square braces.
+    # Returns +nil+. Registries are unnamed containers.
     def fullname
-      "[#{super}]"
+      nil
     end
 
     # Bootstraps the pipeline elements, service models, logger factory, and

data/lib/needle/service-point.rb

@@ -73,7 +73,12 @@ module Needle
     # name, its container's name, and all of its container's ancestors' names
     # concatenated together with dot characters, i.e. "one.two.three".
     def fullname
-      "#{@container.fullname}.#{@name}"
+      container_name = @container.fullname
+      if container_name
+        "#{container_name}.#{@name}"
+      else
+        @name.to_s
+      end
     end
 
     # Adds the given interceptor definition to this service point. The

data/lib/needle/version.rb

@@ -18,7 +18,7 @@ module Needle
   module Version
 
     MAJOR = 0
-    MINOR = 6
+    MINOR = 9
     TINY  = 0
     
     # The version of the Needle library in use.

data/test/models/model_test.rb

@@ -30,6 +30,10 @@ class ModelTest_MockService
     @init_result = :initialized
   end
 
+  def custom_init
+    @init_result = :custom
+  end
+
 end
 
 module ModelTest
@@ -65,7 +69,7 @@ module ModelTest
     def assert_threaded
       define_method( :extra_setup ) do
         cache = Thread.current[:threaded_services]
-        cache.delete "[].test" if cache
+        cache.delete "test" if cache
       end
 
       define_method( :test_multiplicity_singlethread ) do
@@ -109,10 +113,26 @@ module ModelTest
     end
 
     def assert_init
+      if instance_methods.include?( "extra_setup" )
+        save_setup = instance_method( :extra_setup )
+      end
+
+      define_method( :extra_setup ) do
+        save_setup.bind( self ).call if save_setup
+        @registry.register( :test_init, :model=>self.class.model,
+          :init_method=>:custom_init
+        ) { ModelTest_MockService.new }
+      end
+
       define_method( :test_initialize ) do
         o = @registry[ :test ]
         assert_equal :initialized, o.init_result
       end
+
+      define_method( :test_custom_initialize ) do
+        o = @registry[ :test_init ]
+        assert_equal :custom, o.init_result
+      end
     end
   end
 

data/test/tc_container.rb

@@ -146,7 +146,7 @@ class TC_Container < Test::Unit::TestCase
 
     container.define do |b|
       b.test( :pipeline=>[] ) { Hash.new }
-      b.namespace :subitem, :pipeline=>[] do |b2|
+      b.namespace_define :subitem, :pipeline=>[] do |b2|
         b2.test2( :pipeline=>[] ) { Hash.new }
       end
     end
@@ -192,6 +192,33 @@ class TC_Container < Test::Unit::TestCase
     assert_instance_of Needle::Container, container.test2
   end
 
+  def test_namespace_define
+    container = Needle::Container.new
+    container.namespace_define( :test, :pipeline=>[] ) do |b|
+      b.item( :pipeline=>[] ) { Hash.new }
+    end
+    assert container.has_key?( :test )
+    assert container.test.has_key?( :item )
+  end
+
+  def test_namespace_define!
+    container = Needle::Container.new
+    container.namespace_define!( :test, :pipeline=>[] ) do
+      item( :pipeline=>[] ) { Hash.new }
+    end
+    assert container.has_key?( :test )
+    assert container.test.has_key?( :item )
+  end
+
+  def test_namespace!
+    container = Needle::Container.new
+    container.namespace!( :test, :pipeline=>[] ) do
+      item( :pipeline=>[] ) { Hash.new }
+    end
+    assert container.has_key?( :test )
+    assert container.test.has_key?( :item )
+  end
+
   def test_has_key
     container = Needle::Container.new
 

data/test/tc_registry.rb

@@ -31,16 +31,33 @@ class TC_Registry < Test::Unit::TestCase
     assert_equal 12, @registry.service_models.length
   end
 
-  def test_new_no_options!
-    reg = Needle::Registry.new! do
+  def test_define_no_options
+    reg = Needle::Registry.define do |b|
+      b.svc1 { Object.new }
+    end
+
+    assert_respond_to reg, :svc1
+  end
+
+  def test_define_with_options
+    reg = Needle::Registry.define( :logs => { :device => STDOUT } ) do |b|
+      b.svc1 { Object.new }
+    end
+
+    assert_respond_to reg, :svc1
+    assert_equal STDOUT, reg.logs.device
+  end
+
+  def test_define_no_options!
+    reg = Needle::Registry.define! do
       svc1 { Object.new }
     end
 
     assert_respond_to reg, :svc1
   end
 
-  def test_new_with_options!
-    reg = Needle::Registry.new!( :logs => { :device => STDOUT } ) do
+  def test_define_with_options!
+    reg = Needle::Registry.define!( :logs => { :device => STDOUT } ) do
       svc1 { Object.new }
     end
 
@@ -66,7 +83,7 @@ class TC_Registry < Test::Unit::TestCase
   end
 
   def test_fullname
-    assert_equal "[]", @registry.fullname
+    assert_nil @registry.fullname
   end
 
 end

data/test/tc_service_point.rb

@@ -91,6 +91,15 @@ class TC_ServicePoint < Test::Unit::TestCase
     end
   end
 
+  def test_instance_with_explicit_pipeline_class
+    point =
+      Needle::ServicePoint.new( @container, "test", :pipeline => [ Model ] ) {
+        Hash.new }
+
+    inst = point.instance
+    assert_instance_of Hash, inst
+  end
+
   def test_instance
     point =
       Needle::ServicePoint.new( @container, "test", :model => :mock ) {

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.1
 specification_version: 1
 name: needle
 version: !ruby/object:Gem::Version 
-  version: 0.6.0
-date: 2004-10-21
+  version: 0.9.0
+date: 2004-10-28
 summary: Needle is a Dependency Injection/Inversion of Control container for Ruby. It supports both type-2 (setter) and type-3 (constructor) injection. It takes advantage of the dynamic nature of Ruby to provide a rich and flexible approach to injecting dependencies.
 require_paths: 
   - lib
@@ -30,6 +30,7 @@ files:
   - benchmarks/interceptors.rb
   - benchmarks/instantiability.rb
   - benchmarks/interceptors2.rb
+  - doc/faq
   - doc/README
   - doc/LICENSE-RUBY
   - doc/di-in-ruby.rdoc
@@ -38,6 +39,8 @@ files:
   - doc/LICENSE-BSD
   - doc/LICENSE-GPL
   - doc/manual
+  - doc/faq/faq.yml
+  - doc/faq/faq.rb
   - doc/manual-html/manual.css
   - doc/manual-html/chapter-1.html
   - doc/manual-html/chapter-2.html
@@ -46,6 +49,7 @@ files:
   - doc/manual-html/chapter-5.html
   - doc/manual-html/chapter-6.html
   - doc/manual-html/chapter-7.html
+  - doc/manual-html/chapter-8.html
   - doc/manual-html/index.html
   - doc/images/di_classdiagram.jpg
   - doc/manual/manual.css
@@ -58,13 +62,18 @@ files:
   - doc/manual/manual.rb
   - doc/manual/parts/02_namespaces.txt
   - doc/manual/parts/01_support.txt
+  - doc/manual/parts/03_locator.txt
   - doc/manual/parts/02_services.txt
+  - doc/manual/parts/04_setup.txt
   - doc/manual/parts/01_alternatives.txt
+  - doc/manual/parts/04_overview.txt
   - doc/manual/parts/01_what_is_needle.txt
+  - doc/manual/parts/03_overview.txt
   - doc/manual/parts/02_creating.txt
   - doc/manual/parts/01_license.txt
   - doc/manual/parts/01_use_cases.txt
   - doc/manual/parts/02_overview.txt
+  - doc/manual/parts/03_conventional.txt
   - lib/needle.rb
   - lib/needle
   - lib/needle/interceptor.rb