rubybreaker 0.0.2 → 0.0.3

data/NEWS

@@ -1,48 +1,8 @@
-# VERSION 0.0.2 
-
-## Class Method Support
-
-RubyBreaker now supports class methods.  Auto-documentation of class methods
-is done in the eigen class scope of the target module. For example, the
-consider the following:
-
-    class A
-      include RubyBreaker::Breakable
-      class << self
-        def foo(x); x.to_s end
-      end
-    end
-    RubyBreaker.monitor()
-    A.foo(1)
-
-When `foo` method is run, RubyBreaker will auto-document the type of the
-method and output as the following:
-
-    class A
-      include RubyBreaker::Broken
-      class << self
-        typesig("foo(fixnum[to_s]) -> string")
-      end
-    end
+# VERSION 0.0.3
+* A class or module can be both Breakable and Broken at the same time.
+* Better logging/debugging output
 
-## Variable-Length Argument Type
-
-RubyBreaker can now auto-document variable-length argument types if the last
-argument was declared with `*` prefix. For instance,
-
-    class A
-      include RubyBreaker::Breakable
-      def foo(*args)
-        args[0].to_s
-      end
-    end
-    RubyBreaker.monitor()
-    A.new.foo("1")
-
-Will generate the following output:
-
-    class A
-      include RubyBreaker::Broken
-      typesig("foo(string[to_s]*) -> string")
-    end
+# VERSION 0.0.2 
+* Class methods can be auto-documented or manually documented.
+* Variable-length argument type can be auto-documented.
 

data/README.md

@@ -171,10 +171,20 @@ signature `bar(fixnum[to_s]) -> string`, which means it takes an object that
 has `Fixnum`'s `to_s` method and returns a string. More detail on the type
 annotation language will be explained in later section.
 
-It is possible to include either `Breakable` or `Broken` in an eigen-class
-to document class methods. To make this easier, RubyBreaker will
-automatically support auto-documentation and manual documentation of class
-methods if the original module is declared as `Breakable` or `Broken`,
+### Hybrid of Breakable and Broken
+
+Starting from version 0.0.3, RubyBreaker allows a module to be declared as
+`Breakable` and `Broken` at the same time. If a method has a corresponding
+type signature (manually documented) somewhere, then RubyBreaker will not
+monitor it during runtime. All other methods will be instrumented and
+monitored by RubyBreaker.
+
+### Class Methods
+
+It is possible to include `Breakable` and/or `Broken` in an eigen-class to
+document class methods. To make this easier, RubyBreaker will automatically
+support auto-documentation and manual documentation of class methods if the
+original module is declared as `Breakable` and/or `Broken`,
 respectively--that is, up to immediate eigen class level of a "nominal"
 module.  The following example shows how class methods can be
 auto-documented and manually documented, respectively.
@@ -194,11 +204,6 @@ auto-documented and manually documented, respectively.
       end
     end
 
-Keep in mind that `Broken` module always wins against `Breakable`.  In other
-words, if a module is declared as both `Broken` and `Breakable`, it is
-treated as `Broken`. Future versions of RubyBreaker will support a hybrid of
-the two modules, but it remains as a limitation in the current version.
-
 ### Program Entry Point
 
 In Ruby, as soon as a file is `require`d, the execution of that file begins.
@@ -271,8 +276,8 @@ and returns a `String` object. Note that these types are in lowercase,
 indicating they are objects and not modules or classes themselves.
 
 There are several types that represent an object: nominal, duck, fusion,
-nil, 'any', and block. Each type signature itself represents a method type
-or a method list type (explained below). 
+nil, 'any', 'or', optional, variable-length, and block. Each type signature
+itself represents a method type or a method list type (explained below). 
 
 ### Nominal Type
 
@@ -325,6 +330,20 @@ other type is not a subtype of `?`. This becomes a bit complicated for
 method or block argument types because of their contra-variance
 characteristic. Please refer to the section *Subtyping*.
 
+### Or Type
+
+Any above types can be "or"ed together, using `||`, to represent an object
+that can be either one or the other. It _does_ not represent an object that
+has to be both (which is not supported by RubyBreaker).
+
+### Optional Argument Type and Variable-Length Argument Type
+
+Another useful features of Ruby are the optional argument type and the
+variable-length argument type. The former represents an argument that has a
+default value (and therefore does not have to be provided). The latter
+represents zero or more arguments of the same type. These are denoted by
+suffices, `?` and `*`, respectively.
+
 ### Block Type
 
 One of the Ruby's prominent features is the block argument. It allows
@@ -340,14 +359,6 @@ However, *keep in mind* that RubyBreaker *cannot* automatically document the
 block types due to `yield` being a language construct rather than a method,
 which means it cannot be captured by meta-programming!
 
