Class: Safer::IVarFactory

Inherits:
Object
  • Object
show all
Defined in:
lib/safer/ivarfactory.rb

Overview

Create accessor functions for instance variables, in which the accessor function is prefixed with the name of the class in which the instance variable is defined.

==Usage Create one or more instance variables using instance_variable . For example, the following code: class Outer Safer::IVar.instance_variable(self, :variable) class Inner < Outer Safer::IVar.instance_variable(self, :variable) end end puts(Outer.instance_methods.grep(/__variable/).inspect) puts(Outer::Inner.instance_methods.grep(/__variable/).inspect) produces the following output: ["outer__variable", "outer__variable="] ["outer_inner__variable", "outer_inner__variable=", "outer__variable", "outer__variable="]

Accessors for Safer::IVar-defined instance variables can be created using export_reader, export_writer, and export_accessor .

==Rationale Safer::IVar is intended to improve the clarity and consistency of ruby code in at least the following (related) ways:

  1. Reducing the probability of instance variable usage errors.
  2. Documenting the instance variables attached to a class.

===Error Reduction Safer::IVar should help in reducing errors in at least the following ways:

  • Encapsulation errors. Traditional ruby instance variables defined by one class are transparently accessible to all subclasses. They are not, however, part of the public interface to a class (unless an accessor is defined), which means they are not generally documented. These two factors create a situation in which it is quite possible that a subclass inadvertantly re-define an instance variable in such a way as to render the subclass unusable. Bugs of this sort can be very difficult to resolve.

    Because instance variables generated by Safer::IVar are prefixed with a string derived from the class in which the variable is defined, it is much less likely that developers inadvertantly re-define instance variables in sub-classes, dramatically reducing the likelihood of this type of error.

  • Misspelling errors. For example, suppose you typically write software using the en-us dialect, and have an object with a @color instance variable. A en-uk speaker then submits a patch that sets the default color to green:

    --- ex1.rb	2010-09-28 06:24:52.000000000 -0400
+++ ex2.rb	2010-09-28 06:25:00.000000000 -0400
@@ -1,6 +1,7 @@
class Foo
 def initialize
   @size = 3
+    @colour = "green"
 end
 attr_reader :color
end

    This code will not raise any exceptions, but its behavior does not match developer intent. On the other hand, using Safer::IVar --- ex1-safer.rb 2010-09-28 06:31:51.000000000 -0400 +++ ex2-safer.rb 2010-09-28 06:32:08.000000000 -0400 @@ -1,7 +1,8 @@ class Foo Safer::IVar.instance_variable(self, :size, :color) Safer::IVar.export_reader(self, :color) def initialize self.foo__size = 3

    • self.foo__colour = "green" end end The new code will raise an exception at the call to Foo.new, making it much less likely that the error will go undetected.

===Documentation Traditional ruby instance variables are defined and used in an ad hoc manner. As such, there is no natural location in which the instance variables defined by a class can be documented, and no obvious way to determine the set of instance variables used in a class. Safer::IVar instance variables will all be associated with a single call to Safer::IVar.instance_variable. This provides both a natural location for documenting an instance variable's interpretation, as well as a string to search for when determining the set of instance variables defined by a class.

Defined Under Namespace

Classes: Dsl, Prefix

Instance Method Summary collapse

Constructor Details

#initialize(prefix) ⇒ IVarFactory

Returns a new instance of IVarFactory.



93
94
95
 
# File 'lib/safer/ivarfactory.rb', line 93

def initialize(prefix)
  @prefix = prefix
end

Instance Method Details

#_export_accessor_internal(klass, prefix, nmlist) ⇒ Object

Used internally. See Safer::IVarFactory#export_accessor, and Safer::IVarFactory::Dsl#accessor .



240
241
242
243
 
# File 'lib/safer/ivarfactory.rb', line 240

def _export_accessor_internal(klass, prefix, nmlist)
  self._export_reader_internal(klass, prefix, nmlist)
  self._export_writer_internal(klass, prefix, nmlist)
end

#_export_reader_internal(klass, prefix, nmlist) ⇒ Object

Used internally. See Safer::IVarFactory#export_reader, and Safer::IVarFactory::Dsl#reader .



190
191
192
193
194
195
196
197
 
# File 'lib/safer/ivarfactory.rb', line 190

def _export_reader_internal(klass, prefix, nmlist)
  symlist = self._symbol_names_internal(prefix, nmlist)
  nmlist.size.times do |index|
    thisnm = nmlist[index]
    thissym = symlist[index]
    klass.class_eval("def #{thisnm} ; self.#{thissym} ; end")
  end
end

#_export_writer_internal(klass, prefix, nmlist) ⇒ Object

Used internally. See Safer::IVarFactory#export_writer, and Safer::IVarFactory::Dsl#writer .



214
215
216
217
218
219
220
221
222
223
 
# File 'lib/safer/ivarfactory.rb', line 214

def _export_writer_internal(klass, prefix, nmlist)
  symlist = self._symbol_names_internal(prefix, nmlist)
  nmlist.size.times do |index|
    thisnm = nmlist[index]
    thissym = symlist[index]
    klass.class_eval(
      "def #{thisnm}=(value) ; self.#{thissym} = value ; end"
    )
  end
end

#_instance_variable_internal(klass, prefix, nmlist) ⇒ Object

Used internally. See Safer::IVarFactory#instance_variable, and Safer::IVarFactory::Dsl#ivar .



