y_support 2.0.14 → 2.0.15.p1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f2417e6453a390dd0001a7add38638b69989f3da
-  data.tar.gz: 7c430e880d23c375a741572d7758c0dee3edb19b
+  metadata.gz: 326d4643c9c678771d09d5c90046d9e1858f887b
+  data.tar.gz: 7a87cc4045556e716700a2888573d27bbb99e7d5
 SHA512:
-  metadata.gz: 7d4ad637111c552d83e59345ee193b6bb15d9dc1d22e2ef31ca2c38500c70370f05a4a27e64c103b7308a315bc1565c4c6955d38373a37e5945f3729b70ff4d4
-  data.tar.gz: 6b158e5be9d2652019df69e9b2ee3b3ae0d380283d2d15cfda935c13cf174c6a55370264f9d4eb6006dba3720e8980f20d2670b0f9d7d471258a1cc7470008a1
+  metadata.gz: 5049da6a9a4ecde2993d84b81ec38e7ed8a4ca099b49c9c4b807e7926da0fa49f3b993ffe4ccd8e5f8222aeaa5e6ffe31ed4a225bd7701455b886b293de78513
+  data.tar.gz: 297c2bde7a494d9c10731f62827fa6f7b068308796314581739ef175521ea0b770025f02ed2a87b7f67a9124e366c976667175d24176a4b37744e681853f63df

data/lib/y_support/name_magic/array.rb

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+class Array
+  # Maps an array to an array of the element names, obtained by applying +#name+
+  # method to them. Takes one optional argument, which regulates its behavior
+  # regarding unnamed objects. If set to _nil_ (default) unnamed objects will
+  # be mapped to _nil_ (default behavior of the +#name+ method). If set to
+  # _true_, unnamed objects will be mapped to themselves. If set to _false_,
+  # unnamed object will not be mapped at all -- the returned array will contain
+  # only the names of the named objects.
+  # 
+  def names option=nil
+    return map &:name if option.nil?                 # unnamed --> nil
+    return map { |e| e.name || e } if option == true # unnamed --> instance
+    return map( &:name ).compact if option == false  # unnamed squeezed out
+    fail ArgumentError, "Unknown option: #{option}"
+  end
+end

data/lib/y_support/name_magic/class_methods.rb

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+module NameMagic::ClassMethods
+  # Presents the instances registered by the namespace. Takes one optional
+  # argument. If set to _false_, the method returns all the instances
+  # registered by the namespace. If set to _true_ (default), only returns
+  # those instances registered by the namespace, which are of the exact same
+  # class as the method's receiver. Example:
+  #
+  #   class Animal; include NameMagic end
+  #   Cat, Dog = Class.new( Animal ), Class.new( Animal )
+  #   Spot = Dog.new
+  #   Livia = Cat.new
+  #   Animal.instances #=> returns 2 instances
+  #   Dog.instances #=> returns 1 instance
+  #   Dog.instances( false ) #=> returns 2 instances of the namespace Animal
+  #
+  def instances option=false
+    const_magic
+    return __instances__.keys if option
+    __instances__.keys.select { |i| i.kind_of? self }
+  end
+
+  # Presents the instance names. Takes one optional argument, same as
+  # #instances method. Unnamed instances are completely disregarded.
+  #
+  def instance_names option=false
+    instances( option ).names( false )
+  end
+
+  # In addition the ability to name objects upon constant assignment, as common
+  # with eg. Class instances, NameMagic redefines class method #new so that it
+  # swallows the named argument :name (alias :ɴ), and takes care of naming the
+  # instance accordingly. Also, :name_avid named argument mey be supplied, which
+  # makes the naming avid (able to overwrite the name already in use by
+  # another object) if set to _true_.
+  # 
+  def new *args, &block
+    oo = args[-1].is_a?( Hash ) ? args.pop : {} # extract hash
+    nm = if oo[:name] then oo.delete :name       # consume :name if supplied
+         elsif oo[:ɴ] then oo.delete :ɴ          # consume :ɴ if supplied
+         else nil end
+    avid = oo[:name_avid] ? oo.delete( :name_avid ) : false # => true/false
+    # Avoid overwriting existing names unless avid:
+    fail NameError, "#{self} instance #{nm} already exists!" if
+      __instances__.keys.include? nm unless avid
+    args << oo unless oo.empty?    # prepare the arguments
+    new_before_name_magic( *args, &block ).tap do |new_inst| # instantiate
+      __instances__.update new_inst => nil # Instance is created unnamed...
+      namespace.new_instance_closure.tap { |λ|
+        λ.( new_inst ) if λ
+        if nm then # name has been supplied, we can name the instance:
+          avid ? new_inst.name!( nm ) : new_inst.name = nm
+        else # name hasn't been supplied, making the instance avid:
+          __avid_instances__ << new_inst
+        end
+      }
+    end
+  end
+
+  # Calls #new in _avid_ _mode_ (name_avid: true); see #new method for avid mode
+  # explanation.
+  # 
+  def new! *args, &block
+    oo = args[-1].is_a?( Hash ) ? args.pop : {} # extract options
+    new *args, oo.update( name_avid: true ), &block
+  end
+end # module NameMagic::ClassMethods

