needle 1.2.0 → 1.2.1

data/doc/manual/parts/interceptors_custom.txt

@@ -2,24 +2,24 @@ Creating your own interceptors is very easy. As was demonstrated earlier, you ca
 
 An interceptor factory can be any object, as long as it implements the method @#new@ with two parameters, the _service point_ (service "definition") of the service that the interceptor will be bound to, and a hash of the options that were passed to the interceptor when it was attached to the service. This method should then return a new interceptor instance, which must implement the @#process@ method. The @#process@ method should accept two parameters: an object representing the _chain_ of interceptors, and the invocation _context_.
 
-<pre>
-  class MyInterceptorFactory
-    def initialize( point, options )
-      ...
-    end
+{{{lang=ruby,number=true,caption=Custom interceptor example
+class MyInterceptorFactory
+  def initialize( point, options )
+    ...
+  end
 
-    def process( chain, context )
-      # context.sym   : the name of the method that was invoked
-      # context.args  : the array of arguments passed to the method
-      # context.block : the block passed to the method, if any
-      # context.data  : a hash that may be used to share data between interceptors
-      return context.process_next( context )
-    end
+  def process( chain, context )
+    # context.sym   : the name of the method that was invoked
+    # context.args  : the array of arguments passed to the method
+    # context.block : the block passed to the method, if any
+    # context.data  : a hash that may be used to share data between interceptors
+    return context.process_next( context )
   end
-</pre>
+end
+}}}
 
 Once you've created your factory, you can attach it to a service:
 
-<pre>
-  reg.intercept( :foo ).with { MyInterceptorFactory }
-</pre>
+{{{lang=ruby,caption=Attaching a custom interceptor
+reg.intercept( :foo ).with { MyInterceptorFactory }
+}}}

data/doc/manual/parts/interceptors_ordering.txt

@@ -4,10 +4,10 @@ You can specify a different ordering of the interceptors by giving each one a _p
 
 You can specify the priority as an option when attaching an interceptor:
 
-<pre>
-  reg.register( :foo ) { ... }
-  reg.intercept( :foo ).with { Something }.with_options( :priority => 100 )
-  reg.intercept( :foo ).with { SomethingElse }.with_options( :priority => 50 )
-</pre>
+{{{lang=ruby,number=true,caption=Setting interceptor priorities
+reg.register( :foo ) { ... }
+reg.intercept( :foo ).with { Something }.with_options( :priority => 100 )
+reg.intercept( :foo ).with { SomethingElse }.with_options( :priority => 50 )
+}}}
 
 Without the priorities, when a method of @:foo@ was invoked, Something would be called first, and then SomethingElse. _With_ the priorities (as specified), SomethingElse would be called before Something (since SomethingElse has a lower priority).

data/doc/manual/parts/libraries_creating.txt

@@ -2,28 +2,28 @@ This centralization is implemented by creating a module for each library you wan
 
 For example, if I had a library of cryptographic routines and I wanted to make them accessible as Needle services, I would create a module to contain the service definitions. Typically, this module will be defined in a file called "services.rb", although you can certainly name it whatever you like.
 
-<pre>
-  module Crypto
-    
-    def register_services( container )
-      container.namespace_define( :crypto ) do |b|
-        b.prng do
-          require 'crypto/prng'
-          PRNG.new
-        end
-
-        b.des do
-          require 'crypto/des'
-          DES.new
-        end
+{{{lang=ruby,number=true,caption=Needle-enabled library example
+module Crypto
+  
+  def register_services( container )
+    container.namespace_define( :crypto ) do |b|
+      b.prng do
+        require 'crypto/prng'
+        PRNG.new
+      end
 
-        ...
+      b.des do
+        require 'crypto/des'
+        DES.new
       end
-    end
-    module_function :register_services
 
+      ...
+    end
   end
-</pre>
+  module_function :register_services
+
+end
+}}}
 
 Notice that there are no explicit dependencies on Needle, only on the interfaces Needle publishes. Thus, third-parties can add service configuration modules to their libraries without introducing dependencies on Needle.
 

data/doc/manual/parts/libraries_using.txt

@@ -1,31 +1,31 @@
 Using the libraries is as simple as requiring the file that has the service definitions, and then invoking the @#register_services@ module function:
 
