needle-extras 1.0.0

data/doc/manual/manual.rb

@@ -0,0 +1,202 @@
+# --------------------------------------------------------------------------
+# 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, :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 ) rescue "" }
+    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
+
+      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
+
+  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,45 @@
+--- !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-Extras
+  tagline: for all your needle needs
+  version: !!eval require "../../lib/needle/extras/version"; Needle::Extras::Version::STRING
+  urls:
+    - Project Page: http://rubyforge.org/projects/needle
+    - User Manual: http://needle.rubyforge.org/extras
+    - API Documentation: http://needle.rubyforge.org/extras/api
+    - FAQ Document: http://needle.rubyforge.org/extras/faq.html
+    - Needle Wiki: http://needle.rubyforge.org/wiki/wiki.pl
+
+recent_updates:
+  - First Draft
+
+chapters:
+
+- Introduction:
+  - What is Needle-Extras?: !!file parts/intro_what_is_extras.txt
+  - How Do I Use It?: !!file parts/intro_usage.txt
+  - License Information: !!file parts/intro_license.txt
+  - Support: !!file parts/intro_support.txt
+      
+- AttrInject:
+  - Overview: !!file parts/attrinject_overview.txt
+  - Usage: !!file parts/attrinject_usage.txt
+
+- Multicast:
+  - Overview: !!file parts/multicast_overview.txt
+  - Usage: !!file parts/multicast_usage.txt
+
+- RequireLibrary:
+  - Overview: !!file parts/requirelibrary_overview.txt
+  - Usage: !!file parts/requirelibrary_usage.txt

data/doc/manual/page.erb

@@ -0,0 +1,71 @@
+<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>Other Documentation</h2>
+
+          <ul>
+            <li><a href="http://needle.rubyforge.org/extras/api/index.html">Needle-Extras API</a></li>
+          </ul>
+
+          <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/attrinject_overview.txt

@@ -0,0 +1 @@
+AttrInject is an implementation of dependency injection that uses declared interfaces to determine dependencies. It is based on an implementation by Christian Neukirchen at "http://rafb.net/paste/results/sexpfu84.html":http://rafb.net/paste/results/sexpfu84.html.

data/doc/manual/parts/attrinject_usage.txt

@@ -0,0 +1,34 @@
+AttrInject is very straightforward to use. Just require the AttrInject library in every service implementation and use the new @attr_inject@ macro to specify which other services the class depends on:
+
+<pre>
+  require 'needle/extras/attr-inject'
+
+  class Foo
+    attr_inject :bar
+    attr_inject :baz, :blah
+
+    def frobnicate
+      @bar + @baz / @blah
+    end
+  end
+</pre>
+
+The @attr_inject@ macro does not create any accessors--it only declares the dependencies that the corresponding service has. Then, when you register the service, you specify one of the @inject@ service models:
+
+<pre>
+  require 'needle'
+  require 'needle/extras'
+  ...
+  reg.require_library 'needle/extras'
+  reg.define do |b|
+    b.bar { 5 }
+    b.baz { 10 }
+    b.blah { Math::PI }
+
+    b.foo( :model => :singleton_inject ) { Foo.new }
+  end
+</pre>
+
+The @singleton_inject@ service model is just like @singleton@, but it will also automatically inject all of the declared dependencies into the new service. Thus, invoking @#frobnicate@ on the @foo@ service would compute and return (in this case) @5 + 10 / PI@.
+
+This approach has the benefit of reducing the amount of initialization code you have to write. On the other hand, it more tightly couples your implementation code to Needle itself.

data/doc/manual/parts/intro_license.txt

@@ -0,0 +1,5 @@
+Needle-Extras 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-Extras 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/intro_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/intro_usage.txt

@@ -0,0 +1,30 @@
+You can make all of the services in Needle-Extras available to your applications in either of two ways.
+
+The first way uses the standard @Collection#require@ method to load a service library and include it in a container:
+
+<pre>
+  require 'needle'
+
+  reg = Needle::Registry.new
+  reg.require 'needle/extras', 'Needle::Extras'
+  ...
+</pre>
+
+The second way uses the RequireLibrary framework provided by Needle-Extras itself:
+
+<pre>
+  require 'needle'
+  require 'needle/extras'
+
+  reg = Needle::Registry.new
+  reg.require_library 'needle/extras'
+</pre>
+
+If you don't want to use _all_ of the services available in Needle-Extras, you can include just the ones you want by requiring them directly:
+
+<pre>
+  require 'needle'
+
+  reg = Needle::Registry.new
+  reg.require 'needle/extras/multicast', 'Needle::Extras::Multicast'
+</pre>

