y_support 2.1.18 → 2.4.4

data/lib/y_support/name_magic.rb

@@ -1,17 +1,18 @@
 # encoding: utf-8
 
-require 'y_support'
-require 'y_support/core_ext/hash/misc'
+require_relative '../y_support'
+require_relative 'core_ext/hash/misc'
+require_relative 'literate'
 
-require_relative 'name_magic/array'
-require_relative 'name_magic/hash'
-
-# This mixin imitates Ruby constant magic and automates the named argument
-# :name, alias :ɴ (Character "ɴ", Unicode small capital N, generally stands
-# for "name" ins YSupport). One can write:
+# Module NameMagic imitates Ruby constant magic and automates the
+# named argument :name, alias :ɴ (Character "ɴ", Unicode small
+# capital N). At the same time, NameMagic provides the registry of
+# instances of the user class. In Ruby, we frequently want to keep
+# a list of instances of some classes, and NameMagic also helps
+# with this task. Simple example:
 #
 #   require 'y_support/name_magic'
-#   class Foo;
+#   class Foo
 #     include NameMagic
 #   end
 #   Bar = Foo.new
@@ -20,78 +21,162 @@ require_relative 'name_magic/hash'
 #
 #   Bar.name #=> "Bar"
 #
-# This is done by searching whole Ruby namespace for constants, via #const_magic
-# defined in the namespace mixin. (Once the object is named, its assignments to
-# other constants have no further effects.) By default, the class, in which
-# NameMagic is included acts as a namespace: holds a list of instances and their
-# names, which is often useful.
+# We can get the list of instances by:
 #
 #   Foo.instances #=> [Bar]
 #
-# It is possible to set another module as namespace:
+# Additionally, NameMagic provides two hooks: Instantiation hook
+# activates when a new instance is created, and naming hook
+# activates when the created instance is baptized. Let us set the
+# first hook, for example, as follows:
 #
-#   Quux = Module.new
-#   class FooBar
-#     include NameMagic
+#   Foo.instantiation_hook do |instance|
+#     puts "New instance of Foo with object id " +
+#           "#{instance.object_id} created!"
+#   end
+#
+# Now let us set the second hook as follows:
+#
+#   Foo.naming_hook do |name, instance|
+#     puts "Instance with object id #{instance.object_id} " +
+#          "is baptized #{name}!"
+#     name
 #   end
-#   FooBar.namespace = Quux
-#   FooBar.new name: "Baz"
-#   Quux.instances #=> [Baz]
 #
-# When subclassing the classes with NameMagic included, namespace setting does
-# not change:
+# Note that the naming hook must always return name. (This can be
+# used to censor the name on the fly, but that's beyond this basic
+# intro.) Now that we set the hooks, let us observe when do they
+# activate:
+#
+#   i = Foo.new
+#   New instance of Foo with object id 73054440 created!
+#
+#   Baz = i
+#   Instance with object id 73054440 is baptized Baz!
+#  
+# We can see that the registry of instances now registers two
+# instances:
+#
+#   Foo.instances #=> [Bar, Baz]
+#
+# NameMagic has been programmed to be simple and intuitive to use,
+# so with this little demonstration, you can start using it without
+# fear. You can find the rest of the methods provided by NameMagic
+# in the documentation.
+# 
+# However, behind the scenes, inner workings of NameMagic require
+# understanding.  The key part of NameMagic is the code that
+# searches Ruby namespace for constants. This search is done
+# automatically when necessary. It can be also explicitly initiated
+# by calling .const_magic class method, but this is rarely
+# needed. When you write "include NameMagic" in some class, three
+# things happen:
+#
+# 1. Module NameMagic is included in that class, as expected.
+# 2. Class is extended with NameMagic::ClassMethods.
+# 3. Namespace is extended with NameMagic::NamespaceMethods.
+#
+# Namespace (in the NameMagic sense) is a module that holds the
+# list of instances and their names. Typically, the user class acts
+# as its own namespace. Note that the meaning of the word
+# 'namespace' is somewhat different from its meaning in general
+# Ruby. NameMagic actually provides class method .namespace that
+# returns the namespace of the class. Consider this example:
+#
+#   require 'y_support/name_magic'
+#   class Animal
+#     include NameMagic
+#   end
+#   Animal.namespace #=> Animal
+# 
+# We can see that the namespace of Animal class is again Animal
+# class. But when we subclass it:
 #
