rubybreaker 0.0.6 → 0.0.7

data/NEWS

@@ -1,3 +1,6 @@
+# VERSION 0.0.7
+* Early dynamic type check is implemented.
+
 # VERSION 0.0.6
 * Running RubyBreaker in shell mode does not require manual code change.
 * Official RubyBreaker logo!

data/README.md

@@ -19,14 +19,13 @@ and effectively.
 Currently, RubyBreaker *cannot*
 
 * Auto-document block arguments (inherent)
-* Perform early dynamic type checks
 * Support parametric polymorphic types
 * Support RDoc or YARD output format
 
 To contribute to the project, visit RubyBreaker's
 [GitHub page](http://github.com/rockalizer/rubybreaker) and 
 [RubyGems page](http://rubygems.org/gems/rubybreaker). The web version of
-this document can be found 
+this document and the tutorial can be found 
 [here](http://rockalizer.webfactional.com/projects/rubybreaker).
 
 ## Requirements

data/Rakefile

@@ -99,6 +99,7 @@ Rake::RubyBreakerTestTask.new(:"testtask_test") do |t|
   t.libs << "lib" << "test/tc_testtask/sample.rb"
   t.test_files = ["test/testtask/tc_testtask.rb"]
   t.break = ["SampleClassA"]
+  t.check = ["SampleClassB"]
 end
 
 if defined?(RSpec)

data/TODO

@@ -1,11 +1,3 @@
-# Dynamic Type Checker
-
-Type documentation generated by RubyBreaker can be more useful if the types
-are actually enforced during runtime. In order to do this, each method has
-to be dynamically instrumented (as "breakable" methods are) and inspected
-for each argument type and return type. Although this is still a dynamic
-type checking, it finds type errors earlier in the program execution.
-
 # Additional Testing Frameworks
 
 RubyBreaker supports the built-in testing framework and RSpec. There are

data/TUTORIAL.md

@@ -19,7 +19,7 @@ to use RubyBreaker in a Rakefile later.
 
 The above command 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 instrument (`-b`) classes `A` and `B`.
+import (`-l`) `lib.rb` and _break_ (`-b`) classes `A` and `B`.
 Here is `lib.rb`:
 
     class A
@@ -70,7 +70,7 @@ obtain precise and accurate type information.
 ### Using Ruby Unit Testing Framework
 
 Instead of manually inserting the entry point indicator in the source
-program, you can take advantage of Ruby's built-in testing framework. This
+program, you can take advantage of Ruby’s built-in testing framework. This
 is preferred to modifying the source program directly, especially for the
 long term program maintainability. But no worries! This method is as simple
 as the previous one.
@@ -85,7 +85,7 @@ as the previous one.
       # ...tests!...
     end
 
-That's it! The only requirements are to indicate to RubyBreaker which modules
+That’s it! The only requirements are to indicate to RubyBreaker which modules
 and classes to "break" and to place `require rubybreaker` _after_
 `require test/unit`.
 
@@ -124,7 +124,7 @@ RubyBreaker.  The following code snippet describes how it can be done:
 Note that `RubyBrakerTestTask` can simply replace your `TestTask` block in
 Rakefile. In fact, the former is a subclass of the latter and includes all
 features supported by the latter. The only additional options are
-`rubybreaker_opts` which is RubyBreaker's command-line options and
+`rubybreaker_opts` which is RubyBreaker command-line options and
 `break` which specifies which modules and classes to monitor.  Since
 `Class1` and `Class2` are not _recognized_ by this Rakefile, you must use
 string literals to specify modules and classes (and with full namespace). 
@@ -184,7 +184,7 @@ precise return type.
 
 ### Duck Type
 
-This type is inspired by the Ruby Language's duck typing, _"if it
+This type is inspired by the Ruby Language’s duck typing, _"if it
 walks like a duck and quacks like a duck, it must be a duck."_ Using this
 type, an object can be represented simply by a list of method names. For
 example `[walks, quacks]` is an object that has `walks` and `quacks`
@@ -231,7 +231,7 @@ suffices, `?` and `*`, respectively.
 
 ### Block Type
 
-One of the Ruby's prominent features is the block argument. It allows
+One of the Ruby’s prominent features is the block argument. It allows
 the caller to pass in a piece of code to be executed inside the callee. This
 code block can be executed by the Ruby construct, `yield`, or by directly
 calling the `call` method of the block object. In RubyBreaker, this type can
@@ -263,7 +263,7 @@ code:
     end
 
 There is no way to document the type of `foo` without using a method list
-type. Let's try to give a method type to `foo` without a method list. The
+type. Let’s try to give a method type to `foo` without a method list. The
 closest we can come up with would be `foo(fixnum or string) -> fixnum and
 string`. But RubyBreaker does not have the "and" type in the type annotation
 language because it gives me an headache! (By the way, it needs to be an
@@ -289,3 +289,29 @@ 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.6
+0.0.7

data/lib/rubybreaker.rb

@@ -25,10 +25,11 @@ module RubyBreaker
     :append       => false,       # append to the input file (if there is)?
     :stdout       => false,       # also display on the screen?
     :verbose      => false,       # in RubyBreaker.verbose mode?
-    :save_output  => true,     # save output to a file?
-    :break        => [],       # modules to break
-    :libs         => [],       # list of library files to import
-    :prog         => nil,      # program or test file
+    :save_output  => true,        # save output to a file?
+    :break        => [],          # modules/classes to break
+    :check        => [],          # modules/classes to check
+    :libs         => [],          # list of library files to import
+    :prog         => nil,         # program or test file
   }
 
   # This option parser may be used for the command-line mode or for the
@@ -43,6 +44,11 @@ module RubyBreaker
       tokens.each {|t| OPTIONS[:break] << t}
     end
     
+    opts.on("-c MODULES", "--check MODULES", "Specify modules/classes to check") do |s|
+      tokens = s.split(/[;,]/)
+      tokens.each {|t| OPTIONS[:check] << t}
+    end
+
     opts.on("-l LIBRARIES", "--libs LIBRARIES", "Specify libraries to load") do |s|
       tokens = s.split(":")
       tokens.each {|t| OPTIONS[:libs] << t}
@@ -172,12 +178,14 @@ module RubyBreaker
       task = self.task
       OPTION_PARSER.parse(*task[:rubybreaker_opts])
       Runtime.break(*task[:break])
+      Runtime.check(*task[:check])
       task_name = task[:name]
       RubyBreaker.verbose("Done reading task information")
       io_file = self.io_file(task_name)
     elsif OPTIONS[:prog] # running in shell mode 
       Runtime.break(*mods) # should not happen but for backward-compatibility
       Runtime.break(*OPTIONS[:break])
+      Runtime.check(*OPTIONS[:check])
       io_file = self.io_file(OPTIONS[:prog_file])
     else
       # Otherwise, assume there are no explicit IO files.

data/lib/rubybreaker/debug/error.rb

@@ -41,7 +41,7 @@ module RubyBreaker
     # program.
     class UserError < ::Exception
       
-      def initialize(msg, ctx)
+      def initialize(msg, ctx=nil)
         super(msg)
         @ctx = ctx
       end

data/lib/rubybreaker/runtime.rb

@@ -10,20 +10,13 @@ require_relative "runtime/inspector"
 
 module RubyBreaker
 
+  # This module contains things that are needed at runtime.
   module Runtime
 
     # This set keeps track of modules/classes that will be monitored.
     # *DEPRECATED* : Use +breakable+ method instead.
     BREAKABLES = Set.new 
 
-    # This hash maps a module to a nested hash that maps a method name to a
-    # method type. This hash is shared between breakable modules/classes and
-    # non-breakable modules/classes.
-    TYPE_MAP = {} # module => {:meth_name => type}
-
-    # This hash maps a (breakable) module to a type monitor
-    MONITOR_MAP = {}  # module => monitor
-
     private
 
     # Instruments the monitor to the specified modules/classes. 
@@ -36,9 +29,10 @@ module RubyBreaker
         when Array
           self.install(monitor_type, *mod)
         when Module, Class
-          MonitorInstaller.install_monitor(mod)
+          # Install both instance and its eigen class
+          MonitorInstaller.install_monitor(monitor_type, mod)
           eigen_class = self.eigen_class(mod)
-          MonitorInstaller.install_monitor(eigen_class)
+          MonitorInstaller.install_monitor(monitor_type, eigen_class)
         when String, Symbol
           begin
             # Get the actual module and install it right now
@@ -56,17 +50,23 @@ module RubyBreaker
     public
 
     # This method instruments the specified modules/classes at the time of
-    # the call.
+    # the call so they are monitored for type documentation.
     def self.break(*mods)
       self.install(:break, *mods)
     end
 
+    # This method instruments the specified modules/classes at the time of
+    # the call so that they are type checked during runtime.
+    def self.check(*mods)
+      self.install(:check, *mods)
+    end
+
     # This method installs a monitor for each breakable module. 
     # *DEPRECATED*: Use +breakable()+ method instead.
     def self.instrument() 
       BREAKABLES.each do |mod|
         # Duplicate checks in place in these calls.
-        MonitorInstaller.install_monitor(mod)
+        MonitorInstaller.install_monitor(:break, mod)
       end
     end
 
@@ -94,6 +94,10 @@ module RubyBreaker
     Runtime.break(*mods)
   end
 
+  def self.check(*mods)
+    Runtime.check(*mods)
+  end
+
   # *DEPRECATED*: Use +Runtime.breakable()+ or +RubyBreaker.run()+ method
   #               instead.
   module Breakable  

data/lib/rubybreaker/runtime/monitor.rb

@@ -13,6 +13,15 @@ module RubyBreaker
 
   module Runtime
 
+    # This hash maps a module to a nested hash that maps a method name to a
+    # method type. This hash is shared between breakable modules/classes and
+    # non-breakable modules/classes.
+    TYPE_MAP = {} # module => {:meth_name => type}
+
+    # This hash maps a (breakable) module to a type monitor
+    MONITOR_MAP = {}  # module => monitor
+
+    # The default type system for RubyBreaker
     DEFAULT_TYPE_SYSTEM = TypeSystem.new
 
     # This class monitors method calls before and after. It simply reroutes
@@ -20,73 +29,12 @@ module RubyBreaker
     # the actual work of gathering type information. 
     class Monitor 
 
-      # attr_accessor :mod
       attr_accessor :pluggable
 
-      public
-
-      def initialize(mod, pluggable)
-        # @mod = mod
-        @pluggable = pluggable
-      end
-
-      # Starts monitoring of a method; it wraps each argument so that they
-      # can gather type information in the callee.
-      def monitor_before_method(obj, meth_info)
-        @pluggable.before_method(obj, meth_info)
-      end
-
-      # This method is invoked after the actual method is invoked. 
-      def monitor_after_method(obj, meth_info)
-        @pluggable.after_method(obj, meth_info)
-      end
-
-    end
-
-    # This class is a switch to turn on and off the type monitoring system.
-    # It is important to turn off the monitor once the process is inside the
-    # monitor; otherwise, it WILL fall into an infinite loop.
-    class MonitorSwitch
-
-      attr_accessor :switch
-
-      def initialize(); @switch = true end
-
-      def turn_on();
-        RubyBreaker.log("Switch turned on")
-        @switch = true; 
-      end
-
-      def turn_off(); 
-        RubyBreaker.log("Switch turned off")
-        @switch = false; 
-      end
-
-      def set_to(mode); @switch = mode; end
-    end
-
-    # TODO:For now, we use a global switch; but in future, a switch per
-    # object should be used for multi-process apps. However, there is still
-    # a concern for module tracking in which case, there isn't really a way
-    # to do this unless we track with the process or some unique id for that
-    # process.
-    GLOBAL_MONITOR_SWITCH = MonitorSwitch.new 
-
-    # This context is used for keeping track of context in the user code.
-    # This will ignore the context within the RubyBreaker code, so it is
-    # easy to pinpoint program locations without distraction from the
-    # RubyBreaker code.
-    CONTEXT = Context.new(ObjectPosition.new(self,"main"))
-
-    # This module contains helper methods for monitoring objects and
-    # modules.
-    module MonitorUtils
-
-      public
-
       # This will do the actual routing work for a particular "monitored"
       # method call.
       #
+      # route_type:: :break or :check
       # obj:: is the object receiving the message; is never wrapped object
       # meth_name:: is the original method name being called args:: is a
       # list of arguments for the original method call blk:: is the block
@@ -96,7 +44,7 @@ module RubyBreaker
       # NOTE: This method should not assume that obj is a monitored
       # object.  That is, no special method should be called to obj unless it
       # checks first.
-      def self.route(obj,meth_name,*args,&blk)
+      def self.route(route_type, obj, meth_name, *args, &blk)
 
         # remember the switch mode before turning it off
         switch = GLOBAL_MONITOR_SWITCH.switch
@@ -138,9 +86,21 @@ module RubyBreaker
 
         meth_info = MethodInfo.new(meth_name, args, blk, nil)
 
-        mm.monitor_before_method(obj, meth_info)
+        begin
+          case route_type
+          when :break
+            mm.break_before_method(obj, meth_info)
+          when :check
+            mm.check_before_method(obj, meth_info)
+          end
+        rescue Errors::TypeError => e
+          # Trap it, turn on the global monitor and then re-raise the
+          # exception
+          GLOBAL_MONITOR_SWITCH.turn_on()
+          raise e
+        end
 
-        RubyBreaker.log("monitor_before_method ended")
+        RubyBreaker.log("break_before_method ended")
 
         # we are going to turn the switch back on
         GLOBAL_MONITOR_SWITCH.turn_on()
@@ -153,7 +113,21 @@ module RubyBreaker
         GLOBAL_MONITOR_SWITCH.turn_off()
 
         meth_info.ret = retval
-        mm.monitor_after_method(obj, meth_info)
+
+        begin
+          case route_type
+          when :break
+            mm.break_after_method(obj, meth_info)
+          when :check
+            mm.check_after_method(obj, meth_info)
+          end
+        rescue Errors::TypeError => e
+          # Trap it, turn on the global monitor and then re-raise the
+          # exception
+          GLOBAL_MONITOR_SWITCH.turn_on()
+          raise e
+        end
+
         retval = meth_info.ret  # Return value may have been altered by the
                                 # after_method monitoring code
 
@@ -177,36 +151,91 @@ module RubyBreaker
         return meth_name[2..-1]
       end
 
+      def initialize(pluggable)
+        @pluggable = pluggable
+      end
+
+      # This method is invoked before the original method is executed.
+      def check_before_method(obj, meth_info)
+        @pluggable.check_before_method(obj, meth_info)
+      end
+
+      # This method is invoked after the original method is executed.
+      def check_after_method(obj, meth_info)
+        @pluggable.check_after_method(obj, meth_info)
+      end
+
+      # This method is invoked before the original method is executed.
+      def break_before_method(obj, meth_info)
+        @pluggable.break_before_method(obj, meth_info)
+      end
+
+      # This method is invoked after the original method is executed.
+      def break_after_method(obj, meth_info)
+        @pluggable.break_after_method(obj, meth_info)
+      end
+
     end
 
+    # This class is a switch to turn on and off the type monitoring system.
+    # It is important to turn off the monitor once the process is inside the
+    # monitor; otherwise, it WILL fall into an infinite loop.
+    class MonitorSwitch
+
+      attr_accessor :switch
+
+      def initialize(); @switch = true end
+
+      def turn_on();
+        RubyBreaker.log("Switch turned on")
+        @switch = true; 
+      end
+
+      def turn_off(); 
+        RubyBreaker.log("Switch turned off")
+        @switch = false; 
+      end
+
+      def set_to(mode); @switch = mode; end
+    end
+
+    # TODO:For now, we use a global switch; but in future, a switch per
+    # object should be used for multi-process apps. However, there is still
+    # a concern for module tracking in which case, there isn't really a way
+    # to do this unless we track with the process or some unique id for that
+    # process.
+    GLOBAL_MONITOR_SWITCH = MonitorSwitch.new 
+
+    # This context is used for keeping track of context in the user code.
+    # This will ignore the context within the RubyBreaker code, so it is
+    # easy to pinpoint program locations without distraction from the
+    # RubyBreaker code.
+    CONTEXT = Context.new(ObjectPosition.new(self,"main"))
+
     # This module installs a monitor in the object.
     module MonitorInstaller
 
-      include MonitorUtils
-
       # returns true if the receiver is a module or a class
-      def self.is_module?(recv)
-        return recv.respond_to?(:class) && recv.kind_of?(Module)
+      def self.is_module?(mod)
+        return mod.respond_to?(:class) && mod.kind_of?(Module)
       end
 
       # renames the method in essence; this method also "installs" the
       # module monitor for the class
-      def self.rename_meth(recv, meth_name)
-        alt_meth_name = MonitorUtils.get_alt_meth_name(meth_name)
-        recv.module_eval("alias :\"#{alt_meth_name}\" :\"#{meth_name}\"")
+      def self.monkey_patch_meth(monitor_type, mod, meth_name)
+        alt_meth_name = Monitor.get_alt_meth_name(meth_name)
+        mod.module_eval("alias :\"#{alt_meth_name}\" :\"#{meth_name}\"")
         RubyBreaker.log("Adding alternate method for #{meth_name}")
-        recv.module_eval <<-EOF
+        route_call = "RubyBreaker::Runtime::Monitor.route"
+        mod.module_eval <<-EOF
           def #{meth_name}(*args, &blk)
-            RubyBreaker::Runtime::MonitorUtils.route(self, 
-                                                     "#{meth_name}",
-                                                     *args,
-                                                     &blk)
+            #{route_call}(:#{monitor_type}, self,"#{meth_name}",*args,&blk)
           end
         EOF
       end
 
       # Installs an module (class) monitor to the object. 
-      def self.install_monitor(mod)
+      def self.install_monitor(monitor_type, mod)
 
         RubyBreaker.log("Installing module monitor for #{mod}")
 
@@ -216,7 +245,7 @@ module RubyBreaker
           return
         end
 
-        MONITOR_MAP[mod] = Monitor.new(mod, DEFAULT_TYPE_SYSTEM)
+        MONITOR_MAP[mod] = Monitor.new(DEFAULT_TYPE_SYSTEM)
 
         # Create the type map if it does not exist already. Remember, this
         # map could have been made by typesig().
@@ -226,12 +255,15 @@ module RubyBreaker
         # methods. Those are part of the owner's not this module.
         meths = mod.instance_methods(false)  
 
-        # See if any method is already broken (explicitly typesig'ed)
-        broken_mt_map = Inspector.inspect_all(mod)
-        broken_meths = broken_mt_map.keys
+        # See if any method is already documented (explicitly typesig'ed)
+        doc_mt_map = Inspector.inspect_all(mod)
+        doc_meths = doc_mt_map.keys
 
         meths.each do |m| 
-          self.rename_meth(mod,m) unless broken_meths.include?(m)
+          # Documented method will not be monkey-patched for "breaking"
+          unless monitor_type == :break && doc_meths.include?(m)
+            self.monkey_patch_meth(monitor_type, mod, m) 
+          end
         end
 
       end