Module: NameMagic::NamespaceMethods

Defined in:
lib/y_support/name_magic/namespace_methods.rb

Instance Method Summary collapse

Instance Method Details

#__avid_instances__ ⇒ Object

Avid instances registered in this namespace. (“Avid” means that the instance is able to steal (overwrite) a name from another registered instance. (The method does not trigger #const_magic.)



31
32
33
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 31

def __avid_instances__
  @avid_instances ||= []
end

#__forget__(instance, *args) ⇒ Object

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.



90
91
92
93
94
95
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 90

def __forget__( instance, *args )
  return false unless __instances__.keys.include? instance
  namespace.send :remove_const, instance.name if instance.name
  __avid_instances__.delete( instance )
  __instances__.delete instance
end

#__instances__ ⇒ Object

Presents namespace-owned @instances hash. The hash consists of pairs { instance => instance_name }. Unnamed instances have nil assigned to them as their name. (The method does not trigger #const_magic.)



23
24
25
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 23

def __instances__
  @instances ||= {}
end

#const_magic ⇒ Object

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.



56
57
58
59
60
61
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 56

def const_magic
  puts "#{self}#const_magic invoked!" if ::NameMagic::DEBUG
  return 0 if nameless_instances.size == 0
  serve_all_modules
  return nameless_instances.size
end

#forget(instance_identifier, *args) ⇒ Object

Clears namespace-owned references to a specified instance. (This is different from “unnaming” an instance by setting inst.name = nil, which makes the instance anonymous, but still registered.)



73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 73

def forget instance_identifier, *args
  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

#forget_all_instances ⇒ Object

Clears namespace-owned references to all the instances.



108
109
110
111
112
113
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 108

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

#forget_nameless_instances ⇒ Object

Clears namespace-owned references to all the anonymous instances.



99
100
101
102
103
104
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 99

def forget_nameless_instances
  nameless_instances.each { |inst, ɴ|
    __instances__.delete inst
    __avid_instances__.delete inst # also from here
  }
end

#instance(id, *args) ⇒ Object

Returns the instance identified by the argument, which can be typically a name (string/symbol). If a registered instance is supplied, it will be returned unchanged.



39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 39

def instance id, *args
  # puts "#instance( #{identifier} )" if DEBUG
  # In @instances hash, value 'nil' indicates a nameless instance!
  fail TypeError, "'nil' is not an instance identifier!" if id.nil?
  ii = instances
  return id if ii.include? id # return the instance back
  begin # identifier not a registered instace -- treat it as a name
    ary = [id, id.to_sym]
    ii.find { |inst| ary.include? inst.name }
  rescue NoMethodError
  end or fail NameError, "No instance #{id} in #{self}."
end

#instance_names(*args) ⇒ Object

Presents the instance names registered in this namespace.



14
15
16
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 14

def instance_names *args
  instances.names( false )
end

#instances(*args) ⇒ Object

Presents the instances registered in this namespace.



7
8
9
10
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 7

def instances *args
  const_magic
  __instances__.keys
end

#name_get_hook(&block) ⇒ Object

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.



145
146
147
148
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 145

def name_get_hook &block
  @name_get_hook = block if block
  @name_get_hook ||= -> name { name }
end

#name_set_hook(&block) ⇒ Object

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.



133
134
135
136
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 133

def name_set_hook &block
  @name_set_hook = block if block
  @name_set_hook ||= -> name, instance, old_name=nil { name }
end

#nameless_instances(*args) ⇒ Object

Returns those instances, which are nameless (whose name is set to nil).



65
66
67
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 65

def nameless_instances *args
  __instances__.select { |key, val| val.nil? }.keys
end

#new_instance_hook(&block) ⇒ Object

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.



119
120
121
122
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 119

def new_instance_hook &block
  @new_instance_hook = block if block
  @new_instance_hook ||= -> instance { instance }
end