151
152
153
154
155
156
157
 
# File 'lib/safer/ivarfactory.rb', line 151

def _instance_variable_internal(klass, prefix, nmlist)
  self._symbol_names_internal(prefix, nmlist).each do |symnm|
    klass.class_eval do
      attr_accessor symnm
    end
  end
end

#_symbol_names(klass, nmlist) ⇒ Object

Used internally. [+klass+] Class object for which to generate a symbol name. [+nmlist+] Array of Symbol objects. [return] Array of Symbol objects generated from klass and each element of nmlist.



123
124
125
126
 
# File 'lib/safer/ivarfactory.rb', line 123

def _symbol_names(klass, nmlist)
  kname = self.class_symbol_prefix(klass)
  self._symbol_names_internal(kname, nmlist)
end

#_symbol_names_internal(prefix, nmlist) ⇒ Object

Used internally. [+prefix+] Prefix of generated symbol names. [+nmlist+] Array of Symbol objects. [return] Array of Symbol objects. Each element will be the concatenation of the prefix, '__', and the corresponding element of nmlist



111
112
113
114
115
 
# File 'lib/safer/ivarfactory.rb', line 111

def _symbol_names_internal(prefix, nmlist)
  nmlist.map do |nm|
    (prefix + '__' + nm.to_s).to_sym
  end
end

#class_symbol_prefix(klass) ⇒ Object

Given a Class object, derive the prefix string for the accessor functions that instance_variable will create.



100
101
102
 
# File 'lib/safer/ivarfactory.rb', line 100

def class_symbol_prefix(klass)
  @prefix.class_symbol_prefix(klass)
end

#export_accessor(klass, *nmlist) ⇒ Object

export both reader and writer routines for instance variables in a safer way. [+klass+] Class object for which to define accessors for instance variables defined by Safer::IVar.instance_variable. [+nmlist+] List of symbols for which to define accessors. Each symbol in nmlist should have previously been given as an argument to Safer::IVar.instance_variable(+klass+).



253
254
255
256
 
# File 'lib/safer/ivarfactory.rb', line 253

def export_accessor(klass, *nmlist)
  self._export_accessor_internal(
    klass, self.class_symbol_prefix(klass), nmlist)
end

#export_reader(klass, *nmlist) ⇒ Object

export the reader routines for instance variables in a safer way. [+klass+] Class object for which to define reader accessors for instance variables defined by Safer::IVar.instance_variable. [+nmlist+] List of symbols for which to define reader accessors. Each symbol in nmlist should have previously been given as an argument to Safer::IVar.instance_variable(+klass+).



206
207
208
209
 
# File 'lib/safer/ivarfactory.rb', line 206

def export_reader(klass, *nmlist)
  self._export_reader_internal(
    klass, self.class_symbol_prefix(klass), nmlist)
end

#export_writer(klass, *nmlist) ⇒ Object

export the writer routines for instance variables in a safer way. [+klass+] Class object for which to define writer accessors for instance variables defined by Safer::IVar.instance_variable. [+nmlist+] List of symbols for which to define writer accessors. Each symbol in nmlist should have previously been given as an argument to Safer::IVar.instance_variable(+klass+).



232
233
234
235
 
# File 'lib/safer/ivarfactory.rb', line 232

def export_writer(klass, *nmlist)
  self._export_writer_internal(
    klass, self.class_symbol_prefix(klass), nmlist)
end

#instance_variable(klass, *nmlist) ⇒ Object

create accessor routines for an instance variable, with variable name determined by the class in which the instance variable was declared. [+klass+] Class object into which to generate the variable accessor functions. [+nmlist+] List of symbols for which to create accessor routines. Uses Safer::IVar.symbol_names to determine the symbol names of the accessor routines. For example, the listing:

class MyClass
class SubClass
  Safer::IVar.instance_variable(self, :foo, :bar)
end
end

is equivalent to the following code:

class MyClass
class SubClass
  attr_accessor :myclass_subclass__foo
  attr_accessor :myclass_subclass__bar
end
end

The name-mangling signals that these instance variables are, for all intents and purposes, private to klass.



182
183
184
185
 
# File 'lib/safer/ivarfactory.rb', line 182

def instance_variable(klass, *nmlist)
  self._instance_variable_internal(
    klass, self.class_symbol_prefix(klass), nmlist)
end

#run(klass) {|Dsl.new(self, klass)| ... } ⇒ Object

Yield DSL interface for instance variable creation to caller. See Safer::IVarFactory::Dsl for the DSL API. [+klass+] Class object used by DSL interface.

Yields:

  • (Dsl.new(self, klass)) 


262
263
264
 
# File 'lib/safer/ivarfactory.rb', line 262

def run(klass)
  yield(Dsl.new(self, klass))
end

#symbol_names(klass, *nmlist) ⇒ Object

compute accessor routine symbol names, where the symbol name prefix is derived from the class name. [+klass+] Class object for which to generate a symbol name. [+nmlist+] Array of Symbol objects. [return] Array of Symbol objects generated from klass and each element of nmlist. For example, given the following listing:

class OuterClass
class InnerClass
  SYMNM = Safer::IVar.symbol_names(self, :foo)
  puts(SYMNM.to_s)
end
end

the following output would be produced:

outerclass_innerclass__foo


144
145
146
 
# File 'lib/safer/ivarfactory.rb', line 144

def symbol_names(klass, *nmlist)
  self._symbol_names(klass, nmlist)
end