utilrb 1.0 → 1.1

data/lib/utilrb/hash/to_s.rb

@@ -1,8 +1,11 @@
+require 'utilrb/enumerable/to_s_helper'
 class Hash
     # Displays hashes as { a => A, b => B, ... } instead of the standard #join
     # Unlike #inspect, it calls #to_s on the elements too
     def to_s
-	"{" << map { |k, v| "#{k} => #{v}" }.join(", ") << "}"
+	EnumerableToString.to_s_helper(self, '{', '}') do |k, v| 
+	    "#{k} => #{v}" 
+	end
     end
 end
 

data/lib/utilrb/kernel/options.rb

@@ -6,8 +6,8 @@ module Kernel
     # converted to symbols for consistency.
     #
     # The following rules apply:
-    #	* if a hash is given, non-nil values are treated as default values.
-    #	* an array is equivalent to a hash where all values are 'nil'
+    #   * if a hash is given, non-nil values are treated as default values.
+    #   * an array is equivalent to a hash where all values are 'nil'
     #
     # See #validate_options and #filter_and_validate_options
     #
@@ -54,7 +54,7 @@ module Kernel
     end
 
     # call-seq:
-    #	validate_option(options, name, required, message) { |v| ... }
+    #	validate_option(options, name, required, message) { |v| ... }
     #	validate_option(options, name, required, message)
     #
     # Validates option +name+ in the +options+ hash. If required is true,

data/lib/utilrb/logger/forward.rb

@@ -1,9 +1,13 @@
 class Logger
     # Forward logger output methods to the logger attribute, so that
     # we can do
+    #   module MyModule
+    #     extend Logger::Forward
+    #   end
     #	MyModule.debug "debug_info"
     # instead of 
     #   MyModule.logger.debug "debug_info"
+    # 
     module Forward
         [ :debug, :info, :warn, :error, :fatal, :unknown ].each do |level|
             class_eval <<-EOF

data/lib/utilrb/module/ancestor_p.rb

@@ -12,12 +12,12 @@ class Module
 	#   singleton.has_ancestor?(MyClass) # => true 
 	#
 	def has_ancestor?(klass)
-	    self == klass || self < klass || (is_singleton? && superclass.has_ancestor?(klass))
+	    self <= klass || (is_singleton? && superclass.has_ancestor?(klass))
 	end
     end
     Utilrb.unless_faster do
 	def has_ancestor?(klass) # :nodoc:
-	    self == klass || self < klass || superclass == klass || superclass < klass
+	    self <= klass || superclass == klass || superclass < klass
 	end
     end
 end

data/lib/utilrb/module/attr_enumerable.rb

@@ -1,14 +1,27 @@
 require 'utilrb/object/attribute'
 
 class Module
-    # Define 'name' to be a read-only enumerable attribute. The method
-    # defines a +attr_name+ read-only attribute and an enumerator method 
-    # each_#{name}. +init_block+ is used to initialize the attribute.
+    # Support for attributes that are enumerables. This methods defines two
+    # methods:
+    #   obj.attr_name # => enumerable
+    #   obj.each_name(key = nil) { |value| ... } # => obj
     #
-    # The enumerator method accepts a +key+ argument. If the attribute is
-    # a key => enumerable map, then the +key+ attribute can be used to iterate
-    # 
-    # +enumerator+ is the name of the enumeration method
+    # The first one returns the enumerable object itself. The second one
+    # iterates on the values in attr_name. If +key+ is not nil, then #attr_name
+    # is supposed to be a hash of enumerables, and +key+ is used to select the
+    # enumerable to iterate on. 
+    #
+    # The following calls are equivalent
+    #   obj.attr_name.each { |value| ... }
+    #   obj.each_name { |value| ... }
+    #
+    # And these two are equivalent:
+    #   obj.attr_name[key].each { |value| ... }
+    #   obj.each_name(key) { |value| ... }
+    #
+    # +enumerator+ is the name of the enumeration method we should use.
+    # +init_block+, if given, should return the value at which we should
+    # initialize #attr_name. 
     def attr_enumerable(name, attr_name = name, enumerator = :each, &init_block)
 	class_eval do
 	    attribute(attr_name, &init_block)
@@ -21,6 +34,7 @@ class Module
                 else
                     #{attr_name}.#{enumerator}(&iterator)
                 end
+		self
             end
         EOF
     end

data/lib/utilrb/module/attr_predicate.rb

@@ -1,8 +1,9 @@
 class Module
