quality_extensions 0.1.1

data/lib/qualitysmith_extensions/module/ancestry_of_instance_method.rb

@@ -0,0 +1,43 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+# Developer notes::
+# * May not have taken every single case into consideration. Needs a bit more testing.
+#   * public/private/protected?
+# * Tests for this method can be found in ../object/ancestry_of_method.rb . It made more sense to test those two methods together;
+#   yet it's still to _use_ module/ancestry_of_instance_method.rb without using ../object/ancestry_of_method.rb.
+#++
+
+class Module
+
+  # Returns the module/class which defined the given instance method. If more than one module/class defined the method, returns the _closest_
+  # ancestor to have defined it (would be +self+ if it is defined in +self+).
+  #
+  # This looks at the results of <tt>instance_methods</tt>, which means that if you call this on a module/class, it will _only_ look 
+  # at _instance_ methods. Thus, (unlike +ancestry_of_method+) it _only_ makes sense to call this method on modules/classes, 
+  # not _instances_ of those modules/classes.
+  #
+  # Example:
+  #   class Base
+  #     def it; end
+  #   end
+  #   class SubWithIt < Base
+  #     def it; end
+  #   end
+  #   class SubWithoutIt < Base
+  #   end
+  #   SubWithIt.ancestors # => [SubWithIt, Base, Object, Kernel]
+  #   SubWithIt.ancestry_of_instance_method(:it)    # => SubWithIt  # (Stops with self)
+  #   SubWithoutIt.ancestry_of_instance_method(:it) # => Base       # (Goes one step up the ancestry tree)
+  #
+  # Returns nil if it cannot be found in self or in any ancestor.
+  def ancestry_of_instance_method(method_name)
+    method_name = method_name.to_s
+    self.ancestors.find do |ancestor|
+      ancestor.instance_methods(false).include? method_name
+    end
+  end
+
+end

data/lib/qualitysmith_extensions/module/attribute_accessors.rb

@@ -0,0 +1,49 @@
+# Copied from ActiveSupport because I couldn't get the ones in Facets to work...
+
+# Extends the module object with module and instance accessors for class attributes, 
+# just like the native attr* accessors for instance attributes.
+class Module # :nodoc:
+  def mattr_reader(*syms)
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__+1)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+        
+        def self.#{sym}
+          @@#{sym}
+        end
+
+        def #{sym}
+          @@#{sym}
+        end
+      EOS
+    end
+  end
+  alias_method :cattr_reader, :mattr_reader
+  
+  def mattr_writer(*syms)
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__+1)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+        
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+
+        def #{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+  alias_method :cattr_writer, :mattr_writer
+  
+  def mattr_accessor(*syms)
+    mattr_reader(*syms)
+    mattr_writer(*syms)
+  end
+  alias_method :cattr_accessor, :mattr_accessor
+end

data/lib/qualitysmith_extensions/module/basename.rb

@@ -0,0 +1,76 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+# Developer notes::
+# Changes::
+#++
+
+
+require 'rubygems'
+require 'facets/core/module/basename'
+require 'facets/core/string/basename'
+require 'qualitysmith_extensions/module/namespace'
+
+class Module
+  # Gets the basename of a "module path" (the name of the module without any of the namespace modules that it is contained in), 
+  # in the same sense that <tt>File.basename</tt> returns the basename of a _filesystem_ path.
+  #
+  # This is identical to Facets' String#basename ('facets/core/string/basename') except that:
+  # * it is a class method instead of an instance method of String,
+  # * it accepts modules, strings, and symbols.
+  #
+  # See also <tt>Module.dirname</tt>/<tt>Module.namespace_name_of</tt>.
+  #
+  # These can be used together, such that the following is always true:
+  #   OuterModule::MiddleModule::InnerModule == Module.join(Module.dirname(some_module), Module.basename(some_module)).constantize
+  #   
+  def self.basename(module_or_name)
+    case module_or_name
+      when Module
+        module_or_name.basename
+      when Symbol
+        module_or_name.to_s.basename
+      when String
+        module_or_name.basename
+      else
+        raise ArgumentError
+    end
+  end
+end
+
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+
+module OuterModule; end
+module OuterModule::MiddleModule; end
+module OuterModule::MiddleModule::InnerModule; end
+
+class BasenameTest < Test::Unit::TestCase
+  def test_simple
+    assert_equal 'OuterModule', Module.basename(OuterModule)
+    assert_equal 'OuterModule', Module.basename(:OuterModule)
+    assert_equal 'OuterModule', Module.basename('OuterModule')
+  end
+  def test_nesting
+    assert_equal 'InnerModule',
+                 Module.basename(OuterModule::MiddleModule::InnerModule)
+    assert_equal 'InnerModule',
+                 Module.basename(:'OuterModule::MiddleModule::InnerModule')
+    assert_equal 'InnerModule',
+                 Module.basename('OuterModule::MiddleModule::InnerModule')
+  end
+end
+=end
+
+

