aquarium 0.4.0 → 0.4.1

data/lib/aquarium/dsl.rb

@@ -0,0 +1,2 @@
+# NEVER require  'aquarium/dsl/object_dsl' here!
+require 'aquarium/dsl/aspect_dsl'

data/lib/aquarium/dsl/aspect_dsl.rb

@@ -0,0 +1,77 @@
+require 'aquarium/aspects/aspect'
+require 'aquarium/utils/type_utils'
+
+# Convenience methods added to the current type to provide a low-level AOP DSL. 
+# If you don't want these methods added to a type, then only require aspect.rb
+# and create instances of Aspect.
+
+module Aquarium
+  module DSLMethods
+        
+    def advise *options, &block
+      o = append_implicit_self options
+      Aquarium::Aspects::Aspect.new *o, &block
+    end  
+  
+    %w[before after after_returning after_raising around].each do |advice_kind|
+      module_eval(<<-ADVICE_METHODS, __FILE__, __LINE__)
+        def #{advice_kind} *options, &block
+          advise :#{advice_kind}, *options, &block
+        end
+      ADVICE_METHODS
+    end
+  
+    %w[after after_returning after_raising].each do |after_kind|
+      module_eval(<<-AFTER, __FILE__, __LINE__)
+        def before_and_#{after_kind} *options, &block
+          advise :before, :#{after_kind}, *options, &block
+        end
+      AFTER
+    end
+    
+    alias :after_returning_from :after_returning
+    alias :after_raising_within :after_raising
+    alias :after_raising_within_or_returning_from :after
+  
+    alias :before_and_after_returning_from :before_and_after_returning
+    alias :before_and_after_raising_within :before_and_after_raising
+    alias :before_and_after_raising_within_or_returning_from :before_and_after
+ 
+    def pointcut *options, &block
+      o = append_implicit_self options
+      Aquarium::Aspects::Pointcut.new *o, &block
+    end
+
+    private
+    def append_implicit_self options
+      opts = options.dup
+      if (!opts.empty?) && opts.last.kind_of?(Hash)
+        opts.last[:default_objects] = self
+      else
+        opts << {:default_objects => self}
+      end
+      opts
+    end
+  end
+
+  module DSL
+    include Aquarium::DSLMethods
+    # Add the methods as class, not instance, methods.
+    def self.append_features clazz
+      super(class << clazz; self; end)
+    end
+  end
+
+  # Backwards compatibility with old name.
+  module Aspects
+    module DSL
+      module AspectDSL
+        include Aquarium::DSLMethods
+        # Add the methods as class, not instance, methods.
+        def self.append_features clazz
+          super(class << clazz; self; end)
+        end
+      end
+    end
+  end
+end

data/lib/aquarium/{aspects/dsl → dsl}/object_dsl.rb

@@ -1,8 +1,8 @@
-require 'aquarium/aspects/dsl/aspect_dsl'
+require 'aquarium/dsl/aspect_dsl'
 
 # Add aspect convenience methods to Object. Only require this
 # file if you really want these methods on all objects in your runtime!
 class Object
-  include Aquarium::Aspects::DSL::AspectDSL
+  include Aquarium::DSL
 end
 

data/lib/aquarium/extras/design_by_contract.rb

@@ -1,7 +1,7 @@
 # A simple Design by Contract module. Adds advice to test that the contract, which is specified with
 # a block passes. Note that it doesn't attempt to handle the correct behavior under contract 
 # inheritance.
-# Warning: This module automatically includes Aquarium::Aspects::DSL::AspectDSL into the class with 
+# Warning: This module automatically includes Aquarium::DSL into the class with 
 # the contract and it adds the :precondition, :postcondition, and the :invariant methods to Object! 
 require 'aquarium'
 

data/lib/aquarium/finders.rb

@@ -1,3 +1,3 @@
 require 'aquarium/finders/finder_result'
-require 'aquarium/finders/method_finder'
 require 'aquarium/finders/type_finder'
+require 'aquarium/finders/method_finder'

data/lib/aquarium/finders/method_finder.rb

@@ -1,6 +1,7 @@
 require 'set'
 require File.dirname(__FILE__) + '/../utils/array_utils'
 require File.dirname(__FILE__) + '/../utils/invalid_options'
