safer 0.4.0 → 0.4.1

data/History.txt

@@ -1,3 +1,7 @@
+=== 0.4.1 / 2011-10-29
+
+* Fixed Manifest.txt.
+
 === 0.4.0 / 2011-10-29
 
 * Safer::IVar functionality moved into Safer::IVarFactory class.

data/Manifest.txt

@@ -5,8 +5,13 @@ README.rdoc
 Rakefile
 lib/safer.rb
 lib/safer/ivar.rb
+lib/safer/ivarfactory.rb
+lib/safer/ivarfactory/dsl.rb
+lib/safer/ivarfactory/prefix.rb
 lib/safer/protocol.rb
 lib/safer/hashprotocol.rb
 test/test_safer_ivar.rb
+test/test_safer_ivar_run.rb
+test/test_safer_ivarfactory.rb
 test/test_safer_protocol.rb
 test/test_safer_hashprotocol.rb

data/lib/safer.rb

@@ -15,5 +15,5 @@
 class Safer
   ##
   # Current release of Safer.
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/safer/ivarfactory.rb

@@ -0,0 +1,269 @@
+require '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 Safer::IVarFactory
+  def initialize(prefix)
+    @prefix = prefix
+  end
+
+  ##
+  # Given a Class object, derive the prefix string for the accessor functions
+  # that instance_variable will create.
+  def class_symbol_prefix(klass)
+    @prefix.class_symbol_prefix(klass)
+  end # Safer::IVarFactory#class_symbol_prefix
+
+  ##
+  # 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+
+  def _symbol_names_internal(prefix, nmlist)
+    nmlist.map do |nm|
+      (prefix + '__' + nm.to_s).to_sym
+    end
+  end
+
+  ##
+  # 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 _symbol_names(klass, nmlist)
+    kname = self.class_symbol_prefix(klass)
+    self._symbol_names_internal(kname, nmlist)
+  end # Safer::IVarFactory#_symbol_names
+
+  ##
+  # 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
+  def symbol_names(klass, *nmlist)
+    self._symbol_names(klass, nmlist)
+  end # Safer::IVarFactory#symbol_names
+
+  ##
+  # Used internally.  See Safer::IVarFactory#instance_variable, and
+  # Safer::IVarFactory::Dsl#ivar .
+  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
+
+  ##
+  # 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 instance_variable(klass, *nmlist)
+    self._instance_variable_internal(
+      klass, self.class_symbol_prefix(klass), nmlist)
+  end # Safer::IVarFactory#instance_variable
+
+  ##
+  # Used internally.  See Safer::IVarFactory#export_reader, and
+  # Safer::IVarFactory::Dsl#reader .
+  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 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+).
+  def export_reader(klass, *nmlist)
+    self._export_reader_internal(
+      klass, self.class_symbol_prefix(klass), nmlist)
+  end # Safer::IVarFactory#export_reader
+
+  ##
+  # Used internally.  See Safer::IVarFactory#export_writer, and
+  # Safer::IVarFactory::Dsl#writer .
+  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
+
+  ##
+  # 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+).
+  def export_writer(klass, *nmlist)
+    self._export_writer_internal(
+      klass, self.class_symbol_prefix(klass), nmlist)
+  end # Safer::IVarFactory#export_writer
+
+  ##
+  # Used internally.  See Safer::IVarFactory#export_accessor, and
+  # Safer::IVarFactory::Dsl#accessor .
+  def _export_accessor_internal(klass, prefix, nmlist)
+    self._export_reader_internal(klass, prefix, nmlist)
+    self._export_writer_internal(klass, prefix, nmlist)
+  end
+
+  ##
+  # 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+).
+  def export_accessor(klass, *nmlist)
+    self._export_accessor_internal(
+      klass, self.class_symbol_prefix(klass), nmlist)
+  end # Safer::IVarFactory#export_accessor
+
+  ##
+  # Yield DSL interface for instance variable creation to caller.  See
+  # Safer::IVarFactory::Dsl for the DSL API.
+  # [+klass+] Class object used by DSL interface.
+  def run(klass)
+    yield(Dsl.new(self, klass))
+  end # Safer::IVarFactory#run
+
+end # Safer::IVarFactory
+
+require 'safer/ivarfactory/dsl.rb'
+require 'safer/ivarfactory/prefix.rb'

data/lib/safer/ivarfactory/dsl.rb

