y_support 2.1.18 → 2.4.4

data/lib/y_support/name_magic/class_methods.rb

@@ -3,210 +3,254 @@
 # Class methods for the classes that include NameMagic.
 # 
 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 exactly the
-  # same class as the receiver (ie. excluding the instances of the subclasses
-  # of this class). Example:
+  # Delegates methods to the namespace used by the class. Since the
+  # class frequently acts as its own namespace, this delegation
+  # requires special handling.
   # 
-  # <code>
-  # class Animal; include NameMagic end
-  # Cat, Dog = Class.new( Animal ), Class.new( Animal )
-  # Spot = Dog.new
-  # Livia = Cat.new
-  # Animal.instances #=> returns 2 instances (2 animals)
-  # Dog.instances #=> returns 1 instance (only 1 is of Dog subclass)
-  # Dog.instances( false ) #=> 2 instances again (all the animals)
-  # </code>
-  #
-  def instances option=true
-    return super if namespace == self
-    ii = namespace.instances
-    option ? ii.select { |i| i.kind_of? self } : ii
+  def self.delegate_to_namespace *symbols
+    symbols.each { |ß|
+      module_eval "def #{ß} *args\n" +
+                  "  return super if namespace == self\n" +
+                  "  namespace.#{ß}( *args )\n" +
+                  "end"
+    }
   end
 
-  # Deprecated method to get full names of the named instances. Use
-  # <code>instances.names</code> instead. Takes one optional argument,
-  # same as +#instances+ method.
-  #
-  def instance_names option=true
-    warn "Method #instance_names is deprecated. Use 'instances._names_' or 'instances.names' instead!"
-    instances( option ).names( false )
-  end
+  delegate_to_namespace :permanent_names!
+  delegate_to_namespace :permanent_names?
+  delegate_to_namespace :__instances__
+  delegate_to_namespace :__avid_instances__
+  delegate_to_namespace :const_magic
+  delegate_to_namespace :validate_name
+  delegate_to_namespace :forget_nameless_instances
+  delegate_to_namespace :instantiation_exec
+  delegate_to_namespace :exec_when_naming
+  delegate_to_namespace :exec_when_unnaming
 
-  # Presents namespace-owned +@instances+ hash. The hash consists of pairs
-  # <code>{ instance => instance_name }</code>. Unnamed instances have +nil+
-  # assigned to them as their name. (The method does not trigger
-  # +#const_magic+.)
-  # 
-  def __instances__
-    namespace == self ? super : namespace.__instances__
-  end
+  # Note: These aliases must stay while the dependencies need them.
+  alias new_instance_hook instantiation_exec
+  alias name_set_hook exec_when_naming
 
-  # 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. (This method does not trigger +#const_magic+.)
+  # Sets the namespace for the class.
   # 
-  def __avid_instances__
-    namespace == self ? super : namespace.__avid_instances__
+  def namespace= modul
+    fail "Namespace cannot be redefined when instance registry " +
+         "is not empty!" unless instances.empty?
+    modul.extend ::NameMagic::Namespace
+    define_singleton_method :namespace do modul end
   end
 
-  # Returns the instance identified by the first argument, which can typically
-  # be a name (string/symbol). If a registered instance is supplied, it is
-  # returned without change. The second argument is optional, with the same
-  # meaning as in +NameMagic::ClassMethods#instances+ method.
+  # Sets the namespace for the class to self.
   # 
-  def instance instance, option=true
-    return super if namespace == self
-    return namespace.instance( instance ) unless option
-    namespace.instance( instance ).tap { |instance|
-      fail NameError, "No #{self} instance #{instance} registered in " +
-        "#{namespace}!" unless instance.kind_of? self
-    }
+  def namespace!
+    nil.tap { self.namespace = self }
   end
 
-  # Searches all the modules in the the object space for constants pointing to
-  # anonymous instances of this class, and names them accordingly. The number
-  # of remaining anonymous instances is returned.
+  # Returns the registered instances. Example:
+  # 
+  # <code>
+  # class Animal; include NameMagic end
+  # Cat, Dog = Class.new( Animal ), Class.new( Animal )
+  # Spot, Livia = Dog.new, Cat.new
+  # Animal.instances #=> [Spot, Livia]
+  # Dog.instances #=> [Spot]
+  # Cat.instances #=> [Livia]
+  # </code>
   #
