needle 0.5.0

data/doc/manual/manual.rb

@@ -0,0 +1,240 @@
+# --------------------------------------------------------------------------
+# Portions of this code were taken from the "poignant.rb" script created
+# by whytheluckystiff, which generates "Why's (Poignant) Guide to Ruby".
+# The original script may be obtained from the poignant CVS repository,
+# at http://poignant.rubyforge.org.
+#
+# This script is distributed under the by-sa/1.0 Creative Commons license.
+# --------------------------------------------------------------------------
+
+require 'erb'
+require 'fileutils'
+require 'yaml'
+require 'redcloth'
+
+module Needle
+  module Manual
+
+    class Manual
+      attr_accessor :product, :meta, :chapters, :tutorials, :examples, :recent_updates
+
+      def Manual.load( file_name )
+        File.open( file_name ) { |file| YAML.load( file ) }
+      end
+    end
+
+    class Meta
+      attr_accessor :copyright, :author, :email
+    end
+
+    class Product
+      attr_accessor :name, :tagline, :version, :logo, :urls, :project
+    end
+
+    class Sidebar
+      attr_accessor :title, :content
+    end
+
+    class Chapter
+      attr_accessor :index, :title, :sections
+
+      def initialize( index, title, sections )
+        @index = index
+        @title = title
+
+        section_index = 0
+        @sections = ( sections || [] ).collect do |section|
+          section_index += 1
+          if section.respond_to? :keys
+            Section.new( section_index, section.keys.first, section.values.first )
+          else
+            section_index -= 1
+            Section.new( section_index, nil, section )
+          end
+        end
+      end
+
+      def page_title
+        "Chapter #{index}: #{title}"
+      end
+    end
+
+    class Tutorial
+      attr_accessor :index, :title, :brief, :intro, :steps, :summary
+
+      def initialize( index, title, brief, intro, steps, summary )
+        @index = index
+        @title = title
+        @brief = RedCloth.new( brief )
+        @intro = RedCloth.new( intro ) if intro
+        @summary = RedCloth.new( summary ) if summary
+        @steps = steps.map { |step| RedCloth.new( step ) }
+      end
+
+      def page_title
+        "Tutorial #{index}: #{title}"
+      end
+    end
+
+    class Example
+      attr_accessor :index, :title, :brief, :intro, :design, :implementation, :summary
+
+      def initialize( index, title, brief, intro, design, implementation, summary )
+        @index = index
+        @title = title
+        @brief = RedCloth.new( brief )
+        @intro = RedCloth.new( intro )
+        @design = RedCloth.new( design )
+        @implementation = RedCloth.new( implementation )
+        @summary = RedCloth.new( summary )
+      end
+
+      def page_title
+        "Example #{index}: #{title}"
+      end
+    end
+
+    class Section
+      attr_accessor :index, :title, :content
+
+      def initialize( index, title, content )
+        @index = index
+        @title = RedCloth.new( title ).to_html.gsub( %r{</?p>}, "" ) if title
+        @content = RedCloth.new( content )
+      end
+    end
+
+    YAML.add_private_type( 'file' ) { |type_id, value| File.read( value ) }
+    YAML.add_private_type( 'eval' ) { |type_id, value| eval( value ) }
+
+    YAML.add_domain_type( 'jamisbuck.org,2004', 'manual' ) do |taguri, val|
+      index = 0
+
+      val['chapters'].collect! do |chapter|
+        index += 1
+        Chapter.new( index, chapter.keys.first, chapter.values.first )
+      end
+
+      index = 0
+      ( val['tutorials'] ||= [] ).collect! do |tutorial|
+        index += 1
+        content = tutorial.values.first
+        Tutorial.new( index, tutorial.keys.first, content['brief'], content['intro'],
+                      content['steps'], content['summary'] )
+      end
+
+      index = 0
+      ( val['examples'] ||= [] ).collect! do |example|
+        index += 1
+        content = example.values.first
+        Example.new( index, example.keys.first, content['brief'], content['intro'], content['design'],
+                     content['implementation'], content['summary'] )
+      end
+
+      YAML.object_maker( Manual, val )
+    end
+
+    YAML.add_domain_type( 'jamisbuck.org,2004', 'meta' ) do |taguri, val|
+      YAML.object_maker( Meta, val )
+    end
+
+    YAML.add_domain_type( 'jamisbuck.org,2004', 'product' ) do |taguri, val|
+      version = val["version"]
+      if version.respond_to?( :type_id )
+        if version.type_id == "version"
+          if version.value =~ %r{(.*)/(.*)}
+            require_file, constant = $1, $2
+          else
+            constant = version.value
+          end
+
+          require require_file if require_file
+          val["version"] = eval(constant)
+        else
+          raise "Unexpected type: #{val.type_id}"
+        end
+      end
+      YAML.object_maker( Product, val )
+    end
+
+    YAML.add_domain_type( 'jamisbuck.org,2004', 'sidebar' ) do |taguri, val|
+      YAML.object_maker( Sidebar,
+                         'title' => val.keys.first,
+                         'content'=> RedCloth.new( val.values.first ) )
+    end
+
+  end
+end
+
+if __FILE__ == $0
+
+  def log_action( action )
+    $stderr.puts action
+  end
+
+  unless ( output_path = ARGV[0] )
+    $stderr.puts "Usage: #{$0} [/path/to/save/html]"
+    exit
+  end
+
+  Dir.mkdir output_path rescue nil
+
+  log_action "Loading manual.yml..."
+  manual = Needle::Manual::Manual.load( 'manual.yml' )
+
+  # force these to be defined at the TOPLEVEL_BINDING
+  object = nil
+  guts = nil
+
+  page = File.open( "page.erb" ) { |file| ERB.new( file.read ) }
+  page.filename = "page.erb"
+
+  template = File.open( "index.erb" ) { |file| ERB.new( file.read ) }
+  template.filename = "index.erb"
+
+  File.open( File.join( output_path, "index.html" ), "w" ) do |file|
+    guts = template.result
+    file << page.result
+  end
+
+  template = File.open( "chapter.erb" ) { |file| ERB.new( file.read ) }
+  template.filename = "chapter.erb"
+
+  manual.chapters.each do |object|
+    log_action "Processing chapter ##{object.index}..."
+    File.open( File.join( output_path, "chapter-#{object.index}.html" ), "w" ) do |file|
+      guts = template.result
+      file << page.result
+    end
+  end
+
+  template = File.open( "tutorial.erb" ) { |file| ERB.new( file.read ) }
+  template.filename = "tutorial.erb"
+
+  manual.tutorials.each do |object|
+    log_action "Processing tutorial ##{object.index}..."
+    File.open( File.join( output_path, "tutorial-#{object.index}.html" ), "w" ) do |file|
+      guts = template.result
+      file << page.result
+    end
+  end
+
+#  template = File.open( "example.erb" ) { |file| ERB.new( file.read ) }
+#  template.filename = "example.erb"
+
+#  manual.examples.each do |object|
+#    log_action "Processing example ##{object.index}..."
+#    File.open( File.join( output_path, "example-#{object.index}.html" ), "w" ) do |file|
+#      guts = template.result
+#      file << page.result
+#    end
+#  end
+
+  log_action "Copying style sheets..."
+  FileUtils.cp Dir["*.css"], output_path
+
+  log_action "Copying images..."
+  FileUtils.cp Dir["img/*.jpg"], output_path
+
+  log_action "Done!"
+end