-#   class Animal; include NameMagic end
 #   class Dog < Animal; end
 #   class Cat < Animal; end
 #   Dog.namespace #=> Animal
 #   Cat.namespace #=> Animal
+#
+# The subclasses retain Animal as their namespace. Let us continue
+# with the example:
+#
 #   Livia = Cat.new
-#   Cat.instances._names_ #=> []
-#   Animal.instances._names_ #=> [:Livia]
+#   Cat.instances #=> [Livia]
+#   Dog.instances #=> []
+#   Animal.instances #=> [Livia]
+#
+# Let us demonstrate alternative ways of creating named objects:
+#
+#   Dog.new name: :Spot
+#   Dog.new ɴ: "Rover"
+#   Cat.instances #=> [Livia]
+#   Dog.instances #=> [Spot, Rover]
+#   Animal.instances #=> [Livia, Spot, Rover]
 #
-# To make the subclasses use each their own namespace, use +#namespace!+ method:
+# Make the subclasses be their own namespaces with +#namespace!:
 #
 #   Dog.namespace!
 #   
-# NameMagic also provides an alternative way to create named objects by taking
-# care of :name (alias :ɴ) named argument of the constructor:
+# NameMagic also provides another way of naming objects by taking
+# care of :name (alias :ɴ) parameter of #new constructor:
 #
 #   Dog.new name: "Spot"
-#   Dog.new ɴ: :Rover
+#   Dog.new.name = :Rover
 #   Dog.instances._names_ #=> [:Spot, :Rover]
 #   Animal.instances._names_ #=> []
 #
-# Lastly, a name can be assigned by #name= accssor, as in
+# Note that the Dog instances above did not disappear even though
+# we did not assign them to any variables or constants. This is
+# because the instances of the classes using NameMagic, whether
+# named or not, are since their creation referred to from the
+# instance registry, which prevents them from being garbage
+# collected. To get rid of Spot and Rover, we would have to delete
+# them from the instance registry:
 #
-# <tt>o = SomeClass.new</tt>
-# <tt>o.name = "SomeName"</tt>
+#   Dog.forget "Spot"
+#   Dog.forget "Rover"
 #
-# Hook is provided for when the name magic is performed, as well as when the
-# name is retrieved.
+# Spot and Rover show their inspect string for the last time and
+# are garbage collected.
 # 
 module NameMagic
-  DEBUG = false
+  require_relative 'name_magic/array_methods'
+  require_relative 'name_magic/hash_methods'
 
-  require_relative 'name_magic/namespace_methods'
+  Array.class_exec { include ArrayMethods }
+  Hash.class_exec { include HashMethods }
+
+  require_relative 'name_magic/namespace'
   require_relative 'name_magic/class_methods'
 
   def self.included target
-    if target.is_a? Class then # decorate #new
+    if target.is_a? Class then
+      # Define target.namespace method.
       target.singleton_class.class_exec do
-        # Primer that sets the namespace of the class to self if the user has
-        # not defined otherwise when this method is first called.
+        # Primer that sets the namespace of the class to self if
+        # the user has not defined otherwise when this method is
+        # first called.
         # 
         define_method :namespace do
-          target.extend ::NameMagic::NamespaceMethods
-          define_singleton_method :namespace do target end # redefines itself
+          # The method first extends target with Namespace methods.
+          target.extend NameMagic::Namespace
+          # The method then redefines itself.
+          define_singleton_method :namespace do target end
+          # And finally calls the redefined version of itself.
           namespace
         end
       end
