aquarium 0.4.1 → 0.4.2

data/lib/aquarium/finders/type_finder.rb

@@ -10,24 +10,35 @@ require File.dirname(__FILE__) + '/finder_result'
 # Finds types known to the runtime environment.
 module Aquarium
   module Finders
+    # == TypeFinder
+    # Locate types.
     class TypeFinder
       include Aquarium::Utils::ArrayUtils
       include Aquarium::Utils::TypeUtils
       include Aquarium::Utils::OptionsUtils
 
-      def self.add_ancestors_and_descendents_option_variants_for option, options_hash
+      class TypeFinderResult < Aquarium::Finders::FinderResult
+        include Enumerable
+        def each
+          matched_keys.each { |x| yield x }
+        end
+      end
+      
+      def self.add_ancestors_descendents_and_nested_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"}
+        options_hash["#{option}_and_nested_types"] = 
+          all_variants.map {|x| "#{x}_and_nested_types"} + all_variants.map {|x| "#{x}_and_nested"}
       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...
+      # Add the ancestors, descendents, and nested variants 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
+        add_ancestors_descendents_and_nested_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
@@ -39,60 +50,85 @@ module Aquarium
       canonical_options_given_methods CANONICAL_OPTIONS
       canonical_option_accessor CANONICAL_OPTIONS
       
-      # Usage:
-      #  finder_result = TypeFinder.new.find [options => [...] ]
-      # where
-      # <tt>:types => types_and_type_names_and_regexps</tt>::
-      # <tt>:names => types_and_type_names_and_regexps</tt>::
-      # <tt>:type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:name  => types_and_type_names_and_regexps</tt>::
-      #   A single type or array of types, specified using any combination of the type 
-      #   name strings, the type "constants" and/or regular expessions. The four different
-      #   flags are just "sugar" for each other. 
+      # Returns a TypeFinder::TypeFinderResult, where the "matched" keys are the input 
+      # types, type names, and/or regular expressions, and objects for which matches were found and the 
+      # corresponding values are the class constant or variable pointcuts that were found.
+      # The keys in the "not_matched" part of the result are the specified types and objects
+      # for which no matches were found.
       #
-      # <tt>:types_and_descendents => types_and_type_names_and_regexps</tt>::
-      # <tt>:names_and_descendents => types_and_type_names_and_regexps</tt>::
-      # <tt>:type_and_descendents  => types_and_type_names_and_regexps</tt>::
-      # <tt>:name_and_descendents  => types_and_type_names_and_regexps</tt>::
+      # The options are as follows:
       #
-      # Same as for <tt>:types</tt> <i>etc.</i>, but also match their descendents.
+      # ==== Types
+      # A single type, type name, name regular expression, or an array of the same. (Mixed allowed.)
+      # * <tt>:types => types_and_type_names_and_regexps</tt>
+      # * <tt>:names => types_and_type_names_and_regexps</tt>
+      # * <tt>:type  => types_and_type_names_and_regexps</tt>
+      # * <tt>:name  => types_and_type_names_and_regexps</tt>
       #
-      # <tt>:types_and_ancestors => types_and_type_names_and_regexps</tt>::
-      # <tt>:names_and_ancestors => types_and_type_names_and_regexps</tt>::
-      # <tt>:type_and_ancestors  => types_and_type_names_and_regexps</tt>::
-      # <tt>:name_and_ancestors  => types_and_type_names_and_regexps</tt>::
+      # ==== Types and Descendents
+      # A single type, type name, name regular expression, or an array of the same. (Mixed allowed.)
+      # Matching types and their descendents will be found. A type that includes a module is considered
+      # a descendent, since the module would show up in that type's ancestors.
+      # * <tt>:types_and_descendents => types_and_type_names_and_regexps</tt>
+      # * <tt>:names_and_descendents => types_and_type_names_and_regexps</tt>
+      # * <tt>:type_and_descendents  => types_and_type_names_and_regexps</tt>
+      # * <tt>:name_and_descendents  => types_and_type_names_and_regexps</tt>
       #
