needle 0.5.0

data/lib/needle/container.rb

@@ -0,0 +1,318 @@
+#--
+# =============================================================================
+# 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/errors'
+require 'needle/interceptor'
+require 'needle/service-point'
+
+module Needle
+
+  # The container is the heart of Needle's model. Every Container instance is
+  # a miniature registry, and is really a namespace separate from every other
+  # Container instance. Service lookups inside of a container always look in
+  # +self+ first, and if not found, they then look in their parent container,
+  # recursively.
+  #
+  # You will rarely need to instantiate a Container directly. Instead, use the
+  # Container#namespace method to create new containers.
+  class Container
+
+    # This class is used by the #register! 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
+      ( private_instance_methods +
+        protected_instance_methods +
+        public_instance_methods -
+        [ "instance_eval", "__id__", "__send__", "initialize", "remove_const",
+          "method_missing", "inspect" ]
+      ).
+      each { |m| undef_method m }
+
+      # Create a new RegistrationContext that wraps the given container. All
+      # operations performed on this context will be delegated to the
+      # container.
+      def initialize( container )
+        @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.
+      def namespace( *parms, &block )
+        @container.namespace!( *parms, &block )
+      end
+
+      # Any method invocation with no block and no parameters is interpreted to
+      # be a service reference on the wrapped container, and delegates to
+      # Container#[]. If the block is not given but the args are not empty, a
+      # NoMethodError will be raised.
+      #
+      # If a block is given, this delegates to Container#register, leaving
+      # all parameters in place.
+      def method_missing( sym, *args, &block )
+        if block.nil?
+          if args.empty?
+            @container[sym]
+          else
+            super
+          end
+        else
+          @container.register( sym, *args, &block )
+        end
+      end
+    end
+
+    # The container that contains this container. This will be +nil+ for
+    # the root of a hierarchy (see Registry).
+    attr_reader :parent
+
+    # The name of this container. May be +nil+.
+    attr_reader :name
+
+    # Create a new empty container with the given parent and name.
+    def initialize( parent=nil, name=nil )
+      @root = nil
+
+      @name = name
+      @parent = parent
+      @service_points = Hash.new
+    end
+
+    # Returns the root of the current hierarchy. If the container is the
+    # root, returns self, otherwise calls Container#root on its parent.
+    # The value is cached for future reference.
+    def root
+      return @root if @root
+      return self if parent.nil?
+      @root = parent.root
+    end
+
+    # Return the fully qualified name of this container, which is the
+    # container's name and all parent's names up to the root container,
+    # catenated together with dot characters, i.e., "one.two.three".
+    def fullname
+      return @name.to_s unless @parent
+      "#{@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.
+    #
+    # Usage:
+    #
+    #   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 RegistrationContext around the container, and then evaluate
+    # the block within the new context instance (via +instance_eval+).
+    #
+    # Usage:
+    #
+    #   container.register! do
+    #     calc( :model => :prototype ) { Calc.new( operations ) }
+    #   end
+    def register!( &block )
+      raise ArgumentError, "block expected" unless block
+      ctx = RegistrationContext.new( self )
+      ctx.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).
+    #
+    # If a block is given, the latest namespace created is yielded to the
+    # block.
+    #
+    # The last parameter may be a Hash, in which case it is used to specify
+    # options describing how the namespace should be created.
+    #
+    # For the curious, namespaces are simply services that are implemented
+    # by Container.  The two statements are really identical:
+    #
+    #   container.namespace( :calc )
+    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #
+    # Usage:
+    #
+    #   container.namespace( :calc, :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"
+      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.
+    #
+    # For the curious, namespaces are simply services that are implemented
+    # by Container.  The two statements are really identical:
+    #
+    #   container.namespace( :calc )
+    #   container.register( :calc ) { |c| Needle::Container.new( c, :calc ) }
+    #
+    # Usage:
+    #
+    #   container.namespace!( :calc, :operations ) do
+    #     add { Adder.new }
+    #     ...
+    #   end
+    #
+    #   adder = container.calc.operations.add
+    def namespace!( *parms, &block )
+      raise ArgumentError, "block expected" unless block
+      namespace( *parms ) { |ns| ns.register!( &block ) }
+    end
+
+    # Describe a new interceptor to use that will intercept method calls
+    # on the named service. This method returns a new Interceptor instance,
+    # which can be used directly to configure the behavior of the interceptor.
+    #
+    # Usage:
+    #
+    #   container.intercept( :calc ).with { |c| c.logging_interceptor }
+    def intercept( name )
+      point = find_definition( name )
+      raise ServiceNotFound, "#{fullname}.#{name}" unless point
+
+      interceptor = Interceptor.new
+      point.interceptor interceptor
+
+      interceptor
+    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.
+    def find_definition( name )
+      point = @service_points[ name ]
+      point = @parent.find_definition( name ) if @parent unless point
+      point
+    end
+
+    # Retrieves the named service, if it exists. Ancestors are searched if the
+    # service is not defined by the current container (see #find_definition).
+    # If the named service does not exist, ServiceNotFound is raised.
+    #
+    # Note that this returns the instantiated service, not the service point.
+    def []( name )
+      point = find_definition( name )
+      raise ServiceNotFound, "#{fullname}.#{name}" unless point
+
+      point.instance
+    end
+
+    # Returns +true+ if this container includes a service point with the given
+    # name. Returns +false+ otherwise.
+    def has_key?( name )
+      @service_points.has_key?( name )
+    end
+
+    # Returns +true+ if this container <em>or any ancestor</em> includes a
+    # service point with the given name. Returns +false+ otherwise.
+    def knows_key?( name )
+      return true if has_key?( name )
+      return @parent.knows_key?( name ) if @parent
+      false
+    end
+
+    # Return an array of the names of all service points in this container.
+    def keys
+      @service_points.keys
+    end
+
+    # As a convenience for accessing services, this delegates any message
+    # sent to the container (which has no parameters and no block) to
+    # Container#[]. Note that this incurs slightly more overhead than simply
+    # calling Container#[] directly, so if performance is an issue, you should
+    # avoid this approach.
+    #
+    # Usage:
+    #
+    #   container.register( :add ) { Adder.new }
+    #   p container.add == container[:add] # => true
+    #
+    def method_missing( sym, *args, &block )
+      if block.nil? && args.empty? && knows_key?( sym )
+        self[sym]
+      else
+        super
+      end
+    end
+
+    # Returns true if this container responds to the given message, or if it
+    # explicitly contains a service with the given name (see #has_key?). In
+    # this case, #has_key? is used instead of #knows_key? so that subcontainers
+    # may be used as proper hashes by their parents.
+    def respond_to?( sym )
+      @service_points.has_key?( sym ) || super
+    end
+
+  end
+
+end

