needle 1.2.0 → 1.2.1

data/doc/manual/parts/03_conventional.txt

@@ -1,29 +1,29 @@
 A conventional architecture will have each component instantiate its own dependencies. For example, the @Application@ would do something like this:
 
-<pre>
-  class Application
-    def initialize
-      @logger = Logger.new
-      @authenticator = Authenticator.new
-      @database = Database.new
-      @view = View.new
-      @session = Session.new
-    end
+{{{lang=ruby,number=true,caption=A conventional application implementation
+class Application
+  def initialize
+    @logger = Logger.new
+    @authenticator = Authenticator.new
+    @database = Database.new
+    @view = View.new
+    @session = Session.new
   end
-</pre>
+end
+}}}
 
 However, the above is already flawed, because the @Authenticator@ and the @Session@ both need access to the @Database@, so you really need to make sure you instantiate things in the right order and pass them as parameters to the constructor of each object that needs them, like so:
 
-<pre>
-  class Application
-    def initialize
-      @view = View.new
-      @logger = Logger.new
-      @database = Database.new( @logger )
-      @authenticator = Authenticator.new( @logger, @database )
-      @session = Session.new( @logger, @database )
-    end
+{{{lang=ruby,number=true,caption=A parameterized application implementation
+class Application
+  def initialize
+    @view = View.new
+    @logger = Logger.new
+    @database = Database.new( @logger )
+    @authenticator = Authenticator.new( @logger, @database )
+    @session = Session.new( @logger, @database )
   end
-</pre>
+end
+}}}
 
 The problem with this is that if you later decide that @View@ needs to access the database, you need to rearrange the order of how things are instantiated in the @Application@ constructor.

data/doc/manual/parts/03_locator.txt

@@ -1,40 +1,40 @@
 The _service locator_ pattern makes things a _little_ easier. Instead of instantiating everything in the constructor of the @Application@, you can create a factory method somewhere that returns the new @Application@ instance. Then, inside of this factory method, you assign each new object to collection, and pass that collection to each constructor.
 
-<pre>
-  require 'needle'
-
-  def create_application
-    locator = Needle::Registry.new
-
-    locator.register( :view ) { View.new(locator) }
-    locator.register( :logger ) { Logger.new(locator) }
-    locator.register( :database ) { Database.new(locator) }
-    locator.register( :authenticator ) {Authenticator.new(locator) }
-    locator.register( :session ) { Session.new(locator) }
-    locator.register( :app ) { Application.new(locator) }
-
-    locator[:app]
+{{{lang=ruby,number=true,caption=Service locator example
+require 'needle'
+
+def create_application
+  locator = Needle::Registry.new
+
+  locator.register( :view ) { View.new(locator) }
+  locator.register( :logger ) { Logger.new(locator) }
+  locator.register( :database ) { Database.new(locator) }
+  locator.register( :authenticator ) {Authenticator.new(locator) }
+  locator.register( :session ) { Session.new(locator) }
+  locator.register( :app ) { Application.new(locator) }
+
+  locator[:app]
+end
+
+class Application
+  def initialize( locator )
+    @view = locator[:view]
+    @logger = locator[:logger]
+    @database = locator[:database]
+    @authenticator = locator[:authenticator]
+    @session = locator[:session]
   end
+end
 
-  class Application
-    def initialize( locator )
-      @view = locator[:view]
-      @logger = locator[:logger]
-      @database = locator[:database]
-      @authenticator = locator[:authenticator]
-      @session = locator[:session]
-    end
+class Session
+  def initialize( locator )
+    @database = locator[:database]
+    @logger = locator[:logger]
   end
+end
 
-  class Session
-    def initialize( locator )
-      @database = locator[:database]
-      @logger = locator[:logger]
-    end
-  end
-
-  ...
-</pre>
+...
+}}}
 
 This has the benefit of allowing each object to construct itself _� la carte_ from the objects in the locator. Also, each object no longer cares what class implements each service--it only cares that each object implements the methods it will attempt to invoke on that object.
 
@@ -44,17 +44,17 @@ Thus, when we get the @:app@ service (on the last line), the @Application@ const
 
 In the interest of brevity, the @create_application@ could have been written like this, using a "builder" object (called @b@ in the example below) to help register the services:
 
