rubybreaker 0.0.3 → 0.0.4

data/NEWS

@@ -1,3 +1,7 @@
+# VERSION 0.0.4
+* RSpec is supported.
+* Namespace is recognized in type signatures.
+
 # VERSION 0.0.3
 * A class or module can be both Breakable and Broken at the same time.
 * Better logging/debugging output

data/README.md

@@ -2,7 +2,7 @@
 
 # Introduction
 
-RubyBreaker is a dynamic type documentation tool written purely in Ruby. It
+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 executions and document the observed type
 information. The type documentation generated by RubyBreaker is also an
@@ -13,7 +13,7 @@ program.
 The primary goal of RubyBreaker is to assign a type signature to every
 method in designated modules and classes.  A type signature is written in
 the RubyBreaker Type Annotation Language which resembles the documentation
-style used in RubyDoc. Overall, this tool should help Ruby programmers
+style used in Ruby API Doc. Overall, this tool should help Ruby programmers
 document their code more rigorously and effectively.  Currently, manual
 modification of the user program is required to run RubyBreaker, but this is
 kept minimal. 
@@ -25,10 +25,9 @@ be found in [here](rdoc/index.html).
 
 ## Limitations
 
-* It only works on toy Ruby programs so far :)
 * Block argument cannot be auto-documented. (Inherent)
 * Manual modification (minimal) of code is required.
-* No parametric polymorphic types are supported. 
+* Parametric polymorphic types are not supported. 
 
 ## Requirements
 
@@ -129,7 +128,8 @@ In order to use RubyBreaker, there needs two kinds of manual code changes.
 First, the user must indicate which modules are subject to analysis and
 which modules can be used for the analysis. Next, the user has to indicate
 where the entry point of the program is. Alternatively, he has to make a
-small change to the test cases to use RubyBreaker's testing framework.
+small change to the test cases to use RubyBreaker's testing framework. (If
+you are using RSpec, there is no need for this change.)
 
 ### Breakable and Broken
 
@@ -209,9 +209,7 @@ auto-documented and manually documented, respectively.
 In Ruby, as soon as a file is `require`d, the execution of that file begins.
 For RubyBreaker, however, it is not trivial to find the actual starting
 point of the program because there *has* to be a clear point in time at
-which monitoring of `Breakable` modules begins. *This is necessary as
-attempting to instrument and monitor at the same time will cause an infinite
-loop!* 
+which monitoring of `Breakable` modules begins. 
 
 Indicating the program entry point is simply done by inserting the following
 line at the code (assuming "`require 'rubybreaker'`" is already placed at
@@ -226,11 +224,11 @@ run the instrumented code (for `Breakable` modules) which will gather type
 information for methods.
 
 Although this seems simple and easy, this is not the recommended way for
-analyzing a program. Why? Because RubyBreaker has a built-in testing
-framework that (supposedly :)) works seemlessly with the existing tests of
-the program.
+analyzing a program. Why? Because RubyBreaker comes with a replacement for
+the built-in testing framework for Ruby. Even better, if you are using
+RSpec, there is no need to change any test code.
 
-### Using RubyBreaker Testing Framework
+### Using the Built-in Testing Framework
 
 Instead of manually inserting the entry point indicator into the program,
 the user can take advantage of the Ruby Unit Test framework. This is the
@@ -245,11 +243,27 @@ one.
       # ...tests!...
     end
 
-That's it! 
+That's it! Also, remember that classes and modules can be re-opened for
+"patches" in Ruby. This means that the original classes or modules do not
+need to be modified to include `Broken` and/or `Breakable`. In each test
+suite or test case, those classes and modules can be re-opened to include
+`Broken` and/or `Breakable`. The following shows an example of such a test
+case.
 
-Currently, RubyBreaker only supports the standard unit test framework.
-Other testing frameworks such as RSpec and Cucumber are not supported at the
-moment (but will be in future/hopefully).
+    require "rubybreaker"
+    require "test/unit"
+    class A
+      include RubyBreaker::Breakable
+    end
+    class TestClassA < Test::Unit::TestCase
+       ...
+    end
+
+### Using RSpec
+
+If using RSpec, it is even easier! No changes are needed for the test code.
+Really! _Well, it is still necessary to `require rubybreaker` and manually
+insert `Breakable` and `Broken` to appropriate classes and modules._
 
 ## Type Annotation
 