-<pre>
-  require 'needle'
+{{{lang=ruby,number=true,caption=Example of using a Needle-enabled library
+require 'needle'
 
-  reg = Needle::Registry.new
-  reg.define do |b|
-    b.foo { Foo.new }
+reg = Needle::Registry.new
+reg.define do |b|
+  b.foo { Foo.new }
 
-    require 'crypto/services'
-    Crypto.register_services( reg )
-  end
+  require 'crypto/services'
+  Crypto.register_services( reg )
+end
 
-  prng = reg.crypto.prng
-</pre>
+prng = reg.crypto.prng
+}}}
 
 To make this easier, the Container class has a convenience method named @#require@:
 
-<pre>
-  require 'needle'
+{{{lang=ruby,number=true,caption=Example of using Container#require
+require 'needle'
 
-  reg = Needle::Registry.new
-  reg.define do |b|
-    b.foo { Foo.new }
-    b.require 'crypto/services', "Crypto"
-  end
+reg = Needle::Registry.new
+reg.define do |b|
+  b.foo { Foo.new }
+  b.require 'crypto/services', "Crypto"
+end
 
-  prng = reg.crypto.prng
-</pre>
+prng = reg.crypto.prng
+}}}
 
 The @Container#require@ method will require the file, and then look for a @#register_services@ method of the named module. It will execute that method, passing the container as an argument.

data/doc/manual/parts/logging_configuration.txt

@@ -12,19 +12,19 @@ You can configure the LogFactory when you create the registry by passing a hash
 
 By default, the filename is "./needle.log", and the roll_size is one megabyte. The default level is @:debug@. If you wanted to specify a different filename and default level of @:warn@, you could do:
 
-<pre>
-  reg = Needle::Registry.new(
-    :logs => {
-      :filename => "./my-app.log",
-      :default_level => :warn }
-  )
-</pre>
+{{{lang=ruby,number=true,caption=Configuring the loggers
+reg = Needle::Registry.new(
+  :logs => {
+    :filename => "./my-app.log",
+    :default_level => :warn }
+)
+}}}
 
 Alternatively, you can easily put the logging configuration in a YAML file and read it in, like so:
 
-<pre>
-  require 'yaml'
-  reg = Needle::Registry.new(
-    :logs => YAML.load( File.read( "log-conf.yml" ) )
-  )
-</pre>
+{{{lang=ruby,number=true,caption=Configuring the loggers from a YAML file
+require 'yaml'
+reg = Needle::Registry.new(
+  :logs => YAML.load( File.read( "log-conf.yml" ) )
+)
+}}}

data/doc/manual/parts/logging_logfactory.txt

@@ -1,14 +1,14 @@
 The LogFactory is available as a service, so that any component that needs a logger instance can gain easy access to one. The factory's service name is @:logs@.
 
-<pre>
-  factory = reg.logs
-</pre>
+{{{lang=ruby,caption=Accessing the LogFactory service
+factory = reg.logs
+}}}
 
 You obtain logger instances from the factory by passing a logger name to @#get@:
 
-<pre>
-  logger = reg.logs.get "a logger name"
-</pre>
+{{{lang=ruby,caption=Getting a named logger instance
+logger = reg.logs.get "a logger name"
+}}}
 
 Subsequent calls to @#get@ will return the same logger instance for the given logger name.
 
@@ -16,25 +16,24 @@ h3. Loggers for Services
 
 Typically, you'll use this to assign a logger instance to a service when it is constructed. In that case, the name of the logger is the fully-qualified name of the service:
 
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.logs.get( p.fullname ) )
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Getting a logger for a service
+reg.register( :foo ) do |c,p|
+  Foo.new( c.logs.get( p.fullname ) )
+end
+}}}
 
 As a convenience, if the value passed to @#get@ responds to either @fullname@ or @name@, the return value of that message will be used as the name. Thus, you can do the following:
 
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.logs.get( p ) )
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Getting a logger for a service (simplified)
+reg.register( :foo ) do |c,p|
+  Foo.new( c.logs.get( p ) )
+end
+}}}
 
 As a further convenience, there is a @:log_for@ service that is parameterized. Just pass the name of the log to retreive (or the service point instance) and it will return the log handle directly:
 
-<pre>
-  reg.register( :foo ) do |c,p|
-    Foo.new( c.log_for( p ) )
-  end
-</pre>
-
+{{{lang=ruby,number=true,caption=Getting a logger for a service (simplified further)
+reg.register( :foo ) do |c,p|
+  Foo.new( c.log_for( p ) )
+end
+}}}