+require File.dirname(__FILE__) + '/../utils/set_utils'
 require File.dirname(__FILE__) + '/../utils/type_utils'
 require File.dirname(__FILE__) + '/../utils/options_utils'
 require File.dirname(__FILE__) + '/finder_result'
@@ -17,7 +18,7 @@ module Aquarium
       # Method names, not method objects, are always returned, because we can only get
       # method objects for instance methods if we have an instance!
       #
-      # finder_result = MethodFinder.new.find :types => ... {, :methods => ..., :options => [...]}
+      # finder_result = MethodFinder.new.find :types => ... {, :methods => ..., :method_options => [...]}
       # where
       # "{}" indicate optional arguments
       #
@@ -68,10 +69,10 @@ module Aquarium
       #   One or more method names and regular expressions to exclude from the match.
       #   Specify one or an array of values.
       #
-      # <tt>:options => method_options</tt>::
-      # <tt>:method_options => method_options</tt>::
-      # <tt>:method_option  => method_options</tt>::
-      # <tt>:restricting_methods_to => method_options</tt>::
+      # <tt>:method_options => options</tt>::
+      # <tt>:method_option => options</tt>::
+      # <tt>:options  => options</tt>::
+      # <tt>:restricting_methods_to => options</tt>::
       #   By default, searches for public instance methods. Specify one or more
       #   of the following options for alternatives. You can combine any of the
       #   <tt>:public</tt>, <tt>:protected</tt>, and <tt>:private</tt>, as well as
@@ -90,7 +91,9 @@ module Aquarium
       # +Derived+ class that is defined in the +Base+ class, you won't find it!
       #
       def find options = {}
-        init_specification options, CANONICAL_OPTIONS
+        init_specification options, CANONICAL_OPTIONS do
+          finish_specification_initialization 
+        end
         return Aquarium::Finders::FinderResult.new if nothing_to_find?
         types_and_objects = input_types + input_objects
         method_names_or_regexps = input_methods
@@ -108,28 +111,25 @@ module Aquarium
   
       NIL_OBJECT = MethodFinder.new unless const_defined?(:NIL_OBJECT)
 