-<pre>
-  def create_application
-    locator = Needle::Registry.define do |b|
-      b.view { View.new(locator) }
-      b.logger { Logger.new(locator) }
-      b.database { Database.new(locator) }
-      b.authenticator {Authenticator.new(locator) }
-      b.session { Session.new(locator) }
-      b.app { Application.new(locator) }
-    end
-
-    locator[:app]
+{{{lang=ruby,number=true,caption=Service locator example using #define
+def create_application
+  locator = Needle::Registry.define do |b|
+    b.view { View.new(locator) }
+    b.logger { Logger.new(locator) }
+    b.database { Database.new(locator) }
+    b.authenticator {Authenticator.new(locator) }
+    b.session { Session.new(locator) }
+    b.app { Application.new(locator) }
   end
-</pre>
+
+  locator[:app]
+end
+}}}

data/doc/manual/parts/04_overview.txt

@@ -6,4 +6,4 @@ The service locator works well when there are few dependencies, and the dependen
 
 # For deep dependency graphs, it can become cumbersome to have to pass the locator to each constructor.
 
-This is where _dependency injection_ comes in. It allows you to define how each service is initialized, including setting dependencies (either via constructor parameters or via property accessors). In fact, it can do a lot more than that, even allowing you to specify how the lifecycle of the service should be managed and hooking "interceptors" onto the service to filter method invocations.
+This is where _dependency injection_ comes in. It allows you to define how each service is initialized, including setting dependencies (either via constructor parameters or via property accessors). In fact, it can do a lot more than that, even allowing you to specify how the lifestyle of the service should be managed and hooking "interceptors" onto the service to filter method invocations.

data/doc/manual/parts/04_setup.txt

