needle 0.5.0 → 0.6.0

data/doc/manual-html/chapter-2.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>
@@ -177,7 +179,27 @@
   registry = Needle::Registry.new
 </pre>
 
-	<p>Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.<br />
+	<p>Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.</p>
+
+	<p>Alternatively, you can pass a block to <code>#new</code>:</p>
+
+<pre>
+  registry = Needle::Registry.new do |r|
+    ...
+  end
+</pre>
+
+	<p>The parameter to the block will be a reference to the registry. This allows you to register services with the registry as soon as it is created.</p>
+
+	<p>One other convenience method is <code>#new!</code>:</p>
+
+<pre>
+  registry = Needle::Registry.new! do
+    ...
+  end
+</pre>
+
+	<p>This block accepts no parameters, and evaluates the block as if it were passed to <code>Registry#define!</code> (see below).<br />
 </p>
    </div>
 
@@ -211,17 +233,29 @@
 
 	<h3>Convenience Methods</h3>
 
-	<p>Because you will often need to register many services with a registry at once, a convenience method has been provided to make this use case lean and mean. Just call <code>registry!</code>, passing a block that accepts no parameters. This block will be evaluated in a new context, with any unrecognized method call being interpreted as a new service registration of that name:</p>
+	<p>Because you will often need to register many services with a registry at once, two convenience methods have been provided to make this use case lean and mean.</p>
+
+	<p>The first is <code>define</code>. Just pass a block to define that accepts one parameter. This parameter will be a &#8220;builder&#8221; object that allows you to define services just by sending them as messages to the builder:</p>
+
+<pre>
+  registry.define do |b|
+    b.foo { Bar.new }
+    b.bar { Foo.new }
+    ...
+  end
+</pre>
+
+	<p>Alternative, you can call <code>define!</code>, passing a block that accepts no parameters. This block will be evaluated in the &#8220;builder&#8221; object&#8217;s context, with any unrecognized method call being interpreted as a new service registration of that name:</p>
 
 <pre>
-  registry.register! do
+  registry.define! do
     foo { Bar.new }
     bar { Foo.new }
     ...
   end
 </pre>
 
-	<p>The above will register two new services with the registry, <code>:foo</code> and <code>:bar</code>.</p>
+	<p>Both of the above will register two new services with the registry, <code>:foo</code> and <code>:bar</code>.</p>
 
 	<h3>Default Lifecycle</h3>
 
@@ -287,7 +321,7 @@
   end
 </pre>
 
-	<p>And, to mirror the <code>register!</code> method, there is also a <code>namespace!</code> method. This method creates a new namespace and then does a <code>register!</code> call on that namespace.</p>
+	<p>And, to mirror the <code>namespace</code> method, there is also a <code>namespace!</code> method. This method creates a new namespace and then does a <code>define!</code> call on that namespace.</p>
 
 <pre>
   registry.namespace! :stuff do

data/doc/manual-html/chapter-3.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/chapter-4.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/chapter-5.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/chapter-6.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/chapter-7.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/index.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Needle Version: <strong>0.5.0</strong><br />
-            Manual Last Updated: <strong>2004-10-15 03:41 GMT</strong>
+            Needle Version: <strong>0.6.0</strong><br />
+            Manual Last Updated: <strong>2004-10-21 16:17 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -41,9 +41,11 @@
                 
                   <li><a href="chapter-1.html#s2">How Can It Help Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">License Information</a></li>
+                  <li><a href="chapter-1.html#s3">Alternatives</a></li>
                 
-                  <li><a href="chapter-1.html#s4">Support</a></li>
+                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s5">Support</a></li>
                 
               </ol>
             </li>
@@ -161,6 +163,19 @@
 </p>
 
 
