Module: NameMagic::NamespaceMethods

Defined in:
lib/y_support/name_magic.rb

Instance Method Summary collapse

Instance Method Details

#__avid_instances__ ⇒ Object

Presents class-owned @avid_instances (no const_magic).



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

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

#__forget__(instance) ⇒ Object

Clears class-owned references to a specified instance without performing #const_magic first. The argument must be an instance of the target class.



225
226
227
228
229
230
 
# File 'lib/y_support/name_magic.rb', line 225

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

#__instances__ ⇒ Object

Presents class-owned @instances without const_magic.



141
142
143
144
 
# File 'lib/y_support/name_magic.rb', line 141

def __instances__
  namespace.instance_variable_get( :@instances ) ||
    namespace.instance_variable_set( :@instances, {} )
end

#const_magic ⇒ Object

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.



195
196
197
198
199
 
# File 'lib/y_support/name_magic.rb', line 195

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

#forget(which_instance) ⇒ Object

Clears class-owned references to a specified instance.



209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/y_support/name_magic.rb', line 209

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

#forget_all_instances ⇒ Object

Clears class-owned references to all the instances.



244
245
246
247
248
249
 
# File 'lib/y_support/name_magic.rb', line 244

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_anonymous_instances ⇒ Object Also known as: forget_nameless_instances

Clears class-owned references anonymous instances.



234
235
236
237
238
239
 
# File 'lib/y_support/name_magic.rb', line 234

def forget_anonymous_instances
  nameless_instances.each { |inst, ɴ|
    __instances__.delete inst
    __avid_instances__.delete inst
  }
end

#instance(arg) ⇒ 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 as string, symbol, or an instance itself, in which case, the instance in question is merely returned without changes.)



175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/y_support/name_magic.rb', line 175

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

#instance_names ⇒ Object

Presents an array of all the instance names (disregarding anonymous instances).



135
136
137
 
# File 'lib/y_support/name_magic.rb', line 135

def instance_names
  instances.map( &:name ).compact
end

#instances ⇒ Object

Presents class-owned @instances hash of { instance => name } pairs.



127
128
129
130
 
# File 'lib/y_support/name_magic.rb', line 127

def instances
  const_magic
  __instances__.keys.select { |i| i.kind_of? self }
end

#name_get_closure(&block) ⇒ Object

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.



271
 
# File 'lib/y_support/name_magic.rb', line 271

def name_get_closure █ @name_get_closure = block end

#name_set_closure(&block) ⇒ Object

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



265
 
# File 'lib/y_support/name_magic.rb', line 265

def name_set_closure █ @name_set_closure = block end

#nameless_instances ⇒ Object

Returns those instances, which are nameless (@instances hash value is nil).



203
204
205
 
# File 'lib/y_support/name_magic.rb', line 203

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

#namespace ⇒ Object

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.



157
158
159
 
# File 'lib/y_support/name_magic.rb', line 157

def namespace
  self
end

#namespace!(namespc = self) ⇒ Object

Makes the class use the namespace supplied as the argument. If no argument is given, the class/module itself will be made its own namespace. Returns self.



165
166
167
168
 
# File 'lib/y_support/name_magic.rb', line 165

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

#new_instance_closure(&block) ⇒ Object

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.



256
 
# File 'lib/y_support/name_magic.rb', line 256

def new_instance_closure █ @new_instance_closure = block end