qualitysmith_extensions 0.0.20 → 0.0.24

data/lib/qualitysmith_extensions/module.bak/guard_method.rb

@@ -0,0 +1,309 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes!
+# Developer notes::
+# * Is it thread-safe?? Probably not, as it stands...
+#   But the whole thing that prompted me to create a guard method in the first place was to try to avoid a deadlock that was
+#   caused by recursively calling a method with a synchronize in it (in other words, someone else's attempt at thread-safety
+#   resulted in me getting into a deadlock, which is why I wrote this method to begin with). So I'm not even sure if it's
+#   possible to make it thread-safe?
+#++
+
+require 'rubygems'
+require 'qualitysmith_extensions/module/attribute_accessors'
+require 'qualitysmith_extensions/module/mattr_tester'
+require 'qualitysmith_extensions/module/attr_tester'
+require 'qualitysmith_extensions/symbol/match'
+
+
+class Module
+  # A guard method (by this definition anyway) is a method that sets a flag, executes a block, and then returns the flag to its
+  # previous value. It ensures that the flag is set during the execution of the block.
+  #
+  # In the simplest case, you'd use it like this:
+  #   class A
+  #     guard_method :disable_stupid_stuff!, :@stupid_stuff_disabled
+  #   end
+  #   a = A.new
+  #   a.disable_stupid_stuff! do   # Causes @stupid_stuff_disabled to be set to true
+  #     # Section of code during which you don't want any stupid stuff to happen
+  #   end                          # Causes @stupid_stuff_disabled to be set back to false
+  #   # Okay, a, you can resume doing stupid stuff again...
+  #   
+  # If you also want a guard method that *disables* the flag rather than *enabling* it, simply pass in the desired name of this
+  # "unguard" method as the value of the +unguard_method_name+ argument.
+  #   class A
+  #     guard_method :guard_the_fruit!, :@guarding_the_fruit, :stop_guarding_the_fruit!
+  #   end
+  #
+  # Examples of unguard methods:
+  #   mguard_method :color_on!, :@@color_enabled, :color_off!
+  #   mguard_method :without_benchmarking, :@@benchmarking_disabled, :with_benchmarking
+  #
+  # These calls can be nested however you wish:
+  #   a.guard_the_fruit! do
+  #     a.stop_guarding_the_fruit! do
+  #       assert_equal false, a.guarding_the_fruit?
+  #     end
+  #     assert_equal true, a.guarding_the_fruit?
+  #   end
+  #
+  # You can also use the guard methods as normal flag setter/clearer methods by simply not passing a block to it. Hence
+  #     a.guard_the_fruit!
+  # will simply set @guarding_the_fruit to true, and
+  #     a.stop_guarding_the_fruit!
+  # will set @guarding_the_fruit to false.
+  #
+  def guard_method(guard_method_name, guard_variable, unguard_method_name = nil)
+    raise ArgumentError.new("Expected an instance variable name but got #{guard_variable}") if guard_variable !~ /^@([\w_]+)$/
+    guard_variable.to_s =~ /^@([\w_]+)$/    # Why didn't the regexp above set $1 ??
+    class_eval do
+      attr_tester $1.to_sym
+    end
+    module_eval <<-End, __FILE__, __LINE__+1
+      def #{guard_method_name}(new_value = nil, &block)
+        old_guard_state, #{guard_variable} = #{guard_variable}, true
+        if block_given?
+          returning = yield
+          #{guard_variable} = old_guard_state
+          returning
+        end
+      end
+    End
+    module_eval <<-End, __FILE__, __LINE__+1 unless unguard_method_name.nil?
+      def #{unguard_method_name}(new_value = nil, &block)
+        old_guard_state, #{guard_variable} = #{guard_variable}, false
+        if block_given?
+          returning = yield
+          #{guard_variable} = old_guard_state
+          returning
+        end
+      end
+    End
+  end
+
+  # See the documentation for guard_method. mguard_method does the same thing, only it creates a _class_ (or _module_) method
+  # rather than an instance method and it uses a _class_ (or _module_) variable rather than an instance variable to store the
+  # guard state.
+  #
+  # Example:
+  #   mguard_method :guard_the_fruit!, :@@guarding_the_fruit
+  def mguard_method(guard_method_name, guard_variable, unguard_method_name = nil)
+    raise ArgumentError.new("Expected a class variable name but got #{guard_variable}") if guard_variable !~ /^@@[\w_]+$/
+    guard_variable.to_s =~ /^@@([\w_]+)$/
+    class_eval do
+      mattr_tester $1.to_sym
+    end
+    module_eval <<-End, __FILE__, __LINE__+1
+      class << self
+        def #{guard_method_name}(new_value = nil, &block)
+          old_guard_state, #{guard_variable} = #{guard_variable}, true
+          if block_given?
+            returning = yield
+            #{guard_variable} = old_guard_state
+            returning
+          end
+        end
+      end
+    End
+    module_eval <<-End, __FILE__, __LINE__+1 unless unguard_method_name.nil?
+      class << self
+        def #{unguard_method_name}(new_value = nil, &block)
+          old_guard_state, #{guard_variable} = #{guard_variable}, false
+          if block_given?
+            returning = yield
+            #{guard_variable} = old_guard_state
+            returning
+          end
+        end
+      end
+    End
+  end
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+
+class GuardMethodTest_Simple < Test::Unit::TestCase
+  class A
+    guard_method :guard_the_fruit!, :@guarding_the_fruit
+  end
+  def test_guard_method
+    a = A.new
+    assert_equal nil, a.guarding_the_fruit?
+    a.guard_the_fruit! do
+      # Call it recursively!
+      a.guard_the_fruit! do
+        assert_equal true, a.guarding_the_fruit?
+      end
+      assert_equal true, a.guarding_the_fruit?   # This is the reason why we have to save the 'old_guard_state'. So that we don't stupidly set it back to false if we still haven't exited from the outermost call to the guard black.
+    end
+    assert_equal nil, a.guarding_the_fruit?
+  end
+  def test_guard_method_error
+    assert_raise(ArgumentError) do
+      self.class.class_eval do
+        guard_method :guard_the_fruit!, :@@guarding_the_fruit
+      end
+    end
+  end
+  def test_return_value
+    assert_equal 'special return value', A.new.guard_the_fruit! { 'special return value' }
+  end
+end
+
+class GuardMethodTest_WithUnguard < Test::Unit::TestCase
+  class A
+    guard_method :guard_the_fruit!, :@guarding_the_fruit, :stop_guarding_the_fruit!
+  end
+  def test_guard_method
+    a = A.new
+    assert_equal nil, a.guarding_the_fruit?
+    a.guard_the_fruit! do
+      a.guard_the_fruit! do
+        assert_equal true, a.guarding_the_fruit?
+
+        a.stop_guarding_the_fruit! do
+          assert_equal false, a.guarding_the_fruit?
+          a.guard_the_fruit! do
+            assert_equal true, a.guarding_the_fruit?
+          end
+          assert_equal false, a.guarding_the_fruit?
+        end
+
+        assert_equal true, a.guarding_the_fruit?
+      end
+      assert_equal true, a.guarding_the_fruit?
+    end
+    assert_equal nil, a.guarding_the_fruit?
+  end
+
+  def test_guard_method_with_simple_blockless_toggles
+    a = A.new
+    assert_equal nil, a.guarding_the_fruit?
+    a.guard_the_fruit!
+    assert_equal true, a.guarding_the_fruit?
+
+    a.stop_guarding_the_fruit! do
+      assert_equal false, a.guarding_the_fruit?
+      a.guard_the_fruit! do
+        assert_equal true, a.guarding_the_fruit?
+        a.stop_guarding_the_fruit!
+        assert_equal false, a.guarding_the_fruit?
+        a.guard_the_fruit!
+        assert_equal true, a.guarding_the_fruit?
+      end
+      assert_equal false, a.guarding_the_fruit?
+    end
+
+    assert_equal true, a.guarding_the_fruit?
+  end
+
+  def test_return_value
+    assert_equal nil, A.new.guard_the_fruit!
+    assert_equal nil, A.new.stop_guarding_the_fruit!
+    assert_equal 'special return value', A.new.guard_the_fruit!         { 'special return value' }
+    assert_equal 'special return value', A.new.stop_guarding_the_fruit! { 'special return value' }
+  end
+end
+
+#---------------------------------------------------------------------------------------------------------------------------------
+# Begin duplication
+# The following TestCases are simply duplicates of the previous except that they test mguard_method rather than guard_method
+# The main differenes/substitutions:
+# * @@guarding_the_fruit, rather than @guarding_the_fruit
+# * :'<,'>s/A.new/B/g
+# * :'<,'>s/\<a\>/B/g
+
+class MGuardMethodTest_Simple < Test::Unit::TestCase
+  class B
+    mguard_method :guard_the_fruit!, :@@guarding_the_fruit
+  end
+  def test_mguard_method
+    assert_equal nil, B.guarding_the_fruit?
+    B.guard_the_fruit! do
+      # Call it recursively!
+      B.guard_the_fruit! do
+        assert_equal true, B.guarding_the_fruit?
+      end
+      assert_equal true, B.guarding_the_fruit?   # This is the reason why we have to save the 'old_guard_state'. So that we don't stupidly set it back to false if we still haven't exited from the outermost call to the guard black.
+    end
+    assert_equal nil, B.guarding_the_fruit?
+  end
+  def test_mguard_method_error
+    assert_raise(ArgumentError) do
+      self.class.class_eval do
+        mguard_method :guard_the_fruit!, :@guarding_the_fruit
+      end
+    end
+  end
+  def test_return_value
+    assert_equal 'special return value', B.guard_the_fruit! { 'special return value' }
+  end
+end
+
+class MGuardMethodTest_WithUnguard < Test::Unit::TestCase
+  class B
+    mguard_method :guard_the_fruit!, :@@guarding_the_fruit, :stop_guarding_the_fruit!
+  end
+  def test_guard_method
+    assert_equal nil, B.guarding_the_fruit?
+    B.guard_the_fruit! do
+      B.guard_the_fruit! do
+        assert_equal true, B.guarding_the_fruit?
+
+        B.stop_guarding_the_fruit! do
+          assert_equal false, B.guarding_the_fruit?
+          B.guard_the_fruit! do
+            assert_equal true, B.guarding_the_fruit?
+          end
+          assert_equal false, B.guarding_the_fruit?
+        end
+
+        assert_equal true, B.guarding_the_fruit?
+      end
+      assert_equal true, B.guarding_the_fruit?
+    end
+    assert_equal nil, B.guarding_the_fruit?
+  end
+
+  def test_guard_method_with_simple_blockless_toggles
+    assert_equal nil, B.guarding_the_fruit?
+    B.guard_the_fruit!
+    assert_equal true, B.guarding_the_fruit?
+
+    B.stop_guarding_the_fruit! do
+      assert_equal false, B.guarding_the_fruit?
+      B.guard_the_fruit! do
+        assert_equal true, B.guarding_the_fruit?
+        B.stop_guarding_the_fruit!
+        assert_equal false, B.guarding_the_fruit?
+        B.guard_the_fruit!
+        assert_equal true, B.guarding_the_fruit?
+      end
+      assert_equal false, B.guarding_the_fruit?
+    end
+
+    assert_equal true, B.guarding_the_fruit?
+  end
+
+  def test_return_value
+    assert_equal nil, B.guard_the_fruit!
+    assert_equal nil, B.stop_guarding_the_fruit!
+    assert_equal 'special return value', B.guard_the_fruit!         { 'special return value' }
+    assert_equal 'special return value', B.stop_guarding_the_fruit! { 'special return value' }
+  end
+end
+# End duplication
+#---------------------------------------------------------------------------------------------------------------------------------
+=end
+