+  <p align="center"><strong>Recent Updates to This Manual</strong></p>
+  <table border='0' cellpadding='0' cellspacing='0' align='center'><tr><td>
+    <ul>
+      
+        <li>added Container#define</li>
+      
+        <li>renamed Container#register! to Container#define!</li>
+      
+        <li>added documentation of Container#new!</li>
+      
+    </ul>
+  </table>
+
 
 <p class="copyright">
   Copyright &copy; 2004

data/lib/needle/container.rb

@@ -30,13 +30,13 @@ module Needle
   # Container#namespace method to create new containers.
   class Container
 
-    # This class is used by the #register! and #namespace! methods to allow
+    # This class is used by the #define! and #namespace! methods to allow
     # an +instance_eval+'d block to create new service points simply by
     # invoking imaginary methods. It is basically an empty shell, with almost
     # all of the builtin methods removed from it. (This allows services like
     # "hash" and "print" to be defined, where they would normally conflict
     # with the Kernel methods of the same name.)
-    class RegistrationContext
+    class DefinitionContext
       ( private_instance_methods +
         protected_instance_methods +
         public_instance_methods -
@@ -45,24 +45,33 @@ module Needle
       ).
       each { |m| undef_method m }
 
-      # Create a new RegistrationContext that wraps the given container. All
+      # Create a new DefinitionContext that wraps the given container. All
       # operations performed on this context will be delegated to the
       # container.
       def initialize( container )
         @container = container
       end
 
+      # A way to access the container reference being operated on from within
+      # the context.
+      def this_container
+        @container
+      end
+
       # Delegate to Container#intercept.
       def intercept( name )
         @container.intercept( name )
       end
 
-      # Delegate to Container#namespace!. Note that this is an exception to the
-      # general rule regarding bang methods, since this (non-bang) method
-      # delegates to a bang-method. However, because this is typically called
-      # within the context of a bang method (like Container#register!), it felt
-      # redundant to have the bang here as well. Disagree? Let me know.
+      # Delegate to Container#namespace. Instead of passing the container to
+      # the new namespace, however, pass the definition context for the new
+      # container.
       def namespace( *parms, &block )
+        @container.namespace( *parms ) { |ns| block.call( ns.builder ) }
+      end
+
+      # Delegate to Container#namespace!.
+      def namespace!( *parms, &block )
         @container.namespace!( *parms, &block )
       end
 
@@ -96,6 +105,7 @@ module Needle
     # Create a new empty container with the given parent and name.
     def initialize( parent=nil, name=nil )
       @root = nil
+      @builder = nil
 
       @name = name
       @parent = parent
@@ -119,49 +129,66 @@ module Needle
       "#{@parent.fullname}.#{@name}"
     end
 
-    # Register the named service with the container. When the service is
-    # requested (with Container#[]), the associated callback will be used
-    # to construct it.
+    # Returns the DefinitionContext instance that can be used to "build"
+    # this container.
+    def builder
+      @builder ||= DefinitionContext.new( self )
+    end
+
+    # If a block is given, yields the container's builder instance to the
+    # block. Otherwise, simply returns the builder instance.
     #
     # Usage:
     #
-    #   container.register( :calc, :model=>:prototype ) do |c|
-    #     Calc.new( c.operations )
+    #   container.define do |b|
+    #     b.foo { Bar.new }
+    #     b.baz { Baz.new }
+    #     ...
     #   end
-    def register( name, opts={}, &callback )
-      raise ArgumentError, "expect block" unless callback
-      name = name.to_s.intern unless name.is_a?( Symbol )
-      @service_points[ name ] =
-        ServicePoint.new( self, name, opts, &callback )
+    #
+    # Or:
+    #
+    #   container.define.foo { Bar.new }
+    #   container.define.baz { Baz.new }
+    def define
+      yield builder if block_given?
+      builder
     end
 
-    # Create a new RegistrationContext around the container, and then evaluate
+    # Create a new DefinitionContext around the container, and then evaluate
     # the block within the new context instance (via +instance_eval+).
     #
     # Usage:
     #
