rubybreaker 0.0.4 → 0.0.5

data/lib/rubybreaker.rb

@@ -3,164 +3,212 @@
 # observed at runtime and generates type annotation at the end.  It can be
 # run as either a stand-alone script or as a Ruby library. 
 
+require "set"
+require "optparse"
 require_relative "rubybreaker/debug"
 require_relative "rubybreaker/runtime"
 require_relative "rubybreaker/test"
 
 # RubyBreaker is a dynamic instrumentation and monitoring tool that
-# documents type information automatically.
+# generates type documentation for Ruby programs. 
 module RubyBreaker
-
-  # This constant contains the copyright information.
-  COPYRIGHT = "Copyright (c) 2012 Jong-hoon (David) An. All Rights Reserved."
+  include TypeDefs
+  include Runtime
 
   # Options for RubyBreaker
   OPTIONS = {
-    :debug => false,               # in debug mode?
-    :verbose => false,             # in RubyBreaker.verbose mode?
-    :mode => :lib,                 # bin or lib?
-    :io_file => nil,               # generate input/output other than default?
-    :append => true,               # append to the input file (if there is)?
-    :stdout => true,               # also display on the screen?
-    :rubylib => true,              # include core ruby library documentation?
-    :file => nil,                  # the input Ruby program (as typed by the user)
+    :debug     => false,       # in debug mode?
+    :style     => :underscore, # type signature style-underscore or camelize
+    :io_file   => nil,         # generate input/output other than default?
+    :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?
+    :prog_file    => nil,      # INTERNAL USE ONLY
   }
 
-  # This array lists modules/classes that are actually instrumented with a
-  # monitor.
-  INSTALLED = []
-  
-  # Extension used by RubyBreaker for output/input
-  EXTENSION = "rubybreaker"
-
-  # This module has a set of entry points to the program and misc. methods
-  # for running RubyBreaker.
-  module Main
+  # This option parser may be used for the command-line mode or for the
+  # library mode when used with Rakefile. See rubybreaker/task.rb for how
+  # this can be used in the latter.
+  OPTION_PARSER = OptionParser.new do |opts|
 
-    include TypeDefs
-    include Runtime
+    opts.banner = "Usage: #{File.basename(__FILE__)} [options] prog[.rb]" 
 
-    public
+    opts.on("--debug", "Run in debug mode") do 
+      OPTIONS[:debug] = true
+    end
 
-    # This method is the trigger point to install a monitor in each
-    # module/class.
-    def self.setup()
+    opts.on("--style STYLE", "Select type signature style - underscore or camelize") do |v|
+      OPTIONS[:style] = v.downcase.to_sym
+    end
 
-      BREAKABLE.each do |mod|
+    opts.on("--io-file FILE","Specify I/O file") do |f|
+      OPTIONS[:io_file] = f
+    end
 
-        # Remember, RubyBreaker now supports a hybrid of Breakable and
-        # Broken module. Just check if the module has already been
-        # instrumented.
-        unless INSTALLED.include?(mod) 
-          MonitorInstaller.install_module_monitor(mod)
-          INSTALLED << mod
-        end
+    opts.on("--save-output", "Save output to file") do b|
+      OPTIONS[:save_output] = b
+    end
 
-      end
+    opts.on("-s","--[no-]stdout","Show output on screen") do |b|
+      OPTIONS[:stdout] = b
+    end
 
-      # At the end, we generate an output of the type information.
-      at_exit do 
-        self.output
-      end
+    opts.on("-a", "--[no-]append", "Append output to input file") do |b|
+      OPTIONS[:append] = b
+    end
 
+    opts.on("-v","--verbose","Show messages in detail") do
+      OPTIONS[:verbose] = true
     end
 
-    # Reads the input file if specified or exists
-    def self.input()
-      return unless OPTIONS[:io_file] && File.exist?(OPTIONS[:io_file])
-      RubyBreaker.verbose("RubyBreaker input file exists...loading")
-      eval "load \"#{OPTIONS[:io_file]}\"", TOPLEVEL_BINDING
+    opts.on("-h","--help","Show this help text") do 
+      puts opts
+      exit
     end
 
-    # This method will generate the output.
-    def self.output()
+  end
 
-      RubyBreaker.verbose("Generating type documentation")
+  # This constant contains the copyright information.
+  COPYRIGHT = "Copyright (c) 2012 Jong-hoon (David) An. All Rights Reserved."
 
