needle 0.5.0

data/lib/needle/interceptor.rb

@@ -0,0 +1,189 @@
+#--
+# =============================================================================
+# 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 represents the definition of an interceptor as it is attached to a
+  # service point. Instances of Interceptor are also used for configuring
+  # themselves programmatically.
+  #
+  # You will almost never instantiate an Interceptor object directly. Instead,
+  # use the Container#intercept method. You can then configure the new
+  # interceptor by chaining methods of the new object together, quite
+  # readably:
+  #
+  #   container.intercept( :foo ).with! { some_interceptor }.
+  #     with_options( :arg => :value )
+  #
+  # You can also create new interceptors on the fly via the Interceptor#doing
+  # method.
+  class Interceptor
+
+    # This is the wrapper for on-the-fly interceptors that have been created
+    # via Interceptor#doing. The callback registered with Interceptor#doing
+    # gets wrapped by an instance of this class, to comply with the interface
+    # required by InterceptorChainBuilder.
+    #
+    # This class should rarely (if ever) be instantiated directly. Instead,
+    # using the Interceptor#doing method to create dynamic interceptors.
+    class DynamicInterceptor
+
+      # Create a new DynamicInterceptor instance that wraps the given
+      # callback.
+      def initialize( callback )
+        @callback = callback
+      end
+
+      # This method is a concession to the required interceptor factory
+      # interface. It should return the new interceptor, configured to be
+      # attached to the given service point, and with the given options.
+      # It will always return +self+.
+      def new( point, opts )
+        @point = point
+        @options = opts
+        self
+      end
+
+      # Process this link in the interceptor chain. This will invoke the
+      # wrapped callback, passing in the chain and context parameters.
+      # Before invoking the callback, the options and service point
+      # references that were given in #new are assigned to context
+      # data members (so they can be referenced inside the callback).
+      def process( chain, context )
+        context.data[:options] = @options
+        context.data[:point] = @point
+        @callback.call( chain, context )
+      end
+
+    end
+
+    # The set of options that were given to this interceptor via the
+    # #with_options method.
+    attr_reader :options
+
+    # Create a new Interceptor definition. By default, it has no
+    # implementation and a priority of 0.
+    def initialize
+      @options = { :priority => 0 }
+      @doing = @with = nil
+    end
+
+    # Returns the action that was specified for this interceptor as a proc
+    # instance. This will either be the block passed to #with, or a proc
+    # that wraps the instantiation of a DynamicInterceptor (when #doing
+    # was used).
+    #
+    # If neither #with nor #doing were specified, an
+    # InterceptorConfigurationError is raised.
+    def action
+      return @with if @with
+      raise InterceptorConfigurationError,
+        "You must specify either 'with' or 'doing'" unless @doing
+
+      return proc { |c| DynamicInterceptor.new( @doing ) }
+    end
+
+    # Sets the action for this interceptor to be that defined by the
+    # interceptor returned when the block is executed. You can only
+    # invoke #with once, and never after previously invoking #doing on the
+    # same interceptor instance.
+    #
+    # Usage:
+    #
+    #   container.intercept( :foo ).
+    #     with { |c| c.logging_interceptor }
+    def with( &block )
+      if @with
+        raise InterceptorConfigurationError,
+          "you cannot redefine 'with' behavior"
+      end
+
+      if @doing
+        raise InterceptorConfigurationError,
+          "cannot specify 'with' after specifying 'doing'"
+      end
+
+      if block.nil?
+        raise InterceptorConfigurationError,
+          "you must specify a block to 'with'"
+      end
+
+      @with = block
+      self
+    end
+
+    # This is identical to #with, but it wraps the block in another proc that
+    # calls +instance_eval+ on the container, with the block.
+    #
+    # Usage:
+    #
+    #   container.intercept( :foo ).
+    #     with! { logging_interceptor }
+    def with!( &block )
+      with { |c| c.instance_eval( &block ) }
+    end
+
+    # This allows new interceptors to be defined "on-the-fly". The associated
+    # block must accept two parameters--an object representing the chain of
+    # interceptors, and the context of the current method invocation. The block
+    # should then invoke #process_next on the chain (passing the context as
+    # the lone parameter) when the next element of the chain should be invoked.
+    #
+    # You should only call #doing once per interceptor, and never after
+    # invoking #with on the same interceptor.
+    def doing( &block )
+      if @doing
+        raise InterceptorConfigurationError,
+          "you cannot redefine 'doing' behavior"
+      end
+
+      if @with
+        raise InterceptorConfigurationError,
+          "cannot specify 'doing' after specifying 'with'"
+      end
+
+      if block.nil?
+        raise InterceptorConfigurationError,
+          "you must specify a block to 'doing'"
+      end
+
+      @doing = block
+      self
+    end
+
+    # Merge the given +opts+ hash into the interceptors options hash.
+    def with_options( opts={} )
+      @options.update opts
+      self
+    end
+
+    # A convenience method for querying the options on an interceptor
+    # definition.
+    def []( name )
+      @options[ name ]
+    end
+
+    # A convenience method for setting the options on an interceptor
+    # definition.
+    def []=( name, value )
+      @options[ name ] = value
+    end
+
+  end
+
+end