-    #   container.register! do
+    #   container.define! do
     #     calc( :model => :prototype ) { Calc.new( operations ) }
     #   end
-    def register!( &block )
+    def define!( &block )
       raise ArgumentError, "block expected" unless block
-      ctx = RegistrationContext.new( self )
-      ctx.instance_eval( &block )
+      builder.instance_eval( &block )
       self
     end
 
-    # Create a new namespace within the container. Each parameter ought to
-    # be the name of a namespace. If more than one parameter is given,
-    # each one represents the name of a new namespace to create inside of
-    # the last-created namespace, unless that namespace already exists.
-    # This makes it work analogously to FileUtils#mkdir_p (creating new
-    # namespaces along a path of namespaces, as needed).
+    # Register the named service with the container. When the service is
+    # requested (with Container#[]), the associated callback will be used
+    # to construct it.
     #
-    # If a block is given, the latest namespace created is yielded to the
-    # block.
+    # Usage:
     #
-    # The last parameter may be a Hash, in which case it is used to specify
-    # options describing how the namespace should be created.
+    #   container.register( :calc, :model=>:prototype ) do |c|
+    #     Calc.new( c.operations )
+    #   end
+    def register( name, opts={}, &callback )
+      raise ArgumentError, "expect block" unless callback
+
+      name = name.to_s.intern unless name.is_a?( Symbol )
+      @service_points[ name ] =
+        ServicePoint.new( self, name, opts, &callback )
+    end
+
+    # Create a new namespace within the container, with the given name. If a
+    # block is provided, it will be invoked when the namespace is created,
+    # with the new namespace passed to it.
     #
     # For the curious, namespaces are simply services that are implemented
     # by Container.  The two statements are really identical:
@@ -169,46 +196,30 @@ module Needle
     #   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
+    # immediately, singleton instantiation is sufficient for 99% of the things
+    # you'll use namespaces for.)
+    #
     # Usage:
     #
-    #   container.namespace( :calc, :operations ) do |op|
+    #   container.namespace( :operations ) do |op|
     #     op.register( :add ) { Adder.new }
     #     ...
     #   end
     #
     #   adder = container.calc.operations.add
-    def namespace( *parms )
-      opts = {}
-      opts = parms.pop if parms.last.is_a?( Hash )
-
-      if parms.length < 1
-        raise ArgumentError, "you must specify at least one name"
+    def namespace( name, opts={}, &block )
+      register( name, opts ) do |c,p|
+        ns = Container.new( c, name )
+        block.call ns if block
+        ns
       end
-
-      container = self
-      parms.each do |parm|
-        unless container.has_key?( parm )
-          container.register( parm, opts ) { |c| Container.new( c, parm ) }
-        end
-
-        container = container[parm]
-      end
-
-      yield container if block_given?
     end
 
-    # Create a new namespace within the container. Each parameter ought to
-    # be the name of a namespace. If more than one parameter is given,
-    # each one represents the name of a new namespace to create inside of
-    # the last-created namespace, unless that namespace already exists.
-    # This makes it work analogously to FileUtils#mkdir_p (creating new
-    # namespaces along a path of namespaces, as needed).
-    #
-    # The last parameter may be a Hash, in which case it is used to specify
-    # options describing how the namespace should be created.
-    #
-    # The block is passed to the Container#register! method of the last
-    # namespace created.
+    # 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:
@@ -216,17 +227,22 @@ module Needle
     #   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
+    # immediately, singleton instantiation is sufficient for 99% of the things
+    # you'll use namespaces for.)
+    #
     # Usage:
     #
-    #   container.namespace!( :calc, :operations ) do
+    #   container.namespace!( :operations ) do
     #     add { Adder.new }
     #     ...
     #   end
     #
     #   adder = container.calc.operations.add
-    def namespace!( *parms, &block )
+    def namespace!( name, opts={}, &block )
       raise ArgumentError, "block expected" unless block