-      io_exist = OPTIONS[:io_file] && File.exist?(OPTIONS[:io_file])
+  # Extension used for files that contain RubyBreaker task information
+  TASK_EXTENSION = "rb"
 
-      code = ""
-      # Document each module that was monitored
-      INSTALLED.each { |mod| 
-        str = Runtime::TypesigUnparser.unparse(mod) 
-        code << str
-        if OPTIONS[:mode] == :lib
-          print str
-        end
-      }
+  # Extension used for files that contain type information in YAML format
+  YAML_EXTENSION = "yaml"
+
+  # Extension used for files that contain type information in Ruby format
+  IO_EXTENSION = "rubybreaker.rb"
+
+  private
+
+  # This method determines if RubyBreaker is running as a task.
+  def self.running_as_task?(); return $__rubybreaker_task != nil end
+
+  # This method returns the task currently being run.
+  def self.task(); return $__rubybreaker_task end
 
-      # If this was a library mode run, exit now. 
-      return if OPTIONS[:mode] == :lib
+  # This method loads the IO file by loading it.
+  def self.load_input(fname)
+    return fname
+    eval "load \"#{fname}\"", TOPLEVEL_BINDING
+    RubyBreaker.verbose("RubyBreaker input file #{fname} is loaded")
+  end
+
+  # This method will generate the output to the given filename.
+  def self.output(fname)
+
+    RubyBreaker.verbose("Generating type documentation")
 
+    code = ""
+
+    # Document each module that was monitored.
+    INSTALLED.each { |mod| 
+      str = Runtime::TypeSigUnparser.unparse(mod) 
+      code << str
+      print str if OPTIONS[:stdout] # display on the screen if requested
+    }
+
+    if fname && OPTIONS[:save_output]
+      # Check if the file already exists--that is, if it was used for input
+      io_exist = File.exists?(fname)
+      RubyBreaker.verbose("Saving it to #{fname}")
       # Append the result to the input file (or create a new file)
-      open(OPTIONS[:io_file],"a") do |f|
-        unless io_exist 
-          f.puts "# This file is auto-generated by RubyBreaker"
-          f.puts "require \"rubybreaker\""
+      fmode = OPTIONS[:append] ? "a" : "w"
+      open(fname, fmode) do |f|
+        # When append, do not write the header
+        unless OPTIONS[:append] 
+          f.puts "# This file is auto-generated by RubyBreaker" 
         end
+        # But time stamp always
+        f.puts "# Last modified: #{Time.now}"
+        f.puts "require \"rubybreaker\"" unless OPTIONS[:append] 
         f.print code
       end
+    end
 
-      RubyBreaker.verbose("Done generating type documentation")
+    RubyBreaker.verbose("Done generating type documentation")
+  end
+
+  # This method finds the IO file for this run. It is either specified in
+  # io-file option or using the program name or the task name.
+  def self.io_file(prog_or_task)
+    if OPTIONS[:io_file]
+      fname = OPTIONS[:io_file]
+    elsif prog_or_task
+      fname = "#{File.basename(prog_or_task.to_s, ".rb")}.#{IO_EXTENSION}"
     end
+    return nil unless fname
+    fname = File.absolute_path(fname) 
+    return fname
+  end
 
-    # This method will run do things in the following order:
-    #
-    #   * Checks to see if the user program and an input file exists
-    #   * Loads the documentation for Ruby Core Library (TODO)
-    #   * Reads the input type documentation if any
-    #   * Reads (require's) the user program
-    #
-    def self.run()
-
-      RubyBreaker.setup_logger()
-      RubyBreaker.verbose("Running RubyBreaker")
-
-      # First, take care of the program file.
-      argv0 = OPTIONS[:file]
-      prog_file = argv0
-      prog_file = File.expand_path(prog_file)
-
-      # It is ok to omit .rb extension. So try to see if prog_file.rb exists
-      if !File.exist?(prog_file) && !File.extname(prog_file) == ".rb" 
-        prog_file = "#{prog_file}.rb"
-      end 
-
-      if !File.exist?(prog_file)
-        fatal("#{argv0} is an invalid file.")
-        exit(1)
-      end
+  public
+
+  # This method runs RubyBreaker for a particular test case (class). This
+  # is a bit different from running RubyBreaker as a shell program. 
+  def self.run(*mods)
+    RubyBreaker.setup_logger() unless RubyBreaker.defined_logger?()
+
+    # Task based run should use the rubybreaker options same as in shell
+    # mode. So, parse the options first.
+    if self.running_as_task?() # running in task mode
+      RubyBreaker.verbose("Running RubyBreaker within a testcase")
+      task = self.task
+      OPTION_PARSER.parse(*task[:rubybreaker_opts])
+      Runtime.breakable(*task[:breakable])
+      task_name = task[:name]
+      RubyBreaker.verbose("Done reading task information")
+      io_file = self.io_file(task_name)
+    elsif OPTIONS[:prog_file] # running in shell mode 
+      Runtime.breakable(*mods)
+      io_file = self.io_file(OPTIONS[:prog_file])
+    else
+      # Otherwise, assume there are no explicit IO files.
+    end
+    self.load_input(io_file)
 