-  def const_magic
-    namespace == self ? super : namespace.const_magic
+  def instances
+    return super if namespace == self
+    namespace.instances.select { |i| i.kind_of? self }
   end
 
-  # Returns the nameless instances. The optional argument has the same meaning
-  # as in +NameMagic::ClassMethods#instances+ method.
+  # Returns the instance identified by the first argument.
   # 
-  def nameless_instances option=true
+  def instance instance
     return super if namespace == self
-    return namespace.nameless_instances unless option
-    namespace.nameless_instances.select { |i| i.kind_of? self }
+    namespace.instance( instance ).tap do |i|
+      fail NameError, "No #{self} instance #{instance} " +
+        "registered in #{namespace}!" unless i.kind_of? self
+    end
   end
 
-  # Clears namespace-owned references to a specified instance. (This is
-  # different from de-naming an instance by setting <code>inst.name =
-  # nil</code>, which makes the instance anonymous, but still registered.)
+  # Returns those of the registered instances, which are nameless.
   # 
-  def forget instance, option=true
-    namespace == self || ! option ? super : namespace.forget( instance instance )
+  def nameless_instances
+    return super if namespace == self
+    __instances__
+      .select { |key, val| val.nil? and key.is_a? self }
+      .keys
   end
 
-  # Clears namespace-owned references to an instance, without performing
-  # #const_magic first. The argument should be a registered instance. Returns
-  # the instance's name for named instances, _nil_ for anonymous instances,
-  # and _false_ if there was no such registered instance. The optional second
-  # argument has the same meaning as in +NameMaic::ClassMethods#instances+.
+  # Clears namespace-owned references to the specified
+  # instance. (This is different from de-naming an instance by
+  # setting <code>inst.name = nil</code>, which makes the instance
+  # anonymous, but still registered.)
   # 
-  def __forget__( instance, option=true )
+  def forget instance
     return super if namespace == self
-    fail NameError, "Supplied argument not an instance of #{self}!" unless
-      instance.is_a? self if option
-    namespace.__forget__ instance
+    namespace.forget( instance instance )
   end
 
-  # Clears namespace-owned references to all the anonymous instances.
+  # De-registers an instance without performing #const_magic
+  # first. The argument must be a registered instance, or TypeError
+  # ensues. Returns instance name for forgotten named instances,
+  # _nil_ for forgotten nameless instances.
   # 
-  def forget_nameless_instances
-    namespace == self ? super : namespace.forget_nameless_instances
+  def __forget__ instance
+    fail TypeError, "Supplied argument is not an instance " +
+                    "of #{self}!" unless instance.is_a? self
+    return super if namespace == self
+    namespace.__forget__ instance
   end
 
-  # Clears namespace-owned references to all the instances.
+  # Clears references to all the instances.
   # 
   def forget_all_instances
-    namespace == self ? super : namespace.forget_all_instances
+    return super if namespace == self
+    instances.map { |instance| __forget__ instance }
   end
 
-  # Registers a hook to execute upon instantiation. Expects a unary block, whose
-  # argument represents the new instance. It is called right after instantiation,
-  # but before naming the instance.
+  # In addition to the ability to name objects by constant
+  # assignment it provides, +NameMagic+ modifies #new method so
+  # that it will swallow certain parameters, namely +:name+ (alias
+  # +:ɴ+), +:name!+ and +:avid+. These can be used to name
+  # instances right off the bat with #new constructor:
+  #
+  # Human = Class.new do include NameMagic end
+  # Human.new name: "Fred"
+  # Human.instances #=> [Fred]
   # 
-  def new_instance_hook &block
-    namespace == self ? super : namespace.new_instance_hook( &block )
-  end
-
-  # Registers a hook to execute upon instance naming. Expects a ternary block,
-  # with arguments instance, name, old_name, representing respectively the
-  # instance to be named, the requested name, and the previous name of that
-  # instance (if any). The output of the block should be the name to actually
-  # be used. In other words, the hook can be used (among other things) to check
-  # and/or modify the requested name when christening the instance. It is the
-  # responsibility of this block to output a symbol that can be used as a Ruby
-  # constant name.
+  # Option +:avid+ (_true_ or _false_), when set to _true_, makes
+  # the instance so eager to be named that it will overwrite
+  # (steal) names already given to other instances. This allows us
+  # to redefine names to which we have already assigned something
+  # else.
+  #
+  # Finally, parameter +:name!+ acts as +:name+ with +:avid+ set to
+  # _true_:
   # 