-      target.singleton_class.class_exec { prepend ::NameMagic::ClassMethods }
-    else # it is a Module -- infect it with this #include
-      orig, this = target.method( :included ), method( :included )
-      target.define_singleton_method :included do |m| this.( m ); orig.( m ) end
+      # Prepend NameMagic::ClassMethod to class << target.
+      target.singleton_class.class_exec do
+        prepend NameMagic::ClassMethods
+      end
+    else # Target is a Module, infect it with this #include
+      original_included_method = target.method :included
+      this_method = method :included
+      target.define_singleton_method :included do |target|
+        this_method.( target )
+        original_included_method.( target )
+      end
     end
   end # self.included
 
@@ -101,67 +186,143 @@ module NameMagic
     self.class.namespace
   end
 
-  # Retrieves the instance's name not prefixed by the namespace as a symbol.
-  # Underlines (+#_name_+) distinguish this method from +#name+ method, which
-  # returns full name string for compatibility with vanilla Ruby +Module#name+.
+  # Retrieves the demodulized instance's name as a symbol.
+  # "Demodulized" means that if the full name is "Foo::Bar", only
+  # :Bar is returned. Underlines (+#_name_+) distinguish this
+  # method from +#name+ method, which returns full name string for
+  # compatibility with vanilla Ruby +Module#name+.
   # 
   def _name_
     self.class.const_magic
     __name__ or ( yield self if block_given? )
   end
   alias ɴ _name_
-  # FIXME: Delete the line below! Do it!  Make #name return #full_name, as compatible with Class#name behavior!!!
+  # FIXME: Delete the line below! Do it!  Make #name return
+  # #full_name, as compatible with Class#name behavior!!!
   alias name _name_
 
-  # Returns the instance's full name, a string in the style of those returned
-  # by +Module#name+ method, eg. "Namespace::Name".
+  # Returns the instance's full name, a string in the style of
+  # those returned by +Module#name+ method, eg. "Namespace::Name".
   # 
   def full_name
-    "#{namespace.name || namespace.inspect}::#{namespace.instances[ self ]}"
+    # FIXME: This method cannot work until Namespace#const_magic
+    # starts noticing not just constant names, as it does now,
+    # but also names of the modules those constants are in. This
+    # is no simple task.
+    #
+    # The code below is the closest approximation, yet still
+    # patently wrong.
+    [ namespace.name || namespace.inspect,
+      namespace.instances[ self ]
+    ].join "::"
   end
-  # FIXME: Uncomment the line below! Do it! Make #name return #full_name, as compatible with Class#name behavior!!!
-  # alias name full_name
+  # FIXME: Uncomment the line below! Do it! Make #name return
+  # #full_name, as compatible with Class#name behavior!!!  alias
+  # name full_name
   
-  # Retrieves the instance name. Does not trigger #const_magic before doing so.
+  # Retrieves the instance name. Does not trigger #const_magic
+  # before doing so.
   # 
   def __name__
-    ɴ = self.class.__instances__[ self ]
-    namespace.name_get_hook.( ɴ ) if ɴ
+    self.class.__instances__[ self ]
   end
 
-  # Names an instance, cautiously (ie. no overwriting of existing names).
+  # Names the receiver, while rejecting names already in use by
+  # another instance. If nil is supplied as an argument, unnames
+  # the instance. (This method does not trigger const_magic.)
   # 
   def name=( name )
-    old_ɴ = namespace.__instances__[ self ]         # previous name
-    if name.nil? then
-      namespace.__instances__.update( self => nil ) # unname in @instances
-      namespace.send :remove_const, old_ɴ if old_ɴ  # remove namespace const.
-    else
-      ɴ = honor_name_set_hooks( name, old_ɴ )
-      return if old_ɴ == ɴ                  # already named as required
-      fail NameError, "Name '#{ɴ}' already exists in #{namespace} namespace!" if
-        self.class.__instances__.rassoc( ɴ )
-      namespace.__forget__ old_ɴ            # forget the old name of self
-      namespace.const_set ɴ, self           # write a constant
-      namespace.__instances__[ self ] = ɴ   # write to @instances
-    end
+    # If the argument is nil, the method performs unnaming.
+    return unname! if name.nil?
+    # Otherwise, the method performs naming the instance, while
+    # avoiding stealing names already in use by another instance.
+    # Let us look at the current name of the instance first.
+    previous_name = namespace.__instances__[ self ]
+    # Honor class'es #exec_when_naming hook.
+    requested_new_name = honor_exec_when_naming( name )
+    # Return if the instance is already named as requested.
+    return if previous_name == requested_new_name
+    # Raise error if the requested name is already taken.
+    self.class.__instances__.rassoc( requested_new_name ) and
+      fail NameError, "Name '#{requested_new_name}' already " +
+                      "exists in #{namespace} namespace!"
+    # Now it is sure that the instance will be named, so it does
+    # not need to be avid.
+    make_not_avid!
+    # Rename self by modifying the registry.
+    namespace.__instances__.update self => requested_new_name
+    # Honor instance's #exec_when_named hook.
+    honor_exec_when_named
   end
 