@@ -286,7 +300,9 @@ instance, `fixnum` is an object of type `Fixnum`. Use lower-case letters and
 underscores instead of _camelized_ name. `MyClass`, for example would be
 `my_class` in RubyBreaker type signatures. There is no particular
 reason for this convention other than it is the common practice used in
-RubyDoc. 
+RubyDoc. Use `/` to indicate the namespace delimiter `::`. For example,
+`NamspaceA::ClassB` would be represented by `namespace_a/class_b` in
+a RubyBreaker type signature.
 
 ### Self Type
 
@@ -443,8 +459,6 @@ The term, "Fusion Type," is first coined by Professor Michael W. Hicks at
 University of Maryland and represents an object using a structural type with
 respect to a nominal type. 
 
-* * *
-
 # Copyright
 Copyright (c) 2012 Jong-hoon (David) An. All Rights Reserved.
 

data/Rakefile

@@ -9,7 +9,13 @@ require "rake/clean"
 begin 
   require "rdiscount"   # used to generate the doc html page
 rescue LoadError => e
-  puts "[WARNING] No rdiscount is installed."
+  puts "[WARNING] No rdiscount is installed on this computer."
+end
+
+begin 
+  require 'rspec/core/rake_task'
+rescue LoadError => e
+  puts "[WARNING] No rspec-core is installed on this computer."
 end
 
 # Use rake/clean to remove generated files
