safer 0.3.1 → 0.4.0

data/lib/safer/ivar.rb

@@ -1,222 +1,7 @@
+require 'safer/ivarfactory'
+
 class Safer
   ##
-  # 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 <i>ad hoc</i>
-  # 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.
-  # 
-  class IVar
-
-    ##
-    # Given a Class object, derive the prefix string for the accessor functions
-    # that instance_variable will create.
-    def self.class_symbol_prefix(klass)
-      klass.to_s.split('::').inject(nil) do |memo, el|
-        # reset the symbol name when an anonymous class is encountered.
-        if /^\#<.*>$/.match(el)
-          nil
-        elsif memo
-          memo + '_' + el.downcase
-        else
-          el.downcase
-        end
-      end
-    end # Safer::IVar.class_symbol_prefix
-
-    ##
-    # 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+.
-    def self._symbol_names(klass, nmlist)
-      kname = self.class_symbol_prefix(klass)
-
-      nmlist.map do |nm|
-        (kname + '__' + nm.to_s).to_sym
-      end
-    end # Safer::IVar._symbol_names
-
-    ##
-    # compute accessor routine symbol names, so that the names include the
-    # entire class namespace.
-    # [+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
-    def self.symbol_names(klass, *nmlist)
-      self._symbol_names(klass, nmlist)
-    end # Safer::IVar.symbol_names
-
-    ##
-    # 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+.
-    def self.instance_variable(klass, *nmlist)
-      self.symbol_names(klass, *nmlist).each do |symnm|
-        klass.class_eval do
-          attr_accessor symnm
-        end
-      end
-    end # Safer::IVar.instance_variable
-
-    ##
-    # export the reader routines for instance variables in a nicer 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+).
-    def self.export_reader(klass, *nmlist)
-      symlist = self.symbol_names(klass, *nmlist)
-      nmlist.size.times do |index|
-        thisnm = nmlist[index]
-        thissym = symlist[index]
-        klass.class_eval("def #{thisnm} ; self.#{thissym} ; end")
-      end
-    end # Safer::IVar.export_reader
-
-    ##
-    # export the writer routines for instance variables in a nicer 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+).
-    def self.export_writer(klass, *nmlist)
-      symlist = self.symbol_names(klass, *nmlist)
-      nmlist.size.times do |index|
-        thisnm = nmlist[index]
-        thissym = symlist[index]
-        klass.class_eval(
-          "def #{thisnm}=(value) ; self.#{thissym} = value ; end"
-        )
-      end
-    end # Safer::IVar.export_writer
-
-    ##
-    # export both reader and writer routines for instance variables in a
-    # nicer 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+).
-    def self.export_accessor(klass, *nmlist)
-      self.export_reader(klass, *nmlist)
-      self.export_writer(klass, *nmlist)
-    end # Safer::IVar.export_accessor
-
-  end # Safer::IVar
+  # Default IVarFactory object.
+  IVar = IVarFactory.new(IVarFactory::Prefix::Full)
 end # Safer