-### Optional Argument Type and Variable-Length Argument Type
-
-Another useful features of Ruby are the optional argument type and the
-variable-length argument type. The former represents an argument that has a
-default value (and therefore does not have to be provided). The latter
-represents zero or more arguments of the same type. These are denoted by
-suffices, `?` and `*`, respectively.
-
 ### Method Type and Method List Types
 
 Method type is similar to the block type, but it represents an actual method

data/TODO

@@ -1,30 +1,32 @@
-# Dynamic Type Check
+# Dynamic Type Checker
 
-Although type documentation is the main purpose of RubyBreaker, this
-documentation can be used to enforce correct types at runtime. It is often
-helpful to find type errors earlier on during execution to narrow down the
-root cause of the problem.
+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.
 
-# Hybrid of Breakable and Broken
+# More Testing Frameworks
 
-A module or class cannot be both Breakable and Broken. Once it is declared
-to be Broken, it is Broken no matter what. In theory, it is possible to
-selectively auto-document methods that are not yet documented.
+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.
 
-# RDoc Documentation
+# RDoc and YARD Documentation Support
 
-The output of RubyBreaker is an executable Ruby code (for the convenience of
-the author). But, for most Ruby programmers, this documentation may be more
-useful if the output was somehow incorporated with the RDoc output.
+It is cool (and actually useful in a way) to output the type documentation
+in an executable Ruby code. However, for documetation purpose, it would be
+better to have the information in RDoc or YARD format.
 
-# Ruby on Rails Support
+# Core Library Documentation
 
-Duh...
+The core idea behind RubyBreaker is the incremental type documentation,
+starting from the core library to the application level modules.
+Unfortunately, due to technical difficulties, it is not intuitive to
+auto-document the core library code. Thus, it might be necessary to document
+it manually and import this information for upper-level modules.
 
-# PERMANENT LIMITATIONS
+# Ruby on Rails Support
 
-* Block argument cannot be auto-documented. 
-* Manual modification (minimal) of code is required.
-* No parametric polymorphic types are supported. The lack of this type is
-  not a bug but a feature! Polymorphic types are just headaches!
+What more can I say?
 

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/bin/rubybreaker

@@ -13,6 +13,10 @@ module RubyBreaker
 
       opts.banner = "Usage: #{File.basename(__FILE__)} [options] in_file[.rb]" 
 
+      opts.on("--debug", "Run in debug mode") do 
+        OPTIONS[:debug] = true
+      end
+
       opts.on("-f","--io-file FILE","Specify an input/output file") do |f|
         OPTIONS[:output] = f
       end
@@ -45,15 +49,20 @@ module RubyBreaker
     OPTIONS[:mode] = :bin  # indicate that RubyBreaker is being run as a
                            # binary (program).
     
-    puts COPYRIGHT
-    puts
+    if OPTIONS[:verbose]   # Show copyright info only when verbose
+      puts COPYRIGHT 
+      puts
+    end
 
     # There has to be an input file
     if ARGV.length < 1 then 
+      puts "Specify a Ruby program"
       puts option_parser.banner
       exit(1)
     end
 
+    OPTIONS[:file] = ARGV[0]
+
     Main.run()
 
   end

data/lib/rubybreaker.rb

@@ -3,6 +3,7 @@
 # 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_relative "rubybreaker/debug"
 require_relative "rubybreaker/runtime"
 require_relative "rubybreaker/test"
 
@@ -16,12 +17,13 @@ module RubyBreaker
   # Options for RubyBreaker
   OPTIONS = {
     :debug => false,               # in debug mode?
-    :verbose => true,              # in verbose 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)
   }
 
   # This array lists modules/classes that are actually instrumented with a
@@ -48,10 +50,11 @@ module RubyBreaker
     def self.setup()
 
       BREAKABLE.each do |mod|
-        # Avoid already installed module or now Broken module. Remember,
-        # once a module is a declared to be Broken, it wins. Broken modules
-        # cannot be Breakable!
-        unless INSTALLED.include?(mod) || BROKEN.include?(mod)
+
+        # 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
@@ -68,6 +71,7 @@ module RubyBreaker
     # 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
     end
 
@@ -136,9 +140,11 @@ module RubyBreaker
       pp.breakable()
     end
 
-    # This method will generate the output 
+    # This method will generate the output.
     def self.output()
 
+      RubyBreaker.verbose("Generating type documentation")
+
       io_exist = OPTIONS[:io_file] && File.exist?(OPTIONS[:io_file])
 
       str = ""
@@ -162,14 +168,24 @@ module RubyBreaker
         end
         f.puts str
       end
+
+      RubyBreaker.verbose("Done generating type documentation")
     end
 