-      namespace( *parms ) { |ns| ns.register!( &block ) }
+      namespace( name, opts ) { |ns| ns.define!( &block ) }
     end
 
     # Describe a new interceptor to use that will intercept method calls
@@ -246,6 +262,21 @@ module Needle
       interceptor
     end
 
+    # Returns the pipeline object for the named service, which allows clients
+    # to explicitly manipulate the service's instantiation pipeline.
+    #
+    # Usage:
+    #
+    #   container.pipeline( :calc ).
+    #     add( :initialize ).
+    #     add( :custom ) { |me,*args| me.succ.call( *args ) }
+    def pipeline( name )
+      point = find_definition( name )
+      raise ServiceNotFound, "#{fullname}.#{name}" unless point
+
+      point.pipeline
+    end
+
     # Searches the current container and its ancestors for the named service.
     # If found, the service point (the definition of that service) is returned,
     # otherwise +nil+ is returned.
@@ -297,6 +328,13 @@ module Needle
     #   container.register( :add ) { Adder.new }
     #   p container.add == container[:add] # => true
     #
+    # This also allows you to register new services in the container by
+    # sending the container a message with an attached block.
+    #
+    # Usage:
+    #
+    #   container.foo { Bar.new }
+    #   p container.foo
     def method_missing( sym, *args, &block )
       if block.nil? && args.empty? && knows_key?( sym )
         self[sym]

data/{test/tc_models.rb → lib/needle/lifecycle/deferred.rb}

@@ -14,31 +14,25 @@
 # =============================================================================
 #++
 
-$:.unshift "../lib"
+require 'needle/pipeline/element'
+require 'needle/lifecycle/proxy'
 
-require 'needle/models'
-require 'test/unit'
+module Needle
+  module Lifecycle
 
-class TC_Models < Test::Unit::TestCase
+    # The instantiation pipeline element that implements deferred
+    # instantiation.
+    class Deferred < Needle::Pipeline::Element
 
-  class Registry < Hash
-    def register( name, opts={}, &callback )
-      self[name] = callback.call( self )
-    end
-  end
-
-  def test_register
-    registry = Registry.new
+      set_default_priority 50
 
-    Needle::Models.register( registry )
-    assert_equal 1, registry.length
-    assert registry.has_key?( :service_models )
+      # Returns a new proxy instance that wraps the next element of the
+      # instantiation pipeline.
+      def call( *args )
+        Proxy.new( succ, *args )
+      end
 
-    models = registry[:service_models]
+    end
 
-    assert_equal 4, models.length
-    assert_equal [:prototype, :prototype_deferred, :singleton, :singleton_deferred],
-      models.keys.sort {|a,b| a.to_s <=> b.to_s}
   end
-
 end

data/lib/needle/lifecycle/initialize.rb

@@ -0,0 +1,49 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Needle dependency injection
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Needle
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# needle website : http://needle.rubyforge.org
+# project website: http://rubyforge.org/projects/needle
+# =============================================================================
+#++
+
+require 'needle/pipeline/element'
+
+module Needle
+  module Lifecycle
+
+    # The instantiation pipeline element that implements calling a separate
+    # initialization method on the instantiated service. This should always be
+    # placed in the pipeline as close to the service implementation as possible
+    # (hence, the low default priority).
+    class Initialize < Needle::Pipeline::Element
+
+      set_default_priority -100
+
+      # Initialize the element. Looks at the options hash to determine the
+      # name of the initialization method to call, defaulting to
+      # <tt>:initialize_service</tt>.
+      def initialize_element
+        @init_method = options[:init_method] || :initialize_service
+      end
+
+      # Invokes the next element of the chain. If the result responds to the
+      # requested initialization method, that method is invoked on the
+      # result, and the result is returned.
+      def call( *args )
+        service = succ.call( *args )
+        service.send @init_method if service.respond_to?( @init_method )
+        service
+      end
+
+    end
+
+  end
+end