rubybreaker 0.0.7 → 0.0.8

data/README.md

@@ -3,11 +3,11 @@
 RubyBreaker is a dynamic type documentation tool written in pure Ruby. It
 provides the framework for dynamically instrumenting a Ruby program to
 monitor objects during the execution and document the observed type
-information. In other words, RubyBreaker "breaks" Ruby code out of its
-obscurity and wildness (as in "code breaking" or "horse breaking") by
-auto-documenting type information. The type documentation generated by
-RubyBreaker is also an executable Ruby code that can be used as an input to
-subsequent analyses.  
+information. In addition, it can perform early dynamic type checking.
+In other words, RubyBreaker helps Ruby programs "break" out of obscurities
+and convolutions by documenting the type information.  The type
+documentation generated by RubyBreaker is also an executable Ruby code that
+can be used as an input to subsequent analyses.  
 
 The primary goal of RubyBreaker is to assign a type signature to every
 method in selected modules and classes. A type signature is written in the
@@ -16,7 +16,7 @@ used in Ruby Core Library Doc. No manual code change is required.  Overall,
 this tool should help Ruby programmers document their code more rigorously
 and effectively.
 
-Currently, RubyBreaker *cannot*
+Currently, RubyBreaker *does not*
 
 * Auto-document block arguments (inherent)
 * Support parametric polymorphic types

data/TUTORIAL.md

@@ -1,7 +1,7 @@
 # Tutorial
 
-This tutorial will describe the basic usage of the tool, the RubyBreaker
-Type Annotation Language, and the RubyBreaker Type System.
+This tutorial will describe the basic usages of the tool and the types
+supported by RubyBreaker.
 
 ## Usage
 
@@ -11,16 +11,36 @@ does require a minimum change in the Rakefile (but no code change in the
 source program) but is better for a long-term maintenance. Regardless of the
 mode you choose to run, no source code change is required. 
 
+### Running RubyBreaker
+
 Let us briefly see how RubyBreaker can be run directly as a command-line
 program to understand the overall concept of the tool. We will explain how
-to use RubyBreaker in a Rakefile later.
+to use RubyBreaker in a Rakefile later. The following is the banner of
+RubyBreaker when running in the command-line mode:
+
+    Usage: rubybreaker.rb [options] prog[.rb]
+        -b, --break MODULES              Specify modules/classes to 'break'
+        -c, --check MODULES              Specify modules/classes to check
+        -l, --libs LIBRARIES             Specify libraries to load
+            --debug                      Run in debug mode
+            --style STYLE                Select type signature style - underscore or camelize
+            --io-file FILE               Specify I/O file
+            --save-output                Save output to file
+        -s, --[no-]stdout                Show output on screen
+        -a, --[no-]append                Append output to input file
+        -v, --verbose                    Show messages in detail
+        -h, --help                       Show this help text
+
+#### Example
+
+Here is an example of running Rubybreaker as a command.
 
     $ rubybreaker -v -s -l lib.rb -b A,B prog.rb
 
-The above command runs RubyBreaker in verbose mode (`-v`) and will display
+This runs RubyBreaker in verbose mode (`-v`) and will display
 the output on the screen (`-s`). Before RubyBreaker runs `prog.rb`, it will
 import (`-l`) `lib.rb` and _break_ (`-b`) classes `A` and `B`.
-Here is `lib.rb`:
+Here is the source of `lib.rb`:
 
     class A
       def foo(x)
@@ -33,12 +53,12 @@ Here is `lib.rb`:
       end
     end
 
-And, `prog.rb` simply imports the library file and executes it:
+And, `prog.rb` simply imports the library file and executes `A#foo` with a
+number:
 
     require "lib"
     A.new.foo(1)
 
-This example will show how `A#foo` method is given a type by RubyBreaker.
 After running the command shown above, the following output will be
 generated and displayed on the screen:
 
@@ -46,11 +66,12 @@ generated and displayed on the screen:
       typesig("foo(fixnum[to_s]) -> string")
     end
 