-    # Defines a +name+ predicate (name should end with '?'), and if writable is true
-    # a writer method which is +name+ without '?'
+    # Defines a +name?+ predicate, and if writable is true a #name= method.
+    # Note that +name+ can end with '?', in which case the ending '?' is
+    # removed.
     #
-    # The predicate reads the instance variable which is +name+ without the '?'
+    # The methods use the @name instance variable internally
     def attr_predicate(name, writable = false)
 	attr_name = name.to_s.gsub(/\?$/, '')
 	attr_reader attr_name

data/lib/utilrb/module/cached_enum.rb

@@ -0,0 +1,26 @@
+class Module
+    # Creates <tt>enum_#{name}</tt> method which returs an Enumerator object
+    # for the <tt>each_#{enum_name}</tt> method. This enumerator is created
+    # once.
+    #
+    # If +with_arg+ is true, it is supposed that the 'each_' method requires
+    # one argument, which is given in argument of the 'enum' method. In that
+    # case, an enumerator is created for each argument
+    def cached_enum(enum_name, name, with_arg)
+	if with_arg
+	    class_eval <<-EOD
+		def enum_#{name}(arg)
+		    @enum_#{name} ||= Hash.new
+		    @enum_#{name}[arg] ||= enum_for(:each_#{enum_name}, arg)
+		end
+		EOD
+	else
+	    class_eval <<-EOD
+		def enum_#{name}
+		    @enum_#{name} ||= enum_for(:each_#{enum_name})
+		end
+		EOD
+	end
+    end
+end
+

data/lib/utilrb/module/define_method.rb

@@ -16,7 +16,7 @@ class Module
     #	define_method_with_block('my_method') do |block, *args|
     #	end
     #
-    # +block+ is +nil+ if no block is given on the method call
+    # +block+ is +nil+ if no block is given during the method call
     #
     def define_method_with_block(name, &mdef)
 	class_eval <<-EOD

data/lib/utilrb/module/include.rb

@@ -6,11 +6,11 @@ class Module
     # Includes a module in this one, with support for class extensions
     #
     # If a module defines a ClassExtension submodule, then 
-    #  * if it is included in a module, the target's ClassExtension
-    #    module includes the source ClassExtension (and if there is no
-    #    ClassExtension in the target, it is created)
-    #  * if it is included in a Class, the ClassExtension module
-    #    extends the class.
+    # * if it is included in a module, the target's ClassExtension
+    #   module includes the source ClassExtension (and if there is no
+    #   ClassExtension in the target, it is created)
+    # * if it is included in a Class, the ClassExtension module
+    #   extends the class.
     def include(mod)
 	__instance_include__ mod
 	return unless mod.const_defined?(:ClassExtension)

data/lib/utilrb/module/inherited_enumerable.rb

@@ -15,37 +15,54 @@ class Module
             class_eval <<-EOF
             def each_#{name}(key = nil, uniq = true)
 		if key
