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.



230
231
232
233
234
235
 
# File 'lib/y_support/name_magic.rb', line 230

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.



200
201
202
203
204
 
# File 'lib/y_support/name_magic.rb', line 200

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.



214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/y_support/name_magic.rb', line 214

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.



249
250
251
252
253
254
 
# File 'lib/y_support/name_magic.rb', line 249

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.



239
240
241
242
243
244
 
# File 'lib/y_support/name_magic.rb', line 239

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



181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/y_support/name_magic.rb', line 181

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.



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

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



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

def name_set_closure █ @name_set_closure = block end

#nameless_instances ⇒ Object

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



208
209
210
 
# File 'lib/y_support/name_magic.rb', line 208

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! ⇒ Object

Makes the class/module use itself as a namespace. (Useful eg. with parametrized subclassing to tell the subclasses to maintain each their own namespaces.)



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

def namespace!
  self.namespace = self
end

#namespace=(namespc) ⇒ Object

Makes the class use the namespace supplied as an argument.



163
164
165
166
 
# File 'lib/y_support/name_magic.rb', line 163

def namespace= namespc
  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.



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

def new_instance_closure █ @new_instance_closure = block end