data/lib/y_support/name_magic/namespace_methods.rb

@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+
+module NameMagic
+  module NamespaceMethods
+    # Presents class-owned namespace. By default, this is the class itself, but
+    # may be overriden to use some other module as a namespace.
+    # 
+    def namespace
+      self
+    end
+
+    # Sets the namespace of the class.
+    # 
+    def namespace= modul
+      modul.extend ::NameMagic::NamespaceMethods unless modul == self
+      tap { define_singleton_method :namespace do modul end }
+    end
+
+    # Makes the class/module its own namespace. This is useful especially to tell
+    # the subclasses of a class using NameMagic to maintain their own namespaces.
+    # 
+    def namespace!
+      nil.tap { self.namespace = self }
+    end
+
+    # Presents the instances registered by the namespace.
+    #
+    def instances
+      const_magic
+      __instances__.keys
+    end
+
+    # Presents the instance names. Takes one optional argument, same as
+    # #instances method. Unnamed instances are completely disregarded.
+    #
+    def instance_names
+      instances.names( false )
+    end
+
+    # Presents namespace-owned @instances hash of pairs <code>{ instance =>
+    # instance_name }</code>. Unnamed instances have nil value. (Also, this
+    # method does not trigger #const_magic.)
+    #
+    def __instances__
+      namespace.instance_variable_get( :@instances ) ||
+        namespace.instance_variable_set( :@instances, {} )
+    end
+
+    # Presents namespace-owned @avid_instances array of avid instances. "Avid"
+    # means that the instance is able to overwrite a name used by another
+    # registered instance. (Also, this method does not trigger const_magic).
+    #
+    def __avid_instances__
+      namespace.instance_variable_get( :@avid_instances ) ||
+        namespace.instance_variable_set( :@avid_instances, [] )
+    end
+
+    # Returns the instance identified by the argument. NameError is raised, if
+    # the argument does not identify an instance. (It can be an instance name
+    # (string/symbol), or an instance itself, in which case, it is just returned
+    # back without changes.)
+    #
+    def instance identifier
+      puts "#instance( #{identifier} )" if DEBUG
+      # In @instances hash, value 'nil' indicates a nameless instance!
+      fail TypeError, "'nil' is not an instance identifier!" if identifier.nil?
+      ii = instances
+      return identifier if ii.include? identifier # return the instance back
+      begin # identifier not a registered instace -- treat it as a name
+        ary = [identifier, identifier.to_sym]
+        ii.find do |i| ary.include? i.name end
+      rescue NoMethodError
+      end or raise NameError, "No instance #{identifier} in #{self}."
+    end
+
+    # Searches all the modules in the the object space for constants containing
+    # receiver class objects, and names the found instances accordingly. The
+    # number of the remaining nameless instances is returned.
+    #
+    def const_magic
+      return 0 if nameless_instances.size == 0
+      serve_all_modules
+      return nameless_instances.size
+    end # def const_magic
+
+    # Returns those instances, which are nameless (whose name is set to nil).
+    # 
+    def nameless_instances
+      __instances__.select { |key, val| val.nil? }.keys
+    end
+    alias unnamed_instances nameless_instances
+    alias anonymous_instances nameless_instances
+
+    # Clears namespace-owned references to a specified instance. (This is
+    # different from "unnaming" an instance by setting <code>inst.name =
+    # nil</code>, which makes the instance anonymous, but still registered.)
+    # 
+    def forget( instance_identifier )
+      inst = begin
+               instance( instance_identifier )
+             rescue ArgumentError
+               return nil            # nothing to forget
+             end
+      ɴ = inst.nil? ? nil : inst.name
+      namespace.send :remove_const, ɴ if ɴ   # clear constant assignment
+      __instances__.delete( inst )           # remove @instances entry
+      __avid_instances__.delete( inst )      # remove if any
+      return inst                            # return the forgotten instance
+    end
+
+    # Clears namespace-owned references to an instance, without performing
+    # #const_magic first. The argument should be a registered instance. Returns
+    # the instance name, or _false_, if there was no such registered instance.
+    # 
+    def __forget__( instance )
+      return false unless __instances__.keys.include? instance
+      namespace.send :remove_const, instance.name if instance.name
+      __avid_instances__.delete( instance )
+      __instances__.delete instance
+    end
+
+    # Clears namespace-owned references to all the anonymous instances.
+    # 
+    def forget_nameless_instances
+      nameless_instances.each { |inst, ɴ|
+        __instances__.delete inst
+        __avid_instances__.delete inst # also from here
+      }
+    end
+    alias forget_unnamed_instances forget_nameless_instances
+    alias forget_anonymous_instances forget_nameless_instances
+
+    # Clears namespace-owned references to all the instances.
+    # 
+    def forget_all_instances
+      __instances__.clear           # clears @instances
+      constants( false ).each { |ß| # clear constants in the namespace
+        namespace.send :remove_const, ß if const_get( ß ).is_a? self
+      }
+    end
+
+    # Registers a hook to execute whenever name magic creates a new instance of
+    # the class including NameMagic. The block should take one argument (the new
+    # instance that was created) and is called in #new method right after
+    # instantiation, but before naming.
+    # 
+    def new_instance_closure &block
+      namespace.new_instance_closure &block unless namespace == self
+      @new_instance_closure = block if block
+      @new_instance_closure ||= -> instance { instance }
+    end
+    alias new_instance_hook new_instance_closure
+
+    # Registers a hook to execute whenever name setting is performed on an
+    # instance. The block should take three arguments (instance, name, old_name).
+    # The output value of the block is the name to be actually used – the hook
+    # thus allows to define transformations on the name when naming. It is the
+    # responsibility of the block to output a suitable symbol (capitalized,
+    # usable as a constant name etc.)
+    # 
+    def name_set_closure &block
+      namespace.name_set_closure &block unless namespace == self
+      @name_set_closure = block if block
+      @name_set_closure ||= -> name, instance, old_name=nil { name }
+    end
+    alias name_set_hook name_set_closure
+
+    # Registers a hook to execute whenever the instance is asked about its
+    # name. The name object contained in __instances__[self] is subjected
+    # to the name_get_closure before being returned as instance name.
+    # 
+    def name_get_closure &block
+      namespace.name_get_closure &block unless namespace == self
+      @name_get_closure = block if block
+      @name_get_closure ||= -> name { name }
+    end
+    alias name_get_hook name_get_closure
+
+    private
+
+    # Checks all the constants in some module's namespace, recursively.
+    # 
+    def serve_all_modules
+      todo = ( nameless_instances + __avid_instances__ ).map( &:object_id ).uniq
+      ObjectSpace.each_object Module do |ɱ|
+        ɱ.constants( false ).each do |const_ß|
+          begin
+            ◉ = ɱ.const_get( const_ß ) # insurance against const. loading fails
+          rescue LoadError, StandardError; next end
+          next unless todo.include? ◉.object_id
+          puts "NameMagic: Anonymous object under #{const_ß}!" if DEBUG
+          if __avid_instances__.map( &:object_id ).include? ◉.object_id # avid
+            puts "NameMagic: It is avid." if DEBUG
+            __avid_instances__       # 1. remove from avid list
+              .delete_if { |inst| inst.object_id == ◉.object_id }
+            ◉.name! const_ß          # 2. name rudely
+          else puts "NameMagic: It is not avid." if DEBUG # not avid
+            ɴ = validate_name( name_set_closure.( const_ß, ◉, nil ) ).to_sym
+            puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
+            conflicter = begin; namespace.const_get( ɴ ); rescue NameError; end
+            if conflicter then
+              msg = "Another #{self}-registered instance named '#{ɴ}' exists!"
+              fail NameError, msg unless conflicter == ◉
+            else # add the instance to the namespace
+              __instances__.update( ◉ => ɴ )
+              namespace.const_set( ɴ, ◉ )
+            end
+          end
+          todo.delete ◉.object_id # remove the id from todo list
+          break if todo.empty?    # and break the loop if done
+        end # each
+      end # each_object Module
+    end # def serve_all_modules
+
+    # Checks whether a name starts with a capital letter.
+    # 
+    def validate_name name
+      name.to_s.tap do |ɴ| # check whether the name starts with 'A'..'Z'
+        fail NameError, "#{self}-registered name must start with a capital " +
+        " letter 'A'..'Z' ('#{ɴ}' given)!" unless ( ?A..?Z ) === ɴ[0]
+      end
+    end
+  end # module NamespaceMethods
+end # module NameMagic