@@ -0,0 +1,49 @@
+##
+# Present a lightweight interface to instance variable creation. An
+# instance of this class is given to the user as an argument to the yield
+# block passed to Safer::IVarFactory#run. For example:
+#  class Foo
+#    Safer::IVar.run(self) do |ivar|
+#      # ivar is an instance of Safer::IVarFactory::Dsl
+#    end
+#  end
+class Safer::IVarFactory::Dsl
+  ##
+  # Initialize a DSL object.
+  # [+factory+] IVarFactory to use for creating instance variables.
+  # [+klass+] +klass argument to Safer::IVarFactory#run; create instance
+  #           variables in this class.
+  def initialize(factory, klass)
+    @factory = factory
+    @klass = klass
+    @symbol_prefix = factory.class_symbol_prefix(klass)
+  end # Safer::IVarFactory::Dsl#initialize
+
+  ##
+  # Define Safer::IVarFactory instance variables for the class attached to
+  # this DSL object. See Safer::IVarFactory#instance_variable
+  def ivar(*args)
+    @factory._instance_variable_internal(@klass, @symbol_prefix, args)
+  end # Safer::IVarFactory::Dsl#ivar
+
+  ##
+  # Export readers for Safer::IVarFactory instance variables in the class
+  # attached to this DSL object. See Safer::IVarFactory#export_reader
+  def reader(*args)
+    @factory._export_reader_internal(@klass, @symbol_prefix, args)
+  end # Safer::IVarFactory::Dsl#reader
+
+  ##
+  # Export writers for Safer::IVarFactory instance variables in the class
+  # attached to this DSL object. See Safer::IVarFactory#export_reader
+  def writer(*args)
+    @factory._export_writer_internal(@klass, @symbol_prefix, args)
+  end # Safer::IVarFactory::Dsl#writer
+
+  ##
+  # Export accessors for Safer::IVarFactory instance variables in the class
+  # attached to this DSL object. See Safer::IVarFactory#export_reader
+  def accessor(*args)
+    @factory._export_accessor_internal(@klass, @symbol_prefix, args)
+  end # Safer::IVarFactory::Dsl#accessor
+end # Safer::IVarFactory::Dsl

data/lib/safer/ivarfactory/prefix.rb

@@ -0,0 +1,29 @@
+class Safer::IVarFactory::Prefix
+  def self.is_anon(component)
+    /^\#<.*>$/.match(component)
+  end
+
+  class Full < Safer::IVarFactory::Prefix
+    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 self.is_anon(el)
+          nil
+        elsif memo
+          memo + '_' + el.downcase
+        else
+          el.downcase
+        end
+      end
+    end # Safer::IVarFactory::Prefix::Full#class_symbol_prefix
+  end # Safer::IVarFactory::Prefix::Full
+
+  class Last < Safer::IVarFactory::Prefix
+    def self.class_symbol_prefix(klass)
+      el = klass.to_s.split('::').reverse.find do |obj|
+        ! self.is_anon(obj)
+      end
+      el.downcase
+    end
+  end # Safer::IVarFactory::Prefix::Last
+end # Safer::IVarFactory::Prefix

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: safer
 version: !ruby/object:Gem::Version 
-  hash: 15
   prerelease: false
   segments: 
   - 0
   - 4
-  - 0
-  version: 0.4.0
+  - 1
+  version: 0.4.1
 platform: ruby
 authors: 
 - Aidan Cully
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
         segments: 
         - 2
         - 0
@@ -42,12 +40,11 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
         segments: 
         - 2
-        - 6
-        - 2
-        version: 2.6.2
+        - 7
+        - 0
+        version: 2.7.0
   type: :development
   version_requirements: *id002
 description: |-
@@ -81,13 +78,16 @@ files:
 - Rakefile
 - lib/safer.rb
 - lib/safer/ivar.rb
+- lib/safer/ivarfactory.rb
+- lib/safer/ivarfactory/dsl.rb
+- lib/safer/ivarfactory/prefix.rb
 - lib/safer/protocol.rb
 - lib/safer/hashprotocol.rb
 - test/test_safer_ivar.rb
-- test/test_safer_protocol.rb
-- test/test_safer_hashprotocol.rb
 - test/test_safer_ivar_run.rb
 - test/test_safer_ivarfactory.rb
+- test/test_safer_protocol.rb
+- test/test_safer_hashprotocol.rb
 has_rdoc: true
 homepage: http://safer.rubyforge.org
 licenses: []
@@ -103,7 +103,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -112,7 +111,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"