+This example shows how RubyBreaker documents the type of `A#foo`.
 Here, the `typesig` method call registers `foo` as a method type that takes
 an object that has `Fixnum#to_s` method and returns a `String`. This
 method is made available simply by importing `rubybreaker`.  Now, assume
 that an additional code, `B.new.bar(A.new,1)`, is added at the end of
-`prog.rb`. The subsequent run will generate the following result:
+`prog.rb`. It generate the following result:
 
     class A
       typesig("foo(fixnum[to_s]) -> string")
@@ -67,6 +88,20 @@ the program behaves correctly (for those test runs) as intended by the
 programmer. This assumption is not a strong requirement, but is necessary to
 obtain precise and accurate type information. 
 
+#### Early Dynamic Type Checking
+
+RubyBreaker gives you an option to run the early dynamic type check. If a
+method is documented and its module is specified to be _type checked_, then
+RubyBreaker will verify if the argument types and the return type are
+appropriate at runtime. To allow this feature in command-line, use `-c`
+(checking) option:
+
+    rubybreaker -l lib.rb -c A prog.rb
+
+Here, the library code `lib.rb` will be imported (`-l`) and class `A` will
+be instrumented for type checking (`-c`) during the execution of `prog.rb`.
+We will explain how to run type checking in non-command mode.
+
 ### Using Ruby Unit Testing Framework
 
 Instead of manually inserting the entry point indicator in the source
@@ -133,6 +168,27 @@ If this is the route you are taking, there needs no editing of the source
 program whatsoever. This task will take care of instrumenting the specified
 modules and classes at proper moments.
 
+#### Early Dynamic Type Checking in Rakefile
+
+Previously, we explained how to perform type checking in the command mode.
+You can also specify which modules/classes to type check in the Rakfile. The
+following shows an example usage of `check` option.
+
+    require "rubybreaker/task"
+    ...
+    desc "Run RubyBreaker"
+    Rake::RubyBreakerTestTask.new(:"rubybreaker") do |t|
+      t.libs << "lib" 
+      t.test_files = ["test/foo/tc_foo1.rb"]
+      # ...Other test task options..
+      t.rubybreaker_opts << "-v"           # run in verbose mode
+      t.break = ["Class1", "Class2", ...]  # specify classes to monitor
+      t.check = ["Class3", ....] # specify classes to check
+    end
+
+Alternatively, you can use `RubyBreaker.check()` to specify classes to type
+check in the setup code of the test case.
+
 ## Type Annotation
 
 The annotation language used in RubyBreaker resembles the method
@@ -289,29 +345,3 @@ compatibility between the return types and "promote" the method type to a
 method list type by spliting the type signature into two (or more in
 subsequent "promotions").
 
-### Early Dynamic Type Checking
-
-RubyBreaker gives you an option to run the early dynamic type check. If a
-method is documented and its module is specified to be _type checked_, then
-RubyBreaker will verify if the argument types and the return type are
-appropriate at runtime. To allow this feature in command-line, use `-c`
-(checking) option:
-
-    rubybreaker -l lib.rb -c A prog.rb
-
-Or use it in Rakefile:
-
-    require "rubybreaker/task"
-    ...
-    desc "Run RubyBreaker"
-    Rake::RubyBreakerTestTask.new(:"rubybreaker") do |t|
-      t.libs << "lib" 
-      t.test_files = ["test/foo/tc_foo1.rb"]
-      # ...Other test task options..
-      t.rubybreaker_opts << "-v"           # run in verbose mode
-      t.break = ["Class1", "Class2", ...]  # specify classes to monitor
-      t.check = ["Class3", ....] # specify classes to check
-    end
-
-Alternatively, you can use `RubyBreaker.check()` to specify classes to type
-check in the setup code of the test case.

data/VERSION

@@ -1 +1 @@
-0.0.7
+0.0.8

data/lib/rubybreaker/debug/error.rb

@@ -51,7 +51,13 @@ module RubyBreaker
     class TypeError < UserError
     end
 