data/lib/y_support/name_magic.rb

@@ -1,26 +1,61 @@
 # -*- coding: utf-8 -*-
+
 require 'y_support'
+require_relative 'name_magic/array'
+require_relative 'name_magic/namespace_methods'
+require_relative 'name_magic/class_methods'
 
 # This mixin imitates Ruby constant magic and automates the named argument
-# :name (alias :ɴ). One thus can write:
+# :name (alias :ɴ). One can write:
 #
-# <tt>class Someclass; include NameMagic end</tt>
-# <tt>SomeName = SomeClass.new</tt>
+#   require 'y_support/name_magic'
+#   class Foo; include NameMagic end
+#   Bar = Foo.new
 #
 # and the resulting object will know its #name:
 #
-# <tt>SomeName.name = "SomeName"</tt>
+#   Bar.name #=> :Bar
+#   Foo::Bar #=> <Foo:0x.....>
+#
+# This is done by searching whole Ruby namespace for constants, triggered by the
+# method #const_magic defined in the namespace mixin. (Once the object is named,
+# subsequent constant assignments have no effects.) By default, the namespace
+# is the class, in which NameMagic is included, but it is possible to prescribe
+# another module as a namespace:
+#
+#   Quux = Module.new
+#   class FooBar
+#     include NameMagic
+#     self.namespace = Quux
+#   end
+#   FooBar.new name: "Baz"
+#   FooBar::Baz #=> NameError
+#   Quux::Baz #=> <FooBar:0x.....>
+#
+# When subclassing the classes with NameMagic included, namespace setting does
+# not change:
 #