data/doc/manual/manual.yml

@@ -0,0 +1,48 @@
+--- !jamisbuck.org,2004/^manual
+
+# This content is made available under the Attribution-ShareAlike 2.0
+# license from the Create Commons:
+#
+#   http://creativecommons.org/licenses/by-sa/2.0/
+
+meta: !^meta
+  copyright: 2004
+  author: Jamis Buck
+  email: jgb3@email.byu.edu
+
+product: !^product
+  name: Needle
+  tagline: to the point -->
+  version: !!eval require "../../lib/needle/version"; Needle::Version::STRING
+  #logo: needle.png
+  urls:
+    - Project Page: http://rubyforge.org/projects/needle
+    - User Manual: http://needle.rubyforge.org
+    - API Documentation: http://needle.rubyforge.org/api
+    - Needle Wiki: http://needle.rubyforge.org/wiki/wiki.pl
+
+recent_updates:
+
+chapters:
+
+- Introduction:
+  - What is Needle?: !!file parts/01_what_is_needle.txt
+  - How Can It Help Me?: !!file parts/01_use_cases.txt
+  - License Information: !!file parts/01_license.txt
+  - Support: !!file parts/01_support.txt
+      
+- Registry:
+  - Overview: !!file parts/02_overview.txt
+  - Creating: !!file parts/02_creating.txt
+  - Services: !!file parts/02_services.txt
+  - Namespaces: !!file parts/02_namespaces.txt
+
+- Dependency Injection:
+
+- Interceptors:
+
+- Service Models:
+
+- Logging:
+
+- Creating Libraries:

