Module: NameMagic::NamespaceMethods

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

Instance Method Summary collapse

Instance Method Details

#__avid_instances__ ⇒ Object

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).



53
54
55
56
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 53

def __avid_instances__
  namespace.instance_variable_get( :@avid_instances ) ||
    namespace.instance_variable_set( :@avid_instances, [] )
end

#__forget__(instance) ⇒ 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.



115
116
117
118
119
120
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 115

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

#__instances__ ⇒ Object

Presents namespace-owned @instances hash of pairs { instance => instance_name }. Unnamed instances have nil value. (Also, this method does not trigger #const_magic.)



44
45
46
47
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 44

def __instances__
  namespace.instance_variable_get( :@instances ) ||
    namespace.instance_variable_set( :@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.



80
81
82
83
84
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 80

def const_magic
  return 0 if nameless_instances.size == 0
  serve_all_modules
  return nameless_instances.size
end

#forget(instance_identifier) ⇒ 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.)



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 98

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

#forget_all_instances ⇒ Object

Clears namespace-owned references to all the instances.



135
136
137
138
139
140
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 135

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 Also known as: forget_unnamed_instances, forget_anonymous_instances

Clears namespace-owned references to all the anonymous instances.



124
125
126
127
128
129
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 124

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

#instance(identifier) ⇒ Object

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.)



63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 63

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

#instance_names ⇒ Object

Presents the instance names. Takes one optional argument, same as #instances method. Unnamed instances are completely disregarded.



36
37
38
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 36

def instance_names
  instances.names( false )
end

#instances ⇒ Object

Presents the instances registered by the namespace.



28
29
30
31
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 28

def instances
  const_magic
  __instances__.keys
end

#name_get_closure(&block) ⇒ Object Also known as: name_get_hook

Registers a hook to execute whenever the instance is asked about its name. The name object contained in __instances__ is subjected to the name_get_closure before being returned as instance name.



172
173
174
175
176
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 172

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

#name_set_closure(&block) ⇒ Object Also known as: name_set_hook

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.)



161
162
163
164
165
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 161

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

#nameless_instances ⇒ Object Also known as: unnamed_instances, anonymous_instances

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



88
89
90
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 88

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

#namespace ⇒ Object

Presents class-owned namespace. By default, this is the class itself, but may be overriden to use some other module as a namespace.



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

def namespace
  self
end

#namespace! ⇒ Object

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.



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

def namespace!
  nil.tap { self.namespace = self }
end

#namespace=(modul) ⇒ Object

Sets the namespace of the class.



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

def namespace= modul
  modul.extend ::NameMagic::NamespaceMethods unless modul == self
  tap { define_singleton_method :namespace do modul end }
end

#new_instance_closure(&block) ⇒ Object Also known as: new_instance_hook

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.



147
148
149
150
151
 
# File 'lib/y_support/name_magic/namespace_methods.rb', line 147

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