-      # Same as for <tt>:types</tt> <i>etc.</i>, but also match their ancestors.
-      # This option will also match <tt>Class</tt>, <tt>Module</tt>, <i>etc.</>, 
+      # ==== Types and Ancestors
+      # A single type, type name, name regular expression, or an array of the same. (Mixed allowed.)
+      # Matching types and their ancestors will be found.
+      # * <tt>:types_and_ancestors => types_and_type_names_and_regexps</tt>
+      # * <tt>:names_and_ancestors => types_and_type_names_and_regexps</tt>
+      # * <tt>:type_and_ancestors  => types_and_type_names_and_regexps</tt>
+      # * <tt>:name_and_ancestors  => types_and_type_names_and_regexps</tt>
+      #
+      # ==== Types and Nested Types
+      # A single type, type name, name regular expression, or an array of the same. (Mixed allowed.)
+      # Matching types and any types nested within them will be found.
+      # * <tt>:types_and_nested_types => types_and_type_names_and_regexps</tt>
+      # * <tt>:names_and_nested_types => types_and_type_names_and_regexps</tt>
+      # * <tt>:type_and_nested_types  => types_and_type_names_and_regexps</tt>
+      # * <tt>:name_and_nested_types  => types_and_type_names_and_regexps</tt>
+      # * <tt>:types_and_nested => types_and_type_names_and_regexps</tt>
+      # * <tt>:names_and_nested => types_and_type_names_and_regexps</tt>
+      # * <tt>:type_and_nested  => types_and_type_names_and_regexps</tt>
+      # * <tt>:name_and_nested  => types_and_type_names_and_regexps</tt>
+      #
+      # Note: This option will also match <tt>Class</tt>, <tt>Module</tt>, <i>etc.</>, 
       # so use with caution!
       #
       # To get both descendents and ancestors, use both options with the same type
       # specification.
       #
-      # The "other options" include the following:
-      #
+      # ==== Exclude Types
+      # Exclude the specified type(s) from the list of matched types. 
+      # Note: These excluded types <i>won't</i> appear in the FinderResult#not_matched. 
+      # * <tt>:exclude_type  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_types => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_name  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_names => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_types_and_descendents => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_names_and_descendents => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_type_and_descendents  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_name_and_descendents  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_types_and_ancestors => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_names_and_ancestors => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_type_and_ancestors  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_name_and_ancestors  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_types_and_nested_types => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_names_and_nested_types => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_type_and_nested_types  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_name_and_nested_types  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_types_and_nested => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_names_and_nested => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_type_and_nested  => types_and_type_names_and_regexps</tt>
+      # * <tt>:exclude_name_and_nested  => types_and_type_names_and_regexps</tt>
       #
-      # <tt>:exclude_type  => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_types => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_name  => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_names => types_and_type_names_and_regexps</tt>::
-      #   Exclude the specified type or list of types from the list of matched types. 
-      #   These excluded types <b>won't</b> appear in the FinderResult#not_matched. 
-      #
-      # <tt>:exclude_types_and_descendents => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_names_and_descendents => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_type_and_descendents  => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_name_and_descendents  => types_and_type_names_and_regexps</tt>::
-      #
-      # <tt>:exclude_types_and_ancestors => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_names_and_ancestors => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_type_and_ancestors  => types_and_type_names_and_regexps</tt>::
-      # <tt>:exclude_name_and_ancestors  => types_and_type_names_and_regexps</tt>::
-      #
-      # Exclude the descendents or ancestors, as well.
-      #
-      # Because of the special sigificance of the module ("namespace") separator "::", the rules
-      # for the regular expressions are as follows. Assume that "subexp" is a "sub regular
+      # ==== Namespaces (Modules) and Regular Expressions
+      # Because of the special sigificance of the module ("namespace") separator "::", 
+      # special rules for the regular expressions apply. Normally, you can just use the
+      # "*_and_nested_types" or "*_and_nested" to match enclosed types, but if you want to
+      # be selective, note the following. First, assume that "subexp" is a "sub regular 
       # expression" that results if you split on the separator "::".
       #
       # A full regexp with no "::"::
@@ -121,8 +157,7 @@ module Aquarium
         result 
       end
   
-      
-      protected
+      private
 
       # Hack. Since the finder could be reused, unset the specification created by #find.
       def unset_specification
@@ -130,9 +165,9 @@ module Aquarium
       end
       
       def do_find_types
-        result   = Aquarium::Finders::FinderResult.new
-        excluded = Aquarium::Finders::FinderResult.new
+        result = TypeFinderResult.new
         return result if noop