data/lib/needle/log-factory.rb

@@ -0,0 +1,207 @@
+#--
+# =============================================================================
+# 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/logger'
+require 'thread'
+
+module Needle
+
+  # A factory class that returns Logger instances. Since each registry
+  # has its own logger factory, the logger factory must be separately
+  # instantiable.
+  class LogFactory
+
+    # The default name of the log file to write to.
+    DEFAULT_LOG_FILENAME = "./needle.log"
+
+    # The default format of the log messages (see Logger for more info)
+    DEFAULT_MESSAGE_FORMAT = "[%-5p] %d -- %C: %m"
+
+    # Translate names of levels to their actual values.
+    LEVEL_TRANSLATOR = {
+      "DEBUG" => Logger::DEBUG,
+      "INFO" => Logger::INFO,
+      "WARN" => Logger::WARN,
+      "ERROR" => Logger::ERROR,
+      "FATAL" => Logger::FATAL,
+      "UNKNOWN" => Logger::UNKNOWN
+    }
+
+    # The default date format string to use when logging.
+    attr_reader :default_date_format
+
+    # The default message format string to use when logging.
+    attr_reader :default_message_format
+
+    # The default log level to use for logs that are created.
+    attr_reader :default_level
+
+    # The device that logs will write to.
+    attr_reader :device
+
+    # Create a new LogFactory using the given initialization parameters.
+    # The valid options are:
+    #
+    # * <tt>:device</tt>: the device (pseudo-IO object) to write log
+    #   messages to. Either this, or <tt>:filename</tt> must be specified.
+    # * <tt>:filename</tt>: the filename of the log to write to.
+    # * <tt>:roll_age</tt>: the number of days before the log should be
+    #   rolled.
+    # * <tt>:roll_frequency</tt>: either 'daily', 'weekly', or 'monthly'.
+    # * <tt>:roll_size</tt>: the maximum size of a log file.
+    # * <tt>:default_date_format</tt>: the default date format string for
+    #   the log.
+    # * <tt>:default_message_format</tt>: the default message format string
+    #   for  the log.
+    # * <tt>:default_level</tt>: the default log level for the log.
+    # * <tt>:levels</tt>: a hash of patterns that map to a hash of 'level'
+    #   'date_format', and 'message_format' keys, specifying the log level,
+    #   date format, and message format for any log whose name matches the key.
+    def initialize( opts={} )
+      if opts[:device]
+        @device = opts[:device]
+      else
+        filename = opts[:filename] || DEFAULT_LOG_FILENAME
+        roll_age = opts[:roll_age ] || opts[:roll_frequency] || 0
+        roll_size = opts[:roll_size] || 0
+        @device = Logger::LogDevice.new( filename,
+          :shift_age=>roll_age, :shift_size=>roll_size )
+      end
+
+      @default_date_format = opts[:default_date_format]
+      @default_message_format = opts[:default_message_format] ||
+        DEFAULT_MESSAGE_FORMAT
+      @default_level = opts[:default_level]
+
+      if @default_level.is_a?( String ) || @default_level.is_a?( Symbol )
+        @default_level = LEVEL_TRANSLATOR[@default_level.to_s]
+      end
+
+      @levels = Hash.new "level" => nil, "date-format" => nil,
+        "message-format" => nil
+
+      ( opts[:levels] || {} ).each_pair do |key, value|
+        key = Regexp.new( "^" + key.gsub( /\./, "\\." ).gsub( /\*/, ".*" ) )
+
+        if value.is_a?( String ) || value.is_a?( Symbol )
+          value = { "level" => value.to_s }
+        end
+
+        @levels[ key ] = value
+      end
+
+      @loggers = Hash.new
+      @mutex = Mutex.new
+      @closed = false
+    end
+
+    # Changes the device that the loggers write to. Every log that was created
+    # by this log factory will be changed to use the given device.
+    def write_to( device, shift_age = 0, shift_size = 1048576 )
+      saved_critical = Thread.critical
+      Thread.critical = true
+
+      @device.close if @device unless [ $stdout, $stderr ].include?( @device )
+      if device.respond_to?( :write ) && device.respond_to?( :close )
+        @device = device
+      else
+        @device = Logger::LogDevice.new( device.to_str,
+          :shift_age => shift_age, 
+          :shift_size => shift_size )
+      end
+
+      @loggers.each_value { |logger| logger.write_to( @device ) }
+      device
+
+    ensure
+      Thread.critical = saved_critical
+    end
+
+    # Searches for a level definition hash that matches the given log
+    # name.
+    def find_definition( name )
+      best_match = { :length => 0, :value => Hash.new }
+
+      @levels.each_pair do |key, value|
+        length = key.to_s.length
+        if best_match[ :length ] < length && key === name
+          best_match[ :length ] = length
+          best_match[ :value ] = value
+        end
+      end
+
+      return best_match[ :value ]
+    end
+    private :find_definition
+
+    # Retrieves the logger with the given name. If no such log has been
+    # created, the log will be created and initialized. Otherwise, the
+    # log with the given name is returned.
+    def get( name )
+      name = name.fullname if name.respond_to?( :fullname )
+      name = name.name if name.respond_to?( :name )
+      name = name.to_s
+
+      # the common case first, outside the synchronize, for speed
+      return @loggers[ name ] if @loggers[ name ]
+
+      @mutex.synchronize do
+        # check again, inside the synchronize, to avoid race conditions
+        return @loggers[ name ] if @loggers[ name ]
+
+        definition = find_definition( name )
+
+        level = definition[ "level" ] || @default_level
+        date_format = definition[ "date-format" ] || @default_date_format
+        message_format = definition[ "message-format" ] ||
+          @default_message_format
+
+        level = LEVEL_TRANSLATOR[ level ] || level
+
+        logger = Needle::Logger.new( @device )
+        logger.level = level if level
+        logger.progname = name
+        logger.datetime_format = date_format if date_format
+        logger.message_format = message_format if message_format
+
+        @loggers[ name ] = logger
+        return logger
+      end
+    end
+
+    # Closes the logging device and makes this factory invalid for future
+    # accesses.
+    def close
+      @mutex.synchronize do
+        return if @closed
+
+        if @device
+          @device.close unless [ $stdout, $stderr ].include?( @device )
+        end
+
+        @loggers = nil
+        @closed = true
+      end
+    end
+
+    # Returns true if the factory has been closed.
+    def closed?
+      @closed
+    end
+
+  end
+
+end