-      # Then, input/output file if specified
-      if !OPTIONS[:io_file] || OPTIONS[:io_file].empty?
-        OPTIONS[:io_file] = "#{File.basename(argv0, ".rb")}.#{EXTENSION}"
-      end
-      OPTIONS[:io_file] = File.absolute_path(OPTIONS[:io_file])
+    # The following is deprecated but doing this for backward compatibility
+    Runtime.instrument()
 
-      if OPTIONS[:rubylib]
-        RubyBreaker.verbose("Loading RubyBreaker's Ruby Core Library documentation")
-        # Load the core library type documentation
-        eval("require \"rubybreaker/rubylib\"", TOPLEVEL_BINDING)
-      end
+    # At the end, we WILL generate an output of the type information.
+    at_exit { self.output(io_file) }
+  end
+  
+end
 
-      # Read the input file first (as it might contain type documentation
-      # already)
-      Main.input()
+# This method is available by default.
+module Kernel
 
-      # Finally, require the program file! Let it run! Wheeee!
-      eval("require '#{prog_file}'", TOPLEVEL_BINDING)
+  def typesig(str)
+    _TypeDefs = RubyBreaker::TypeDefs
 
-      RubyBreaker.verbose("Done running the input program")
+    # This MUST BE set for self type to work in type signatures.
+    _TypeDefs::SelfType.set_self(self) 
 
-    end
+    t = RubyBreaker::Runtime::TypeSigParser.parse(str)
+    t_map = RubyBreaker::Runtime::TYPE_MAP[self]
 
-  end
+    # If the type map doesn't exist, create it on the fly. Now this module
+    # is broken!
+    if !t_map
+      t_map = {}
+      RubyBreaker::Runtime::TYPE_MAP[self] = t_map
+    end
 
-  # This is the manual indicator for the program entry point. It simply
-  # redirects to the monitor setup code.
-  def self.monitor()
-    Main.setup()
+    meth_type = t_map[t.meth_name]
+    if meth_type
+      if meth_type.instance_of?(_TypeDefs::MethodListType)
+        meth_type.types << t
+      else
+        # then promote it to a method list type
+        t_map[t.meth_name] = _TypeDefs::MethodListType.new([meth_type, t])
+      end
+    else
+      t_map[t.meth_name] = t
+    end
+    return t
   end
-
 end
 

data/test/integrated/tc_both_broken_breakable.rb

@@ -3,18 +3,19 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedBothBrokenBreakableTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A
-    include RubyBreaker::Breakable
-    include RubyBreaker::Broken
+    # include RubyBreaker::Breakable
     typesig("foo(fixnum[to_s]) -> string") 
     def foo(x); x.to_s end
     def bar(x); x.to_sym end
   end
 
+  def setup
+    RubyBreaker.breakable(A)
+  end
+
   def test_both_broken_and_breakable
-    # A.new.foo(1)
     A.new.bar("abc")
     a_foo_meth_type = Runtime::Inspector.inspect_meth(A, :foo)
     a_bar_meth_type = Runtime::Inspector.inspect_meth(A, :bar)

data/test/integrated/tc_class_methods.rb

@@ -3,21 +3,22 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedClassMethodsTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A
-    include RubyBreaker::Breakable
     def self.foo(x); x.to_s end
   end
 
   class B
-    include RubyBreaker::Broken
     class << self
       typesig("bar(fixnum[to_s]) -> string")
       def bar(x); x.to_s end
     end
   end
 
+  def setup()
+    RubyBreaker.breakable(A, B)
+  end
+
   def test_class_methods
     A.foo(1)
     a_foo_meth_type = Runtime::Inspector.inspect_class_meth(A, :foo)

data/test/integrated/tc_inherit_broken.rb