data/lib/qualitysmith_extensions/module.bak/includable_once.rb

@@ -0,0 +1,10 @@
+
+#    mattr_accessor :already_included
+#    def self.already_included
+#      @@already_included ||= false
+#    end
+#
+#    def self.included(base_module)
+#      return if @@already_included
+#      @@already_included = true
+#

data/lib/qualitysmith_extensions/module.bak/mattr_tester.rb

@@ -0,0 +1,235 @@
+#--
+# Author::    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 would rename this one to bool_attr_accessor, which calls both bool_attr_reader and bool_attr_writer, but also lets you just create a reader or writer if you so desire.
+#++
+
+class Module
+  # This creates two methods for each given variable name. One is used to test
+  # the attribute and the other is used to set or toggle it.
+  #
+  #   bool_attr_accessor :a
+  #
+  # is equivalent to
+  #
+  #   def self.a?
+  #     @@a ? true : @@a
+  #   end
+  #
+  #   def self.a!(switch=Exception)
+  #     if switch == Exception
+  #       @@a = !@@a
+  #     else
+  #       @@a = switch ? true : false
+  #       self
+  #     end
+  #   end
+  #
+  # Works for both classes and modules.
+  #
+  def mbool_attr_accessor(*args)
+
+    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}?(true_value=true)
+          @@#{a} ? true_value : @@#{a}
+        end
+      }
+      make["#{a}!".to_sym] = %{
+        def self.#{a}!(switch=Exception)
+          if switch == Exception
+            @@#{a} = !@@#{a}
+          else
+            @@#{a} = switch ? true : false
+            self
+          end
+        end
+      }
+    }
+    module_eval make.values.join("\n"), __FILE__, __LINE__
+
+    make.keys
+  end
+end
+
+
+
+
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+require 'rubygems'
+require 'qualitysmith_extensions/object/ignore_access'
+require 'set'
+
+require 'qualitysmith_extensions/module/bool_attr_accessor'   # Simply to show a comparison of mbool_attr_accessor and using class<<self and bool_attr_accessor
+
+# 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
+
+# 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
+    mbool_attr_accessor :a
+  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 nil, C.a? 
+    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
+