data/lib/needle/logger.rb

@@ -0,0 +1,161 @@
+#--
+# =============================================================================
+# 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 'logger'
+require 'strscan'
+require 'needle/errors'
+
+module Needle
+
+  # A specialization of the standard Logger class that comes with Ruby. This
+  # provides the additional functionality of a fully-customizable message
+  # format, whereas the original only provided a customizable date format.
+  class Logger < ::Logger
+
+    # The brief name of this logger (derived from #progname).
+    attr_reader :name
+
+    # The format string for the message (+nil+ if the default should be used)
+    attr_reader :message_format
+
+    # The map of specifier options supported by this class.
+    SPECIFIER_OPTIONS = {
+      "c" => { :type => "s", :value => "@name" },
+      "C" => { :type => "s", :value => "self.progname" },
+      "d" => { :type => "s", :value => "opts[:timestamp]" },
+      "F" => { :type => "s", :value => "opts[:caller_file]" },
+      "l" => { :type => "s", :value => "opts[:caller_info]" },
+      "L" => { :type => "d", :value => "opts[:caller_line]" },
+      "m" => { :type => "s", :value => "opts[:msg]" },
+      "M" => { :type => "s", :value => "opts[:caller_method]" },
+      "n" => { :type => "s", :value => "$/" },
+      "p" => { :type => "s", :value => "opts[:severity]" },
+      "t" => { :type => "d", :value => "Thread.current.__id__" },
+      "%" => { :type => "s", :value => "'%'" },
+      "P" => { :type => "s", :value => "opts[:progname]" },
+      "$" => { :type => "d", :value => "$$" }
+    }
+
+    # The regular expression for matching specifier patterns in the
+    # format strings.
+    SPECIFIER_PATTERN = /(.*?)%(-?\d*(?:\.\d+)?)?([cCdFlLmMnpt%$P])/
+
+    # Extracts the unqualified name from the progname, after setting the
+    # progname.
+    def progname=( progname )
+      super
+      @name = progname.split( /\./ ).last
+    end
+
+    # Changes the device that the given logger writes to, to be the given
+    # device. Does so in a thread-safe manner.
+    def write_to( device, shift_age = 0, shift_size = 1048576 )
+      saved_critical = Thread.critical
+      Thread.critical = true
+
+      if device
+        if device.respond_to?( :write ) && device.respond_to?( :close )
+          @logdev = device
+        else
+          @logdev = Logger::LogDevice.new( device,
+            :shift_age => shift_age, 
+            :shift_size => shift_size )
+        end
+      end
+
+      device
+    ensure
+      Thread.critical = saved_critical
+    end
+
+    # Set the message format string to the given string. This also pre-parses
+    # the format for faster processing.
+    #
+    # The format string is a printf-formatted string, which supports the following
+    # format specifiers:
+    #
+    # c:: the unqualified name of the logger
+    # C:: the fully-qualified name of the logger
+    # d:: the date/time string (as formatted by the #datetime_format string)
+    # F:: the filename of the calling routine
+    # l:: the location of the calling routine
+    # L:: the line number of the calling routine
+    # m:: the message to log
+    # M:: the name of the calling method
+    # n:: the newline character
+    # p:: the name of the priority (or severity) used to log this method
+    # t:: the id of the current thread
+    # %:: a percentage character
+    # P:: the progname that was passed to the logger method
+    # $:: the current process id
+    def message_format=( format )
+      @message_format = format
+      return unless format
+
+      @needs_caller_info = false
+
+      format_string = ""
+      format_parameters = []
+
+      @message_format_tokens = []
+      format.scan( SPECIFIER_PATTERN ) do |v|
+        format_string << v[0] if v[0].length > 0
+        opts = SPECIFIER_OPTIONS[ v[2] ]
+        format_string << "%#{v[1]}#{opts[:type]}"
+        format_parameters << opts[:value]
+        @needs_caller_info = true if v[2] =~ /[FlLM]/
+      end
+      format_string << $' if $'.length > 0
+      format_string << "\n"
+
+      definition =
+        "proc { |opts| #{format_string.inspect} " +
+        "% [ #{format_parameters.join(',')} ] }"
+      @message_formatter = eval( definition )
+    end
+
+    # Format the message using the given parameters. If a message format has
+    # not been given, just call the superclass's implementation. Otherwise,
+    # process the tokens from the parsed message format.
+    def format_message( severity, timestamp, msg, progname )
+      if @message_format.nil?
+        super
+      else
+        opts = {
+          :severity => severity,
+          :timestamp => timestamp,
+          :msg => msg,
+          :progname => progname
+        }
+        
+        if @needs_caller_info
+          stack = caller
+          stack.shift while stack.first =~ /\blogger\.rb/
+          opts[:caller_info] = caller_info = stack.first
+          match = caller_info.match( /(.*):(\d+)(?::in `(.*)')?/ )
+          opts[:caller_file] = match[1]
+          opts[:caller_line] = match[2]
+          opts[:caller_method] = match[3]
+        end
+
+        @message_formatter.call( opts )
+      end
+    end
+    private :format_message
+
+  end
+
+end

data/lib/needle/logging-interceptor.rb

@@ -0,0 +1,62 @@
+#--
+# =============================================================================
+# 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/include-exclude'
+
+module Needle
+
+  # A LoggingInterceptor is an interceptor object that logs method
+  # invocations and exceptions. It includes the IncludeExclude functionality.
+  class LoggingInterceptor
+    include IncludeExclude
+
+    # Create a new LoggingInterceptor for the given service point, with the
+    # given list of include and exclude patterns. The logger object will be
+    # created as well, named with the service point's full name.
+    def initialize( point, parms )
+      @log = point.container.logs.get( point.fullname )
+
+      @includes = build_map( parms[ :include ] )
+      @excludes = build_map( parms[ :exclude ] )
+    end
+
+    # Processes a method invocation context. If the current log has debugging
+    # activated, and the requested method is not excluded by the
+    # interceptor's exclude and include patterns, then a message will be
+    # written for the method's invocation, its return code, and any exception
+    # that is thrown.
+    def process( chain, context )
+      if @log.debug? && match( context )
+        args = context.args.map { |i| i.inspect } .join( ', ' )
+        @log.debug "#{context.sym}( #{args} )"
+
+        begin
+          result = chain.process_next( context )
+        rescue Exception => e
+          @log.debug "#{context.sym} raised #{e.message.inspect} (#{e.class})"
+          raise
+        end
+
+        @log.debug "#{context.sym} => #{result.inspect}"
+        return result
+      else
+        return chain.process_next( context )
+      end
+    end
+
+  end
+
+end

data/lib/needle/models/prototype-deferred.rb

@@ -0,0 +1,41 @@
+#--
+# =============================================================================
+# 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/models/proxy'
+
+module Needle
+  module Models
+
+    # The definition of the "prototype-deferred" lifecycle service model.
+    # This will result in deferred instantiation of the requested service,
+    # with a new instance being returned every time #instance is invoked.
+    class PrototypeDeferred
+
+      # Create a new PrototypeDeferred service model.
+      def initialize( container, opts={}, &callback )
+        @container = container
+        @callback = callback
+      end
+
+      # Return a new Proxy instance that wraps the container and callback
+      # references given when the service model was instantiated.
+      def instance
+        Proxy.new( @container, &@callback )
+      end
+    end
+
+  end
+end

data/lib/needle/models/prototype.rb

@@ -0,0 +1,39 @@
+#--
+# =============================================================================
+# 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
+  module Models
+
+    # The definition of the "prototype" lifecycle service model. This will
+    # result in immediate instantiation of the requested service, with a new
+    # instance being returned every time #instance is invoked.
+    class Prototype
+
+      # Create a new instance of the Prototype service model.
+      def initialize( container, opts={}, &callback )
+        @container = container
+        @callback = callback
+      end
+
+      # Invoke the callback that was given when the service model was
+      # instantiated, passing the service model's container reference.
+      def instance
+        @callback.call( @container )
+      end
+    end
+
+  end
+end