-		    if #{attribute_name}.has_key?(key)
-			yield(#{attribute_name}[key])
-			return self if uniq
+		    for klass in ancestors
+			if klass.instance_variable_defined?(:@#{attribute_name})
+			    if klass.#{attribute_name}.has_key?(key)
+				yield(klass.#{attribute_name}[key])
+				return self if uniq
+			    end
+			end
+		    end
+		elsif !uniq
+		    for klass in ancestors
+			if klass.instance_variable_defined?(:@#{attribute_name})
+			    klass.#{attribute_name}.#{options[:enum_with]} { |el| yield(el) }
+			end
 		    end
-		elsif uniq
-		    @enum_#{name}_uniq ||= enum_uniq(:each_#{name}, nil, false) { |k, v| k }
-		    @enum_#{name}_uniq.each { |el| yield(el) }
-		    return self
 		else
-                    #{attribute_name}.#{options[:enum_with]} { |el| yield(el) }
-		end
-		if superclass = ancestors[1..-1].find { |k| k.respond_to?(:each_#{name}) }
-		    superclass.each_#{name}(key, uniq) { |el| yield(el) }
+		    seen = Set.new
+		    for klass in ancestors
+			if klass.instance_variable_defined?(:@#{attribute_name})
+			    klass.#{attribute_name}.#{options[:enum_with]} do |el| 
+				unless seen.include?(el.first)
+				    seen << el.first
+				    yield(el)
+				end
+			    end
+			end
+		    end
+
 		end
                 self
             end
             def has_#{name}?(key)
-                return true if #{attribute_name}[key]
-		if superclass = ancestors[1..-1].find { |k| k.respond_to?(:has_#{name}) }
-		    superclass.has_#{name}(key)
+		for klass in ancestors
+		    if klass.instance_variable_defined?(:@#{attribute_name})
+			return true if klass.#{attribute_name}.has_key?(key)
+		    end
 		end
+		false
             end
             EOF
         else
             class_eval <<-EOF
-            def each_#{name}(&iterator)
-                #{attribute_name}.#{options[:enum_with]}(&iterator) if #{attribute_name}
-		if superclass = ancestors[1..-1].find { |k| k.respond_to?(:each_#{name}) }
-		    superclass.each_#{name} { |el| yield(el) }
+            def each_#{name}
+		for klass in ancestors
+		    if klass.instance_variable_defined?(:@#{attribute_name})
+			klass.#{attribute_name}.#{options[:enum_with]} { |el| yield(el) }
+		    end
 		end
-                self
+		self
             end
             EOF
         end
@@ -69,38 +86,80 @@ class Module
     # define a +each_value+ method). +attribute_name+ defines the attribute
     # name. +init+ is a block called to initialize the attribute. 
     # Valid options in +options+ are: 
-    # map:: the attribute should respond to +[]+. The enumeration method takes two 
-    #	    arguments, +key+ and +uniq+. If +key+ is given, we iterate on the values
-    #	    given by <tt>attribute[key]</tt>. If +uniq+ is true, the enumeration will
-    #	    yield at most one value for each +key+ found (so, if both +key+ and +uniq+ are
-    #	    given, the enumeration yields at most one value)
+    # map:: 
+    #   If true, the attribute should respond to +[]+. In that case, the
+    #   enumeration method is each_value(key = nil, uniq = false) If +key+ is
+    #   given, we iterate on the values given by <tt>attribute[key]</tt>. If
+    #   +uniq+ is true, the enumeration will yield at most one value for each
+    #   +key+ found (so, if both +key+ and +uniq+ are given, the enumeration
+    #   yields at most one value). See the examples below
+    # enum_with:: the enumeration method of the enumerable, if it is not +each+
+    #
+    # === Example
+    # Let's define some classes and look at the ancestor chain
+    #
+    #   class A;  end
+    #   module M; end
+    #   class B < A; include M end
+    #   A.ancestors # => [A, Object, Kernel]
+    #   B.ancestors # => [B, M, A, Object, Kernel]
+    #
+    # ==== Attributes for which 'map' is not set
+    #
+    #   class A
+    #     inherited_enumerable("value", "values") do
+    #         Array.new
+    #     end
+    #   end
+    #   module M
+    #     inherited_enumerable("mod") do
+    #         Array.new
+    #     end
+    #   end
+    #   
+    #   A.values << 1 # => [1]
+    #   B.values << 2 # => [2]
+    #   M.mod << 1 # => [1]
+    #   b = B.new 
+    #   class << b
+    #       self.values << 3 # => [3]
+    #       self.mod << 4 # => [4]
+    #   end
+    #   M.mod << 2 # => [1, 2]
+    #   
+    #   A.enum_for(:each_value).to_a # => [1]
+    #   B.enum_for(:each_value).to_a # => [2, 1]
+    #   b.singleton_class.enum_for(:each_value).to_a # => [3, 2, 1]
+    #   b.singleton_class.enum_for(:each_mod).to_a # => [4, 1, 2]
     #
-    # For instance
+    # ==== Attributes for which 'map' is set
     #
-    #	class A 
-    #	    class_inherited_enumerable("value", "enum") { Array.new }
-    #	end
-    #	module M
-    #	    inherited_enumerable("attr") { Array.new }
-    #	end
-    #	class B < A
-    #	    include M
-    #	end
-    #	b = B.new
+    #   class A
+    #     inherited_enumerable("mapped", "map", :map => true) do
+    #         Hash.new { |h, k| h[k] = Array.new }
+    #     end
+    #   end
+    #   
+    #   A.map['name'] = 'A' # => "A"
+    #   A.map['universe'] = 42
+    #   B.map['name'] = 'B' # => "B"
+    #   B.map['half_of_it'] = 21
+    #   
+    # Let's see what happens if we don't specify the key option.  
+    #   A.enum_for(:each_mapped).to_a # => [["name", "A"], ["universe", 42]]
+    # If the +uniq+ option is set (the default), we see only B's value for 'name'
+    #   B.enum_for(:each_mapped).to_a # => [["half_of_it", 21], ["name", "B"], ["universe", 42]]
+    # If the +uniq+ option is not set, we see both values for 'name'. Note that
+    # since 'map' is a Hash, the order of keys in one class is not guaranteed.
+    # Nonetheless, we have the guarantee that values from B appear before
+    # those from A
+    #   B.enum_for(:each_mapped, nil, false).to_a # => [["half_of_it", 21], ["name", "B"], ["name", "A"], ["universe", 42]]
     #
-    #	A.enum << 1
-    #	B.enum << 2
-    #	M.attr << 1
-    #	class << b
-    #	    enum << 3
-    #	    attr << 4
-    #	end
-    #	M.attr << 2
     #
-    #	A.each_enum => 1
-    #	B.each_enum => 2, 1
-    #	b.singleton_class.each_enum => 3, 2, 1
-    #	b.singleton_class.each_attr => 4, 1, 2
+    # Now, let's see how 'key' behaves
+    #   A.enum_for(:each_mapped, 'name').to_a # => ["A"]
+    #   B.enum_for(:each_mapped, 'name').to_a # => ["B"]
+    #   B.enum_for(:each_mapped, 'name', false).to_a # => ["B", "A"]
     #
     def inherited_enumerable(name, attribute_name = name, options = Hash.new, &init)
 	singleton_class.class_eval { define_inherited_enumerable(name, attribute_name, options, &init) }

data/lib/utilrb/object/attribute.rb

@@ -39,49 +39,35 @@ end
 
 Utilrb.if_faster do
     class Object
-	# :call-seq
-	#   attribute :name => default_value
-	#   attribute(:name) { default_value }
-	#
-	# In the first form, defines a read-write attribute
-	# named 'name' with default_value for default value.
-	# In the second form, the block is called if the attribute
-	# is read before it has been ever written, and its return
-	# value is used as default value.
-	def attribute(attr_def, &init)
+	def attribute(attr_def, &init) # :nodoc:
 	    if Hash === attr_def
 		name, defval = attr_def.to_a.flatten
 	    else
 		name = attr_def
 	    end
 
-	    if is_singleton? || instance_of?(Module)
-		class_eval do
-		    attr_writer name
-		    define_method("#{name}_defval") do
-			defval || (instance_eval(&init) if init)
-		    end
+	    class_eval do
+		attr_writer name
+		if !defval && init
+		    define_method("#{name}_defval", &init)
+		else
+		    define_method("#{name}_defval") { defval }
 		end
+	    end
 
-		class_eval <<-EOD
-		def #{name}
-		    if defined? @#{name} then @#{name}
-		    else @#{name} = #{name}_defval
-		    end
-		end
-		EOD
-	    else
-		class_eval { attr_writer name }
-		define_method(name) do
-		    singleton_class.class_eval { attr_reader name }
-		    instance_variable_set("@#{name}", defval || (instance_eval(&init) if init))
+	    class_eval <<-EOD
+	    def #{name}
+		if defined? @#{name} then @#{name}
+		else @#{name} = #{name}_defval
 		end
 	    end
+	    EOD
 	end
     end
 end
 
 class Object
+    # Like #attribute, but on the singleton class of this object
     def class_attribute(attr_def, &init)
 	singleton_class.class_eval { attribute(attr_def, &init) }
     end

data/lib/utilrb/object/singleton_class.rb

@@ -7,20 +7,16 @@ end
 
 if RUBY_VERSION >= "1.9"
     class Object
-	# Returns the singleton class for this object
-	#
-	# The first element of #ancestors on the returned singleton class is
-	# the singleton class itself. A #singleton_instance accessor is also
-	# defined, which returns the object instance the class is the singleton
-	# of.
-	def singleton_class
+	def singleton_class # :nodoc:
 	    if defined? @singleton_class
 		return @singleton_class
 	    else
 		@singleton_class = class << self
 		    class << self
-			alias __ancestors__ ancestors
-			def ancestors; __ancestors__.unshift(self) end
+			alias __ancestors__ ancestors # :nodoc:
+			def ancestors # :nodoc:
+			    __ancestors__.unshift(self) 
+			end
 		    end
 		    
 		    self 
@@ -57,8 +53,10 @@ else
 			    "#{@superclass.name}!0x#{@singleton_instance.address.to_s(16)}"
 			end
 
-			alias __ancestors__ ancestors
-			def ancestors; __ancestors__.unshift(self) end
+			alias __ancestors__ ancestors # :nodoc:
+			def ancestors # :nodoc:
+			    __ancestors__.unshift(self) 
+			end
 		    end
 		end