-# This is done by searching the whole Ruby namespace for constants, to which
-# the object might have been assigned. The search is performed by the method
-# #const_magic defined by this mixin. Once the object is found to be assigned
-# to a constant, and named accordingly, its subsequent assignments to other
-# constants have no additional effect.
+#   class Animal; include NameMagic end
+#   class Dog < Animal; end
+#   class Cat < Animal; end
+#   Dog.namespace #=> Animal
+#   Cat.namespace #=> Animal
+#   Livia = Cat.new
+#   Cat.instance_names #=> []
+#   Animal.instance_names #=> [:Livia]
 #
-# Alternative way to create a named object is by specifying :name (alias :ɴ)
-# named argument:
+# To make the subclasses use each their own namespace, use +#namespace!+ method:
 #
-# <tt>SomeClass.new a, b, ..., name: "SomeName", aa: v1, bb: v2 ...</tt>
+#   Dog.namespace!
+#   
+# NameMagic also provides an alternative way to create named objects by taking
+# care of :name (alias :ɴ) named argument of the constructor:
+#
+#   Dog.new name: "Spot"
+#   Dog.new ɴ: :Rover
+#   Dog.instance_names #=> [:Spot, :Rover]
+#   Animal.instance_names #=> []
+#   
 #
 # Lastly, a name can be assigned by #name= accssor, as in
 #
@@ -33,345 +68,85 @@ require 'y_support'
 module NameMagic
   DEBUG = false
 
-  def self.included ɱ
-    case ɱ
-    when Class then # we will decorate its #new method
-      class << ɱ
-        alias :original_method_new :new # Make space to decorate #new
+  def self.included modul
+    if modul.is_a? Class then # decorate #new
+      class << modul
+        alias :new_before_name_magic :new
       end
-      # Attach the decorators etc.
-      ɱ.extend ::NameMagic::ClassMethods
-      ɱ.extend ::NameMagic::NamespaceMethods
-      # Attach namespace methods also to the namespace, if given.
+      modul.extend NameMagic::NamespaceMethods
+      modul.extend NameMagic::ClassMethods
+      # Attach namespace methods also to the namespace, if given
       begin
-        if ɱ.namespace == ɱ then
-          ɱ.define_singleton_method :namespace do ɱ end
+        if modul.namespace == modul then
+          modul.define_singleton_method :namespace do modul end
         else
-          ɱ.namespace.extend ::NameMagic::NamespaceMethods
+          modul.namespace.extend NameMagic::NamespaceMethods
         end
       rescue NoMethodError
       end
