rubybreaker 0.0.4 → 0.0.5

data/NEWS

@@ -1,3 +1,8 @@
+# VERSION 0.0.5
+* Rake::RubyBreakerTestTask is supported.
+* Manual modification is no longer required if run as a Rake task.
+* Deprecating Breakable and Broken modules. Use breakable() method instead.
+
 # VERSION 0.0.4
 * RSpec is supported.
 * Namespace is recognized in type signatures.

data/NOTES

@@ -0,0 +1,9 @@
+
+# Adding RDoc support:
+* Use :rubybreaker: directive. This is needed.
+* Register it using RDoc::Markup::Preprocess#register,preprocess.
+* Use YAML to store the RubyBreaker result and load it when RDoc is run.
+* The user program would use it in Rakefile.
+
+
+

data/README.md

@@ -5,30 +5,30 @@
 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
-executable Ruby code. It contains type signatures that can be interpreted by
-RubyBreaker Runtime Library and can be used in future documentation of the
-program.
+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.  
 
 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 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. 
+method in selected modules and classes. A type signature is written in the
+RubyBreaker Type Annotation Language which resembles the documentation style
+used in Ruby API Doc. Manual code change is _not_ required if used in
+Rakefile and is kept minimal if otherwise.  Overall, this tool should help
+Ruby programmers document their code more rigorously and effectively.
+
+Current limitations are:
+
+* Auto-documentation of block arguments (inherent)
+* Parametric polymorphic types
+* RDoc or YARD documentation support
 
 To contribute to the project, visit RubyBreaker's
 [GitHub page](http://github.com/rockalizer/rubybreaker) and 
 [RubyGems page](http://rubygems.org/gems/rubybreaker). RubyBreaker RDoc can
 be found in [here](rdoc/index.html).
 
-## Limitations
-
-* Block argument cannot be auto-documented. (Inherent)
-* Manual modification (minimal) of code is required.
-* Parametric polymorphic types are not supported. 
-
 ## Requirements
 
 Ruby 1.9.x and TreeTop 1.x
@@ -39,15 +39,10 @@ following URL: [TreeTop](http://treetop.rubyforge.org/)
 
 ## Installation
 
-It is as simple as running the following:
+It is as simple as running the following command:
 
     $ gem install rubybreaker
 
-You probably want to test out your installation by running
-`rake test` in your RubyBreaker directory:
-
-    $ rake test
-
 * * *
 
 # Tutorial
@@ -57,213 +52,135 @@ Type Annotation Language, and the RubyBreaker Type System.
 
 ## Usage
 
-There are two ways to use RubyBreaker:
-
-    $ rubybreaker prog.rb
-   
-Or, use it as a Ruby library and just run the program on Ruby.
+RubyBreaker takes advantage of test cases that already come with the source
+program.  It is recommended that RubyBreaker is run as a Rake task, which
+requires a minimum code change in the Rakefile and no code change in the
+source program.  If not used as a Rake task, it requires a minimum code
+change in each test case or the source program but should not affect the
+development process much. Let's briefly see how RubyBreaker can be run
+directly as a command-line program to understand the general concept of the
+tool. We will explain how to use RubyBreaker in a Rakefile later.
 
-    $ ruby prog.rb
+    $ rubybreaker -v prog.rb
 
-Both methods require manual modification of the code, but the former will
-generate the output into a separate `.rubybreaker` file whereas the latter
-will display the output on the screen. The former will also automatically
-import the `.rubybreaker` file for the user program of which the output is
-appended at the end. Consequently, this output/input file will grow as more
-analysis is done on the program. 
+This runs RubyBreaker in verbose mode on `prog.rb`. Note that RubyBreaker
+will actually run `prog.rb` (by simply `require`ing the program file).
+Somewhere in the program, there has to be a _program entry point_ to
+indicate where the _monitoring_ of objects starts. Let's assume `prog.rb`
+as the following:
 
-For example, let us assume `prog.rb` as the following:
-
-    require "rubybreaker"
+    require "rubybreaker"  # required if using "ruby" instead
     class A
-      include RubyBreaker::Breakable
       def foo(x)
         x.to_s
       end
     end
     class B
-      # include RubyBreaker::Breakable
       def bar(y,z)
         y.foo(z)
       end
     end
-    RubyBreaker.monitor()
+    RubyBreaker.run(A, B)
     A.new.foo(1)
 
-Do not worry about other parts of the code for now. This example is to show
-how `foo` method is *typed* by RubyBreaker.  After running `rubybreaker
-prog.rb`, the following output will be generated and saved into
-`prog.rubybreaker`.
+This example will show how `A#foo` method is given a type by RubyBreaker.
+After running `rubybreaker -v prog.rb`, the following output will be
+generated and saved into `prog.rubybreaker.rb`.
 
+    # This file is auto-generated by RubyBreaker
     require "rubybreaker"
     class A
-      include RubyBreaker::Broken
       typesig("foo(fixnum[to_s]) -> string")
     end
 
-Now, assume that the last line of `prog.rb` is changed to
-`B.new.bar(A.new,1)` and the `include` command in class `B` is uncommented.
-The subsequent analysis will generate the following result:
+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 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:
 
-    # This is auto-generated by RubyBreaker
+    # This file is auto-generated by RubyBreaker
     require "rubybreaker"
     class A
-      include RubyBreaker::Broken
       typesig("foo(fixnum[to_s]) -> string")
     end
     class B
-      include RubyBreaker::Broken
       typesig("bar(a[foo], fixnum[to_s]) -> string")
     end
 
-RubyBreaker is designed to gather type information based on the actual
-execution of a program. This means the program should be equipped with
-test suites that cover a reasonable number of program paths for accurate
-results. Additionally, RubyBreaker assumes that test runs are correct
-and the program behaves correctly (for the test runs) as intended by
-the programmer. This assumption is not a strong requirement, but is
-necessary to obtain precise type information. 
-
-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. (If
-you are using RSpec, there is no need for this change.)
-
-### Breakable and Broken
-
-In order to indicate modules and classes that already have type information
-or to designate those that need to be auto-documented, the user must be
-familiar with the two most important modules of RubyBreaker--`Breakable` and
-`Broken`. The former refers to a module (or a class) that needs dynamic
-instrumentation and monitoring for getting type information. The latter
-refers to a module that have type information already documented in type
-signature form.
-
-For example, consider the following Ruby code:
+Keep in mind that RubyBreaker is designed to gather type information based
+on the _actual_ execution of the source program. This means the program
+should be equipped with test cases that have a reasonable program path
+coverage.  Additionally, RubyBreaker assumes that test runs are correct and
+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. 
 
-    require "rubybreaker"
-    class A
-      include RubyBreaker::Breakable
-      def foo(x)
-        x.to_s
-      end
-    end
+### Using Ruby Unit Testing Framework
 
-By including `Breakable`, class `A` is subject to dynamic instrumentation
-and monitoring. On the other hand, the following class is a `Broken` module.
-(Yes, like a crazy wild horse that has been _broken_!)
+Instead of manually inserting the entry point indicator into the 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.
 
-    require "rubybreaker"
-    class B
-      include RubyBreaker::Broken
-      typesig("bar(fixnum[to_s]) -> string")
-      def foo(x)
-        x.to_s
+    require "test/unit"
+    require "rubybreaker" # This should come after test/unit.
+    class TestClassA < Test::Unit::TestCase
+      def setup()
+         RubyBreaker.breakable(Class1, Class2, ...)
+         ...
       end
+      # ...tests!...
     end
 
-This tells RubyBreaker that class `B` has type information in place, and
-therefore, it will use the information for analyzing `Breakable` modules
-elsewhere (if applicable). In this example, a method `foo` has a type
-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.
+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`.
 
-### 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
+### Using RSpec
 
-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.
+The requirement is same for RSpec but use `before` instead of `setup` to
+specify which modules and classes to "break".
 
+    require "rspec"
     require "rubybreaker"
-    class A
-      include RubyBreaker::Breakable
-      class << self
-        def foo(x); x.to_s end
-      end
-    end
-    class B
-      include RubyBreaker::Broken
-      class << self
-        typesig("foo(fixnum[to_s]) -> string")
-        def foo(x); x.to_s end
-      end
-    end
-
-### Program Entry Point
-
-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. 
-
-Indicating the program entry point is simply done by inserting the following
-line at the code (assuming "`require 'rubybreaker'`" is already placed at
-the top of the file):
-
-    RubyBreaker.monitor()
-
-It basically tells RubyBreaker to start monitoring. What really happens at
-this point is that all `Breakable` modules are dynamically instrumented so
-that they are ready to be monitored. Any execution after this point will
-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 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 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
-recommended way of using RubyBreaker, especially for a long term program
-maintainability. But no worries! This method is as simple as the previous
-one.
-
-    require "rubybreaker"
-    require "test/unit"
-    class TestClassA < Test::Unit::TestCase
-      include RubyBreaker::TestCase
+    describe "TestClassA Test"
+      before { RubyBreaker.breakable(Class1, Class2, ...) }
+      ...
       # ...tests!...
     end
 
-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.
-
-    require "rubybreaker"
-    require "test/unit"
-    class A
-      include RubyBreaker::Breakable
-    end
-    class TestClassA < Test::Unit::TestCase
-       ...
+### Using Rakefile
+
+By running RubyBreaker along with the Rakefile, you can avoid modifying the
+source program at all. (You no longer need to import `rubybreaker` in the
+test cases neither.) Therefore, this is the recommended way to use
+RubyBreaker.  The following code snippet describes how it can be done:
+
+    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.breakable = ["Class1", "Class2", ...]  # specify what to monitor
     end
 
-### Using RSpec
+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
+`breakable` 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). 
 
-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._
+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.
 
 ## Type Annotation
 
@@ -423,7 +340,7 @@ subsequent "promotions").
 ## Type System
 
 RubyBreaker comes with its own type system to auto-document the type
-information. Each method in a `Breakable` module is dynamically instrumented
+information. Each method in a "breakable" module is dynamically instrumented
 to be monitored during runtime. This monitoring code observes the types of
 the arguments, block, and return value of each method. Once this information
 is gathered, RubyBreaker will compare it to the information gathered so far.

data/Rakefile

@@ -5,6 +5,7 @@ require "rake"
 require "rake/testtask"
 require "rdoc/task"
 require "rake/clean"
+require_relative "lib/rubybreaker/task"
 
 begin 
   require "rdiscount"   # used to generate the doc html page
@@ -21,15 +22,21 @@ end
 # Use rake/clean to remove generated files
 CLEAN.concat(FileList["webpage/rdoc", 
                       "rubybreaker-*.gem",
-                      "webpage/index.html", 
-                      "lib/rubybreaker/type/type_grammar.rb"
-                     ])
+                      "webpage/index.html",
+                      "*.rubybreaker.rb",
+                      "lib/rubybreaker/type/type_grammar.rb"])
 
 # If no task specified, do test
-task :default => [:test]
+task :default => [:test, :testtask_test]
 
 desc "Do all"
-task :all => [:parser, :test, :rspec, :rdoc, :webpage, :gem] do |t|
+task :all => [:parser, 
+              :test, 
+              :testtask_test,
+              :rspec, 
+              :rdoc, 
+              :webpage, 
+              :gem] do |t|
 end
 
 desc "Generate gemspec"
@@ -40,7 +47,7 @@ end
 Rake::RDocTask.new do |rd|
   rd.rdoc_dir = "#{File.dirname(__FILE__)}/webpage/rdoc"
   rd.rdoc_files.include("lib/**/*.rb")
-  rd.rdoc_files.exclude("lib/rubybreaker/rubylib/*.rb", "lib/rubybreaker/type/type_grammar.rb")
+  rd.rdoc_files.exclude("lib/rubybreaker/type/type_grammar.rb")
 end
 
 desc "Generate the webpage"
@@ -69,9 +76,17 @@ Rake::TestTask.new(:"test") do |t|
   t.libs << "lib"
   test_files = FileList["test/ts_*.rb"]
   test_files.exclude("test/ts_rspec.rb")
+  test_files.exclude("test/ts_testtask.rb")
   t.test_files = test_files
 end
 
+desc "Run rubybreaker testtask test"
+Rake::RubyBreakerTestTask.new(:"testtask_test") do |t|
+  t.libs << "lib" << "test/tc_testtask/sample.rb"
+  t.test_files = ["test/testtask/tc_testtask.rb"]
+  t.breakable = ["SampleClassA"]
+end
+
 if defined?(RSpec)
   desc "Run RSpec test"
   RSpec::Core::RakeTask.new(:rspec) do |t|

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/bin/rubybreaker

@@ -1,72 +1,56 @@
 #!/usr/bin/env ruby
-require "optparse"
-
 require_relative "../lib/rubybreaker"
 
 module RubyBreaker
 
-  # This method is the main method for running RubyBreaker as a shell
-  # program.
-  def self.main()
-
-    option_parser = OptionParser.new do |opts|
-
-      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
-
-      opts.on("-s","--[no-]stdout","Show output on the screen") do |b|
-        OPTIONS[:stdout] = b
-      end
-
-      opts.on("-a", "--[no-]append", "Append output to the input file") do |b|
-        OPTIONS[:append] = b
-      end
+  # This method shows the banner and exits with code 1.
+  def self.show_banner_and_exit()
+    puts OPTION_PARSER.banner
+    exit(1)
+  end
 
-      opts.on("-v","--verbose","Show messages in detail") do
-        OPTIONS[:verbose] = true
-      end
+  # This method prepares shell mode execution of RubyBreaker.
+  def self.main()
+    RubyBreaker.setup_logger()
+    RubyBreaker.verbose("Running RubyBreaker in shell mode")
 
-      opts.on("--[no-]rubylib", "Use Core Ruby Library documentation") do |b|
-        OPTIONS[:rubylib] = b
-      end
+    # parse the command-line arguments
+    OPTION_PARSER.parse!   
 
-      opts.on("-h","--help","Show this help text") do 
-        puts opts
-        exit
-      end
+    # Show copyright info if verbose
+    puts COPYRIGHT if OPTIONS[:verbose]     
 
-    end
+    # Quit if there is program specified.
+    self.show_banner_and_exit() if ARGV.length != 1
 
-    option_parser.parse!
+    # Get the specified program.
+    prog = ARGV[0]
+    prog_file = File.expand_path(prog)
 
-    OPTIONS[:mode] = :bin  # indicate that RubyBreaker is being run as a
-                           # binary (program).
-    
-    if OPTIONS[:verbose]   # Show copyright info only when verbose
-      puts COPYRIGHT 
-      puts
-    end
+    # 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 
 
-    # There has to be an input file
-    if ARGV.length < 1 then 
-      puts option_parser.banner
+    # Quit the specified program does not exist.
+    if !File.exist?(prog_file)
+      fatal("#{ARGV[0]} is an invalid file.")
       exit(1)
     end
 
-    OPTIONS[:file] = ARGV[0]
+    # Remember the program path for later use
+    OPTIONS[:prog_file] = prog_file
 
-    Main.run()
+    # Run the program file!
+    self.verbose("Running #{prog}")
+    eval "require '#{prog_file}'", TOPLEVEL_BINDING
+    self.verbose("Done running #{prog}")
 
+    # Keep in mind that the source program must specify the entry
+    # point--using RubyBreaker.run()--in order to observe the type
+    # information.
   end
 
 end
 
 RubyBreaker.main()
-

data/lib/rubybreaker/debug/debug.rb

@@ -8,6 +8,12 @@ require_relative "context"
 
 module RubyBreaker
 
+  # This method returns true if the logger is already created and false
+  # otherwise.
+  def self.defined_logger?()
+    return defined?(LOGGER)
+  end
+
   # This sets up the logger for debugging RubyBreaker
   def self.setup_logger #:nodoc:
     return if defined?(LOGGER)

data/lib/rubybreaker/doc/rdoc.rb

@@ -0,0 +1,37 @@
+require "yaml"
+require_relative "../type"
+
+module RubyBreaker
+
+  # This module has functionalities that are necessary for supporting RDoc
+  # output
+  module RDocSupport
+
+    include TypeDefs
+
+    # This array keeps track of modules/classes whose type information is
+    # documented.
+    DOCUMENTED = {} # module => method map
+
+    # This method exports the RubyBreaker output into a yaml file.
+    def self.export_to_yaml(yaml_file, breakable_modules, broken_modules)
+      hash = {
+        breakable: breakable_modules,
+        broken: broken_modules
+      }
+      File.open(yaml_file, "w") do |f|
+        f.puts YAML.dump(hash)
+      end
+    end
+
+    # This method imports the RubyBreaker output from a yaml file.
+    def self.import_from_yaml(yaml_file)
+      File.open(yaml_file, "r") do |f|
+        raw = f.read
+        hash = YAML.to_hash(raw)
+      end
+    end
+
+  end
+
+end

data/lib/rubybreaker/doc.rb

@@ -0,0 +1,3 @@
+
+require_relative "doc/rdoc"
+