-  def name_set_hook &block
-    namespace == self ? super : namespace.name_set_hook( &block )
-  end
-
-  # Registers a hook to execute whenever the instance is asked its name. The
-  # instance names are objects that are kept in a hash referred to by
-  # +@instances+ variable owned by the namespace. Normally, +NameMagic#name+
-  # simply returns the name of the instance, as found in the +@instances+ hash.
-  # When +name_get_hook+ is defined, this name is transformed by it before being
-  # returned.
+  # instance_1 = Human.new name: "Joe"
+  # instance_1.name #=> :Joe
+  # Human.instance( :Joe ) == instance_1 #=> true
+  # instance_2 = Human.new name!: "Joe"
+  # instance_2.name #=> :Joe
+  # instance_1.name #=> nil
+  # Human.instance( :Joe ) == instance_1 #=> false
+  # Human.instance( :Joe ) == instance_2 #=> true
   # 
-  def name_get_hook &block
-    namespace == self ? super : namespace.name_get_hook( &block )
+  def new *args, &block
+    # Extract hash from args.
+    oo = if args.last.is_a? Hash then args.pop else {} end
+    # Swallow :name / :ɴ parameters.
+    requested_name = oo.delete( :name ) || oo.delete( :ɴ )
+    # Swallow :name! parameter.
+    if oo[ :name! ] then
+      fail ArgumentError, "Parameters :name! and :name (:ɴ) " +
+        "cannot be supplied both at once!" if requested_name
+      requested_name = oo.delete( :name! )
+      exclamation_mark = true
+    else
+      exclamation_mark = false
+    end
+    # Prepare the arguments for instantiation.
+    args << oo unless oo.empty?
+    # Instantiate.
+    instance = super *args, &block
+    # Instantiation contract specifies that instances are created
+    # unnamed. Thus, register the instance and set its name to nil.
+    __instances__.update( instance => nil )
+    # Instantiation contract specifies that instances are created
+    # avid. Thus, make the instance avid.
+    instance.send :make_avid!
+    # Now, we have prepared the new instance nameless and avid
+    # exactly according to the instantiation contract. Depending on
+    # the arguments supplied to this method, the instance may soon
+    # lose its avid state and get a name, but now, before any of
+    # that happens, is the time to honor .instantiation_exec hook.
+    honor_instantiation_exec( instance )
+    # Return the instance if no name was requested for it.
+    return instance unless requested_name
+    # Now we know that a name was requested. The necessary action
+    # depends on whether :name (:ɴ) or :name! parameter was used.
+    # But already now, we know that the instance no longer needs
+    # to be avid.
+    instance.make_not_avid!
+    # Depending on whether :name (:ɴ) or :name! was supplied...
+    if exclamation_mark then
+      # Name the instance aggresively.
+      instance.name! requested_name
+    else
+      # Name the instance only if the name is not already in use.
+      instance.name = requested_name
+    end
+    # Return the instance.
+    return instance
   end
 
-  # Sets the namespace for the class.
-  # 
-  def namespace= modul
-    puts "Assigning #{modul} as the namespace of #{self}." if ::NameMagic::DEBUG 
-    modul.extend ::NameMagic::NamespaceMethods
-    define_singleton_method :namespace do modul end
-  end
+  private
 
-  # Sets the namespace for the class to self.
+  # Honors class'es hook .instantiation_exec. Takes one argument,
+  # the newly constructed instance.
   # 
-  def namespace!
-    nil.tap { self.namespace = self }
+  def honor_instantiation_exec( instance )
+    # Method #instantiation_exec, when called without a block,
+    # returns the block defined earlier.
+    block = instantiation_exec
+    # Block is executed within the context of this class.
+    instance_exec instance, &block
+    # The method returns nil.
+    return nil
   end
 
