rconditions 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2007 Norman Timmler, Tammo Freese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,5 @@
+= RConditions
+
+RConditions generates a bang method (for example, <tt>Array#empty!</tt>) for each predicate method (for example, <tt>Array#empty?</tt>). The bang method will return true if the predicate method returns true, otherwise it will throw an exception. The exception will include auto-generated modules that give information which predicate methods passed or failed in the bang method's execution.
+
+For more information, see the roc or ri documentation of the module RConditions.

data/lib/rconditions.rb

@@ -0,0 +1,234 @@
+# = RConditions
+# 
+# RConditions generates a bang method (for example, <tt>Array#empty!</tt>) 
+# for each predicate method (for example, <tt>Array#empty?</tt>). The bang 
+# method will return true if the predicate method returns true, otherwise it
+# will throw an exception. The exception will include auto-generated modules
+# that give information which predicate methods passed or failed in the bang
+# method's execution.
+# 
+# == Example
+# 
+# Here is a simple example. The raised exception includes a module defined
+# on the class where the method is defined:
+# 
+#   require "rconditions"
+#   
+#   begin 
+#     [1,2].empty!
+#   rescue Array::NotEmptyError => e
+#     p e    
+#   end
+#   
+#   # => #<Exception: Array::NotEmptyError>
+#   
+# Here is a more complicated example:
+# 
+#   require "rconditions"
+#   
+#   class Posting
+#     attr_writer :spam, :active
+# 
+#     def spam?
+#       @spam
+#     end
+#   
+#     def active?
+#       @active
+#     end
+# 
+#     def visible?
+#       !spam? && active? 
+#     end  
+#   end
+# 
+#   class User
+#     attr_writer :admin
+#     
+#     def admin?
+#       @admin
+#     end
+#   
+#     def can_view_posting?(posting)
+#        admin? || posting.visible?
+#     end
+#   end
+# 
+#   user = User.new
+#   user.admin = false
+# 
+#   posting = Posting.new
+#   posting.active = false
+#   posting.spam = true
+# 
+#   begin
+#     user.can_view_posting!(posting)
+#   rescue Posting::SpamError => e
+#     p e
+#   rescue Posting::NotActiveError
+#     puts "should not get here"
+#   end
+#   
+#   # => #<Exception: User::NotAdminError, Posting::SpamError,
+#   #      Posting::NotVisibleError, User::NotCanViewPostingError>  
+# 
+# As you can see, the exception includes modules for each of the evaluated 
+# predicate methods: <tt>User#can_view_posting!(posting)</tt> in the context
+# above called <tt>User#can_view_posting?(posting)</tt>, which called 
+# <tt>User#admin?</tt> and <tt>Posting#can_view_posting?</tt>, which called
+# <tt>Posting#spam?</tt>.
+#     
+# The results were
+# 
+# * <tt>User#admin?                # => false</tt>
+# * <tt>Posting#spam?              # => true</tt>
+# * <tt>Posting#can_view_posting?  # => false</tt>
+# * <tt>User#can_view_posting?     # => false</tt>
+# 
+# so the included exception modules are
+# 
+# * <tt>User::NotAdminError</tt>
+# * <tt>Posting::SpamError</tt>
+# * <tt>Posting::NotCanViewPostingError</tt> 
+# * <tt>User::NotCanViewPostingError</tt>
+# 
+# == Performance
+# 
+# As almost all predicate methods are extended by default, RConditions carries
+# a performance penalty which varies with the number of calls to predicate
+# methods. A simple test setup using mongrel/rails was slowed down by 10-20%
+# by adding <tt>require "rconditions"</tt> to the bottom of its 
+# <tt>enviroment.rb</tt>.
+# 
+# The performance penalty can be avoided by applying RConditions only to new
+# methods, that is, methods defined after <tt>require "rconditions"</tt>. To
+# achieve this, set <tt>RCONDITIONS_ONLY_FOR_NEW_METHODS = true</tt> before
+# the require call. Our test setup had no measurable slowdown afterwards.
+# 
+# == Known Limitations
+# 
+# * RConditions does only support predicate methods starting with a letter and
+#   containing only word characters except the question mark at the end.  
+# * RConditions does not support singleton methods. These includes all class
+#   methods.
+module RConditions
+  class << self
+    
+    # Extends the given predicate method and defines a bang method for it. You
+    # should never call this method directly, it is called from 
+    # Module#method_added.
+    # * <tt>mod</tt> -- the module on which the method is defined.
+    # * <tt>id</tt> -- the name of the method.
+    def extend_predicate_method_and_define_bang_method(mod, id)
+      return if Thread.current[:rconditions_processing_predicate_method]
+      return if (predicate_method = id.to_s) !~ PREDICATE_METHOD
+      
+      begin
+        Thread.current[:rconditions_processing_predicate_method] = true
+        extend_predicate_method(mod, predicate_method)
+        define_bang_method(mod, predicate_method)
+      ensure  
+        Thread.current[:rconditions_processing_predicate_method] = false
+      end
+    end
+    
+    def exception_modules #:nodoc:
+      Thread.current[:rconditions_exception_modules]
+    end
+    
+    def exception_modules=(value) #:nodoc:
+      Thread.current[:rconditions_exception_modules] = value
+    end
+    
+    private
+      
+      PREDICATE_METHOD = /\A[a-zA-Z]\w*\?\z/ #:nodoc:
+    
+      def extend_predicate_method(mod, predicate_method)
+        predicate_method_without_questionmark = predicate_method[0...-1]
+
+        positive_module = camelize("#{predicate_method_without_questionmark}_error")
+        mod.const_set(positive_module, Module.new) unless mod.const_defined?(positive_module)
+        negative_module = camelize("not_#{predicate_method_without_questionmark}_error")
+        mod.const_set(negative_module, Module.new) unless mod.const_defined?(negative_module)
+        
+        time = Time.now
+        predicate_method_without_rconditions = "#{predicate_method_without_questionmark}_rconditions_#{mod.object_id}_#{time.to_i}_#{time.usec}"
+        original_visibility = visibility(mod, predicate_method)
+
+        mod.class_eval <<-EOS, __FILE__, __LINE__ + 1
+          alias_method :#{predicate_method_without_rconditions}, :#{predicate_method}
+          private :#{predicate_method_without_rconditions}
+
+          def #{predicate_method}(*args, &block)
+            result = #{predicate_method_without_rconditions}(*args, &block)
+            RConditions.exception_modules << (result ? #{positive_module} : #{negative_module}) if RConditions.exception_modules
+            result
+          end
+          #{original_visibility} :#{predicate_method}
+        EOS
+      end
+      
+      def define_bang_method(mod, predicate_method)
+        bang_method = predicate_method[0...-1] + '!'
+        return if mod.method_defined?(bang_method) || mod.private_method_defined?(bang_method)
+
+        visibility = visibility(mod, predicate_method)
+
+        mod.class_eval <<-EOS, __FILE__, __LINE__ + 1
+          def #{bang_method}(*args, &block)
+            RConditions.exception_modules = []
+            result = #{predicate_method}(*args, &block)
+            return result if result
+
+            e = Exception.new(RConditions.exception_modules.map { |m| m.name }.join(', '))
+            RConditions.exception_modules.each { |m| e.extend(m) }
+            raise e
+          ensure
+            RConditions.exception_modules = nil
+          end
+          #{visibility} :#{bang_method}
+        EOS
+      end
+      
+      def camelize(lower_case_and_underscored_word)
+        lower_case_and_underscored_word.gsub(/(^|_)(.)/) { $2.upcase }
+      end
+      
+      def visibility(mod, id)
+        case id 
+        when *mod.public_instance_methods(false): 'public'
+        when *mod.protected_instance_methods(false): 'protected'
+        when *mod.private_instance_methods(false): 'private'
+        end
+      end  
+  end
+end
+
+unless defined? RCONDITIONS_ONLY_FOR_NEW_METHODS
+  # To apply RConditions to new methods only, set this constant to <tt>true</tt>
+  # before <tt>require "rconditions"</tt>.
+  RCONDITIONS_ONLY_FOR_NEW_METHODS = false 
+end  
+  
+unless RCONDITIONS_ONLY_FOR_NEW_METHODS
+  ObjectSpace.each_object(Module) do |mod|
+    mod.instance_methods(false).each do |id|
+      RConditions.extend_predicate_method_and_define_bang_method(mod, id) 
+    end
+  end
+end
+
+class Module
+  alias_method :method_added_without_rconditions, :method_added
+  private :method_added_without_rconditions
+  
+  # To provide a bang method and exception modules for each predicate method,
+  # RConditions hooks into <tt>method_added</tt>. An existing 
+  # <tt>method_added</tt> implementation will not be replaced, but executed 
+  # afterwards.
+  def method_added(id)
+    RConditions.extend_predicate_method_and_define_bang_method(self, id)
+    method_added_without_rconditions(id)
+  end
+end

data/test/rconditions_test.rb

@@ -0,0 +1,261 @@
+require 'test/unit'
+require 'rconditions'
+
+class RConditionsTest < Test::Unit::TestCase
+
+  class Foo
+    def a?; false; end
+    def b?; false; end
+    def c?; a? || b?; end
+    def d?; true; end
+    def e?; !d?; end
+  end
+
+  class Bar < Foo
+    def a?; super; end
+  end
+
+  def test_defines_bang_method_on_predicate_methods_defined_before_r_conditions_was_required
+    assert [].class.method_defined?(:empty!)
+  end
+  
+  def test_defines_bang_method_on_predicate_methods_defined_after_r_conditions_was_required
+    assert Foo.method_defined?(:a!)
+  end
+
+  def test_does_not_define_methods_for_non_predicate_methods
+    foo_methods_with_new_method = Foo.new.methods + ['new_method']
+    eval "class Foo;def new_method; end; end"
+    assert_equal foo_methods_with_new_method.sort, Foo.new.methods.sort
+  end  
+
+  def test_bang_method_returns_true_if_predicate_method_returns_true
+    assert Foo.new.d!
+  end
+  
+  def test_bang_method_passes_predicate_method_result
+    eval <<-EOS
+      class Foo
+        def find_file?; 'a string'; end
+      end
+    EOS
+    assert_equal 'a string', Foo.new.find_file!
+  end
+
+  def test_bang_method_raises_exception_if_predicate_method_returns_false
+    assert_raises(Exception) { Foo.new.a! }
+  end
+
+  def test_bang_method_passes_arguments_to_the_predicate_method
+    eval <<-EOS
+      class Foo
+        attr_reader :args, :block
+        def store_args?(*args, &block); @args, @block = args, block; end
+      end
+    EOS
+    foo = Foo.new
+    block = lambda { }
+    foo.store_args!(1, 2, &block)
+    assert_equal [1, 2], foo.args
+    assert_equal block, foo.block
+  end
+  
+  def test_exception_raised_by_bang_method_includes_exception_module_named_after_the_predicate_method
+    assert exception_raised_by { Foo.new.a! }.kind_of?(Foo::NotAError)
+    assert exception_raised_by { Foo.new.b! }.kind_of?(Foo::NotBError)
+    assert exception_raised_by { Foo.new.c! }.kind_of?(Foo::NotCError)
+    assert exception_raised_by { Bar.new.a! }.kind_of?(Bar::NotAError)
+  end
+  
+  def test_exception_raised_by_bang_method_includes_exception_modules_from_predicate_method_called_inside
+    e = exception_raised_by { Foo.new.c! }
+    assert e.kind_of?(Foo::NotAError)
+    assert e.kind_of?(Foo::NotBError)
+  end
+  
+  def test_exception_raised_by_bang_method_includes_exception_module_from_superclass_predicate_method
+    exception_raised_by { Bar.new.a! }.kind_of?(Foo::AError)
+  end
+
+  def test_exception_raised_by_bang_method_includes_negated_exception_module_from_called_predicate_method
+    exception_raised_by { Foo.new.e! }.kind_of?(Foo::NotDError)
+  end
+
+  def test_no_visible_methods_added_except_bang_method
+    foo_methods_with_predicate_method = Foo.new.methods + ['new_predicate_method?']
+    eval "class Foo;def new_predicate_method?; false; end; end"
+    assert_equal ['new_predicate_method!'], Foo.new.methods - foo_methods_with_predicate_method
+  end
+
+  def test_no_bang_method_will_be_overridden
+    eval "class Foo;def do_not_override_me!; 'public'; end; end"
+    eval "class Foo;def do_not_override_me?; true; end; end"
+    
+    assert_equal 'public', Foo.new.do_not_override_me!
+  end
+
+  def test_no_bang_method_will_be_overridden_even_if_it_is_private
+    eval "class Foo;private;def private_do_not_override_me!; 'private'; end; end"
+    eval "class Foo;def private_do_not_override_me?; true; end; end"
+    assert_equal 'private', Foo.new.__send__(:private_do_not_override_me!)
+  end
+  
+  def test_no_bang_method_will_be_overridden_even_if_it_is_in_a_superclas
+    eval "class Foo;def super_do_not_override_me!; 'super'; end; end"
+    eval "class Bar;def super_do_not_override_me?; true; end; end"
+    assert_equal 'super', Foo.new.super_do_not_override_me!
+  end
+
+  def test_some_super_complex_thing
+    eval <<-EOS
+      class Foo
+        def k?; false; end
+        def m?; true; end
+        def n?; !(k? || m?); end
+        def o?; true; end
+        def p?; o? && !n?; end
+        def q?; !p?; end
+      end
+    EOS
+    e = exception_raised_by { Foo.new.q! }
+    assert e.kind_of?(Foo::NotKError)
+    assert e.kind_of?(Foo::MError)
+    assert e.kind_of?(Foo::NotNError)
+    assert e.kind_of?(Foo::OError)
+    assert e.kind_of?(Foo::PError)
+    assert e.kind_of?(Foo::NotQError)
+  end
+  
+  def test_does_work_for_modules
+    # any? is defined in the module Enumerable and included in Array
+    assert Enumerable.instance_methods(false).include?('any?')
+    assert !Array.instance_methods(false).include?('any?')
+    assert Array.ancestors.include?(Enumerable)
+
+    e = exception_raised_by { [].any! } 
+    assert e.kind_of?(Enumerable::NotAnyError)
+    assert_same Array::NotAnyError, Enumerable::NotAnyError
+  end
+
+  def test_does_work_for_alias_method
+    eval <<-EOS
+      class Foo
+        alias_method :a_alias?, :a?
+      end
+    EOS
+    e = exception_raised_by { Foo.new.a_alias! }
+    assert e.kind_of?(Foo::NotAAliasError)
+    assert e.kind_of?(Foo::NotAError)
+  end
+  
+  def test_does_work_for_redefined_methods
+    eval <<-EOS
+      class Foo
+        alias_method :b_old?, :b?
+        def b?
+          b_old?
+        end
+      end
+    EOS
+    e = exception_raised_by { Foo.new.b! }
+    assert e.kind_of?(Foo::NotBError)
+  end
+
+  def test_ignores_methods_starting_with_non_letter
+    eval <<-EOS
+      class Foo
+        def _e?
+        end
+      end
+    EOS
+    assert !Foo.respond_to?(:_e!)
+  end
+
+  def test_ignores_methods_with_whitespace
+    eval <<-EOS
+      class Foo
+        define_method "I?\n am a method?" do
+          true
+        end
+      end
+    EOS
+    assert !Foo.new.respond_to?(:"I?\n am a method!")
+  end
+  
+  def test_does_work_for_unnamed_class
+    c = Class.new
+    c.class_eval <<-EOS
+      def activated?
+        false
+      end
+    EOS
+    e = exception_raised_by { c.new.activated! }
+    assert e.kind_of?(c.const_get(:NotActivatedError))
+    self.class.const_set(:NowANamedClass, c)
+    assert e.kind_of?(NowANamedClass::NotActivatedError)
+  end
+
+  def test_does_work_for_unnamed_module
+    m = Module.new
+    m.module_eval <<-EOS
+      def activated?
+        false
+      end
+    EOS
+    Foo.send(:include, m)
+    e = exception_raised_by { Foo.new.activated! }
+    assert e.kind_of?(m.const_get(:NotActivatedError))
+    self.class.const_set(:NowANamedModule, m)
+    assert e.kind_of?(NowANamedModule::NotActivatedError)
+  end
+  
+  def test_does_not_work_for_virtual_classes
+    f = Foo.new
+    class << f
+      def x?; b?; end
+    end
+    assert !f.respond_to?(:x!)
+  end
+  
+  def test_exception_in_a_predicate_method_does_not_screw_up_the_next_result
+    eval <<-EOS
+      class Foo
+        def raises?; a?; raise "FAILURE"; end
+      end
+    EOS
+    e = exception_raised_by { Foo.new.raises! }
+    assert e.message == "FAILURE"
+    e = exception_raised_by { Foo.new.b! }
+    assert !e.kind_of?(Foo::NotAError)
+  end
+
+  def test_generated_methods_have_the_visibility_of_the_original_methods
+    eval <<-EOS
+      class Foo
+        public
+          def public_p?; true; end
+        protected
+          def protected_p?; true; end
+        private
+          def private_p?; true; end
+      end
+    EOS
+    
+    assert Foo.public_instance_methods(false).include?('public_p?')
+    assert Foo.protected_instance_methods(false).include?('protected_p?')
+    assert Foo.private_instance_methods(false).include?('private_p?')
+    
+    assert Foo.public_instance_methods(false).include?('public_p!')
+    assert Foo.protected_instance_methods(false).include?('protected_p!')
+    assert Foo.private_instance_methods(false).include?('private_p!')
+  end
+  
+  private
+
+    def exception_raised_by(&block)
+      block.call
+      fail("No exception raised")
+    rescue Exception => e
+      e
+    end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: rconditions
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2007-09-27 00:00:00 +02:00
+summary: RConditions generates a bang method (for example, Array#empty!) for each predicate method (for example, Array#empty?). The bang method will return true if the predicate method returns true, otherwise it will throw an exception. The exception will include auto-generated modules that give information on predicate methods passed or failed in the bang method's execution.
+require_paths: 
+- lib
+email: tammo@tammofreese.de
+homepage: http://rconditions.rubyforge.org
+rubyforge_project: 
+description: 
+autorequire: rconditions
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Norman Timmler
+- Tammo Freese
+files: 
+- test/rconditions_test.rb
+- lib/rconditions.rb
+- README
+- MIT-LICENSE
+test_files: 
+- test/rconditions_test.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+