@@ -1,43 +1,43 @@
 Setting up for DI is very similar to the setup for a service locator, but instead of passing the locator (we'll call it a _registry_ now), we only pass (or set) the dependencies that the service itself needs.
 
-<pre>
-  require 'needle'
-
-  def create_application
-    registry = Needle::Registry.define do |b|
-      b.view          { View.new }
-      b.logger        { Logger.new }
-      b.database      { Database.new( b.logger ) }
-      b.authenticator { Authenticator.new(b.logger, b.database) }
-      b.session       { Session.new(b.logger, b.database) }
-
-      b.app do
-        app = Application.new
-        app.logger = b.logger
-        app.view = b.view
-        app.database = b.database
-        app.authenticator = b.authenticator
-        app.session = b.session
-        app
-      end
+{{{lang=ruby,number=true,caption=Dependency injection example
+require 'needle'
+
+def create_application
+  registry = Needle::Registry.define do |b|
+    b.view          { View.new }
+    b.logger        { Logger.new }
+    b.database      { Database.new( b.logger ) }
+    b.authenticator { Authenticator.new(b.logger, b.database) }
+    b.session       { Session.new(b.logger, b.database) }
+
+    b.app do
+      app = Application.new
+      app.logger = b.logger
+      app.view = b.view
+      app.database = b.database
+      app.authenticator = b.authenticator
+      app.session = b.session
+      app
     end
-
-    registry[:app]
   end
 
-  class Application
-    attr_writer :view, :logger, :database, :authenticator, :session
-  end
+  registry[:app]
+end
 
-  class Session
-    def initialize( logger, database )
-      @database = database
-      @logger = logger
-    end
+class Application
+  attr_writer :view, :logger, :database, :authenticator, :session
+end
+
+class Session
+  def initialize( logger, database )
+    @database = database
+    @logger = logger
   end
+end
 
-  ...
-</pre>
+...
+}}}
 
 The @create_application@ method is now (necessarily) a little more complex, since it now contains all of the initialization logic for each service in the application. However, look how much simpler this made the other classes, especially the @Application@ class.
 

data/doc/manual/parts/customizing_contexts.txt

@@ -4,21 +4,21 @@ The default implementation used for definition contexts is defined by the @:defi
 
 Consider the following contrived example, where you want to provide a convenient way to register services of type Hash.
 
-<pre>
-  class MyDefinitionContext < Needle::DefinitionContext
-    def register_hash( name, opts={} )
-      this_container.register( name, opts ) { Hash.new }
-    end
+{{{lang=ruby,number=true,caption=Custom DefinitionContext example
+class MyDefinitionContext < Needle::DefinitionContext
+  def register_hash( name, opts={} )
+    this_container.register( name, opts ) { Hash.new }
   end
+end
 
-  reg = Needle::Registry.new
-  reg.register( :definition_context_factory ) { MyDefinitionContext }
+reg = Needle::Registry.new
+reg.register( :definition_context_factory ) { MyDefinitionContext }
 
-  reg.define do |b|
-    b.register_hash( :test1 )
-    b.register_hash( :test2 )
-  end
+reg.define do |b|
+  b.register_hash( :test1 )
+  b.register_hash( :test2 )
+end
 
-  reg.test1[:key] = "value"
-  reg.test2[:foo] = "bar"
-</pre>
+reg.test1[:key] = "value"
+reg.test2[:foo] = "bar"
+}}}

data/doc/manual/parts/customizing_interceptors.txt

@@ -2,37 +2,37 @@ When you attach an interceptor to a service, that new interceptor is wrapped in
 
 It is this wrapper object that allows interceptor definitions to be done using method chaining:
 
-<pre>
-  reg.intercept( :foo ).with { ... }.with_options(...)
-</pre>
+{{{lang=ruby,caption=Configuring an interceptor
+reg.intercept( :foo ).with { ... }.with_options(...)
+}}}
 
 If you wish to add custom, domain-specific functionality to the interceptor wrapper, you can register your own implementation of the @:interceptor_impl_factory@. Consider the following contrived example, where an "only_if" clause is given to determine when the interceptor should be invoked.
 
-<pre>
-  class OnlyIfInterceptor < Needle::Interceptor
-    def only_if( &block )
-      @only_if = block
-      self
-    end
+{{{lang=ruby,number=true,caption=Advanced configuration of an interceptor
+class OnlyIfInterceptor < Needle::Interceptor
+  def only_if( &block )
+    @only_if = block
+    self
+  end
 
-    def action
-      action_proc = super
-      lambda do |chain,ctx|
-        if @only_if.call( chain, ctx )
-          action_proc.call( chain, ctx )
-        else
-          chain.process_next( ctx )
-        end
+  def action
+    action_proc = super
+    lambda do |chain,ctx|
+      if @only_if.call( chain, ctx )
+        action_proc.call( chain, ctx )
+      else
+        chain.process_next( ctx )
       end
     end
   end
+end
 
-  reg = Needle::Registry.new
-  reg.register( :interceptor_impl_factory ) { OnlyIfInterceptor }
-  reg.register( :foo ) { Bar.new }
+reg = Needle::Registry.new
+reg.register( :interceptor_impl_factory ) { OnlyIfInterceptor }
+reg.register( :foo ) { Bar.new }
 
-  reg.intercept( :foo ).
-    with { |c| c.logging_interceptor }.
-    only_if { |ch,ctx| something_is_true( ch, ctx ) }.
-    with_options(...)
-</pre>
+reg.intercept( :foo ).
+  with { |c| c.logging_interceptor }.
+  only_if { |ch,ctx| something_is_true( ch, ctx ) }.
+  with_options(...)
+}}}

data/doc/manual/parts/customizing_namespaces.txt

@@ -4,21 +4,21 @@ You can specify your own custom implementation for namespaces by registering you
 
 Here's a contrived example. Suppose you want each namespace to keep track of the precise time that it was created.
 
-<pre>
-  class TimeTrackerNamespace < Needle::Container
-    attr_reader :birth_date
+{{{lang=ruby,number=true,caption=Custom namespace implementations
+class TimeTrackerNamespace < Needle::Container
+  attr_reader :birth_date
 
-    def initialize( *args )
-      super
-      @birth_date = Time.now
-    end
+  def initialize( *args )
+    super
+    @birth_date = Time.now
   end
+end
 
-  reg = Needle::Registry.new
-  reg.register( :namespace_impl_factory ) { TimeTrackerNamespace }
+reg = Needle::Registry.new
+reg.register( :namespace_impl_factory ) { TimeTrackerNamespace }
 
-  reg.namespace :hello
-  p reg.hello.birth_date
-</pre>
+reg.namespace :hello
+p reg.hello.birth_date
+}}}
 
 In general, you'll be better off having your custom implementation extend @Needle::Container@, although the only _real_ requirement is that your implementation publish the same interface as the default namespace implementation.

data/doc/manual/parts/interceptors_attaching.txt

@@ -8,37 +8,36 @@ An example is the LoggingInterceptor that ships with Needle. Because it is funct
 
 You can attach interceptor factories to your service using the @#interceptor(...).with {...}@ syntax:
 
-<pre>
-  reg.register( :foo ) {...}
-  reg.intercept( :foo ).with { MyInterceptorFactory }
-</pre>
+{{{lang=ruby,number=true,caption=Attaching an interceptor to a service
+reg.register( :foo ) {...}
+reg.intercept( :foo ).with { MyInterceptorFactory }
+}}}
 
 Note that you could also make the interceptor factory a service:
 
-<pre>
-  reg.register( :foo ) {...}
-  reg.register( :my_interceptor ) { MyInterceptorFactory }
-  reg.intercept( :foo ).with { |c| c.my_interceptor }
-</pre>
+{{{lang=ruby,number=true,caption=Attaching an service as an interceptor
+reg.register( :foo ) {...}
+reg.register( :my_interceptor ) { MyInterceptorFactory }
+reg.intercept( :foo ).with { |c| c.my_interceptor }
+}}}
 
 And, to make accessing interceptor services even more convenient, you can use the @#with!@ method (which executes its block within the context of the calling container):
 
-<pre>
-  reg.register( :foo ) {...}
-  reg.register( :my_interceptor ) { MyInterceptorFactory }
-  reg.intercept( :foo ).with! { my_interceptor }
-</pre>
-
+{{{lang=ruby,number=true,caption=Attaching an service as an interceptor via #with!
+reg.register( :foo ) {...}
+reg.register( :my_interceptor ) { MyInterceptorFactory }
+reg.intercept( :foo ).with! { my_interceptor }
+}}}
 
 h3. Blocks
 
 Sometimes creating an entire class to implement an interceptor is overkill. This is particularly the case during debugging or testing, when you might want to attach an interceptor to class to verify that a parameter passed is correct, or a return value is what you expect. To satisfy these conditions, you can using the
 @#doing@ method.  Just give it a block that accepts two parameters (the chain, and context) and you're good to go!
 
-<pre>
-  reg.register( :foo ) {...}
-  reg.intercept( :foo ).doing { |chain,ctx| ...; chain.process_next( ctx ) }
-</pre>
+{{{lang=ruby,number=true,caption=Defining interceptors on the fly
+reg.register( :foo ) {...}
+reg.intercept( :foo ).doing { |chain,ctx| ...; chain.process_next( ctx ) }
+}}}
 
 Note that this approach is about 40% slower than using an interceptor factory, so it should not be used if performance is an issue.
 
@@ -46,19 +45,19 @@ h3. Options
 
 Some interceptors can accept configuration options. For example, the LoggingInterceptor allows clients to specify methods that should and shouldn't be intercepted. Options are specified via the @#with_options@ method.
 
-<pre>
-  reg.register( :foo ) {...}
-  reg.intercept( :foo ).
-    with { |c| c.logging_interceptor }.
-    with_options( :exclude => [ "method1", "method2" ] )
-</pre>
+{{{lang=ruby,number=true,caption=Configuring interceptors
+reg.register( :foo ) {...}
+reg.intercept( :foo ).
+  with { |c| c.logging_interceptor }.
+  with_options( :exclude => [ "method1", "method2" ] )
+}}}
 
 Options can apply to the blocks given to the @#doing@ method, too. The block may access the options via the @#data[:options]@ member of the context:
 
-<pre>
-  reg.intercept( :foo ).
-    doing { |ch,ctx| ...; p ctx.data[:options][:value]; ... }.
-    with_options( :value => "hello" )
-</pre>
+{{{lang=ruby,number=true,caption=Configuring #doing interceptors
+reg.intercept( :foo ).
+  doing { |ch,ctx| ...; p ctx.data[:options][:value]; ... }.
+  with_options( :value => "hello" )
+}}}
 
 With blocks, of course, the value of such an approach is limited.