@@ -3,19 +3,20 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedInheritBrokenTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A
-    include RubyBreaker::Broken
     typesig("foo(fixnum[to_s]) -> string")
     def foo(x); x.to_s end
   end
 
   class B < A
-    include RubyBreaker::Breakable
     def bar(x); foo(x) end
   end
 
+  def setup()
+    RubyBreaker.breakable(B)
+  end
+
   def test_both
     b = B.new
     b.bar(1)

data/test/integrated/tc_method_missing.rb

@@ -3,16 +3,16 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedMethodMissingTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A
-    include RubyBreaker::Breakable
-
     def method_missing(mname, *args, &blk)
       method_name = mname.to_s
       return method_name + "_" + args.join("_") 
     end
-
+  end
+  
+  def setup()
+    RubyBreaker.breakable(A)
   end
 
   # TODO: This must be fixed once variable length argument type is supported

data/test/integrated/tc_namespace.rb

@@ -3,7 +3,6 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedNamespaceTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A < String
     class C < String
@@ -17,12 +16,15 @@ class IntegratedNamespaceTest < Test::Unit::TestCase
   end
 
   class B
-    include RubyBreaker::Breakable
     def foo(x); x.to_s end
     def bar(x); x.to_s end
     def baz(x); x.to_s end
   end
 
+  def setup()
+    RubyBreaker.breakable(B)
+  end
+
   def test_namspace_b_foo
     a = A.new
     b = B.new

data/test/integrated/tc_simple1.rb

@@ -3,10 +3,8 @@ require_relative "../../lib/rubybreaker"
 
 class IntegratedSimpleTest < Test::Unit::TestCase
   include RubyBreaker
-  include RubyBreaker::TestCase
 
   class A
-    include RubyBreaker::Breakable
 
     def foo(x)
       x.to_s
@@ -33,12 +31,15 @@ class IntegratedSimpleTest < Test::Unit::TestCase
   end
 
   class B
-    include RubyBreaker::Broken
     typesig("baz(string[size], true_class) -> fixnum")
     typesig("baz(string[to_s], false_class) -> string")
     def baz(x,b); end
   end
 
+  def setup()
+    RubyBreaker.breakable(A)
+  end
+
   def test_simple1_a_foo
     a = A.new
     a.foo("test_simple1 >> string")

data/test/runtime/tc_obj_wrapper.rb

@@ -16,6 +16,16 @@ class ObjectWrapperTest < Test::Unit::TestCase
     x.to_s
   end
 
+  def baz(x)
+    x.send(:foo,1)
+  end
+
+  class A
+    def foo(x)
+      x.to_s
+    end
+  end
+
   def test_empty()
     x = 42
     wrapped_x = Runtime::ObjectWrapper.new(x)
@@ -24,28 +34,37 @@ class ObjectWrapperTest < Test::Unit::TestCase
     assert_equal("fixnum[]",str)
   end
 
-  def test_simple_foo()
+  def setup
+    Runtime::GLOBAL_MONITOR_SWITCH.turn_on()
+  end
+
+  def test_foo()
     x = 42
     wrapped_x = Runtime::ObjectWrapper.new(x)
-    Runtime::GLOBAL_MONITOR_SWITCH.turn_on()
     foo(wrapped_x)
-    Runtime::GLOBAL_MONITOR_SWITCH.turn_off()
     type = wrapped_x.__rubybreaker_type()
     str = TypeUnparser.unparse(type)
     assert_equal("fixnum[to_f, to_s]",str)
   end
 
-  def test_simple_bar()
+  def test_bar()
     x = 42
     wrapped_x = Runtime::ObjectWrapper.new(x)
-    Runtime::GLOBAL_MONITOR_SWITCH.turn_on()
     bar(wrapped_x)
-    Runtime::GLOBAL_MONITOR_SWITCH.turn_off()
     type = wrapped_x.__rubybreaker_type()
     str = TypeUnparser.unparse(type)
     assert_equal("fixnum[to_f, to_s]",str)
   end
 
+  def test_baz()
+    x = A.new
+    wrapped_x = Runtime::ObjectWrapper.new(x)
+    baz(wrapped_x)
+    type = wrapped_x.__rubybreaker_type()
+    str = TypeUnparser.unparse(type)
+    assert_equal("object_wrapper_test/a[foo]", str)
+  end
+
   def test_object_id()
     x = 42
     wrapped_x = Runtime::ObjectWrapper.new(x)

data/test/runtime/tc_typesig_parser.rb

@@ -9,7 +9,6 @@ class TypeSigTest < Test::Unit::TestCase
   include RubyBreaker
   
   class A