-  # Names an instance, aggresively (overwrites existing names).
+  # Names the receiver aggresively. "Aggresively" means that in
+  # case the requested new name of the instance is already in use
+  # by another instance, the other instance is unnamed. In other
+  # words, in case of conflict of a name, the name is stolen from
+  # the conflicting instance, which becomes unnamed as a result.
+  # (The method does not trigger const_magic.)
   # 
   def name!( name )
-    old_ɴ = namespace.__instances__[ self ]   # previous name
-    return self.name = nil if name.nil?       # no collider concerns
-    ɴ = honor_name_set_hooks( name, old_ɴ )
-    return false if old_ɴ == ɴ                # already named as required
-    pair = namespace.__instances__.rassoc( ɴ )
-    namespace.__forget__( pair[0] ) if pair   # rudely forget the collider
-    namespace.__forget__ old_ɴ                # forget the old name of self
-    namespace.const_set ɴ, self               # write a constant
-    namespace.__instances__[ self ] = ɴ       # write to @instances
+    # If the argument is nil, the method performs unnaming.
+    return unname! if name.nil?
+    # Otherwise, the method performs aggresive naming the instance,
+    # where "aggresive" means that in case of conflict over a name,
+    # the name is stolen from the conflicting instance.
+    # Let us look at the current name of the instance first.
+    previous_name = namespace.__instances__[ self ]
+    # Honor class'es #exec_when_naming hook.
+    requested_new_name = honor_exec_when_naming( name )
+    # Return if the instance is already named as requested.
+    return if previous_name == requested_new_name
+    # See if the requested name is already taken.
+    colliding_entry =
+      namespace.__instances__.rassoc( requested_new_name )
+    # Unname the colliding instance, if any.
+    begin
+      colliding_entry.first.unname! if colliding_entry
+    ensure
+      # Unnaming the colliding instance may fail. But whether it
+      # fails or succeeds, self must quit being avid. If the
+      # unnaming succeeded, self is getting a new name and thus
+      # no longer needs to be avid. However, if the unnaming
+      # raises an error, we want to avoid seeing the same error
+      # over and over again just because avid self assigned to
+      # a constant with conflicting name tries over and over again
+      # to perform the impossible feat of stealing that name.
+      make_not_avid!
+    end
+    # Rename self by modifying the registry.
+    namespace.__instances__.update self => requested_new_name
+    # Honor instance's #exec_when_named hook.
+    honor_exec_when_named
+    # Return the receiver.
+    return self
+  end
+
+  # Unnames the instance. Does not trigger #const_magic.
+  # 
+  def unname!
+    # Get the current name of the instance.
+    name = namespace.__instances__[ self ]
+    # If the instance is anonymous, we are done.
+    return if name.nil?
+    # Check whether unnaming instances is allowed at all.
+    fail NameError, "Unnaming and naming by a name already in " +
+      "use by another instance has been disallowed!" unless
+      unnaming_allowed?
+    # Honor class'es #exec_when_unnaming hook.
+    honor_exec_when_unnaming
+    # Unname the instance by deleting the name from the registry.
+    namespace.__instances__.update( self => nil )
+    # Honor instance's #exec_when_unnamed hook.
+    honor_exec_when_unnamed
+    # Return value is the previous name.
+    return name
   end
 