data/doc/manual/parts/intro_what_is_extras.txt

@@ -0,0 +1,7 @@
+Needle-Extras is a collection of additional services and utilities that can be used in conjuction with Needle. It is a kind of test-bed for services that may eventually find their way into Needle itself.
+
+Currently, Needle-Extras includes the following services and utilities:
+
+* AttrInject: this is an implementation of simple interface-based dependency injection, inspired by a proof-of-concept by Christian Neukirchen ("http://rafb.net/paste/results/sexpfu84.html":http://rafb.net/paste/results/sexpfu84.html).
+* Multicast: this is a demonstration of how to do multicast services--services that delegate the messages they receive to a collection of other services.
+* RequireLibrary: this is not actually a service, so much as a mini-framework for simplifying the process of including a third-party service in your application.

data/doc/manual/parts/multicast_overview.txt

@@ -0,0 +1 @@
+The multicast service allows you to easily broadcast messages to a specified set of objects. It is, in essence, a kind of observer pattern, with t he observers being given to the multicaster when it is created. Events are then sent to the observers by invoking methods on the multicaster.

data/doc/manual/parts/multicast_usage.txt

@@ -0,0 +1,22 @@
+The multicast service is parameterized. Just send it a list of objects (i.e., other services) that you want multicasted to, and it will return a new multicaster object.
+
+<pre>
+  reg = Needle::Registry.define do |b|
+    b.require 'needle/extras/multicast', 'Needle::Extras::Multicast'
+
+    b.foo { "hello" }
+    b.bar { [ 1, 2, 3 ] }
+    b.baz { "test" }
+
+    b.multicaster { |c,| c.multicast c.foo, c.bar, c.baz }
+  end
+</pre>
+
+Once you've registered your service, you can send messages to the observing services by sending messages to the multicaster:
+
+<pre>
+  m = reg.multicaster
+  p m.length #-> [ 5, 3, 4 ]
+</pre>
+
+The multicaster will return an array of the return values of all of the observing services. Thus, in the above example, an array of the lengths of each of the @foo@, @bar@, and @baz@ services is returned.

data/doc/manual/parts/requirelibrary_overview.txt

@@ -0,0 +1,5 @@
+RequireLibrary is not a service--it is a mini-framework for registering service libraries with Needle so that they can be imported into other projects with a minimum of headache.
+
+Currently, Needle supports @Container#require@ as the library import mechanism. This requires you to specify both the file containing the service registration method, as well as the Module that contains the method.
+
+RequireLibrary takes some of the duplication out of the process by allowing application developers to register a callback hook with Needle, which will be invoked when the new @Container#require_library@ method is invoked.

data/doc/manual/parts/requirelibrary_usage.txt

@@ -0,0 +1,34 @@
+For developers of service libraries, RequireLibrary provides a hook for registering their libraries with Needle:
+
+<pre>
+  module Foo
+    module Bar
+
+      def register_services( container )
+        ...
+      end
+      module_function :register_services
+
+      if defined?(Needle.register_library)
+        Needle.register_library( 'foo/bar', self )
+      end
+
+    end
+  end
+</pre>
+
+The @#register_services@ method is Needle's standard callback for registering a library's services with the given container.
+
+The next lines, though, check to see if @Needle.register_library@ is defined. This allows the library to be used even when Needle-Extras is not loaded, or even installed. If the method exists, it is invoked with the @require@ path of the file, and the module reference that contains the @#register_services@ method.
+
+Then, consumers of the library can load it using RequireLibrary as follows:
+
+<pre>
+  require 'needle'
+
+  reg = Needle::Registry.new
+  reg.require_library 'foo/bar'
+  ...
+</pre>
+
+The call to @Container#require_library@ invokes @Kernel#require@, and then looks to see if there is a hook registered for the @'foo/bar'@ path. If there is, the hook is invoked, which (by default) invokes the @#register_services@ method, passing the current container as the parameter.