-    include RubyBreaker::Broken
     typesig("foo(fixnum) -> fixnum")
     typesig("bar(fixnum) -> self")
   end

data/test/testtask/sample.rb

@@ -0,0 +1,10 @@
+# Below classes are used for internal testing 
+
+class SampleClassA
+  def foo(x); x.to_s end
+end
+
+class SampleClassB
+  def foo(x); x.to_s end
+end
+

data/test/testtask/tc_testtask.rb

@@ -0,0 +1,25 @@
+require "test/unit"
+require_relative "sample"
+require "rubybreaker"
+
+class SampleClassB # re-opening
+  typesig("foo(fixnum[to_s]) -> string")
+end
+
+class RubyBreakerTestTaskTest < Test::Unit::TestCase
+
+  def test_breakable()
+    SampleClassA.new.foo(2)
+    t = RubyBreaker::Runtime::Inspector.inspect_meth(SampleClassA, :foo)
+    str = t.unparse()
+    assert_equal("foo(fixnum[to_s]) -> string", str)
+  end
+
+  def test_broken()
+    t = RubyBreaker::Runtime::Inspector.inspect_meth(SampleClassB, :foo)
+    str = t.unparse()
+    assert_equal("foo(fixnum[to_s]) -> string", str)
+  end
+
+end
+

data/test/ts_rspec.rb

@@ -2,30 +2,36 @@ require "rspec"
 require_relative "../lib/rubybreaker"
 
 class RSpecTestA
-  include RubyBreaker::Breakable
   def foo(x); x.to_s end
 end
 
 class RSpecTestB
-  include RubyBreaker::Broken
   typesig("foo(fixnum[to_s]) -> string")
 end
 
-describe RSpecTestA do
-  it "should return a string of number" do
-    a = RSpecTestA.new
-    a.foo(1)
-    a_foo_type = RubyBreaker::Runtime::Inspector.inspect_meth(RSpecTestA, :foo)
-    str = a_foo_type.unparse()
-    str.should == "foo(fixnum[to_s]) -> string"
+describe "RSpec Test" do
+
+  before do 
+    RubyBreaker.breakable(RSpecTestA)
   end
-end
 
-describe RSpecTestB do
-  it "should return the documented type of B#foo" do
-    b_foo_type = RubyBreaker::Runtime::Inspector.inspect_meth(RSpecTestB, :foo)
-    str = b_foo_type.unparse()
-    str.should == "foo(fixnum[to_s]) -> string"
+  describe RSpecTestA do
+    it "should return a string of number" do
+      a = RSpecTestA.new
+      a.foo(1)
+      a_foo_type = RubyBreaker::Runtime::Inspector.inspect_meth(RSpecTestA, :foo)
+      str = a_foo_type.unparse()
+      str.should == "foo(fixnum[to_s]) -> string"
+    end
   end
+
+  describe RSpecTestB do
+    it "should return the documented type of B#foo" do
+      b_foo_type = RubyBreaker::Runtime::Inspector.inspect_meth(RSpecTestB, :foo)
+      str = b_foo_type.unparse()
+      str.should == "foo(fixnum[to_s]) -> string"
+    end
+  end
+
 end
 

data/test/typing/tc_typing.rb

@@ -8,7 +8,6 @@ class TypingTest < Test::Unit::TestCase
   include RubyBreaker
 
   class A
-    include RubyBreaker::Broken
     typesig("foo(fixnum) -> fixnum")
     typesig("bar(fixnum) {|fixnum| -> string} -> string")
     typesig("baz(fixnum, string?) -> fixnum")
@@ -100,14 +99,14 @@ class TypingTest < Test::Unit::TestCase
     assert(t1.subtype_of?(t2), msg(t1, t2))
     assert(t2.subtype_of?(t1), msg(t1, t2))
     # XXX: The following assert will succeed because Fixnum and String are
-    # not Broken at this point.
+    # not "broken" at this point.
     assert(t1.subtype_of?(t3), msg(t1, t3, true))
   end
 
   def test_duck_fusion_types()
     t1 = DuckType.new([:to_s, :to_f])
     t2 = FusionType.new(NominalType.new(Fixnum), [:to_f, :to_s])
-    # Again, this works because Fixnum is not Broken yet 
+    # Again, this works because Fixnum is not "broken" yet 
     assert(t1.subtype_of?(t2), msg(t1, t2))
     assert(t2.subtype_of?(t1), msg(t1, t2))
   end