-  # Is the instance avid for a name? (Will it overwrite other instance names?)
+  # Is the instance avid? ("Avid" means that the instance is so
+  # eager to get a name that it will use name even if this is
+  # already in use by another instance.)
   # 
   def avid?
     namespace.__avid_instances__.any? &method( :equal? )
@@ -170,21 +331,48 @@ module NameMagic
   # Make the instance not avid.
   # 
   def make_not_avid!
-    namespace.__avid_instances__.delete_if { |i| i.object_id == object_id }
+    namespace.__avid_instances__.delete_if { |i| equal? i }
+    return nil
+  end
+
+  # Is unnaming of the instance allowed? Note: This method just
+  # relies on class'es .permanent_names? method. Unnaming is not
+  # allowed when .permanent_names? is true.
+  # 
+  def unnaming_allowed?
+    ! self.class.permanent_names?
+  end
+
+  # Registers a block to execute as soon as the instance is named.
+  # (In other words, this method provides instance's naming hook.)
+  # The block is executed in the context of the instance. Return
+  # value of the block is unimportant. If no block is given, the
+  # method returns the previously defined block, if any, or a
+  # default block that does nothing.
+  # 
+  def exec_when_named &block
+    @exec_when_named = block if block
+    @exec_when_named ||= -> { }
   end
+  # Note: This alias must stay while the dependencies need it.
+  alias name_set_hook exec_when_named
 
-  # Registers a hook to execute upon instance naming. Instance's `#name_set_hook`
-  # Behaves analogically as namespace's `#name_set_hook`, and is executed right
-  # after the namespace's hook. Expects a block with a single argument, name of
-  # the instance. The return value of the block is not used and should be _nil_.
-  # Without a block, this method acts as a getter.
+  # Registers a block to execute right after the instance is
+  # unnamed. (In other words, this method provides instance's
+  # unnaming hook.) The block is executed in the context of the
+  # instance. Return value of the block is unimportant. If no block
+  # is given, the method returns the previously defined block, if
+  # any, or a default block that does nothing.
   # 
-  def name_set_hook &block
-    tap { @name_set_hook = block } if block
-    @name_set_hook ||= -> name { nil }
+  def exec_when_unnamed &block
+    @exec_when_unnamed = block if block
+    @exec_when_unnamed ||= -> { }
   end
+  # Note: This alias must stay while the dependencies need it.
+  alias name_set_hook exec_when_named
 
-  # Default +#to_s+ method for +NameMagic+ includers, returning the name.
+  # +NameMagic+ redefines #to_s method to show names.
+  # name.
   # 
   def to_s
     name ? name.to_s : super
@@ -198,13 +386,83 @@ module NameMagic
 
   private
 
-  # Honors name set hooks, first for the namespace, then for the instance.
-  # Takes 2 arguments, name and old name of this instance. Returns the final
-  # name to be used
+  # Make the instance avid. Does not trigger const_magic. (Remark:
+  # Invoking this method on named instances is considered gross
+  # indecency.)
+  # 
+  def make_avid!
+    namespace.__avid_instances__ << self unless
+      namespace.__avid_instances__.include? self
+    return nil
+  end
+
+  # Honors the class'es hook #exec_when_naming. Takes 2
+  # arguments, name and old name of this instance. Also calls
+  # Namespace#validate_name method. Returns the final name to be
+  # used.
+  # 
+  def honor_exec_when_naming( suggested_name )
+    instance = self
+    previous_name = namespace.__instances__[ instance ]
+    suggested_name = suggested_name.to_s
+    # Calling exec_when_naming without a block makes the method
+    # return the block defined earlier.
+    block = self.class.exec_when_naming
+    # Execute the namespace hook in the context of the user class.
+    name = self.class.instance_exec( suggested_name,
+                                     instance,
+                                     previous_name,
+                                     &block )
+    # The hook is supposed to return the name to be actually used.
+    # But if the user used the block for other purposes and did
+    # not bother to return a string or symbol (or anything that
+    # can be converted to a symbol), we will assume that the user
+    # meant to leave the suggested name without intervention.
+    # I wonder whether this behavior is too smart.
+    name = begin; name.to_sym; rescue NoMethodError
+             suggested_name
+           end
+    # Finally, apply validate_name method and return the result.
+    return self.class.validate_name( name ).to_sym
+  end
+
+  # Honors instance's hook #exec_when_named.
+  # 
+  def honor_exec_when_named
+    # Method #exec_when_named, when called without a block, returns
+    # the block defined earlier.
+    block = exec_when_named
+    # Block is executed within the context of this instance.
+    instance_exec &block
+    # The method returns nil.
+    return nil
+  end
+
+  # Honors the class'es hook #exec_when_unnaming.
+  # 
+  def honor_exec_when_unnaming
+    instance = self
+    previous_name = namespace.__instances__[ instance ]
+    # Calling exec_when_unnaming without a block makes the method
+    # return the block defined earlier.
+    block = self.class.exec_when_unnaming
+    # Execute the namespace hook in the context of the user class.
+    name = self.class.instance_exec( instance,
+                                     previous_name,
+                                     &block )
+    # The method returns nil.
+    return nil
+  end
+
+  # Honors instance's hook #exec_when_unnamed.
   # 