-      # TODO move Pointcut's options to here.
-      CANONICAL_OPTIONS = {
-        "types"   => %w[type for_type for_types on_type on_types in_type in_types within_type within_types],
+      # TODO remove (or deprecate) the "options" option!
+      METHOD_FINDER_CANONICAL_OPTIONS = {
         "objects" => %w[object for_object for_objects on_object on_objects in_object in_objects within_object within_objects],
         "methods" => %w[method within_method within_methods calling invoking invocations_of calls_to sending_message_to sending_messages_to],
-        "options" => %w[method_options method_option restricting_methods_to] 
+        "method_options" => %w[options method_option restricting_methods_to] 
       }
       
-      %w[types objects methods].each do |key|
-        CANONICAL_OPTIONS["exclude_#{key}"] = CANONICAL_OPTIONS[key].map {|x| "exclude_#{x}"}
+      %w[objects methods].each do |key|
+        METHOD_FINDER_CANONICAL_OPTIONS["exclude_#{key}"] = METHOD_FINDER_CANONICAL_OPTIONS[key].map {|x| "exclude_#{x}"}
       end
-      CANONICAL_OPTIONS["methods"].dup.each do |synonym|
-        CANONICAL_OPTIONS["methods"] << "#{synonym}_methods_matching"
+      METHOD_FINDER_CANONICAL_OPTIONS["methods"].dup.each do |synonym|
+        if synonym =~ /methods?$/
+          METHOD_FINDER_CANONICAL_OPTIONS["methods"] << "#{synonym}_matching"
+        else
+          METHOD_FINDER_CANONICAL_OPTIONS["methods"] << "#{synonym}_methods_matching"
+        end
       end
       
-      ALL_ALLOWED_OPTIONS = CANONICAL_OPTIONS.keys.inject([]) {|ary,i| ary << i << CANONICAL_OPTIONS[i]}.flatten
-
-      ALL_ALLOWED_OPTION_SYMBOLS = ALL_ALLOWED_OPTIONS.map {|o| o.intern}
-         
-      def all_allowed_option_symbols
-        ALL_ALLOWED_OPTION_SYMBOLS
-      end
+      CANONICAL_OPTIONS = METHOD_FINDER_CANONICAL_OPTIONS.merge(Aquarium::Finders::TypeFinder::TYPE_FINDER_CANONICAL_OPTIONS)
 
       RECOGNIZED_METHOD_OPTIONS = {
         "all"       => %w[all_methods],
@@ -200,8 +200,8 @@ module Aquarium
         Aquarium::Finders::FinderResult.new types_and_objects_to_matched_methods.merge(:not_matched => types_and_objects_not_matched)
       end
   
-      def init_type_specific_specification original_options, options_hash
-        @specification[:options] = MethodFinder.init_method_options(@specification[:options]) if @specification[:options]
+      def finish_specification_initialization
+        @specification[:method_options] = MethodFinder.init_method_options(@specification[:method_options]) if @specification[:method_options]
         extra_validation
       end
       
@@ -231,7 +231,7 @@ module Aquarium
       end
   
       def exclude_ancestor_methods?
-        @specification[:options].include?(:exclude_ancestor_methods)
+        @specification[:method_options].include?(:exclude_ancestor_methods)
       end
       
       private
@@ -273,7 +273,7 @@ module Aquarium
         is_type = Aquarium::Utils::TypeUtils.is_type?(type_or_object)
         scope_prefixes = []
         class_instance_prefixes = []
-        @specification[:options].each do |opt, value|
+        @specification[:method_options].each do |opt, value|
           opt_string = opt.to_s
           case opt_string
           when "public", "private", "protected" 
@@ -314,7 +314,7 @@ module Aquarium
       end
   
       def extra_validation 
-        method_options = @specification[:options]
+        method_options = @specification[:method_options]
         return if method_options.nil?
         if method_options.include?(:singleton) && 
           (method_options.include?(:class) || method_options.include?(:public) ||

data/lib/aquarium/finders/type_finder.rb

@@ -13,8 +13,31 @@ module Aquarium
     class TypeFinder
       include Aquarium::Utils::ArrayUtils
       include Aquarium::Utils::TypeUtils
+      include Aquarium::Utils::OptionsUtils
 
-      TYPES_SYNONYMS = %w[name names type types]
+      def self.add_ancestors_and_descendents_option_variants_for option, options_hash
+        all_variants = options_hash[option].dup
+        options_hash["#{option}_and_descendents"] = all_variants.map {|x| "#{x}_and_descendents"}
+        options_hash["#{option}_and_ancestors"]   = all_variants.map {|x| "#{x}_and_ancestors"}
+      end
+      
+      TYPE_FINDER_CANONICAL_OPTIONS = {
+        "types" => %w[type class classes module modules name names],
+      }
+      # Add the ancestors and descendents first, then add all the preposition and exclude variants, so the latter
+      # are added to the former...
+      TYPE_FINDER_CANONICAL_OPTIONS.keys.dup.each do |type_option|
+        add_ancestors_and_descendents_option_variants_for type_option, TYPE_FINDER_CANONICAL_OPTIONS
+      end
+      TYPE_FINDER_CANONICAL_OPTIONS.keys.dup.each do |type_option|
+        add_prepositional_option_variants_for type_option, TYPE_FINDER_CANONICAL_OPTIONS
+        add_exclude_options_for               type_option, TYPE_FINDER_CANONICAL_OPTIONS
+      end
+      
+      CANONICAL_OPTIONS = TYPE_FINDER_CANONICAL_OPTIONS.dup
+      
+      canonical_options_given_methods CANONICAL_OPTIONS
+      canonical_option_accessor CANONICAL_OPTIONS
       
       # Usage:
       #  finder_result = TypeFinder.new.find [options => [...] ]
@@ -90,54 +113,37 @@ module Aquarium
       # Note: a common idiom in aspects is to include descendents of a type, but not the type
       # itself. You can do as in the following example:
       #   <tt>... :type_and_descendents => "Foo", :exclude_type => "Foo" 
-      # TODO: Use the new OptionsUtils.
+      # 
       def find options = {}
-        result   = Aquarium::Finders::FinderResult.new
-        excluded = Aquarium::Finders::FinderResult.new
-        unknown_options = []
-        input_type_nil = false
-        noop = false
-        options.each do |option, value|
-          unless TypeFinder.is_recognized_option option
-            unknown_options << option
-            next
-          end
-          if value.nil?
-            input_type_nil = true
-            next
-          end
-          noop = value if option == :noop
-          next if noop
-          if option.to_s =~ /^exclude_/
-            excluded << find_matching(value, option)
-          else
-            result << find_matching(value, option)
-          end
-        end
-        handle_errors unknown_options, input_type_nil
-        result - excluded
+        init_specification options, CANONICAL_OPTIONS
+        result = do_find_types
+        unset_specification
+        result 
       end
   
       
       protected
 
-      def handle_errors unknown_options, input_type_nil
-        message = ""
-        message += "Unknown options: #{unknown_options.inspect}. " unless unknown_options.empty?
-        message += "Input type specification can't be nil! " if input_type_nil
-        raise Aquarium::Utils::InvalidOptions.new(message) unless message.empty?
+      # Hack. Since the finder could be reused, unset the specification created by #find.
+      def unset_specification
+        @specification = {}
       end
-
-      def self.is_recognized_option option_or_symbol
-        TYPES_SYNONYMS.each do |t|
-          ['', "exclude_"].each do |excl| 
-            return true if ["#{excl}#{t}", "#{excl}#{t}_and_descendents", "#{excl}#{t}_and_ancestors"].include?(option_or_symbol.to_s)
+      
+      def do_find_types
+        result   = Aquarium::Finders::FinderResult.new
+        excluded = Aquarium::Finders::FinderResult.new
+        return result if noop
+        @specification.each do |option, types|
+          next unless TYPE_FINDER_CANONICAL_OPTIONS.keys.include?(option.to_s)
+          next if types.nil? or types.empty?
+          target_result = option.to_s =~ /^exclude_/ ? excluded : result
+          types.each do |value|
+            target_result << find_matching(value, option)
           end
         end
-        return true if option_or_symbol.to_s.eql?("noop")
-        false
+        result - excluded
       end
-  
+      
       def find_matching regexpes_or_names, option
         result = Aquarium::Finders::FinderResult.new
         expressions = make_array regexpes_or_names

data/lib/aquarium/utils/array_utils.rb

@@ -7,22 +7,23 @@ module Aquarium
   
       # Return an array containing the input item or list of items. If the input
       # is an array, it is returned. In all cases, the constructed array is a
-      # flattened version of the input and any nil elements are removed by #strip_nils.
+      # flattened version of the input and any nil elements are removed by #strip_array_nils.
       # Note that this behavior effectively converts +nil+ to +[]+.
       def make_array *value_or_enum
         ArrayUtils.make_array value_or_enum
       end
 
       def self.make_array *value_or_enum
-        strip_nils do_make_array(value_or_enum)
+        strip_array_nils do_make_array(value_or_enum)
       end
       
       # Return a copy of the input array with all nils removed.
-      def strip_nils array
-        ArrayUtils.strip_nils array
+      def strip_array_nils array
+        ArrayUtils.strip_array_nils array
       end
   
-      def self.strip_nils array
+      # Return a copy of the input array with all nils removed.
+      def self.strip_array_nils array
         array.to_a.compact
       end
   

data/lib/aquarium/utils/default_logger.rb

@@ -6,8 +6,9 @@ module Aquarium
     # Individual objects may chose to create their own loggers.
     module DefaultLogger
       
+      DEFAULT_SEVERITY_LEVEL = Logger::Severity::WARN
       @@default_logger = Logger.new STDERR
-      @@default_logger.level = Logger::Severity::WARN
+      @@default_logger.level = DEFAULT_SEVERITY_LEVEL
       
       def self.logger
         @@default_logger

data/lib/aquarium/utils/options_utils.rb

@@ -4,44 +4,88 @@ require 'aquarium/utils/default_logger'
 module Aquarium
   module Utils
 
-    # Support parsing and processing of key-value pairs of options.
-    # Types including this module must define the following methods (see Pointcut for an example):
-    #   <tt>all_allowed_option_symbols</tt>
-    #     Return an array of all allowed options as symbols.
-    #   <tt>init_type_specific_specification(original_options, options_hash)</tt>
-    #     Called to perform any final options handling unique for the type (optional).
-    # In addition, including types should have their <tt>initialize</tt> methods calls this module's
-    # <tt>init_specification</tt> to do the options processing.
+    # Support parsing and processing of key-value pairs of options, where the values are always converted
+    # to sets.
+    # Types including this module should have their <tt>initialize</tt> methods call this module's
+    #   <tt>init_specification</tt> 
+    # to do the options processing. See its documentation for more details.
+    #
+    # Several class methods are included in including types for defining convenience instance methods.
+    # for options +:foo+ and +:bar+, calling:
+    #   <tt>canonical_options_given_methods :foo, :bar</tt>
+    # will define several methods for each option specified, e.g.,:
+    #   <tt>foo_given? # => returns true if a value was specified for the :foo option</tt>
+    #   <tt>foo_given  # => returns the value of @specification[:foo]</tt>
+    #   <tt>bar_given? # etc.
+    #   <tt>bar_given
+    # If you would like corresponding reader and writer methods, pass a list of the keys for which you want these
+    # methods defined to
+    #   <tt>canonical_option_reader   :foo, :bar   # analogous to attr_reader
+    #   <tt>canonical_option_writer   :foo, :bar   # analogous to attr_writer
+    #   <tt>canonical_option_accessor :foo, :bar   # analogous to attr_accessor
+    # For all of these methods, you can also pass CANONICAL_OPTIONS (discussed below) to define methods
+    # for all of the "canonical" options. _E.g.,_
+    #   <tt>canonical_option_accessor CANONICAL_OPTIONS
+    #
+    # These methods are not defined by default to prevent accidentally overriding other methods that you might
+    # have defined with the same names. Also, note that the writer methods will convert the inputs to sets,
+    # following the conventions for the options and the readers will return the sets. If you want different handling,
+    # you'll have to provide custom implementations. Note that special-case accessor methods are already defined 
+    # for the :noop and :logger options (discussed below) where the writers expect single values, not sets, and the
+    # readers return the single values.
+    # Finally, these +canonical_option_*+ methods should only be called with the *keys* for the +CANONICAL_OPTIONS+.
+    # The keys are considered the "canonical options", while the values for the keys are synonyms that can be used instead.
     #
     # This module also defines several universal options that will be available to all types that include this module:
-    # <tt>:logger => options_hash[:logger] || default system-wide Logger</tt>
-    #   A standard library Logger used for any messages. A default system-wide logger is used otherwise.
+    # <tt>:logger</tt>
+    #   A Ruby standard library Logger used for any messages. A default system-wide logger is used otherwise.
     #   The corresponding <tt>logger</tt> and <tt>logger=</tt> accessors are defined.
     #
-    # <tt>:logger_stream => options_hash[:logger_stream]</tt>
+    # <tt>:logger_stream</tt>
     #   An an alternative to defining the logger, you can define just the output stream where log output will be written.
     #   If this option is specified, a new logger will be created for the instance with this output stream.
-    #   There is no corresponding accessors; use the corresponding methods on the <tt>logger</tt> object instead.
+    #   There are no corresponding accessors; use the appropriate methods on the <tt>logger</tt> object instead.
     #
-    # <tt>:severity => options_hash[:severity]</tt>
-    #   The logging severity level, one of the Logger::Severity values or the corresponding integer value.
+    # <tt>:severity</tt>
+    #   The logging severity level, one of the Logger::Severity values or a corresponding integer value.
     #   If this option is specified, a new logger will be created for the instance with this output stream.
-    #   There is no corresponding accessors; use the corresponding methods on the <tt>logger</tt> object instead.
+    #   There are no corresponding accessors; use the corresponding methods on the <tt>logger</tt> object instead.
     #
     # <tt>:noop => options_hash[:noop] || false</tt>
     #   If true, don't do "anything", the interpretation of which will vary with the type receiving the option.
-    #   For example, a type might go through some initialization, such as parsng its argument list, but
-    #   do nothing after that. Primarily useful for debugging.    
+    #   For example, a type might go through some initialization, such as parsng its options, but
+    #   do nothing after that. Primarily useful for debugging and testing.    
     #   The value can be accessed through the <tt>noop</tt> and <tt>noop=</tt> accessors.
+    #
     module OptionsUtils
+      include SetUtils
+      include ArrayUtils
       
       def self.universal_options
         [:logger_stream, :logger, :severity, :noop]
       end
       
-      def init_specification options, canonical_options, &optional_block
+      def self.universal_prepositions
+        [:for, :on, :in, :within]
+      end
+
+      attr_reader :specification
+
+      # Class #initialize methods call this method to process the input options.
+      # Pass an optional block to the method that takes no parameters if you want 
+      # to do additional processing of the options before init_specification validates 
+      # the options. The block will have access to the @specification hash built up by
+      # init_specification and to a new attribute @original_options, which will be a 
+      # copy of the original options passed to init_specification (it will be either a 
+      # hash or an array). 
+      # Finally, if the block returns a value or an array of values, they will be 
+      # treated as keys to ignore in the options when they are validated. This is a 
+      # way of dynamically treating an option as valid that can't be known in advance.
+      # (See Aspect and Pointcut for examples of this feature in use.)
+      def init_specification options, canonical_options, additional_allowed_options = []
         @canonical_options = canonical_options
-        @original_options = options.dup unless options.nil?
+        @additional_allowed_options = additional_allowed_options.map{|x| x.respond_to?(:intern) ? x.intern : x}
+        @original_options = options.nil? ? {} : options.dup 
         @specification = {}
         options ||= {} 
         options_hash = hashify options
@@ -51,39 +95,21 @@ module Aquarium
             ary << options_hash[o.intern] if options_hash[o.intern]
             ary
           end
-          @specification[key.intern] = Set.new(make_array(all_related_options))
+          @specification[key.intern] = Set.new(all_related_options.flatten)
         end
-
-        universal_options = {
-          :logger_stream => options_hash[:logger_stream],
-          :severity      => options_hash[:severity],
-          :noop          => options_hash[:noop] || false
-        }
-
-        set_logger_if_logger_or_stream_specified universal_options, options_hash 
-        set_logger_severity_if_specified         universal_options, options_hash 
-        set_logger_if_not_specified              universal_options, options_hash 
         
         OptionsUtils::universal_options.each do |uopt| 
-          @specification[uopt] = Set.new([universal_options[uopt]]) unless universal_options[uopt].nil?
+          @specification[uopt] = Set.new(make_array(options_hash[uopt])) unless options_hash[uopt].nil? 
         end
-        init_type_specific_specification @original_options, options_hash, &optional_block
-        validate_options options_hash
-      end
-      
-      [:logger, :noop].each do |name|
-        module_eval(<<-EOF, __FILE__, __LINE__)
-          def #{name}
-            @specification[:#{name}].to_a.first
-          end
-          def #{name}= value
-            @specification[:#{name}] = Set.new([value])
-          end
-        EOF
-      end
-      
-      # Override for type-specific initialization
-      def init_type_specific_specification original_options, options_hash, &optional_block
+        @specification[:noop] ||= Set.new([false])
+        set_logger_if_stream_specified     
+        set_logger_severity_if_specified   
+        set_default_logger_if_not_specified 
+        
+        ignorables = yield if block_given?
+        ignorables = [] if ignorables.nil? 
+        ignorables = [ignorables] unless ignorables.kind_of? Array
+        validate_options(options_hash.reject {|k,v| ignorables.include?(k)})
       end
       
       def hashify options
@@ -104,33 +130,118 @@ module Aquarium
         raise Aquarium::Utils::InvalidOptions.new("Unknown options specified: #{unknowns.inspect}") if unknowns.size > 0
       end
   
-      protected
-    
-      def set_logger_if_logger_or_stream_specified universal_options, options_hash 
-        if not options_hash[:logger].nil?
-          universal_options[:logger] = options_hash[:logger]
-        elsif not options_hash[:logger_stream].nil?
-          universal_options[:logger] = Logger.new options_hash[:logger_stream]
-        end
+      [:logger, :noop].each do |name|
+        module_eval(<<-EOF, __FILE__, __LINE__)
+          def #{name}
+            @specification[:#{name}].kind_of?(Set) ? @specification[:#{name}].to_a.first : @specification[:#{name}]
+          end
+          def #{name}= value
+            @specification[:#{name}] = make_set(make_array(value))
+          end
+        EOF
       end
     
-      def set_logger_severity_if_specified universal_options, options_hash 
-        unless options_hash[:severity].nil?
-          unless universal_options[:logger].nil?
-            universal_options[:logger].level = options_hash[:severity]
-          else
-            universal_options[:logger] = Logger.new STDERR
-            universal_options[:logger].level = options_hash[:severity]
+      module ClassMethods
+        def canonical_option_reader *canonical_option_key_list
+          return if canonical_option_key_list.nil? or canonical_option_key_list.empty?
+          keys = determine_options_for_accessors canonical_option_key_list
+          keys.each do |name|
+            define_method(name) do 
+              @specification[name]
+            end
+          end
+        end
+        def canonical_option_writer *canonical_option_key_list
+          return if canonical_option_key_list.nil? or canonical_option_key_list.empty?
+          keys = determine_options_for_accessors canonical_option_key_list
+          keys.each do |name|
+            define_method("#{name}=") do |value|
+              @specification[name] = make_set(make_array(value))
+            end
+          end
+        end
+        def canonical_option_accessor *canonical_option_key_list
+          canonical_option_reader *canonical_option_key_list
+          canonical_option_writer *canonical_option_key_list
+        end
+      
+        def canonical_options_given_methods canonical_options
+          keys = canonical_options.respond_to?(:keys) ? canonical_options.keys : canonical_options 
+          (keys + OptionsUtils::universal_options).each do |name|
+            module_eval(<<-EOF, __FILE__, __LINE__)
+              def #{name}_given
+                @specification[:#{name}]
+              end
+  
+              def #{name}_given?
+                not (#{name}_given.nil? or #{name}_given.empty?)
+              end
+            EOF
+          end
+        end
+
+        # Service method that adds a new canonical option and corresponding array with 
+        # "exclude_" prepended to all values. The new options are added to the input hash.
+        def add_exclude_options_for option, options_hash
+          all_variants = options_hash[option].dup
+          options_hash["exclude_#{option}"] = all_variants.map {|x| "exclude_#{x}"}
+        end
+
+        # Service method that adds a new canonical option and corresponding array with 
+        # "preposition" prefixes, e.g., "on_", "for_", etc. prepended to all values. 
+        # The new options are added to the input hash.
+        def add_prepositional_option_variants_for option, options_hash
+          all_variants = options_hash[option].dup + [option]
+          OptionsUtils.universal_prepositions.each do |prefix|
+            all_variants.each do |variant|
+              options_hash[option] << "#{prefix}_#{variant}" 
+            end
           end
         end
+
+        protected
+        def determine_options_for_accessors canonical_option_key_list
+          keys = canonical_option_key_list
+          if canonical_option_key_list.kind_of?(Array) and canonical_option_key_list.size == 1
+            keys = canonical_option_key_list[0]
+          end
+          if keys.respond_to? :keys
+            keys = keys.keys
+          end
+          keys
+        end
+      end
+      
+      def self.append_features clazz
+        super
+        ClassMethods.send :append_features, (class << clazz; self; end)
+      end
+  
+      protected
+    
+      def all_allowed_option_symbols
+        @canonical_options.to_a.flatten.map {|o| o.intern} + @additional_allowed_options
+      end
+      
+      # While it's tempting to use the #logger_stream_given?, etc. methods, they will only exist if the
+      # including class called canonical_options_given_methods!
+      def set_logger_if_stream_specified 
+        return if @specification[:logger_stream].nil? or @specification[:logger_stream].empty?
+        self.logger = Logger.new @specification[:logger_stream].to_a.first
+        self.logger.level = DefaultLogger::DEFAULT_SEVERITY_LEVEL
       end
     
-      def set_logger_if_not_specified universal_options, options_hash 
-        if universal_options[:logger].nil?
-          universal_options[:logger] = DefaultLogger.logger
-        end 
+      def set_logger_severity_if_specified 
+        return if @specification[:severity].nil? or @specification[:severity].empty?
+        if self.logger.nil?
+          self.logger = Logger.new STDERR
+        end
+        self.logger.level = @specification[:severity].to_a.first
       end
     
+      def set_default_logger_if_not_specified 
+        self.logger ||= DefaultLogger.logger
+      end
     end
   end
 end