@@ -23,7 +29,7 @@ CLEAN.concat(FileList["webpage/rdoc",
 task :default => [:test]
 
 desc "Do all"
-task :all => [:parser, :test, :rdoc, :webpage, :gem] do |t|
+task :all => [:parser, :test, :rspec, :rdoc, :webpage, :gem] do |t|
 end
 
 desc "Generate gemspec"
@@ -39,15 +45,16 @@ end
 
 desc "Generate the webpage"
 task :webpage do |t|
-  break unless defined?(RDiscount)
-  dir = File.dirname(__FILE__)
-  readme_md = "#{dir}/README.md"
-  output = "#{dir}/webpage/index.html"
-  body = RDiscount.new(File.read(readme_md)).to_html
-  header = File.read("#{dir}/webpage/header.html")
-  footer = File.read("#{dir}/webpage/footer.html")
-  html = header + body + footer
-  File.open(output, "w") { |f| f.write(html) }
+  if defined?(RDiscount)
+    dir = File.dirname(__FILE__)
+    readme_md = "#{dir}/README.md"
+    output = "#{dir}/webpage/index.html"
+    body = RDiscount.new(File.read(readme_md)).to_html
+    header = File.read("#{dir}/webpage/header.html")
+    footer = File.read("#{dir}/webpage/footer.html")
+    html = header + body + footer
+    File.open(output, "w") { |f| f.write(html) }
+  end
 end
 
 desc "Generate parser"
@@ -57,9 +64,20 @@ task :parser do |t|
 end
 
 desc "Run basic tests"
-Rake::TestTask.new("test") do |t|
+Rake::TestTask.new(:"test") do |t|
   dir = File.dirname(__FILE__)
   t.libs << "lib"
-  t.test_files = FileList["test/*.rb"]
+  test_files = FileList["test/ts_*.rb"]
+  test_files.exclude("test/ts_rspec.rb")
+  t.test_files = test_files
+end
+
+if defined?(RSpec)
+  desc "Run RSpec test"
+  RSpec::Core::RakeTask.new(:rspec) do |t|
+    t.pattern = ["test/ts_rspec.rb"]
+    t.fail_on_error = false
+  end
 end
 
+

data/TODO

@@ -6,11 +6,13 @@ 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.
 
-# More Testing Frameworks
+# Additional Testing Frameworks
 
-The Ruby community has other testing frameworks such as RSpec and Cucumber.
-RubyBreaker should be able to support these frameworks so that those test
-suites can be used for RubyBreaker.
+RubyBreaker supports the built-in testing framework and RSpec. There are
+other testing frameworks such as Cucumber or Shouda. Since RubyBreaker's
+goal is to help Ruby programmers write better code by taking advantage of
+existing test suites, it seems appropriate to support as many testing
+frameworks as possible.
 
 # RDoc and YARD Documentation Support
 

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.0.4

data/bin/rubybreaker

@@ -56,7 +56,6 @@ module RubyBreaker
 
     # There has to be an input file
     if ARGV.length < 1 then 
-      puts "Specify a Ruby program"
       puts option_parser.banner
       exit(1)
     end

data/lib/rubybreaker/debug/debug.rb

@@ -11,7 +11,7 @@ module RubyBreaker
   # This sets up the logger for debugging RubyBreaker
   def self.setup_logger #:nodoc:
     return if defined?(LOGGER)
-    out = if (defined?(OPTIONS) && !OPTIONS[:file].empty?)
+    out = if (defined?(OPTIONS) && OPTIONS[:debug] && !OPTIONS[:file].empty?)
           then "#{OPTIONS[:file]}.log"
           else STDOUT
           end

data/lib/rubybreaker/runtime/typesig_unparser.rb

@@ -0,0 +1,96 @@
+require "prettyprint"
+require_relative "../type"
+
+module RubyBreaker
+
+  module Runtime
+
+    # This module handles unparsing type signatures.
+    module TypesigUnparser
+
+      include TypeDefs
+
+      # This array lists monitored modules/classes that are outputed.
+      DOCUMENTED = []
+
+      # Pretty prints type information for methods
+      def self.pp_methods(pp, meth_type_map, opts={})
+        meth_type_map.each { |meth_name, meth_type|
+          case meth_type
+          when MethodType
+            pp.breakable()
+            pp.text("typesig(\"")
+            TypeUnparser.unparse_pp(pp, meth_type, opts)
+            pp.text("\")")
+          when MethodListType
+            meth_type.types.each { |real_meth_type|
+              pp.breakable()
+              pp.text("typesig(\"")
+              TypeUnparser.unparse_pp(pp, real_meth_type, opts)
+              pp.text("\")")
+            }
+          else
+            # Can't happen
+          end
+        }
+      end
+
+      # Pretty prints type information for the module/class
+      def self.pp_module(pp, mod, opts={})
+        # Skip it if we already have seen it
+        return if DOCUMENTED.include?(mod) || mod.to_s[0..1] == "#<"
+
+        # Remember that we have documented this module/class
+        DOCUMENTED << mod  
+
+        # Get the method type mapping
+        meth_type_map = Inspector.inspect_all(mod)
+
+        # Check if this module is a class
+        keyword = mod.instance_of?(Class) ? "class" : "module"
+        
+        pp.text("#{keyword} #{mod.to_s}", 80)
+        pp.nest(2) do 
+          pp.breakable("")
+          pp.text("include RubyBreaker::Broken", 80)
+
+          # See if there is any class method to show
+          eigen = Runtime.eigen_class(mod)
+          if !DOCUMENTED.include?(eigen)
+            DOCUMENTED << eigen
+            eigen_meth_type_map = Inspector.inspect_all(eigen)
+            if eigen_meth_type_map.size > 0 
+              pp.breakable()
+              pp.text("class << self", 80)
+              pp.nest(2) do
+                self.pp_methods(pp, eigen_meth_type_map, :namespace => eigen)
+              end
+              pp.breakable()
+              pp.text("end", 80)
+            end
+          end
+
+          self.pp_methods(pp, meth_type_map, :namespace => mod)
+
+        end
+        pp.breakable() 
+        pp.text("end",80)
+        pp.breakable()
+      end
+
+      # This method unparses the type information in the specified module,
+      # displaying one or more type signatures for each method that is
+      # monitored during runtime.
+      def self.unparse(mod, opts={})
+        str = ""
+        pp = PrettyPrint.new(str)
+        self.pp_module(pp, mod, opts)
+        pp.flush
+        return str
+      end
+
+    end
+
+  end
+
+end

data/lib/rubybreaker/runtime.rb

@@ -5,6 +5,7 @@
 
 require_relative "runtime/overrides"
 require_relative "runtime/typesig_parser"
+require_relative "runtime/typesig_unparser"
 require_relative "runtime/monitor"
 require_relative "runtime/inspector"
 

data/lib/rubybreaker/test/rspec.rb

@@ -0,0 +1,15 @@
+#-
+# This file overrides the describe method of RSpec to call the RubyBreaker
+# setup first.
+
+RUBYBREAKER_RSPEC_PREFIX = "__rubybreaker"
+
+if defined?(RSpec)
+  alias :"#{RUBYBREAKER_RSPEC_PREFIX}_describe" :describe
+end
+
+def describe(*args,&blk)
+  RubyBreaker::Main.setup if defined?(RubyBreaker) 
+  send(:"#{RUBYBREAKER_RSPEC_PREFIX}_describe", *args, &blk)
+end
+

data/lib/rubybreaker/test/testcase.rb

@@ -9,11 +9,11 @@ module RubyBreaker
   # class. 
   module TestCase
 
-    def self.setup()
+    def self.__rubybreaker_setup()
       Main.setup()
     end
 
-    def self.teardown()
+    def self.__rubybreaker_teardown()
       # Main.output()
     end
 
@@ -25,9 +25,9 @@ module RubyBreaker
       alias :__run :run
 
       def run(*args,&blk)
-        RubyBreaker::TestCase.setup()
+        RubyBreaker::TestCase.__rubybreaker_setup()
         __run(*args,&blk)
-        RubyBreaker::TestCase.teardown()
+        RubyBreaker::TestCase.__rubybreaker_teardown()
       end
 
       EOS

data/lib/rubybreaker/test.rb

@@ -1 +1,2 @@
 require_relative "test/testcase"
+require_relative "test/rspec"

data/lib/rubybreaker/type/type_grammar.treetop

@@ -227,15 +227,16 @@ grammar TypeGrammar
   end
 
   rule nominal_type
-    [a-z_]+ {
+    [a-z_/]+ { # FIXME: not really accurate
       def value      
         pos = RubyBreaker::Position.get()
         pos.col = interval.first
         begin 
           mod_name = RubyBreaker::Util.camelize(text_value)
-          mod = eval mod_name
-          t = RubyBreaker::NominalType.new(mod,pos)
-        rescue
+          mod = eval(mod_name) # do it at the current binding
+          t = RubyBreaker::NominalType.new(mod, pos)
+        rescue => e
+          puts e
           t = RubyBreaker::AnyType.new(pos)
         end
         return t # RubyBreaker::NominalType.new(text_value,pos)

data/lib/rubybreaker/type/type_unparser.rb

@@ -15,16 +15,45 @@ module RubyBreaker
 
     private
 
+    # This method resolves the mod_name's namespace with respect to the
+    # namespace. For example, if the current namespace is
+    # 
+    # A::B
+    #
+    # and the given module is A::B::C::D, then we show
+    #
+    # C::D
+    #
+    #
+    # If the current namespace is
+    #
+    # A::B::C
+    #
+    # and the given module is A::B::D::E, then we show
+    #
+    # D::E
+    #
+    def self.resolve_namespace(namespace, mod_name)
+      return mod_name if namespace == nil || namespace.empty?
+      if mod_name.start_with?(namespace)
+        pattern = "^#{namespace}::"
+        return mod_name.sub(/#{pattern}/, "")
+      end
+      tokens = namespace.split("::")
+      return mod_name if tokens.size <= 1
+      return self.resolve_namespace(tokens[0..-2].join("::"), mod_name)
+    end
+
     # This method is used to determine if the inner type of +t+ should be
     # wrapped around a parenthesis. This is for optional type and variable
     # length type.
-    def self.peek_and_unparse_pp_inner_type(pp,t)
+    def self.peek_and_unparse_pp_inner_type(pp, t, opts={})
       if t.type.kind_of?(OrType)
         pp.text("(")
-        self.unparse_pp(pp,t.type)
+        self.unparse_pp(pp, t.type, opts)
         pp.text(")")
       else
-        self.unparse_pp(pp,t.type)
+        self.unparse_pp(pp, t.type, opts)
       end
     end
 
@@ -35,23 +64,34 @@ module RubyBreaker
 
     # This recursive method unparses a RubyBreaker type using the pretty
     # print method.
-    def self.unparse_pp(pp,t)
+    def self.unparse_pp(pp, t, opts={})
       if t.instance_of?(NominalType)
-        tname = Util.underscore(t.mod)
-        tokens = tname.split("/")        
-        tname = tokens.last if tokens.size > 1
+        if opts[:namespace] && opts[:namespace].name
+          # resolve the namespace for the module/class given the current
+          # namespace
+          mod_name = self.resolve_namespace(opts[:namespace].name, t.mod.name)
+        else
+          mod_name = t.mod.name
+        end
+        unless opts[:style] == :camelize
+          tname = Util.underscore(mod_name)
+        else
+          tname = mod_name
+        end
+        # tokens = tname.split("/")        
+        # tname = tokens.last if tokens.size > 1
         pp.text(tname)
       elsif t.instance_of?(SelfType)
         pp.text("self")
       elsif t.instance_of?(DuckType)
         unparse_pp_object_type(pp,t)
       elsif t.instance_of?(FusionType)
-        unparse_pp(pp,t.nom_type)
+        unparse_pp(pp, t.nom_type, opts)
         unparse_pp_object_type(pp,t)
       elsif t.instance_of?(MethodType)
         pp.text("#{t.meth_name}(")
         t.arg_types.each_with_index do |arg_type,i|
-          unparse_pp(pp,arg_type)
+          unparse_pp(pp, arg_type, opts)
           if i < t.arg_types.size - 1
             pp.text(",")
             pp.fill_breakable()
@@ -61,17 +101,17 @@ module RubyBreaker
         pp.fill_breakable()
         if t.blk_type
           pp.text("{")
-          unparse_pp(pp,t.blk_type)
+          unparse_pp(pp, t.blk_type, opts)
           pp.text("}")
           pp.fill_breakable()
         end
         pp.text("->")
         pp.fill_breakable()
-        unparse_pp(pp,t.ret_type)
+        unparse_pp(pp, t.ret_type, opts)
       elsif t.instance_of?(BlockType)
         pp.text("|")
         t.arg_types.each_with_index do |arg_type,i|
-          unparse_pp(pp,arg_type)
+          unparse_pp(pp, arg_type, opts)
           if i < t.arg_types.size - 1
             pp.text(",")
             pp.fill_breakable()
@@ -81,33 +121,33 @@ module RubyBreaker
         pp.fill_breakable()
         if t.blk_type
           pp.text("{")
-          unparse_pp(pp,t.blk_type)
+          unparse_pp(pp, t.blk_type, opts)
           pp.text("}")
           pp.fill_breakable()
         end
         pp.text("->")
         pp.fill_breakable()
-        unparse_pp(pp,t.ret_type)
+        unparse_pp(pp, t.ret_type, opts)
       elsif t.instance_of?(MethodListType)
         t.types.each_with_index do |typ,i|
-          unparse_pp(pp,typ)
+          unparse_pp(pp, typ, opts)
           if i < t.types.size - 1 
             pp.fill_breakable()
           end
         end
       elsif t.instance_of?(OrType)
         t.types.each_with_index do |typ,i|
-          unparse_pp(pp,typ)
+          unparse_pp(pp, typ, opts)
           if i < t.types.size - 1
             pp.text(" ||")
             pp.fill_breakable()
           end
         end
       elsif t.instance_of?(OptionalType)
-        peek_and_unparse_pp_inner_type(pp,t)
+        peek_and_unparse_pp_inner_type(pp, t, opts)
         pp.text("?")
       elsif t.instance_of?(VarLengthType)
-        peek_and_unparse_pp_inner_type(pp,t)
+        peek_and_unparse_pp_inner_type(pp, t, opts)
         pp.text("*")
       elsif t.instance_of?(NilType)
         pp.text("nil")
@@ -119,12 +159,16 @@ module RubyBreaker
 
     public
 
-    # This method is used to display any RubyBreaker type in a user-friendly
-    # way using the pretty print method. 
-    def self.unparse(t)
+    # This method unparses the RubyBreaker type according to the specified
+    # options.
+    #
+    # t:: RubyBreaker type
+    # opts:: 
+    #
+    def self.unparse(t, opts={})
       str = ""
       pp = PrettyPrint.new(str)
-      self.unparse_pp(pp,t)
+      self.unparse_pp(pp, t, opts)
       pp.flush
       return str.strip()
     end
@@ -132,9 +176,9 @@ module RubyBreaker
 
   class TypeDefs::Type
 
-    # This method unparses the type using the pretty print method.
-    def unparse()
-      TypeUnparser.unparse(self)
+    # This method is a shorthand for calling TypeUnparser.unparse(t). 
+    def unparse(opts={})
+      TypeUnparser.unparse(self, opts)
     end
   end