-  def honor_name_set_hooks suggested_name, old_name
-    ɴ = namespace.name_set_hook.( suggested_name, self, old_name ).to_sym
-    # puts "NameMagic: Name adjusted to #{name}." if DEBUG
-    namespace.validate_name( ɴ ).to_sym.tap { |ɴ| name_set_hook.( ɴ ) }
+  def honor_exec_when_unnamed
+    # Method #exec_when_unnamed, when called without a block,
+    # returns the block defined earlier.
+    block = exec_when_unnamed
+    # Block is executed within the context of this instance.
+    instance_exec &block
+    # The method returns nil.
+    return nil
   end
 end # module NameMagic

data/lib/y_support/null_object.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require 'y_support'
+require_relative '../y_support'
 
 # Null object pattern implementation in +YSupport+. apart from the expected null
 # object behavior (such as returning self in response to almost all messages),

data/lib/y_support/respond_to.rb

@@ -1,4 +1,4 @@
-require 'y_support'
+require_relative '../y_support'
 
 # RespondTo class for easy use of respond_to? in case statements.
 # 

data/lib/y_support/stdlib_ext/matrix/misc.rb

@@ -5,7 +5,7 @@ class Matrix
   def pretty_inspect
     return inspect if row_size == 0 or column_size == 0
     aa = send( :rows ).each.with_object [] do |row, memo|
-      memo << row.map{ |o|
+      memo << row.map { |o|
         os = o.to_s
         case o
         when Numeric then os[0] == '-' ? os : ' ' + os
@@ -18,7 +18,7 @@ class Matrix
       memo << "\n"
     end
   end
-  
+
   # Pretty print
   def pretty_print
     print pretty_inspect

data/lib/y_support/stdlib_ext/matrix.rb

@@ -1,2 +1,2 @@
-require 'y_support' unless defined? YSupport
-require File.dirname( __FILE__ ) + '/matrix/misc'
+require_relative '../../y_support'
+require_relative 'matrix/misc'

data/lib/y_support/stdlib_ext.rb

@@ -1,4 +1,4 @@
 Dir["#{File.dirname( __FILE__ )}/stdlib_ext/*.rb"].sort.each do |path|
-  require "y_support/stdlib_ext/#{File.basename( path, '.rb' )}"
+  require_relative "y_support/stdlib_ext/#{File.basename( path, '.rb' )}"
 end
 

data/lib/y_support/typing/array.rb

@@ -1 +1 @@
-require File.dirname( __FILE__ ) + '/array/typing'
+require_relative 'array/typing'

data/lib/y_support/typing/enumerable.rb

@@ -1 +1 @@
-require File.dirname( __FILE__ ) + '/enumerable/typing'
+require_relative 'enumerable/typing'

data/lib/y_support/typing/hash.rb

@@ -1 +1 @@
-require File.dirname( __FILE__ ) + '/hash/typing'
+require_relative 'hash/typing'

data/lib/y_support/typing/module.rb

@@ -1 +1 @@
-require File.dirname( __FILE__ ) + '/module/typing'
+require_relative 'module/typing'