data/lib/qualitysmith_extensions/object/ignore_access.rb

@@ -24,10 +24,15 @@ class Object
 
   # Sends all messages to receiver, bypassing access restrictions, allowing you to call private methods (like class_variable_get) without having to write ugly send() calls.
   #
-  #   o.class.ignore_access.class_variable_set(:@@v, 'old value')
+  #   o.class.ignore_access.class_variable_set(:@@v, 'new value')
   # is equivalent to:
   #   o.class.send(:class_variable_set, :@@v, 'new value')
   #
+  # If you tried to just call the method directly, like this:
+  #   o.class.class_variable_set(:@@v, 'new value')
+  # you would get a NoMethodError:
+  #   NoMethodError: private method `class_variable_set' called for Klass:Class
+  #
   def ignore_access
     @_ignore_access_functor ||= Functor.new do |op,*args|
       self.send(op,*args)

data/lib/qualitysmith_extensions/object/send_if.rb

@@ -2,19 +2,26 @@
 # Author::    Tyler Rick
 # Copyright:: Copyright (c) 2007 QualitySmith, Inc.
 # License::   Ruby License
-# Submit to Facets?:: Maybe
+# Submit to Facets?:: Yes.
 # Developer notes::
-# * The name of this method probably ought to be a little more specific.
+# * The name of this method maybe ought to be a little more specific. What does anyone else think?
 #   * It should say something about the fact that it the message sending is conditional but the block execution is unconditional.
 #   * always_execute_block_but_only_send_message_if ? Hmm... a bit too verbose, perhaps.
 #   * conditional_passthrough ?
 #   * passthrough_unless ?
 #   * use_wrapper_method_if ?