-  # In addition the ability to name objects by constant assignment, +NameMagic+
-  # redefines #new method so as to swallow name argument +:name+ (alias :ɴ), and
-  # naming the constructed instance by it. Also, +:name_avid+ option may be
-  # supplied, which, if _true_, makes the instance capable of avid naming:
-  # Overwriting (stealing) a name already given to another instance.
-  # 
-  def new *args, &block
-    oo = if args[-1].is_a? Hash then args.pop else {} end  # extract hash
-    nm = oo.delete( :name ) || oo.delete( :ɴ )   # consume :name / :ɴ if given
-    avid = oo.delete( :name_avid )
-    # 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
-    super( *args, &block ).tap do |inst| # instantiate
-      __instances__.update( inst => nil ) # Instances are created unnamed...
-      namespace.new_instance_hook.tap { |λ|
-        λ.( inst ) if λ
-        if nm then # Name supplied, name the instance.
-          avid ? inst.name!( nm ) : inst.name = nm
-        else # Name not given, make the inst. avid unless expressly prohibited.
-          __avid_instances__ << inst unless avid == false
-        end
-      }
-    end
-  end
+  # Backup of the #new method internals.
 
-  # Calls #new in _avid_ _mode_ (<tt>name_avid: true</tt>); see #new method for
-  # avid mode explanation.
-  # 
-  def avid *ordered_args, **named_args, &block
-    new *ordered_args, **named_args.update( name_avid: true ), &block
-  end
+    # # Extract hash from args.
+    # oo = if args.last.is_a? Hash then args.pop else {} end
+    # # Swallow :name / :ɴ parameters.
+    # requested_name = oo.delete( :name ) || oo.delete( :ɴ )
+    # # Swallow :name! parameter.
+    # if oo[ :name! ] then
+    #   fail ArgumentError, "Parameters :name! and :name (:ɴ) " +
+    #     "cannot be supplied both at once!" if requested_name
+    #   fail ArgumentError, "When parameter :name! is used, :avid " +
+    #     "must not be used!" if oo.keys.include? :avid
+    #   requested_name = oo.delete( :name! )
+    #   avid = true
+    # else
+    #   # Swallow :avid parameter.
+    #   avid = oo.delete( :avid )      
+    # end
+    # # I think this is a program error. The construct below never
+    # # executes, since in the first place it searches names in the
+    # # array of instances.
+    # # 
+    # # # Avoid overwriting existing names unless avid:
+    # # fail NameError, "#{self} instance named #{requested_name} " +
+    # #   "already exists!" if __instances__.keys.include? nm unless avid
+    # # Prepare the arguments for instantiation.
+    # args << oo unless oo.empty?
+    # # Instantiate.
+    # new_instance = super *args, &block
+    # # Instance construction contract specifies that the instances
+    # # are created unnamed. Thus, enter the instance into the
+    # # registry and set its name to nil.
+    # __instances__.update( instance => nil )
+    # # Instance construction contract specifies that the instances
+    # # are created avid Make the instance avid. 
+    
+    # # Honor the #instantiation_exec hook.
+    # honor_instantiation_exec( instance )
 
-  # Performs general name validation.
-  # 
-  def validate_name name
-    namespace == self ? super : namespace.validate_name( name )
-  end
 
-  private
+    # # Name the instance if name has been given.
+    # if nm then
+    #   # If name has been supplied, name the instance.
+    #   avid ? instance.name!( nm ) : instance.name = nm
+    # else # Name has not been given.
+    #   # Make the instance avid unless expressly prohibited.
+    #   __avid_instances__ << instance unless avid == false
+    # end
 
-  # Checks all the constants in some module's namespace, recursively.
-  # 
-  def serve_all_modules
-    namespace == self ? super : namespace.serve_all_modules
-  end
+    # # Return the constructed instance.
+    # return new_instance
 end # module NameMagic::ClassMethods

data/lib/y_support/name_magic/hash_methods.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+module NameMagic::HashMethods
+  # Maps the hash into one whose keys have been replaced with full
+  # names of the keys (using #full_name method).
+  # 
+  def keys_to_names # FIXME: Change to #keys_to_full_names
+    with_keys do |key| key.name || key end
+    # FIXME: Change #name to #full_name
+  end
+
+  # Modifies a hash in place so that the keys are replaced with key
+  # names (key objects are assumed to respond to +#name+ method).
+  # 
+  def keys_to_names! # FIXME: Change to #keys_to_full_names!
+    with_keys! do |key| key.name || key end
+    # FIXME: Change #name to #full_name
+  end
+
+  # Maps the hash into one whose keys have been replaced with
+  # names of the key objects (using #_name_ method).
+  # 
+  def keys_to_ɴ
+    with_keys do |key| key._name_ || key end
+  end
+
+  # Modifies a hash in place so that the keys are replaced with key
+  # names (using +#_name_+ method).
+  # 
+  def keys_to_ɴ!
+    with_keys! do |key| key._name_ || key end
+  end
+end