data/doc/manual/page.erb

@@ -0,0 +1,86 @@
+<html>
+  <head>
+    <title><%= manual.product.name %> Manual<% if object %> :: <%= object.page_title %><% end %></title>
+    <link type="text/css" rel="stylesheet" href="manual.css" />
+  </head>
+  
+  <body>
+    <div id="banner">
+      <table border='0' cellpadding='0' cellspacing='0' width='100%'>
+        <tr><td valign='top' align='left'>
+          <div class="title">
+            <span class="product"><%= manual.product.name %>&mdash;</span><br />
+            <span class="tagline"><%= manual.product.tagline %></span>
+          </div>
+        </td><td valign='middle' align='right'>
+          <div class="info">
+            <%= manual.product.name %> Version: <strong><%= manual.product.version %></strong><br />
+            Manual Last Updated: <strong><%= Time.now.gmtime.strftime('%Y-%m-%d %H:%M %Z') %></strong>
+          </div>
+        </td></tr>
+      </table>
+    </div>
+
+    <table border='0' width='100%' cellpadding='0' cellspacing='0'>
+      <tr><td valign='top'>
+
+        <div id="navigation">
+          <h1><%= manual.product.name %> Manual</h1>
+
+          <h2>Chapters</h2>
+          <ol type="I">
+          <% manual.chapters.each do |c| %>
+            <li><%= "<strong>" if c == object %>
+                <a href="chapter-<%= c.index %>.html">
+                <%= c.title %>
+                </a>
+                <%= "</strong> <big>&larr;</big>" if c == object %>
+              <ol type="1">
+                <% c.sections.each do |s|
+                     next unless s.title %>
+                  <li><a href="chapter-<%= c.index %>.html#s<%= s.index %>"><%= s.title %></a></li>
+                <% end %>
+              </ol>
+            </li>
+          <% end %>
+          </ol>
+
+          <h2>API Reference</h2>
+
+          <ul>
+            <li><a href="http://needle.rubyforge.org/api/index.html">Needle API</a></li>
+          </ul>
+
+          <h2>Tutorials</h2>
+          <ol>
+          <% manual.tutorials.each do |t| %>
+            <li><%= "<strong>" if t == object %>
+                <a href="tutorial-<%= t.index %>.html">
+                <%= t.title %>
+                </a>
+                <%= "</strong> <big>&larr;</big>" if t == object %><br />
+            <%= t.brief.to_html %>
+            </li>
+          <% end %>
+          </ol>
+
+          <p align="center"><strong>More To Come...</strong></p>
+
+          <div class="license">
+            <a href="http://creativecommons.org/licenses/by-sa/2.0/"><img alt="Creative Commons License" border="0" src="http://creativecommons.org/images/public/somerights" /></a><br />
+            This manual is licensed under a <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons License</a>.
+          </div>
+        </div>
+
+      </td><td valign='top' width="100%">
+
+        <div id="content">
+
+          <%= guts %>
+
+        </div>
+
+      </td></tr>
+    </table>
+  </body>
+</html>