+#   * Or just leave it how it is because all the alternatives are too long...
 #++
 
+require 'rubygems'
+gem 'facets'
+require 'facets/core/kernel/with'       # returning
 
 class Object
-  # Unconditionally calls +block_to_always_execute+. But only sends +message+ to +self+ if +condition+ is met.
+  # But only sends +message+ to +self+ if +condition+ is met.
+  #
+  # If a block (+block_to_always_execute+) is supplied, it is passed on to the message if the condition is met; (otherwise it is
+  # simply called without sending the message).
   #
   # This is useful if you want to wrap a block with some method but you only want the method itself to be used some of the time.
   # For example, if it's for benchmarking, you may only want to enable it during development but disable during production to save on some overhead.
@@ -22,17 +29,30 @@ class Object
   # Note: this cannot be used to call methods that expect blocks (Ruby 1.9 maybe?)
   #
   def send_if(condition, message, *args, &block_to_always_execute)
-    if condition
-      self.__send__(message, *args, &block_to_always_execute)
-    else
-      block_to_always_execute.call
-    end
+      if condition
+        self.__send__(message, *args, &block_to_always_execute)
+      else
+        if block_given?
+          block_to_always_execute.call
+        else
+          self
+        end
+      end
   end
 
   # Opposite of send_if
   def send_unless(condition, *args, &block)
     self.send_if(!condition, *args, &block)
   end