data/lib/qualitysmith_extensions/module/bool_attr_accessor.rb

@@ -0,0 +1,497 @@
+#--
+# Author::    Thomas Sawyer, Tyler Rick
+# Copyright:: Copyright (c) Thomas Sawyer, probably, since this is a derivative work
+# License::   Ruby License
+# Submit to Facets?:: Yes
+# Developer notes::
+# * Based on /usr/lib/ruby/gems/1.8/gems/facets-1.8.54/lib/facets/core/module/attr_tester.rb
+# * Hey Thomas, don't you think Module#attr_tester should only create the read-only a? method and have another method that creates the writer (like there how we have attr_reader, _writer, and _accessor?) ? "tester" does not imply "setter" in my mind...
+# * I'm going to rename this one to bool_attr_accessor, which calls both bool_attr_reader and bool_attr_writer
+# * Then you also have the option to use bool_attr_reader and bool_attr_writer separately if you so desire.
+# * Other changes made:
+#   * Changed it so that if you call a!(false) it would actually set @a to false rather than leaving it unchanged. (I assume that was a bug.)
+#++
+
+# bool_attr_accessor
+
+class Module
+  # This creates a reader method for a boolean (flag) attribute (instance variable).
+  #
+  #   bool_attr_reader :a
+  #
+  # is equivalent to
+  #
+  #   def a?
+  #     @a ? true : @a
+  #   end
+  #
+  # Example:
+  #   class Foo
+  #     def set_it
+  #       @a = true
+  #     end
+  #   end
+  #   x = Foo.new
+  #   x.a?        # => false
+  #   x.set_it
+  #   x.a?        # => true
+  #
+  def bool_attr_reader(*args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)    # These options aren't used here, per se, but it allows us to have bool_attr_accessor pass along same args to both bool_attr_reader and bool_attr_setter.
+
+    make = {}
+    args.each { |a|
+      make["#{a}?".to_sym] = %{
+        def #{a}?(true_value=true)
+          @#{a} ? true_value : @#{a}
+        end
+      }
+    }
+    module_eval make.values.join("\n"), __FILE__, __LINE__
+
+    make.keys
+  end
+
+  # This creates a setter method for a boolean (flag) attribute (instance variable).
+  #
+  #   bool_attr_setter :a
+  #
+  # is equivalent to
+  #
+  #   def a!(switch=Exception)
+  #     if switch == Exception
+  #       @a = !@a
+  #     else
+  #       @a = switch ? true : false
+  #       self
+  #     end
+  #   end
+  #
+  # This setter method can either be used to set it directly to true or false or to toggle it.
+  #
+  # Examples:
+  #   x = Klass.new
+  #   x.a! true   # sets @a to true
+  #   x.a!        # toggles @a, so that it ends up being false
+  #   x.a!        # toggles @a, so that it ends up being true
+  #   x.a! false  # sets @a to false
+  #
+  # Use <tt>:allow_nil</tt> if you want it to be a tri-state flag -- that is, if you need to be able to set it to +nil+ as well as true and false.
+  #   bool_attr_setter :a, :b, :allow_nil => true
+  #   x.a! nil  # sets @a to nil
+  #
+  def bool_attr_setter(*args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)
+
+    make = {}
+    args.each { |a|
+      make["#{a}!".to_sym] = %{
+        def #{a}!(switch=Exception)
+          if switch == Exception
+            @#{a} = !@#{a}
+          else
+            #{
+              options[:allow_nil] ?
+                "@#{a} = switch ? true : switch" :
+                "@#{a} = switch ? true : false"
+            }
+            self
+          end
+        end
+      }
+    }
+    module_eval make.values.join("\n"), __FILE__, __LINE__
+    make.keys
+  end
+
+
+  # This creates both a reader and a setter for a boolean (flag) attribute (instance variable).
+  #
+  #   bool_attr_accessor :a
+  #
+  # is equivalent to
+  #
+  #   bool_attr_reader :a
+  #   bool_attr_setter :a
+  #
+  # Examples:
+  #   x = Klass.new
+  #   x.a! true   # sets @a to true
+  #   x.a?        # => true
+  #   x.a!        # toggles @a, so that it ends up being false
+  #   x.a!        # toggles @a, so that it ends up being true
+  #   x.a! false  # sets @a to false
+  #
+  def bool_attr_accessor(*args)
+    bool_attr_reader *args
+    bool_attr_setter *args
+  end
+
+end
+
+# mbool_attr_accessor
+
+class Module
+  # This creates a reader method for a boolean (flag) class/module variable.
+  #
+  #   mbool_attr_reader :a
+  #
+  # is equivalent to
+  #
+  #   def self.a?
+  #     @@a ? true : @@a
+  #   end
+  #
+  # Works for both classes and modules.
+  #
+  def mbool_attr_reader(*args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)    # These options aren't used here, per se, but it allows us to have bool_attr_accessor pass along same args to both bool_attr_reader and bool_attr_setter.
+
+    make = {}
+    args.each { |a|
+      make["#{a}?".to_sym] = %{
+        def self.#{a}?(true_value=true)
+          @@#{a} ? true_value : @@#{a}
+        end
+      }
+    }
+    module_eval make.values.join("\n"), __FILE__, __LINE__
+    make.keys
+  end
+
+  # This creates a setter method for a boolean (flag) class/module variable.
+  #
+  #   mbool_attr_setter :a
+  #
+  # is equivalent to
+  #
+  #   def self.a!(switch=Exception)
+  #     if switch == Exception
+  #       @@a = !@@a
+  #     else
+  #       @@a = switch ? true : false
+  #       self
+  #     end
+  #   end
+  #
+  # Works for both classes and modules.
+  #
+  # Use <tt>:allow_nil</tt> if you want it to be a tri-state flag -- that is, if you need to be able to set it to +nil+ as well as true and false.
+  #   mbool_attr_setter :a, :b, :allow_nil => true
+  #   C.a! nil  # sets @@a to nil
+  #
+  def mbool_attr_setter(*args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)
+
+    make = {}
+    args.each { |a|
+      # Initialize it first so that we won't have any NameErrors.
+      module_eval %{ @@#{a} = nil if !defined?(@@#{a}) }, __FILE__, __LINE__
+
+      make["#{a}!".to_sym] = %{
+        def self.#{a}!(switch=Exception)
+          if switch == Exception
+            @@#{a} = !@@#{a}
+          else
+            #{
+              options[:allow_nil] ?
+                "@@#{a} = switch ? true : switch" :
+                "@@#{a} = switch ? true : false"
+            }
+            self
+          end
+        end
+      }
+    }
+    module_eval make.values.join("\n"), __FILE__, __LINE__
+    make.keys
+  end
+
+  # This creates both a reader and a setter for a boolean (flag) class/module variable.
+  #
+  #   mbool_attr_accessor :a
+  #
+  # is equivalent to
+  #
+  #   mbool_attr_reader :a
+  #   mbool_attr_setter :a
+  #
+  # Works for both classes and modules.
+  #
+  def mbool_attr_accessor(*args)
+    mbool_attr_reader *args
+    mbool_attr_setter *args
+  end
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+require 'rubygems'
+require 'qualitysmith_extensions/object/ignore_access'
+
+#---------------------------------------------------------------------------------------------------
+# Test that it works for *instances*
+class TestBoolAttr < Test::Unit::TestCase
+
+  class C
+    bool_attr_accessor :a, :b
+  end
+
+  def setup
+    @x = C.new
+  end
+
+  # Also tests that it can create multiple accessors at once.
+  def test1_default_is_nil
+    assert_equal nil, C.new.a? 
+    assert_equal nil, C.new.b? 
+  end
+
+  def test2_toggle
+    assert_equal nil, @x.a? 
+    @x.a!
+    assert_equal true, @x.a? 
+    @x.a!
+    assert_equal false, @x.a? 
+  end
+
+  def test3_setter
+    @x.a! true
+    @x.a! true
+    assert_equal true, @x.a? 
+
+    @x.a! false 
+    assert_equal false, @x.a? 
+  end
+  def test4_sets_to_boolean_even_if_try_to_set_to_other_type
+    @x.a! "whatever" 
+    assert_equal true, @x.a?     # Still returns a boolean even though we tried to set it to a string.
+
+    @x.a! nil
+    assert_equal false, @x.a?    # Still returns a boolean even though we tried to set it to nil.
+  end
+
+end
+
+class TestBoolAttr_AllowNil < Test::Unit::TestCase
+
+  class C
+    bool_attr_accessor :a, :b, :allow_nil => true
+  end
+
+  def setup
+    @x = C.new
+  end
+
+  def test1_default_is_nil
+    assert_equal nil, C.new.a? 
+    assert_equal nil, C.new.b? 
+  end
+
+  def test2_for_nilability
+    @x.a! "whatever" 
+    assert_equal true, @x.a?          # Still returns a boolean even though we tried to set it to a string.
+
+    @x.a! nil
+    assert_equal nil, @x.a?           # Lets us set it to nil!
+    #assert_equal true, @x.a?(nil)     # Testing the "is it nil?" question.
+    assert_equal true, @x.a?.nil?     # Testing the "is it nil?" question.
+
+
+    @x.a! false
+    assert_equal false, @x.a?         # Lets us set it to false!
+    assert_equal true, @x.a? == false   # Testing the "is it false?" question.
+  end
+end
+
+
+
+#---------------------------------------------------------------------------------------------------
+# Test that it works for *modules*
+class TestForModules < Test::Unit::TestCase
+
+  class M_for_default_is_nil
+    mbool_attr_accessor :a
+  end
+  def test1_default_is_nil
+    assert_equal nil, M_for_default_is_nil.a? 
+  end
+
+  module M
+    mbool_attr_accessor :a
+  end
+  def test2_toggle
+    assert_equal nil, M.a? 
+    M.a!
+    assert_equal true, M.a? 
+    M.a!
+    assert_equal false, M.a? 
+  end
+  def test3_setter
+    M.a! true
+    M.a! true
+    assert_equal true, M.a? 
+
+    M.a! false 
+    assert_equal false, M.a? 
+  end
+  def test4_sets_to_boolean_even_if_try_to_set_to_other_type
+    M.a! "whatever" 
+    assert_equal true, M.a?     # Still returns a boolean even though we tried to set it to a string.
+
+    M.a! nil
+    assert_equal false, M.a?    # Still returns a boolean even though we tried to set it to nil.
+  end
+end
+class TestForModules_AllowNil < Test::Unit::TestCase
+
+  module M
+    mbool_attr_accessor :a, :b, :allow_nil => true
+  end
+
+  def test1_default_is_nil
+    assert_equal nil, M.a? 
+    assert_equal nil, M.b? 
+  end
+
+  def test2_for_nilability
+    M.a! "whatever" 
+    assert_equal true, M.a?          # Still returns a boolean even though we tried to set it to a string.
+
+    M.a! nil
+    assert_equal nil, M.a?           # Lets us set it to nil!
+    #assert_equal true, M.a?(nil)     # Testing the "is it nil?" question.
+    assert_equal true, M.a?.nil?     # Testing the "is it nil?" question.
+
+
+    M.a! false
+    assert_equal false, M.a?         # Lets us set it to false!
+    assert_equal true, M.a? == false   # Testing the "is it false?" question.
+  end
+end
+
+#---------------------------------------------------------------------------------------------------
+# Test that it also works for *classes*
+class TestForClasses < Test::Unit::TestCase
+
+  class C_for_default_is_nil
+    mbool_attr_accessor :a
+  end
+  def test1_default_is_nil
+    assert_equal nil, C_for_default_is_nil.a? 
+  end
+
+  class C
+    mbool_attr_accessor :a
+  end
+
+  def test2_toggle
+    C.access.class_variable_set :@@a, false 
+    assert_equal false, C.a?    # otherwise would have been nil
+    C.a!
+    assert_equal true, C.a? 
+    C.a!
+    assert_equal false, C.a? 
+
+    assert_equal ["@_ignore_access_functor"], C.instance_variables
+    assert_equal ["@@a"], C.class_variables
+  end
+
+  def test3_setter
+    C.a! true
+    C.a! true
+    assert_equal true, C.a? 
+
+    C.a! false 
+    assert_equal false, C.a? 
+  end
+  def test4_sets_to_boolean_even_if_try_to_set_to_other_type
+    C.a! "whatever" 
+    assert_equal true, C.a?     # Still returns a boolean even though we tried to set it to a string.
+
+    C.a! nil
+    assert_equal false, C.a?    # Still returns a boolean even though we tried to set it to nil.
+  end
+end
+
+
+# Observation: You can also the normal bool_attr_accessor in conjunction with class << self.
+# The methods generated seem to *behave* in the same way. Both techniques allow you to query the class (C.a?).
+# The only difference is in which *variables* are use to store the state:
+# * class << self and the normal bool_attr_accessor:
+#   Stores the state in an instance variable for the *class*: @a
+# * mbool_attr_accessor:
+#   Stores the state in a *class* variable: @@a
+#
+# Can someone explain to me the difference between class variables and instance variables of a class?
+# It seems silly (confusing even!) to have both of them!
+#
+# My best explanation is that the fact that we can even *have* instance variables of a class does *not* mean it's a good idea
+# to use them. It simply means that Matz made the language with as few arbitrary restrictions as possible. He made it
+# technically *possible* to do a lot of things that it is probably not good practice to do... And one of those things is
+# using instance variables of classes to store state information for that class.
+#
+# What do you think class variables are for? Exactly that! There's a *reason* we have both @a and @@a variables -- to
+# *differentiate* between the two kinds of variables and keep programmers sane. So please don't blur the distinction and
+# use the @a-type variable to do the job that @@a-type variables are for.
+#
+# Or am I missing something here?
+#
+class TestWith_class_self_and_plain_bool_attr_accessor < Test::Unit::TestCase
+
+  class C_for_default_is_nil
+    class << self
+      bool_attr_accessor :a
+    end
+  end
+  def test1_default_is_nil
+    assert_equal nil, C_for_default_is_nil.a? 
+  end
+
+  class C
+    class << self
+      bool_attr_accessor :a
+    end
+  end
+  # This is where I spotted a class that uses this technique:
+  # * Test::Unit::Assertions::AssertionMessage
+
+  def test_2_toggle
+    assert_equal false, C.a?  # Why isn't it nil like it is for the instance use case of bool_attr_accessor?
+    C.a!
+    assert_equal true, C.a? 
+    C.a!
+    assert_equal false, C.a? 
+
+    assert_equal ["@a"], C.instance_variables
+    assert_equal [], C.new.instance_variables  # @a is an instance variable of the *class*  *not* objects of the class  -- weird!
+    assert_equal [], C.class_variables
+  end
+
+  def test3_setter
+    C.a! true
+    C.a! true
+    assert_equal true, C.a? 
+
+    C.a! false 
+    assert_equal false, C.a? 
+  end
+  def test4_sets_to_boolean_even_if_try_to_set_to_other_type
+    C.a! "whatever" 
+    assert_equal true, C.a?     # Still returns a boolean even though we tried to set it to a string.
+
+    C.a! nil
+    assert_equal false, C.a?    # Still returns a boolean even though we tried to set it to nil.
+  end
+
+end
+=end
+