-    else # it is a Module; we'll infect it with our #included method
-      ɱ_included, this_included = ɱ.method( :included ), method( :included )
-      ɱ.define_singleton_method :included do |ç|
-        this_included.( ç )
-        ɱ_included.( ç )
-      end
+    else # it is a Module -- infect it with this #include
+      orig, this = modul.method( :included ), method( :included )
+      modul.define_singleton_method :included do |m| this.( m ); orig.( m ) end
     end
   end # self.included
 
-  # Retrieves an instance name (demodulized).
+  # The namespace of the instance's class.
+  # 
+  def namespace
+    self.class.namespace
+  end
+
+  # Retrieves an instance name.
   # 
   def name
     self.class.const_magic
-    ɴ = self.class.__instances__[ self ]
-    if ɴ then
-      name_get_closure = self.class.instance_variable_get :@name_get_closure
-      name_get_closure ? name_get_closure.( ɴ ) : ɴ
-    else nil end
+    __name__ or ( yield self if block_given? )
   end
   alias ɴ name
 
-  # Retrieves either an instance name (if present), or an object id.
+  # Retrieves the instance name. Does not trigger #const_magic before doing so.
   # 
-  def name_or_object_id
-    name || object_id
+  def __name__
+    ɴ = self.class.__instances__[ self ]
+    namespace.name_get_closure.( ɴ ) if ɴ
   end
-  alias ɴ_ name_or_object_id
 
   # Names an instance, cautiously (ie. no overwriting of existing names).
   # 
   def name=( ɴ )
-    puts "NameMagic: Naming with argument #{ɴ}." if DEBUG
-    # get previous name of this instance, if any
-    old_ɴ = self.class.__instances__[ self ]
-    # honor the hook
-    name_set_closure = self.class.instance_variable_get :@name_set_closure
-    ɴ = name_set_closure.call( ɴ, self, old_ɴ ) if name_set_closure
-    ɴ = self.class.send( :validate_capitalization, ɴ ).to_sym
-    puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
-    return if old_ɴ == ɴ # already named as required; nothing to do
-    # otherwise, be cautious about name collision
-    raise NameError, "Name '#{ɴ}' already exists in " +
-      "#{self.class} namespace!" if self.class.__instances__.rassoc( ɴ )
-    # since everything's ok...
-    self.class.namespace.const_set ɴ, self # write a constant
-    self.class.__instances__[ self ] = ɴ   # write __instances__
-    self.class.__forget__ old_ɴ            # forget the old name of self
+    old_ɴ = namespace.__instances__[ self ]    # previous name
+    if ɴ then puts "NameMagic: Naming with argument #{ɴ}." if DEBUG
+      ɴ = namespace.send( :validate_name,     # honor the hook
+                          namespace.name_set_closure.( ɴ, self, old_ɴ ) ).to_sym
+      puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
+      return if old_ɴ == ɴ                     # already named as required
+      fail NameError, "Name '#{ɴ}' already exists in #{namespace} namespace!" if
+        self.class.__instances__.rassoc( ɴ )
+      namespace.const_set ɴ, self           # write a constant
+      namespace.__instances__[ self ] = ɴ   # write to @instances
+      namespace.__forget__ old_ɴ            # forget the old name of self
+    else puts "NameMagic: Unnaming #{old_ɴ || self}" if DEBUG
+      namespace.__instances__.update( self => nil ) # unname in @instances
+      namespace.send :remove_const, old_ɴ if old_ɴ  # remove namespace const.
+    end
   end
 
   # Names an instance, aggresively (overwrites existing names).
   # 
   def name!( ɴ )