-    # This method will run the input file
+    # 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()
 
-      # First, take care of the program file.
+      RubyBreaker.setup_logger()
+      RubyBreaker.verbose("Running RubyBreaker")
 
-      argv0 = ARGV[0]
+      # First, take care of the program file.
+      argv0 = OPTIONS[:file]
       prog_file = argv0
       prog_file = File.expand_path(prog_file)
 
@@ -179,7 +195,7 @@ module RubyBreaker
       end 
 
       if !File.exist?(prog_file)
-        puts "ERROR: '#{argv0}' is an invalid file."
+        fatal("#{argv0} is an invalid file.")
         exit(1)
       end
 
@@ -190,6 +206,7 @@ module RubyBreaker
       OPTIONS[:io_file] = File.absolute_path(OPTIONS[:io_file])
 
       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
@@ -201,11 +218,14 @@ module RubyBreaker
       # Finally, require the program file! Let it run! Wheeee!
       eval("require '#{prog_file}'", TOPLEVEL_BINDING)
 
+      RubyBreaker.verbose("Done running the input program")
+
     end
 
   end
 
-  # Just redirecting
+  # This is the manual indicator for the program entry point. It simply
+  # redirects to the monitor setup code.
   def self.monitor()
     Main.setup()
   end

data/lib/rubybreaker/debug.rb

@@ -1,52 +1,8 @@
 #--
-# This file is for debugging RubyBreaker.
+# This file imports all necessary modules for both debugging RubyBreaker
+# internally and debugging the user program.
 
-require "prettyprint"
-require_relative "context"
+require_relative "debug/context"
+require_relative "debug/error"
+require_relative "debug/debug"
 
-module RubyBreaker
-
-  # This module is for internal purpose only - to help ourselves find bugs
-  # and fix them with more informative error messages.
-  module Debug
-
-    OUTPUT = ""
-
-    def self.debug_mode?()
-      return defined?(RubyBreaker::OPTIONS) && RubyBreaker::OPTIONS[:debug]
-    end
-
-    def self.msg(text,context=nil)
-      return unless self.debug_mode?
-      pp = PrettyPrint.new(OUTPUT)
-      msg = "[DEBUG] #{text}"
-      if context
-        context.format_with_msg(pp,msg)
-      else
-        pp.text(msg,79)
-        pp.breakable()
-      end
-      pp.flush
-      puts OUTPUT
-      OUTPUT.replace("")
-    end
-
-    def self.short_msg(text)
-      return unless self.debug_mode?
-      msg = "[DEBUG] #{text}"
-      print msg
-    end
-
-    def self.token(msg)
-      return unless self.debug_mode?
-      print msg
-    end
-
-    def self.feed_line()
-      return unless self.debug_mode?
-      puts ""
-    end
-
-  end
-
-end

data/lib/rubybreaker/debug/debug.rb

@@ -0,0 +1,61 @@
+#-
+# This file contains the debug module which is exclusively used by
+# RubyBreaker internally.
+#
+require "prettyprint"
+require "logger"
+require_relative "context"
+
+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?)
+          then "#{OPTIONS[:file]}.log"
+          else STDOUT
+          end
+    const_set(:LOGGER, Logger.new(out))
+    LOGGER.level = Logger::DEBUG
+  end
+
+  # This method will display verbose message. It is not for debugging but to
+  # inform users of each stage in the analysis.
+  def self.verbose(str, &blk)
+    return unless defined?(OPTIONS) && (OPTIONS[:verbose] || OPTIONS[:debug])
+    if blk
+      msg = yield
+      msg = "#{str} : #{msg}" if str
+    else
+      msg = str
+    end
+    STDOUT.puts msg if OPTIONS[:verbose]
+    LOGGER.info msg if OPTIONS[:debug]
+  end
+
+  # This method is for reporting an error to the user. It will immediately
+  # show the error message but also log it.
+  def self.error(err, level=:error, &blk)
+    msg = err.to_s
+    msg = "#{msg} : #{yield}" if blk
+    STDOUT.puts "[#{level.to_s.upcase}] #{msg}"
+    LOGGER.send(level, msg) if defined?(OPTIONS) && OPTIONS[:debug]
+  end
+
+  # This method logs a non-error (or error) message but with the provided
+  # context.
+  def self.log(str, level=:debug, context=nil, &blk)
+    return unless defined?(OPTIONS) && OPTIONS[:debug]
+    msg = str.to_s
+    msg = "#{msg} : #{yield}" if blk
+    if context
+      output = ""
+      pp = PrettyPrint.new(output)
+      context.format_with_msg(pp,msg)
+      pp.flush
+      msg = output
+    end
+    LOGGER.send(level, msg) 
+  end
+
+end