data/doc/manual/parts/models_models.txt

@@ -2,7 +2,7 @@ Specifying an entire pipeline for every service point can be tedious. For that r
 
 h3. Standard Service Models:
 
-table{border: 1px solid black}.
+table(list).
 |_<. Name|_<. Pipeline|_<. Effect|
 |^. @:multiton@|^. @:multiton@|The returned value will be unique for each unique parameter set given to the service.|
 |^. @:multiton_deferred@|^. @:multiton@, @:deferred@|As @:multiton@, but a proxy is returned, deferring the instantiation of the service itself until a method is invoked on it.|
@@ -25,15 +25,15 @@ h3. Specifying a Service Model
 
 You specify the service model by passing the @:model@ option when you register a service. (You must only specify _either_ the model, _or_ the pipeline, but not both.)
 
-<pre>
-  reg.register( :foo, :model => :singleton_deferred ) {...}
-</pre>
+{{{lang=ruby,caption=Specifying a service model
+reg.register( :foo, :model => :singleton_deferred ) {...}
+}}}
 
 h3. Defining New Models
 
 You can create your own service models by adding the corresponding pipelines to the @:service_models@ service:
 
-<pre>
-  reg.service_models[ :my_service_model ] = [ :singleton, :my_pipeline_element ]
-  reg.register( :foo, :model => :my_service_model ) {...}
-</pre>
+{{{lang=ruby,number=true,caption=Defining a custom model
+reg.service_models[ :my_service_model ] = [ :singleton, :my_pipeline_element ]
+reg.register( :foo, :model => :my_service_model ) {...}
+}}}

data/doc/manual/parts/models_overview.txt

@@ -1,3 +1,3 @@
-Service models are the mechanism by which a client can specify how the lifecycle of a particular service should be managed. By default, all services are managed as _singletons_, but it is a simple matter to choose a different behavior when a service is registered.
+Service models are the mechanism by which a client can specify how the lifestyle of a particular service should be managed. By default, all services are managed as _singletons_, but it is a simple matter to choose a different behavior when a service is registered.
 
 Underneath, service models are implemented using an _instantiation pipeline_.

data/doc/manual/parts/models_pipelines.txt

@@ -1,10 +1,10 @@
 An _instantiation pipeline_ is a sequence of elements, each of which knows how to perform some aspect of the instantiation of a service.
 
-Every service consists of at least one instantiation element--the block that was given when the service was registered. Other elements may be combined with this block to enforce various aspects of lifecycle management, such as _multiplicity_ (singleton vs. prototype) and _laziness_ (deferred vs. immediate instantiation).
+Every service consists of at least one instantiation element--the block that was given when the service was registered. Other elements may be combined with this block to enforce various aspects of lifestyle management, such as _multiplicity_ (singleton vs. prototype) and _laziness_ (deferred vs. immediate instantiation).
 
 h3. Standard Pipeline Elements
 
-There are five standard pipeline elements available in Needle (although you may certainly create your own):
+There are six standard pipeline elements available in Needle (although you may certainly create your own):
 
 * @deferred@: this will always return a proxy that wraps subsequent pipeline elements, causing the subsequent elements to be executed only when a method is invoked on the proxy (at which point the method is then delegated to the resulting service).
 * @initialize@: this will invoke a method on the resulting service (defaults to @initialize_service@, though it can be changed). It is used for doing final initialization of services (for services that need it).
