rconditions 0.1.0 → 0.1.1

data/README

@@ -1,5 +1,120 @@
 = 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.
+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 pass if the predicate method passes, 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.
+== A Simple Example
+
+  require "rconditions"
+  
+  begin 
+    [1,2].empty!
+  rescue Array::NotEmptyError => e
+    p e    
+  end
+  
+  # => #<Exception: Array::NotEmptyError>
+
+The raised exception includes a module defined on the class where the method is defined. The module's name is derived from the predicate method's name.
+
+== 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.
+
+== Limitations
+
+* RConditions currently 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.
+
+== License
+
+RConditions is released under the MIT license.
+
+== Authors
+
+RConditions is written by Norman Timmler and Tammo Freese.

data/lib/rconditions.rb

@@ -1,122 +1,12 @@
-# = 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.
+# Holds RCondition's methods. You should never call these methods
+# directly, as they are automatically called.
 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.
+    # Extends a given predicate method and defines a bang method for it. You
+    # should never call this method yourself, it is called either from 
+    # RConditions#extend_predicate_methods_and_define_bang_methods, or from 
+    # <tt>Module#method_added</tt> which is extended by RConditions.
     # * <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)
@@ -132,6 +22,19 @@ module RConditions
       end
     end
     
+    # Extends almost all predicate methods and defines bang methods for them.
+    # You should never call this method yourself, it is called automatically 
+    # when RConditions is required. To prevent it from being called, set 
+    # <tt>RCONDITIONS_ONLY_FOR_NEW_METHODS</tt> to <tt>true</tt> before 
+    # requiring RConditions.
+    def extend_predicate_methods_and_define_bang_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  
+      
     def exception_modules #:nodoc:
       Thread.current[:rconditions_exception_modules]
     end
@@ -212,22 +115,14 @@ unless defined? RCONDITIONS_ONLY_FOR_NEW_METHODS
 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
+  RConditions.extend_predicate_methods_and_define_bang_methods
 end
-
-class Module
+ 
+class Module #:nodoc:
   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)
+  def method_added(id) #:nodoc:
     RConditions.extend_predicate_method_and_define_bang_method(self, id)
     method_added_without_rconditions(id)
   end

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: rconditions
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 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: 
@@ -36,10 +36,16 @@ files:
 - MIT-LICENSE
 test_files: 
 - test/rconditions_test.rb
-rdoc_options: []
-
-extra_rdoc_files: []
-
+rdoc_options: 
+- --title
+- RConditions RDoc Documentation
+- --main
+- README
+- --charset
+- utf-8
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
 executables: []
 
 extensions: []