-    class SubtypeFailure < TypeError
+    class ArityError < TypeError
+    end
+
+    class ArgumentTypeError < TypeError
+    end
+
+    class ReturnTypeError < TypeError
     end
 
   end

data/lib/rubybreaker/runtime/monitor.rb

@@ -93,7 +93,7 @@ module RubyBreaker
           when :check
             mm.check_before_method(obj, meth_info)
           end
-        rescue Errors::TypeError => e
+        rescue ::Exception => e
           # Trap it, turn on the global monitor and then re-raise the
           # exception
           GLOBAL_MONITOR_SWITCH.turn_on()
@@ -121,7 +121,7 @@ module RubyBreaker
           when :check
             mm.check_after_method(obj, meth_info)
           end
-        rescue Errors::TypeError => e
+        rescue ::Exception => e
           # Trap it, turn on the global monitor and then re-raise the
           # exception
           GLOBAL_MONITOR_SWITCH.turn_on()

data/lib/rubybreaker/runtime/object_wrapper.rb

@@ -70,14 +70,45 @@ module RubyBreaker
       def method_missing(mname,*args,&blk)
         ::RubyBreaker.log("Method_missing for #{mname}")
         if GLOBAL_MONITOR_SWITCH.switch
+
+          # Be safe and turn the switch off
+          GLOBAL_MONITOR_SWITCH.turn_off
+
           # Must handle send method specially (do not track them)
           if [:"__send__", :send].include?(mname)
             mname = args[0]
             args = args[1..-1]
           end
           @__rubybreaker_type.add_meth(mname)
+
+          # If self is not subject to breaking, then no need to send the
+          # wrapped arguments. This part is super IMPORTANT. Otherwise many
+          # native code stuff won't work including Numeric#+.
+          obj = self.__rubybreaker_obj
+          is_obj_mod = (obj.class == ::Class or obj.class == ::Module)
+          mod = is_obj_mod ? Runtime.eigen_class(obj) : obj.class
+
+          # Monitor map doesn't exist MEANS it's not being monitored.
+          unless MONITOR_MAP[mod]
+            args.map! do |arg|
+              if arg.respond_to?(WRAPPED_INDICATOR)
+                arg.__rubybreaker_obj
+              else
+                arg
+              end
+            end
+          end
+
+          # Turn on the global switch again
+          GLOBAL_MONITOR_SWITCH.turn_on
+
+          # And call the original method 
           retval =  @__rubybreaker_obj.send(mname, *args, &blk)
-          retval = ObjectWrapper.new(retval)
+
+          # No need to wrap the object again...if it's wrapped already
+          unless retval.respond_to?(WRAPPED_INDICATOR)
+            retval = ObjectWrapper.new(retval)
+          end
         else
           retval = @__rubybreaker_obj.send(mname, *args, &blk)
         end

data/lib/rubybreaker/runtime/overrides.rb

@@ -19,6 +19,11 @@ module RubyBreaker
     # indicate overridden methods.
     OVERRIDE_PREFIX = "__rubybreaker"
 
+    # Prohibit these module/class+method from being overriden
+    BLACKLIST = {
+      String => [:to_s, :<<, :concat, :gsub],
+    }
+
   end
 
 end
@@ -53,8 +58,33 @@ end
 
 end
 
+[Symbol, Numeric, Fixnum, Float, Integer, Bignum, String].each do |mod|
+  mod.instance_methods(false).each do |meth_name|
+    black_list = RubyBreaker::Runtime::BLACKLIST
+    next if black_list[mod] && black_list[mod].include?(meth_name)
+    alias_name = "#{RubyBreaker::Runtime::OVERRIDE_PREFIX}_#{mod.object_id}" +
+                 "_#{meth_name}"
+    mod.module_eval <<-EOS
+
+    alias :"#{alias_name}" :"#{meth_name}"
+
+    def #{meth_name}(*args)
+      args = args.map do |arg|
+        if arg.respond_to?(RubyBreaker::Runtime::WRAPPED_INDICATOR)
+          arg.__rubybreaker_obj
+        else
+          arg
+        end
+      end
+      send(:"#{RubyBreaker::Runtime::OVERRIDE_PREFIX}_#{mod.object_id}_#{meth_name}",*args)
+    end
+
+    EOS
+  end
+end
+
 # TODO: add more modules here as necessary!