data/lib/needle/errors.rb

@@ -0,0 +1,32 @@
+#--
+# =============================================================================
+# 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
+# =============================================================================
+#++
+
+module Needle
+
+  # The base class for all Needle-specific errors.
+  class NeedleError < StandardError; end
+
+  # Raised when a requested service could not be located.
+  class ServiceNotFound < NeedleError; end
+
+  # Raised when there was an error configuring an interceptor.
+  class InterceptorConfigurationError < NeedleError; end
+
+  # Raised to denote a condition that should never occur. If this gets
+  # raised, it is Needle's fault, not the consumer's.
+  class Bug < NeedleError; end
+
+end

data/lib/needle/include-exclude.rb

@@ -0,0 +1,116 @@
+#--
+# =============================================================================
+# 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/errors'
+
+module Needle
+
+  # A simple structure for representing a single include/exclude pattern.
+  IncludeExcludePattern = Struct.new( :name, :comparitor, :arity )
+
+  # A module encapsulating the functionality of a service with include/exclude
+  # functionality. Such functionality involves a the ability to specify a
+  # pair of include and exclude arrays, each of which must be an array of
+  # method names that should be included or excluded from some kind of
+  # processing.
+  module IncludeExclude
+
+    # This is the regular expression for parsing elements in an include or
+    # exclude array.
+    PATTERN = /^
+               (.*?)        (?# this matches the method name pattern)
+               (?:          (?# begin optional arity section)
+                 \(         (?# begin parenthesized section)
+                   ([<=>])? (?# optional comparator character)
+                   (\d+)    (?# arity specification)
+                 \)         (?# end parenthesized section)
+               )?           (?# end optional arity section)
+               $/x
+
+    # This is a utility function for converting an array of strings
+    # representing method name patterns, into an array of
+    # IncludeExcludePattern instances.
+    def build_map( array )
+      ( array || [] ).map do |pattern|
+        unless pattern =~ PATTERN
+          raise InterceptorConfigurationError,
+            "invalid logging interceptor method pattern: #{pattern.inspect}"
+        end
+
+        name = $1
+        comparitor = $2
+        arity = ( $3 || -1 ).to_i
+
+        comparitor ||= ">" if arity < 0
+        comparitor ||= "="
+          
+        IncludeExcludePattern.new( Regexp.new( "^" + name + "$" ),
+                                   comparitor,
+                                   arity )
+      end
+    end
+    private :build_map
+
+    # Returns +false+ if the given context object "matches" any of the
+    # exclude patterns without matching any of the include patterns.
+    # The context object must respond to the <tt>:sym</tt> and
+    # <tt>:args</tt> messages, where <tt>:sym</tt> is a symbol identifying
+    # the method being matched, and <tt>:args</tt> is an array of
+    # arguments that will be sent to that method.
+    def match( context )
+      match = true
+
+      @excludes.each do |pattern|
+        if match_pattern( context, pattern )
+          match = false
+          break
+        end
+      end
+
+      unless match
+        @includes.each do |pattern|
+          if match_pattern( context, pattern )
+            match = true
+            break
+          end
+        end
+      end
+
+      return match
+    end
+    private :match
+
+    # Returns +true+ if the given context matches the given pattern, and
+    # +false+ otherwise.
+    def match_pattern( context, pattern )
+      if context.sym.to_s =~ pattern.name
+        case pattern.comparitor
+          when "<"
+            return context.args.length < pattern.arity
+          when ">"
+            return context.args.length > pattern.arity
+          when "="
+            return context.args.length == pattern.arity
+        end
+      end
+
+      return false
+    end
+    private :match_pattern
+
+  end
+
+end

data/lib/needle/interceptor-chain.rb

@@ -0,0 +1,162 @@
+#--
+# =============================================================================
+# 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/errors'
+
+module Needle
+
+  # This module encapsulates the functionality for building interceptor chains.
+  module InterceptorChainBuilder
+
+    # The context of a method invocation.  This is used in an interceptor chain
+    # to encapsulate the elements of the current invocation.
+    # sym:   the name of the method being invoked
+    # args:  the argument list being passed to the method
+    # block: the reference to the block attached to the method invocation
+    # data:  a hash that may be used by clients for storing arbitrary data in
+    #        the context.
+    InvocationContext = Struct.new( :sym, :args, :block, :data )
+
+    # A single element in an interceptor chain.  Each interceptor object is
+    # wrapped in an instance of one of these.  Calling #process_next on a given
+    # chain element, invokes the #process method on the corresponding
+    # interceptor, with the next element in the chain being passed in.
+    class InterceptorChainElement
+
+      # Create a new InterceptorChainElement that wraps the given interceptor.
+      def initialize( interceptor )
+        @interceptor = interceptor
+      end
+
+      # Set the next element in the interceptor chain to the given object.  This
+      # must be either an InterceptorChainElement instance of a
+      # ProxyObjectChainElement instance.
+      def next=( next_obj )
+        @next_obj = next_obj
+      end
+
+      # Invokes the #process method of the interceptor encapsulated by this
+      # object, with the _next_ element in the chain being passed to it.
+      def process_next( context )
+        if @next_obj.nil?
+          raise Bug,
+            "[BUG] interceptor chain should always terminate with proxy"
+        end
+        @interceptor.process( @next_obj, context )
+      end
+
+    end
+
+    # Encapsulates the end of an interceptor chain, which is the actual object
+    # being affected.
+    class ProxyObjectChainElement
+
+      # Create a new ProxyObjectChainElement that wraps the given object.
+      def initialize( obj )
+        @obj = obj
+      end
+
+      # Invoke the method represented by the context on the wrapped object.
+      def process_next( context )
+        @obj.__send__( context.sym, *context.args, &context.block )
+      end
+
+    end
+
+    # This is just a trivial proxy class that is used to wrap a service
+    # before the interceptors are applied to it. This additional level of
+    # abstraction prevents the need for mangling the names of the service's
+    # methods, and also offers those applications that need it the ability
+    # to invoke methods of the service without going through the interceptors.
+    #
+    # The proxy will be decorated with dynamically appended methods by the
+    # InterceptorChainBuilder#build method.
+    class InterceptedServiceProxy
+
+      # Create a new InterceptedServiceProxy that wraps the given interceptor
+      # chain.
+      def initialize( chain )
+        @chain = chain
+      end
+
+    end
+
+    # This will apply the given interceptors to the given service by first
+    # ordering the interceptors based on their relative priorities,
+    # and then dynamically modifying the service's methods so that the chain
+    # of interceptors sits in front of each of them.
+    #
+    # The modified service is returned.
+    def build( point, service, interceptors )
+      return service if interceptors.nil? || interceptors.empty?
+
+      ordered_list =
+        interceptors.sort { |a,b|
+          a.options[:priority] <=> b.options[:priority] }
+
+      chain = ProxyObjectChainElement.new( service )
+
+      ordered_list.reverse.each do |interceptor|
+        factory = interceptor.action.call( point.container )
+        instance = factory.new( point, interceptor.options )
+        element = InterceptorChainElement.new( instance )
+        element.next = chain
+        chain = element
+      end
+
+      # FIXME: should inherited methods of "Object" be interceptable?
+      methods_to_intercept = ( service.class.instance_methods( true ) -
+                               Object.instance_methods +
+                               service.class.instance_methods( false ) ).uniq
+
+      service = InterceptedServiceProxy.new( chain )
+      singleton = class << service; self; end
+
+      methods_to_intercept.each do |method|
+        next if method =~ /^__/
+
+        if singleton.instance_methods(false).include? method
+          singleton.send( :remove_method, method )
+        end
+
+        singleton.class_eval <<-EOF
+          def #{method}( *args, &block )
+            context = InvocationContext.new( :#{method}, args, block, Hash.new )
+            @chain.process_next( context )
+          end
+        EOF
+      end
+
+      # allow the interceptor to intercept methods not explicitly
+      # declared on the reciever.
+      if singleton.instance_methods(false).include? "method_missing"
+        singleton.send( :remove_method, :method_missing )
+      end
+
+      singleton.class_eval <<-EOF
+        def method_missing( sym, *args, &block )
+          context = InvocationContext.new( sym, args, block, Hash.new )
+          @chain.process_next( context )
+        end
+      EOF
+
+      return service
+    end
+    module_function :build
+
+  end
+
+end