data/doc/manual/parts/01_license.txt

@@ -0,0 +1,5 @@
+Needle is made available under either the BSD license, or the same license Ruby (which, by extension, also allows the GPL as a permissable license as well). You can view the full text of any of these licenses in the @doc@ subdirectory of the Needle distrubtion. The texts of the BSD and GPL licenses are also available online: "BSD":http://www.opensource.org/licenses/bsd-license.php and "GPL":http://www.opensource.org/licenses/gpl-license.php.
+
+This manual (in any form, be it source or otherwise) and the scripts and templates used to generate it, are all distributed under the "Creative Commons":http://creativecommons.org "Attribution-ShareAlike":http://creativecommons.org/licenses/by-sa/2.0 license.
+
+If you desire permission to use either Needle or the manual in a manner incompatible with these licenses, please contact the copyright holder ("Jamis Buck":mailto:jgb3@email.byu.edu) in order to negotiate a more compatible license.

data/doc/manual/parts/01_support.txt

@@ -0,0 +1 @@
+Mailing lists, bug trackers, feature requests, and public forums are available (courtesy of "RubyForge":http://rubyforge.org) at Needle's RubyForge project page. Just direct your browser to "http://rubyforge.org/projects/needle":http://rubyforge.org/projects/needle.

data/doc/manual/parts/01_use_cases.txt

@@ -0,0 +1,141 @@
+So, what can Needle do for you? Ultimately, it can reduce the amount of code that you have to write, simplifying many common programming tasks for you. This has the two-fold benefit of both decreasing application development time, and of decreasing the effort needed to maintain your application.
+
+But what, _specifically_, can Needle do for you?
+
+Try these on for size:
+
+* "Log Method Execution":#logexec
+* "Reference Another Service":#refsvc
+* "Unit Testing":#unittest
+* "Lifecycle Management":#lifecycle
+
+(Thanks to Howard Lewis Ship for his "HiveMind":http://jakarta.apache.org/hivemind documentation, from which some of the above bullet points were adapted.)
+
+
+h3. Log Method Execution <a name="#logexec"></a>
+
+Needle has an integrated logging framework, and the ability to log execution trace information without modifying a single line of code in your classes. This means that you can easily see what methods get called, with what arguments, and what the return values are, all without having to physically modify any of your classes.
+
+Consider the following code, demonstrating how this would be done without Needle:
+
+<pre>
+  def foo( arg1, arg2 )
+    @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
+    ...
+    result = the_result_of_the_method
+    @log.debug( "finishing foo with #{result}" ) if @log.debug
+    return result
+  rescue Exception => e
+    @log.debug( "foo raised exception #{e.message} (#{e.class})" ) if @log.debug?
+    raise
+  end
+</pre>
+
+Now, multiply that by the number of methods in your class... the logging messages quickly overpower the rest of the code, and detract from the flow of your program. This makes your program harder to debug, test, and maintain.
+
+Now, consider the same method using Needle's integrated logging framework...
+
+<pre>
+  def foo( arg1, arg2 )
+    ...
+    return the_result_of_the_method
+  end
+</pre>
+
+Then, when you define the service that you want to add the logging to:
+
+<pre>
+  registry.register( :service_name_here ) { |reg| ... }
+  registry.intercept( :service_name_here ).with! { logging_interceptor }
+</pre>
+
+That's right. There's no explicit logging code in there. Instead, you just tell Needle that the methods of the class should be logged, and away it goes. This has the added benefit of allowing your objects to be unit tested, without spewing log messages everywhere.
+
+h3. Reference Another Service <a name="#refsvc"></a>
+
+Invariably in a large application services will reference other services. This is typically accomplished through something like this:
+
+<pre>
+  class Component
+    ...
+    def foo( parms )
+      @service ||= lookup_service
+      @service.do_something( parms )
+    end
+
+    def lookup_service
+      ...
+    end
+    ...
+  end
+</pre>
+
+Whether the lookup is done lazily, as shown above, or when the class is first instantiated is irrelevant. The point is that you either have to implement a bunch of code to look up a service based on some criteria, or you hard code the class of the service (which creates tight coupling and makes things like unit testing harder).
+
+With Needle, you just declare a setter for the service, and then tell Needle that the class depends on the other service:
+
+<pre>
+  class Component
+    attr_writer :service
+    ...
+    def foo( parms )
+      @service.do_something( parms )
+    end
+    ...
+  end
+
+  registry.register( :component ) do |reg| 
+    c = Component.new
+    c.service = reg.some_other_service
+    c
+  end
+</pre>
+
+Then, when your service is instantiated, Needle will automatically look for and instantiate the dependencies for you. This makes for cleaner code, and looser coupling between services.
+
+h3. Unit Testing <a name="#unittest"></a>
+
+Large applications can prove troublesome to unit test exhaustively, especially if there is any kind of tight coupling between components. Such coupling of components can make it difficult to test them separately.
+
+Needle, by its very nature, encourages loose coupling of components. Also, because dependencies are never instantiated in code, but are instead accepted via setters or constructor arguments, it is trivial to replace those dependencies with mock objects at unit test time.
+
+Consider this tightly coupled example:
+
+<pre>
+  def foo( args )
+    @some_dependency ||= MyNewDependency.new
+    @some_dependency.do_something(args)
+  end
+</pre>
+
+It is impossible to test the method @#foo@ without also testing the MyNewDependency class. However, if the @@some_dependency@ object is made a property that is set externally, you can replace it at test time with a blank:
+
+<pre>
+  attr_writer :some_dependency
+
+  def foo( args )
+    @some_dependency.do_something( args )
+  end
+</pre>
+
+The unit test would become something like this:
+
+<pre>
+  def test_foo
+    @obj.some_dependecy = MyMockDependency.new
+    @obj.foo( args )
+    assert @obj.is_in_some_state
+  end
+</pre>
+
+h3. Lifecycle Management <a name="#lifecycle"></a>
+
+Singleton objects are a fact of life in complex systems. The singleton design pattern is powerful and useful. However, using the Singleton mixin, or declaring methods at the class level, can make your code difficult to unit test since the state of such objects cannot be easily reset.
+
+Needle has a solution. You can tell Needle to treat a service as either a _prototype_ service (meaning it will be instantiated every time you ask for it, like calling @#new@), or a _singleton_ service (meaning it will only be instantiated once, and the same instance will be returned for subsequent requests).
+
+Your object is still just a plain ol' ordinary Ruby object, but Needle has effectively transformed it into a singleton. This means you can unit test it as if it were nothing special, but when it is used in your application it will act like a singleton.
+
+Lifecycle management also means that you can control _when_ a service is instantiated.  The _prototype_ and _singleton_ models will always be instantiated as soon as they are requested. Sometimes, though, you don't want that--you'd like the instantiation to be deferred as late as possible.
+
+With Needle, you can indicate that a service should use deferred instantiation. This will cause the service to not actually be instantiated until a method is actually invoked on it.  Using this model, you can have services depend on themselves, or other forms of cyclical dependencies.

data/doc/manual/parts/01_what_is_needle.txt

@@ -0,0 +1 @@
+Needle is a dependency injection (also, inversion of control) container for "Ruby":http://www.ruby-lang.org.

data/doc/manual/parts/02_creating.txt

@@ -0,0 +1,9 @@
+Creating a registry is as simple as calling @Needle::Registry.new@. This will give you a new registry object, bootstrapped to contain a few general services.
+
+<pre>
+  require 'needle'
+
+  registry = Needle::Registry.new
+</pre>
+
+Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.

data/doc/manual/parts/02_namespaces.txt

@@ -0,0 +1,47 @@
+Namespaces allow you to organize your services. The feature has many different applications, including:
+
+# Third-parties may distribute Needle-enabled libraries without worrying about their choice of service names conflicting with the service names of their clients.
+# Developers may organize complex applications into modules, and the service definitions may be stored in the registry to reflect that organization.
+# Services deeper in the hierarchy may override services higher up.
+
+Creating a namespace is as easy as invoking the @#namespace@ method of the registry (or of another namespace):
+
+<pre>
+  registry.namespace :stuff
+</pre>
+
+This would create a new namespace in the registry called @:stuff@. The application may then proceed to register services inside that namespace:
+
+<pre>
+  registry.stuff.register( :foo ) { Bar.new }
+  ...
+  svc = registry.stuff.foo
+</pre>
+
+Here's a tip: _namespaces are just a special kind of service._ This means that you can access namespaces in the same ways that you can access services:
+
+<pre>
+  svc = registry[:stuff][:foo]
+</pre>
+
+h3. Convenience Methods
+
+Because it is often the case that you will be creating a namespace and then immediately registering services on it, you can pass a block to @namespace@. The block will receive a reference to the new namespace:
+
+<pre>
+  registry.namespace :stuff do |spc|
+    spc.register( :foo ) { Bar.new }
+    ...
+  end
+</pre>
+
+And, to mirror the @register!@ method, there is also a @namespace!@ method. This method creates a new namespace and then does a @register!@ call on that namespace.
+
+<pre>
+  registry.namespace! :stuff do
+    foo { Bar.new }
+    ...
+  end
+</pre>
+
+The above code would create a new namespace called @:stuff@ in the registry, and would then proceed to register a service called @:foo@ in the new namespace.

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

@@ -0,0 +1,3 @@
+The registry is at the heart of any dependency-injected application or library. All services are registered with the registry, so that when an application needs an instance of a particular service, it may obtain that service reference by querying the registry.
+
+In order to use Needle, you only really _need_ to understand how to create and manipulate registry objects.

data/doc/manual/parts/02_services.txt

@@ -0,0 +1,44 @@
+Registering services with a Needle registry is very straightforward. The simplest way to do it is:
+
+<pre>
+  registry.register( :foo ) { Bar.new }
+</pre>
+
+The above will register a new service with the registry, naming it @:foo@. When @:foo@ is requested from the registry, a new instance of @Bar@ will be instantiated and returned.
+
+You get services from the registry in either of two ways:
+
+<pre>
+  # Treating the registry as a Hash
+  svc = registry[:foo]
+
+  # Treating the service as a property of the registry
+  svc = registry.foo
+</pre>
+
+h3. Convenience Methods
+
+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 @registry!@, 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:
+
+<pre>
+  registry.register! do
+    foo { Bar.new }
+    bar { Foo.new }
+    ...
+  end
+</pre>
+
+The above will register two new services with the registry, @:foo@ and @:bar@.
+
+h3. Default Lifecycle
+
+By default, a service is only instantiated once per registry. This means that (using the above example) if the service @:foo@ were queried twice, the registry would return the same object for both queries:
+
+<pre>
+  svc1 = registry.foo
+  svc2 = registry.foo
+
+  p svc1.object_id == svc2.object_id #=> true
+</pre>
+
+You can change this behavior, with _service models_. See the chapter on Service Models for more information.

data/doc/manual/tutorial.erb

@@ -0,0 +1,30 @@
+<h1>Tutorial #<%= object.index %>. <%= object.title %></h1>
+
+<p>The sources for this tutorial may be found in the <tt>tutorial/<%= "%02d" % object.index %></tt>
+directory of the Copland distribution.</p>
+
+<% if object.intro %>
+
+  <h2>Introduction</h2>
+
+  <%= object.intro.to_html %>
+
+<% end %>
+
+<h2>Steps</h2>
+
+<ol>
+<% object.steps.each do |step| %>
+
+<li><%= step.to_html %></li>
+
+<% end %>
+</ol>
+
+<% if object.summary %>
+
+  <h2>Summary</h2>
+
+  <%= object.summary.to_html %>
+
+<% end %>