-[Object, Numeric, String, Symbol, Enumerable, Array, Hash].each do |mod| 
+[Object, Enumerable, Array, Hash].each do |mod| 
 
   [:"==", :equal?, :eql?].each do |meth_name|
 

data/lib/rubybreaker/runtime/type_system.rb

@@ -171,11 +171,33 @@ module RubyBreaker
 
       # This method creates the prefix for the type error message.
       def type_error_msg_prefix(mod, meth_name)
+        # Match eigen class and returns a prefix that is a class method
+        # using dot (.) instead of double colons (::).
         result = /#<Class:(.+)>/.match("#{mod}")
         prefix = result ? "#{result[1]}." : "#{mod}#"
         return "#{prefix}#{meth_name}"
       end
 
+      # This method performs the arity check. 
+      def arity_check(num_of_args, meth_type)
+        arg_types = meth_type.arg_types
+
+        opt = false
+        varlen = false
+        
+        arg_types.each_with_index do |arg_type, i|
+          if arg_type.kind_of?(OptionalType)
+            opt = true
+          elsif arg_type.kind_of?(VarLengthType)
+            varlen = true
+          end
+        end
+        check = (opt && num_of_args <= arg_types.size) || 
+                (varlen && num_of_args >= arg_types.size) ||
+                num_of_args == arg_types.size
+        return check
+      end
+
       public
 
       # This method is invoked before the original method is executed.
@@ -189,19 +211,55 @@ module RubyBreaker
         # Let's take things out of the MethodInfo object
         meth_name = meth_info.meth_name
         args = meth_info.args
-        blk = meth_info.blk
-        ret = meth_info.ret
+        # blk = meth_info.blk
 
         # Get the registered method type for this method
         meth_type = meth_type_map[meth_name]
 
-        args.each_with_index do |arg, i|
-          arg_type = NominalType.new(arg.class)
-          if !arg_type.subtype_of?(meth_type.arg_types[i])
+        # Do an arity check first. 
+        if !arity_check(args.size, meth_type)
+          msg = type_error_msg_prefix(mod, meth_name) +
+                " has an arity of #{meth_type.arg_types.size} " +
+                "but #{args.size} arguments were passed in"
+          raise Errors::ArityError.new(msg)
+        end
+
+        # Remember what the last formal argument type was so that, if it is
+        # a variable length argument type, we use to check the remaining
+        # arguments.
+        last_supertype = nil 
+
+        # Check actual arguments up until the last position of the formal
+        # argument type. If the number of the formal arguments is less than
+        # actual arguments, it means the last formal argument is a variable
+        # length. If it's the other way around, there are optional
+        # arguments.
+        meth_type.arg_types.each_with_index do |supertype, i|
+          if supertype.kind_of?(OptionalType) ||
+             supertype.kind_of?(VarLengthType)
+            supertype = supertype.type
+          end
+          last_supertype = supertype
+          break if i >= args.size 
+          subtype = NominalType.new(args[i].class)
+          if !subtype.subtype_of?(supertype)
             msg = type_error_msg_prefix(mod, meth_name) +
                   "'s #{Util.ordinalize(i+1)} argument " +
-                  "does not have type #{arg_type.unparse()}."
-            raise Errors::TypeError.new(msg)
+                  "does not have type #{supertype.unparse()}."
+            raise Errors::ArgumentTypeError.new(msg)
+          end
+        end
+
+        # Handle the remaining actual arguments
+        if meth_type.arg_types.size < args.size
+          for i in meth_type.arg_types.size..args.size-1
+            subtype = NominalType.new(args[i].class)
+            if !subtype.subtype_of?(last_supertype)
+              msg = type_error_msg_prefix(mod, meth_name) +
+                    "'s #{Util.ordinalize(i+1)} argument " +
+                    "does not have type #{last_supertype.unparse()}."
+              raise Errors::ArgumentTypeError.new(msg)
+            end
           end
         end
 