-    puts "NameMagic: Rudely naming with argument #{ɴ}." if DEBUG
-    old_ɴ = self.class.__instances__[ self ] # get instance's old name, if any
-    # honor the hook
-    name_set_closure = self.class.instance_variable_get :@name_set_closure
-    ɴ = name_set_closure.( ɴ, self, old_ɴ ) if name_set_closure
-    ɴ = self.class.send( :validate_capitalization, ɴ ).to_sym
-    puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
-    return false if old_ɴ == ɴ # already named as required; nothing to do
-    # otherwise, rudely remove the collider, if any
-    pair = self.class.__instances__.rassoc( ɴ )
-    self.class.__forget__( pair[0] ) if pair
-    # and add self to the namespace instead
-    self.class.namespace.const_set ɴ, self # write a constant
-    self.class.__instances__[ self ] = ɴ   # write to __instances__
-    self.class.__forget__ old_ɴ            # forget the old name of self
-    return true
-  end
-
-  module NamespaceMethods
-    # Presents class-owned @instances hash of { instance => name } pairs.
-    # 
-    def instances
-      const_magic
-      __instances__.keys.select { |i| i.kind_of? self }
-    end
-
-    # Presents an array of all the instance names (disregarding anonymous
-    # instances).
-    # 
-    def instance_names
-      instances.map( &:name ).compact
-    end
-
-    # Presents class-owned @instances without const_magic.
-    # 
-    def __instances__
-      namespace.instance_variable_get( :@instances ) ||
-        namespace.instance_variable_set( :@instances, {} )
-    end
-
-    # Presents class-owned @avid_instances (no const_magic).
-    # 
-    def __avid_instances__
-      namespace.instance_variable_get( :@avid_instances ) ||
-        namespace.instance_variable_set( :@avid_instances, [] )
-    end
-
-    # Presents class-owned namespace. Normally, this is the class itself,
-    # but can be overriden so as to define constants holding the instances
-    # in some other module.
-    # 
-    def namespace
-      self
-    end
-
-    # Makes the class use the namespace supplied as an argument.
-    # 
-    def namespace= namespc
-      namespc.extend ::NameMagic::NamespaceMethods unless namespc == self
-      tap { define_singleton_method :namespace do namespc end }
-    end
-      
-    # Makes the class/module use itself as a namespace. (Useful eg. with
-    # parametrized subclassing to tell the subclasses to maintain each their
-    # own namespaces.)
-    # 
-    def namespace!
-      self.namespace = self
-    end
-
-    # Returns the instance identified by the argument. NameError is raised, if
-    # the argument does not identify an instance. (It can be an instance name
-    # as string, symbol, or an instance itself, in which case, the instance in
-    # question is merely returned without changes.)
-    # 
-    def instance arg
-      # In @instances hash, name 'nil' means nameless!
-      puts "NameMagic: #instance called with argument #{arg}." if DEBUG
-      msg = "'nil' is not a valid argument type for NameMagic#instance method!"
-      fail TypeError, msg if arg.nil?
-      # if the argument is an actual instance, just return it
-      ii = instances
-      return arg if ii.include? arg
-      # otherwise, assume arg is a name
-      begin
-        ii.find { |i| i.name == arg || i.name == arg.to_sym }
-      rescue NoMethodError
-      end or raise NameError, "No instance #{arg} in #{namespace}."
-    end
-
-    # The method will search all the modules in the the object space for
-    # receiver class objects assigned to constants, and name these instances
-    # accordingly. Number of the remaining nameless instances is returned.
-    # 
-    def const_magic
-      return 0 if nameless_instances.size == 0
-      serve_all_modules
-      return nameless_instances.size
-    end # def const_magic
-
-    # Returns those instances, which are nameless (@instances hash value is nil).
-    # 
-    def nameless_instances
-      __instances__.select { |key, val| val.nil? }.keys
-    end
-
-    # Clears class-owned references to a specified instance.
-    # 
-    def forget( which_instance )
-      inst = begin
-               instance( which_instance )
-             rescue ArgumentError
-               return nil            # nothing to forget
-             end
-      ɴ = inst.nil? ? nil : inst.name
-      namespace.send :remove_const, ɴ if ɴ # clear constant assignment
-      __instances__.delete( inst )   # remove @instances entry
-      __avid_instances__.delete( inst ) # remove if any
-      return inst                            # return forgotten instance
-    end
-
-    # Clears class-owned references to a specified instance without performing
-    # #const_magic first. The argument must be an instance of the target class.
-    # 
-    def __forget__( instance )
-      name = __instances__.delete instance # remove @instances entry
-      __avid_instances__.delete( instance ) # remove if any
-      namespace.send :remove_const, name if name
-      return instance
-    end
-
-    # Clears class-owned references anonymous instances.
-    # 
-    def forget_anonymous_instances
-      nameless_instances.each { |inst, ɴ|
-        __instances__.delete inst
-        __avid_instances__.delete inst
-      }
-    end
-    alias :forget_nameless_instances :forget_anonymous_instances
-
-    # Clears class-owned references to all the instances.
-    # 
-    def forget_all_instances
-      __instances__.clear           # clears @instances
-      constants( false ).each { |ß| # clear constants in the namespace
-        namespace.send :remove_const, ß if const_get( ß ).is_a? self
-      }
-    end
-    
-    # Registers a hook to execute whenever name magic creates a new instance
-    # of the class including NameMagic. The block should take one argument
-    # (the new instance that was created) and is called in #new method right
-    # after instantiation, but before naming.
-    # 
-    def new_instance_closure &block; @new_instance_closure = block end
-
-    # Registers a hook to execute whenever name setting is performed on an
-    # instance. The block should take three arguments (instance, name, old_name).
-    # The output value of the block is the name to be actually used – the hook
-    # thus allows to define transformations on the name when naming. It is the
-    # responsibility of the block to output a suitable symbol (capitalized,
-    # usable as a constant name etc.)
-    # 
-    def name_set_closure &block; @name_set_closure = block end
-
-    # Registers a hook to execute whenever the instance is asked about its
-    # name. The name object contained in __instances__[self] is subjected
-    # to the name_get_closure before being returned as instance name.
-    # 
-    def name_get_closure &block; @name_get_closure = block end
-
-    private
-    
-    # Checks all the constants in some module's namespace, recursively.
-    # 
-    def serve_all_modules
-      todo = ( nameless_instances + __avid_instances__ ).map( &:object_id ).uniq
-      ObjectSpace.each_object Module do |ɱ|     # for all the modules...
-        # ( puts ɱ if DEBUG ) rescue
-        ɱ.constants( false ).each do |const_ß|  # and all the constants...
-          begin # insurance against constant dynamic loading fails
-            ◉ = ɱ.const_get( const_ß )
-          rescue LoadError, StandardError
-            next
-          end
-          if todo.include? ◉.object_id then # we found a wanted object
-            puts "NameMagic: Wanted object found under #{const_ß}." if DEBUG
-            if __avid_instances__.map( &:object_id ).include? ◉.object_id # avid
-              puts "NameMagic: It is avid." if DEBUG
-              __avid_instances__ # 1. remove from avid list
-                .delete_if { |instance| instance.object_id == ◉.object_id }
-              ◉.name! const_ß    # 2. name rudely
-            else # not avid
-              puts "NameMagic: It is not avid." if DEBUG
-              ɴ = if @name_set_closure then # honor name_set_closure
-                    @name_set_closure.( const_ß, ◉, nil )
-                      .tap { |r| puts "The resulting name is #{r}." }
-                  else const_ß end
-              ɴ = validate_capitalization( ɴ ).to_sym
-              puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
-              conflicter = begin # be cautious
-                             namespace.const_get( ɴ )
-                           rescue NameError
-                           end
-              if conflicter then
-                puts "NameMagic: Conflicter exists named #{ɴ}." if DEBUG
-                raise NameError, "Another #{self} named '#{ɴ}' already " +
-                  "exists!" unless conflicter == ◉
-              else
-                puts "NameMagic: No conflicter named #{ɴ}, about to use it." if DEBUG
-                __instances__[ ◉ ] = ɴ   # add the instance to the namespace
-                namespace.const_set ɴ, ◉ # add the instance to the namespace
-              end
-            end
-            todo.delete ◉.object_id # remove the id from todo list
-            break if todo.empty?
-          end
-        end # each
-      end # each_object Module
-    end # def serve_all_modules
-
-    # Checks whether a name starts with a capital letter.
-    # 
-    def validate_capitalization name
-      ɴ = name.to_s
-      # check whether the name starts with 'A'..'Z'
-      raise NameError, "#{self.class} name must start with a capital " +
-        " letter 'A'..'Z' ('#{ɴ}' was given)!" unless ( ?A..?Z ) === ɴ[0]
-      return ɴ
+    old_ɴ = namespace.__instances__[ self ]   # previous name
+    if ɴ then puts "NameMagic: Rudely naming with #{ɴ}." if DEBUG
+      ɴ = namespace.send( :validate_name,     # honor the hook
+                          namespace.name_set_closure.( ɴ, self, old_ɴ ) ).to_sym
+      puts "NameMagic: Name adjusted to #{ɴ}." if DEBUG
+      return false if old_ɴ == ɴ # already named as required
+      pair = namespace.__instances__.rassoc( ɴ )
+      namespace.__forget__( pair[0] ) if pair # rudely forget the collider
+      namespace.const_set ɴ, self             # write a constant
+      namespace.__instances__[ self ] = ɴ     # write to @instances
+      namespace.__forget__ old_ɴ              # forget the old name of self
+    else
+      self.name = nil # unnaming, no collider issues
     end
   end