@@ -23,20 +23,20 @@ h3. Custom Pipeline Elements
 
 Creating new pipeline elements simple. Just create a new class that extends @Needle::Pipeline::Element@. Set the default pipeline priority (using the @#set_default_priority@ class method), and then implement the @#call@ method (accepting at least two parameters: the container and the service point).
 
-<pre>
-  require 'needle/pipeline/element'
-
-  class MyPipelineElement < Needle::Pipeline::Element
-    set_default_priority 50
-    
-    def call( container, point, *args )
-      ...
-      result = succ.call( container, point, *args )
-      ...
-      return result
-    end
+{{{lang=ruby,number=true,caption=Custom pipeline element example
+require 'needle/pipeline/element'
+
+class MyPipelineElement < Needle::Pipeline::Element
+  set_default_priority 50
+  
+  def call( container, point, *args )
+    ...
+    result = succ.call( container, point, *args )
+    ...
+    return result
   end
-</pre>
+end
+}}}
 
 To invoke the next element of the pipeline, just invoke @#succ.call(...)@.
 
@@ -48,9 +48,9 @@ h3. Added Pipelines Elements to Services
 
 You can specify the pipeline elements to use for a service via the @:pipeline@ option. This must refer to an array, each element of which must be either a symbol (in which case it references an element of the @:pipeline_elements@ service), or a class (in which case it must implement the interface required by @Needle::Pipeline::Element).
 
-<pre>
-  reg.register( :foo, :pipeline => [ :singleton, MyPipelineElement ] ) { ... }
-</pre>
+{{{lang=ruby,caption=Adding pipelines to services
+reg.register( :foo, :pipeline => [ :singleton, MyPipelineElement ] ) { ... }
+}}}
 
 The elements will be sorted based on their priorities, with lower priorities sorting closer to the instantiation block, and higher priorities sorting closer to the client.
 
@@ -58,7 +58,7 @@ h3. Making Custom Pipeline Elements Available
 
 You can make your custom pipeline elements available (so they can be referenced by symbol, instead of class name) by adding them to the @:pipeline_elements@ service:
 
-<pre>
-  reg.pipeline_elements[ :my_pipeline_element ] = MyPipelineElement
-  reg.register( :foo, :pipeline => [ :singleton, :my_pipeline_element ] ) { ... }
-</pre>
+{{{lang=ruby,number=true,caption=Publishing custom pipeline elements
+reg.pipeline_elements[ :my_pipeline_element ] = MyPipelineElement
+reg.register( :foo, :pipeline => [ :singleton, :my_pipeline_element ] ) { ... }
+}}}

data/doc/manual/{manual.css → stylesheets/manual.css}

@@ -87,8 +87,8 @@ a:hover {
 }
 
 #navigation ul, #navigation ol {
-  margin-left: 1.5em;
-  padding-left: 1.5em;
+  margin-left: 1.2em;
+  padding-left: 1.2em;
 }
 
 #navigation .license {
@@ -107,12 +107,6 @@ a:hover {
   text-align: justify;
 }
 
-#content pre {
-  background: #FFE;
-  border: 1px dotted #AAA;
-  padding: 1em;
-}
-
 #content h1 {
   background: #005;
   color: #FFF;
@@ -186,7 +180,86 @@ a:hover {
   text-align: center;
 }
 
-table.list td {
-  border-bottom: 1px dotted #005;
+table.list {
+  margin: 2em;
+  border: 1px solid black;
+  background: #FFD;
+  padding: 0px;
+  border-spacing: 0px;
+}
+
+table.list th {
+  border-bottom: 1px solid #005;
   padding-bottom: 5px;
+  background: #008;
+  color: white;
+  padding: 0.5em;
+  text-align: left;
+}
+
+table.list td {
+  padding: 0.2em;
+  text-align: left;
+  vertical-align: top;
+  border-bottom: 1px solid;
+}
+
+.prevnext {
+  padding: 0.5em 1em 0.5em 1em;
+  background: #557;
+  color: #FFF;
+  font-size: small;
+  font-weight: bold;
+  border: 1px solid #000;
+}
+
+.prevnext a {
+  color: #FF0;
+}
+
+.top .prevnext {
+  margin: 0 0 1em 0;
+  text-align: left;
+}
+
+.bottom .prevnext {
+  margin: 1em 0 0 0;
+  text-align: right;
+}
+
+.figure {
+  border: 1px solid black;
+  line-height: normal;
+  background: #FFD;
+  margin: 2em;
+}
+
+.figure .caption {
+  background: #008;
+  color: white;
+  font-weight: bold;
+  font-size: small;
+  padding: 4px 24px 4px 8px;
+  margin-left: -4px;
+  border: 1px dotted #77F;
+}
+
+.figure .body {
+  padding-left: 1em;
+}
+
+.figure pre {
+  padding: 0px;
+  background: transparent;
+  border: none;
+  font-size: small;
+  font-family: mono;
+}
+
+.figure .lineno {
+  text-align: right;
+  color: #B00;
+  font-family: mono;
+  font-size: small;
+  padding-right: 1em;
 }