+        excluded = TypeFinderResult.new
         @specification.each do |option, types|
           next unless TYPE_FINDER_CANONICAL_OPTIONS.keys.include?(option.to_s)
           next if types.nil? or types.empty?
@@ -145,7 +180,7 @@ module Aquarium
       end
       
       def find_matching regexpes_or_names, option
-        result = Aquarium::Finders::FinderResult.new
+        result = TypeFinderResult.new
         expressions = make_array regexpes_or_names
         expressions.each do |expression|
           expr = strip expression
@@ -210,34 +245,41 @@ module Aquarium
       end
   
       def finish_and_make_successful_result found, option
-        all = prettify(found + handle_ancestors_and_descendents(found, option))
+        all = prettify(found + handle_ancestors_descendents_and_nested(found, option))
         hash = make_return_hash(all)
-        Aquarium::Finders::FinderResult.new hash
+        TypeFinderResult.new hash
       end
       
       def make_failed_result name
-        Aquarium::Finders::FinderResult.new :not_matched => {name => Set.new([])}
+        TypeFinderResult.new :not_matched => {name => Set.new([])}
       end
       
-      def handle_ancestors_and_descendents types, option
+      def handle_ancestors_descendents_and_nested types, option
         result = []
-        result << add_descendents(types) if should_find_descendents(option)
         result << add_ancestors(types)   if should_find_ancestors(option)
+        result << add_descendents(types) if should_find_descendents(option)
+        result << add_nested(types)      if should_find_nested(option)
         result
       end
       
+      def add_ancestors types
+        types.inject([]) { |memo, t| memo << t.ancestors }
+      end
       def add_descendents types
         types.inject([]) { |memo, t| memo << Aquarium::Utils::TypeUtils.descendents(t) }
       end
-      def add_ancestors types
-        types.inject([]) { |memo, t| memo << t.ancestors }
+      def add_nested types
+        types.inject([]) { |memo, t| memo << Aquarium::Utils::TypeUtils.nested(t) }
       end
 
+      def should_find_ancestors option
+        option.to_s.include? "_ancestors"
+      end
       def should_find_descendents option
         option.to_s.include? "_descendents"
       end
-      def should_find_ancestors option
-        option.to_s.include? "_ancestors"
+      def should_find_nested option
+        option.to_s.include? "_nested"
       end
       
   

data/lib/aquarium/utils/array_utils.rb

@@ -8,7 +8,7 @@ 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_array_nils.
-      # Note that this behavior effectively converts +nil+ to +[]+.
+      # Note that this behavior effectively converts <tt>nil</tt> to <tt>[]</tt>.
       def make_array *value_or_enum
         ArrayUtils.make_array value_or_enum
       end

data/lib/aquarium/utils/invalid_options.rb

@@ -1,5 +1,7 @@
 module Aquarium
   module Utils
+    # == Invalid Options
+    # The exception thrown when invalid options to any API methods are detected.
     class InvalidOptions < Exception 
       def initialize *args
         super

data/lib/aquarium/utils/name_utils.rb

@@ -1,9 +1,10 @@
 require 'aquarium/utils/type_utils'
 
-# Convert various strings, symbols, object ids, etc. into valid "names" that
-# can be used as method names, etc.
 module Aquarium
   module Utils