-
-  module ClassMethods
-    # In addition to 'constant magic' ability (name upon constant assignment),
-    # NameMagic redefines class method #new so that it eats parameter :name,
-    # alias :ɴ, and takes care of naming the instance accordingly. Option
-    # :name_avid can also be supplied (true/false), which makes the naming
-    # avid if true. (Avid, or aggresive naming means that the instance being
-    # named overwrites whatever was stored under that name earlier.)
-    # 
-    def new *args, &block
-      oo = args[-1].is_a?( Hash ) ? args.pop : {} # extract hash
-      ɴß = if oo[:name] then oo.delete :name # consume :name if supplied
-           elsif oo[:ɴ] then oo.delete :ɴ    # consume :ɴ if supplied
-           else nil end
-      avid = oo[:name_avid] ? oo.delete( :name_avid ) : false # => true/false
-      # Avoid overwriting existing names unless avid:
-      raise NameError, "#{self} instance #{ɴß} already exists!" if
-        __instances__.keys.include? ɴß unless avid
-      # Instantiate:
-      args << oo unless oo.empty?    # fuse hash
-      new_inst = original_method_new *args, &block
-      __instances__.merge! new_inst => nil # Instance is created unnamed
-      # honor the hook
-      @new_instance_closure.( new_inst ) if @new_instance_closure
-      if ɴß then # name was supplied, name the instance
-        if avid then new_inst.name! ɴß else new_inst.name = ɴß end
-      else # name wasn't supplied, make the instance avid
-        __avid_instances__ << new_inst
-      end
-      return new_inst      # return the new instance
-    end
-
-    # Calls #new in avid mode (name_avid: true).
-    # 
-    def new! *args, &block
-      oo = args[-1].is_a?( Hash ) ? args.pop : {} # extract options
-      new *args, oo.merge!( name_avid: true ), &block
-    end
-  end # module ClassMethods
 end # module NameMagic