@@ -217,8 +275,6 @@ module RubyBreaker
 
         # Let's take things out of the MethodInfo object
         meth_name = meth_info.meth_name
-        args = meth_info.args
-        blk = meth_info.blk
         ret = meth_info.ret
 
         # Get the registered method type for this method
@@ -228,7 +284,7 @@ module RubyBreaker
         if !meth_type.ret_type.subtype_of?(ret_type)
           msg = type_error_msg_prefix(mod, meth_name) +
                 " return value does not have type #{ret_type.unparse()}."
-          raise Errors::TypeError.new(msg)
+          raise Errors::ReturnTypeError.new(msg)
         end
       end
       
@@ -251,7 +307,7 @@ module RubyBreaker
         ret = meth_info.ret
 
         args = args.map do |arg|
-          if arg.kind_of?(TrueClass) || arg.kind_of?(FalseClass)
+          if arg == nil || arg.kind_of?(TrueClass) || arg.kind_of?(FalseClass) 
             # XXX: would overrides resolve this issue?
             arg 
           else

data/test/integrated/tc_checking.rb

@@ -12,6 +12,9 @@ class IntegratedCheckingTest < Test::Unit::TestCase
     typesig("f2(fixnum[to_s]) -> string")
     def f2(x); x.to_s end
 
+    typesig("g2([to_s]) -> string")
+    def g2(x); x.to_s end
+
     typesig("f3(fixnum[foo, to_s]) -> string")
     def f3(x); x.to_s end
 
@@ -21,6 +24,12 @@ class IntegratedCheckingTest < Test::Unit::TestCase
     typesig("f5(fixnum, fixnum) -> fixnum")
     def f5(x,y); x+y end
 
+    typesig("f6(fixnum, fixnum?, fixnum*) -> fixnum")
+    def f6(x, y=1, *z)
+      z = eval(z.join("+"))
+      x + y + (z ? z : 0)
+    end
+
   end
 
   def setup()
@@ -32,25 +41,46 @@ class IntegratedCheckingTest < Test::Unit::TestCase
     assert_nothing_thrown do
       a.f1(2)
     end
-    assert_raise RubyBreaker::Errors::TypeError do
+    assert_raise RubyBreaker::Errors::ArgumentTypeError do
       a.f1("2")
     end 
   end
 
+  def test_arity()
+    a = A.new
+    assert_raise Errors::ArityError do
+      a.f1(1, 2)
+    end
+    assert_nothing_thrown do
+      a.f6(1, 2)
+      a.f6(1, 2, 3)
+      a.f6(1, 2, 3, 4)
+      a.f6(1, 2, 3, 4, 5)
+    end
+  end
+
   def test_duck()
+    a = A.new
+    assert_nothing_thrown do
+      a.g2(2)
+      a.g2("2")
+    end
+  end
+
+  def test_fusion()
     a = A.new
     assert_nothing_thrown do
       a.f2(2)
       a.f3(2) # This will pass too
     end
-    assert_raise RubyBreaker::Errors::TypeError do
+    assert_raise RubyBreaker::Errors::ArgumentTypeError do
       a.f3("2")
     end 
   end
 
   def test_ret()
     a = A.new
-    assert_raise RubyBreaker::Errors::TypeError do
+    assert_raise RubyBreaker::Errors::ReturnTypeError do
       a.f4(2)
     end
   end
@@ -60,10 +90,10 @@ class IntegratedCheckingTest < Test::Unit::TestCase
     assert_nothing_thrown do
       a.f5(1, 2)
     end
-    assert_raise RubyBreaker::Errors::TypeError do
+    assert_raise RubyBreaker::Errors::ArgumentTypeError do
       a.f5("1", 2)
     end
-    assert_raise RubyBreaker::Errors::TypeError do
+    assert_raise RubyBreaker::Errors::ArgumentTypeError do
       a.f5(1, "2")
     end
   end