+
+  # Lets you reduce duplication a little bit. Can do this:
+  #   @foo.send_if_true(color)
+  # instead of this:
+  #   @foo.send_if(color, color)
+  #
+  def send_if_true(condition, *args, &block)
+    self.send_if(condition, condition, *args, &block)
+  end
 end
 
 
@@ -58,13 +78,19 @@ class Foo
     sleep 0.1     # Simulate lots of overhead, which we may want to avoid if we can help it
   end
 end
+class String
+  def pink
+    "#{self} (in pink)"
+  end
+end
 
 class TheTest < Test::Unit::TestCase
   def setup
     @foo = Foo.new
+    @string = 'food'
   end
 
-  def test_with_true
+  def test_send_if_with_true_condition
     executed_block = false
     @foo.send_if(true, :benchmark) do
       executed_block = true
@@ -73,7 +99,7 @@ class TheTest < Test::Unit::TestCase
     assert @foo.called_benchmark
   end
 
-  def test_with_false
+  def test_send_if_with_false_condition
     executed_block = false
     @foo.send_if(false, :benchmark) do
       executed_block = true
@@ -82,6 +108,38 @@ class TheTest < Test::Unit::TestCase
     assert !@foo.called_benchmark
   end
 
+  def test_send_if_with_no_block
+    color = nil
+    returned = @string.send_if(color, color)
+    assert_equal 'food', @string
+    assert_equal @string, returned
+
+    color = :pink
+    returned = @string.send_if(color, color)
+    assert_equal 'food', @string    # @string itself should be unchanged, but the return value should be be a modified form of @string
+    assert_equal "#{@string} (in pink)", returned
+  end
+  def test_send_if_true_with_no_block
+    color = nil
+    returned = @string.send_if_true(color)
+    assert_equal 'food', @string
+    assert_equal @string, returned
+
+    color = :pink
+    returned = @string.send_if_true(color)
+    assert_equal 'food', @string
+    assert_equal "#{@string} (in pink)", returned
+  end
+
+  def test_send_unless
+    executed_block = false
+    @foo.send_unless(false, :benchmark) do
+      executed_block = true
+    end
+    assert executed_block
+    assert @foo.called_benchmark
+  end
+
 end
 =end