data/lib/y_support/version.rb

@@ -1,3 +1,3 @@
 module YSupport
-  VERSION = "2.0.14"
+  VERSION = "2.0.15.p1"
 end

data/test/name_magic_test.rb

@@ -14,12 +14,10 @@ describe NameMagic do
     @reporter = Object.new
     puts "..."
     @reporter.singleton_class.class_exec { attr_reader :report, :naming }
-    @ç.new_instance_closure do |instance|
-      @reporter.define_singleton_method :report do
-        "New instance reported"
-      end
+    @ç.namespace.new_instance_closure do |instance|
+      @reporter.define_singleton_method :report do "Instance reported" end
     end
-    @ç.name_set_closure do |name, instance, old_name|
+    @ç.namespace.name_set_closure do |name, instance, old_name|
       @reporter.define_singleton_method :name_set do
         "Name of the new instance was #{name}"
       end
@@ -39,14 +37,14 @@ describe NameMagic do
     @ç.nameless_instances.must_be_empty
     @reporter.report.must_equal nil
     x = @ç.new( name: "Boris" )
-    @reporter.report.must_equal "New instance reported"
+    @reporter.report.must_equal "Instance reported"
     @reporter.name_set.must_equal "Name of the new instance was Boris"
     x.name.must_equal :Boris
     @reporter.name_get.must_equal "Name get closure called on Boris"
     ufo = @ç.new
     @ç.nameless_instances.must_equal [ufo]
     UFO = @ç.new
-    @reporter.report.must_equal "New instance reported"
+    @reporter.report.must_equal "Instance reported"
     @reporter.name_set.must_equal "Name of the new instance was Boris"
     UFO.name
     @reporter.name_set.must_equal "Name of the new instance was UFO"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y_support
 version: !ruby/object:Gem::Version
-  version: 2.0.14
+  version: 2.0.15.p1
 platform: ruby
 authors:
 - boris
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-27 00:00:00.000000000 Z
+date: 2013-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -75,6 +75,9 @@ files:
 - lib/y_support/local_object.rb
 - lib/y_support/misc.rb
 - lib/y_support/name_magic.rb
+- lib/y_support/name_magic/array.rb
+- lib/y_support/name_magic/class_methods.rb
+- lib/y_support/name_magic/namespace_methods.rb
 - lib/y_support/null_object.rb
 - lib/y_support/respond_to.rb
 - lib/y_support/stdlib_ext.rb
@@ -123,9 +126,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.3