+    # == NameUtils
+    # Convert various strings, symbols, object ids, etc. into valid "names" that
+    # can be used as method names, etc.
     module NameUtils
 
       @@char_expr_map = {

data/lib/aquarium/utils/nil_object.rb

@@ -1,10 +1,14 @@
-# One implementation of the Null Object Pattern (renamed "Nil" for Ruby).
-# All methods not defined by Object simply return the Aquarium::Utils::NilObject itself.
-# Users can subclass or add methods to instances to customize the behavior.
 
 module Aquarium
   module Utils
+    # An implementation of the Null Object Pattern (renamed "Nil" for Ruby).
+    # All methods not defined by Object simply return the Aquarium::Utils::NilObject itself.
+    # Users can subclass or add methods to instances to customize the behavior.
     class Aquarium::Utils::NilObject
+        
+      def eql? other
+        other.kind_of? NilObject
+      end
             
       def method_missing method_sym, *args
         self

data/lib/aquarium/utils/options_utils.rb

@@ -4,54 +4,64 @@ require 'aquarium/utils/default_logger'
 module Aquarium
   module Utils
 
+    # == OptionsUtils
     # Support parsing and processing of key-value pairs of options, where the values are always converted
-    # to sets.
+    # 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.
+    # #init_specification to do the options processing. See its documentation for more details.
+    #
+    # Several <i>class</i> methods are included for defining convenience <i>instance</i> methods.
+    # For example, for options <tt>:foo</tt> and <tt>:bar</tt>, calling:
+    #
+    #   canonical_options_given_methods :foo, :bar
     #
-    # 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
+    #
+    #   foo_given    # => returns the value of @specification[:foo]
+    #   foo_given?   # => returns true "foo_given" is not nil or empty.
+    #   bar_given    # etc...
+    #   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
+    # methods defined to one of the following methods:
+    #
+    #   canonical_option_reader   :foo, :bar   # analogous to attr_reader
+    #   canonical_option_writer   :foo, :bar   # analogous to attr_writer
+    #   canonical_option_accessor :foo, :bar   # analogous to attr_accessor
+    #
+    # For all of these methods, you can also pass <tt>CANONICAL_OPTIONS</tt> (discussed below) to define methods
+    # for all of the "canonical" options, <i>e.g.,</i>
+    #
+    #   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+.
+    # you'll have to provide custom implementations. 
+    #
+    # Note that special-case accessor methods are already defined for the <tt>:noop</tt> and <tt>:logger</tt>
+    # options (discussed below) where the writers expect single values, not sets, and the
+    # readers return the single values. (Yea, it's a bit inconsistent...)
+    #
+    # Finally, these <tt>canonical_option_*</tt> 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</tt>
+    # <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</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 are no corresponding accessors; use the appropriate methods on the <tt>logger</tt> object instead.
     #
-    # <tt>:severity</tt>
+    # <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 are no corresponding accessors; use the corresponding methods on the <tt>logger</tt> object instead.
     #
-    # <tt>:noop => options_hash[:noop] || false</tt>
+    # <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 options, but
     #   do nothing after that. Primarily useful for debugging and testing.    
@@ -199,7 +209,8 @@ module Aquarium
           end
         end
 
-        protected
+        private
+        
         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
@@ -217,7 +228,7 @@ module Aquarium
         ClassMethods.send :append_features, (class << clazz; self; end)
       end
   
-      protected
+      private
     
       def all_allowed_option_symbols
         @canonical_options.to_a.flatten.map {|o| o.intern} + @additional_allowed_options

data/lib/aquarium/utils/set_utils.rb

@@ -7,14 +7,14 @@ module Aquarium
       # Return a set containing the input item or list of items. If the input
       # is a set or an array, it is returned. In all cases, the constructed set is a
       # flattened version of the input and any nil elements are removed by #strip_set_nils.
-      # Note that this behavior effectively converts +nil+ to +[]+.
+      # Note that this behavior effectively converts <tt>nil</tt> to <tt>[]</tt>.
       def make_set *value_or_set_or_array
         strip_set_nils(convert_to_set(*value_or_set_or_array))
       end
 
       # Return a new set that is a copy of the input set with all nils removed.
       def strip_set_nils set
-        set.delete_if {|x| x.nil?}
+        SetUtils.strip_set_nils set
       end
   
       # Return a new set that is a copy of the input set with all nils removed.

data/lib/aquarium/utils/type_utils.rb

@@ -18,6 +18,17 @@ module Aquarium
         result.uniq
       end
       
+      def self.nested clazz
+        result = [clazz]
+        clazz.constants.each do |const|
+          mod = clazz.class_eval(const)
+          next unless is_type?(mod)
+          result << mod 
+          result << nested(mod)
+        end
+        result.flatten.uniq
+      end
+      
       protected
       
       # For JRuby classes, we have to "__x__" forms of the reflection methods that don't end in '?'. 

data/lib/aquarium/version.rb

@@ -9,7 +9,7 @@ module Aquarium
     unless defined? MAJOR
       MAJOR  = 0
       MINOR  = 4
-      TINY   = 1
+      TINY   = 2
       RELEASE_CANDIDATE = nil
       
       # RANDOM_TOKEN: 0.598704893979657