rubybreaker 0.0.1 → 0.0.2

data/NEWS

@@ -0,0 +1,48 @@
+# 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
+
+## 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
+

data/README.md

@@ -18,6 +18,11 @@ document their code more rigorously and effectively.  Currently, manual
 modification of the user program is required to run RubyBreaker, but this is
 kept minimal. 
 
+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
 
 * It only works on toy Ruby programs so far :)
@@ -166,11 +171,33 @@ 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.
 
-Currently, both `Breakable` and `Broken` only support instance methods.
-Furthermore, class and module methods can neither be monitored nor used for
-analysis. It is important to keep in mind that `Broken` module always wins.
-In other words, if a module is declared as both `Broken` and `Breakable`, it
-is treated as `Broken`.
+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`,
+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.
+
+    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
+
+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
 
@@ -296,7 +323,7 @@ it should be only used for an object that requires an arbitrary yet most
 specific type--that is, `?` is a subtype of any other type, but any
 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 kefer to the section *Subtyping*.
+characteristic. Please refer to the section *Subtyping*.
 
 ### Block Type
 
@@ -368,25 +395,34 @@ subsequent "promotions").
 
 ## Type System
 
-RubyBreaker comes with its own type system that is used to document type
-information. This section describes how RubyBreaker determines which type(s)
-to document. *More documentation coming soon...*
-
-### Subtyping
-
-*Documentation coming soon...*
-
-### Subtyping vs. Subclassing
-
-*Documentation coming soon...*
+RubyBreaker comes with its own type system to auto-document the type
+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.
+If these two types are "compatiable", RubyBreaker will choose more general
+type of the two. Otherwise, RubyBreaker will use the method list type to
+accommodate two "incompatible" types.
+
+### Subtyping and Subclassing
+
+RubyBreaker uses subtyping to choose one from the two "compatible" types.
+Two types are "compatible" if one is subtype of another. This means that the
+_subtype_ can be represented using the _supertype_ instead. This is why
+RubyBrekaer chooses the latter to document both types. RubyBreaker relies on
+subclassing of Ruby to determine a subtyping relationship between two types.
+For example, `Fixnum` is considered to be subtype of `Numeric` since the
+former is subclass of the latter. (Strictly speaking, `Fixnum` is not really
+subtype of `Numeric` because some methods are overriden in `Fixnum` with
+method types that are not subtype of the counterparts in `Numeric`. But,
+RubyBreaker is lenient and considers them compatible--that is, `Numeric` can
+represent any `Fixnum`.
 
 ### Pluggable Type System (Advanced)
 
 Yes, RubyBreaker was designed with the replaceable type system in mind. In
 other words, anyone can write his own type system and plug it into
-RubyBreaker.
-
-*Documentation coming soon...*
+RubyBreaker. *Technical documentation coming soon...*
 
 * * *
 

data/Rakefile

@@ -4,6 +4,7 @@
 require "rake"
 require "rake/testtask"
 require "rdoc/task"
+require "rake/clean"
 
 begin 
   require "rdiscount"   # used to generate the doc html page
@@ -11,6 +12,13 @@ rescue LoadError => e
   puts "[WARNING] No rdiscount is installed."
 end
 
+# Use rake/clean to remove generated files
+CLEAN.concat(FileList["webpage/rdoc", 
+                      "rubybreaker-*.gem",
+                      "webpage/index.html", 
+                      "lib/rubybreaker/type/type_grammar.rb"
+                     ])
+
 # If no task specified, do test
 task :default => [:test]
 
@@ -18,28 +26,17 @@ desc "Do all"
 task :all => [:parser, :test, :rdoc, :webpage, :gem] do |t|
 end
 
-desc "Clean"
-task :clean do |t|
-  sh 'rm -r -f html'
-  sh 'rm webpage/index.html'
-  sh 'rm lib/rubybreaker/type/type_grammar.rb'
-end
-
 desc "Generate gemspec"
 task :gem do |t|
   sh "gem build rubybreaker.gemspec"
 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")
 end
 
-# desc "Generate RDoc"
-# task :doc do |t|
-#   sh "rdoc -x lib/rubybreaker/rubylib -x lib/rubybreaker/type/type_grammar lib"
-# end
-
 desc "Generate the webpage"
 task :webpage do |t|
   break unless defined?(RDiscount)
@@ -47,28 +44,6 @@ task :webpage do |t|
   readme_md = "#{dir}/README.md"
   output = "#{dir}/webpage/index.html"
   body = RDiscount.new(File.read(readme_md)).to_html
-#   header = <<-EOS
-# <html>
-# <head>
-#   <title>RubyBreaker</title>
-#   <LINK REL=StyleSheet HREF="rubybreaker.css" TYPE="text/css">
-# 	<script type="text/javascript" src="generated_toc.js">  </script>
-# </head>
-# <body onLoad="createTOC()">
-#   <center>
-# 	<div id="content">
-# 		<div id="logo">
-# 			<img src="images/logo.png" border="0">
-# 		</div>
-# 		<hr />
-# 		<div id="generated-toc"></div>
-#   EOS
-#  footer = <<-EOS
-# 	</div>
-#   </center>
-# </body>
-# </html>
-#   EOS
   header = File.read("#{dir}/webpage/header.html")
   footer = File.read("#{dir}/webpage/footer.html")
   html = header + body + footer

data/TODO

@@ -1,13 +1,3 @@
-# Variable-length Argument Type
-
-Currently, the variable-length argument type cannot be auto-documented.
-This can be done by looking at the method arity and initializes the method
-type to have a variable-length argument type for the last argument. 
-
-# Module Methods and Class Methods
-
-RubyBreaker only monitors instance methods at the moment.
-
 # Dynamic Type Check
 
 Although type documentation is the main purpose of RubyBreaker, this
@@ -21,6 +11,16 @@ 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.
 
+# RDoc Documentation
+
+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.
+
+# Ruby on Rails Support
+
+Duh...
+
 # PERMANENT LIMITATIONS
 
 * Block argument cannot be auto-documented. 

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/bin/gen_stub_rubylib

@@ -3,55 +3,54 @@
 
 require "prettyprint"
 
-BLACKLIST = [:Config, :Class, :Module]
+BLACKLIST = [:Config, :Class, :Module, :BasicObject]
 
 def get_const(const_name, binding, visited)
-	return false if BLACKLIST.include?(:"#{const_name}")
-	validated = true
-	begin 
-		const = eval(const_name.to_s, binding)
-	rescue
-		validated = false
-	end
-	return nil unless const.kind_of?(Module) && !visited.include?(const)
-	return const
+  return false if BLACKLIST.include?(:"#{const_name}")
+  validated = true
+  begin 
+    const = eval(const_name.to_s, binding)
+  rescue
+    validated = false
+  end
+  return nil unless const.kind_of?(Module) && !visited.include?(const)
+  return const
 end
 
 def visit(pp, mod, binding, visited=[])
-	visited << mod
-	keyword = mod.kind_of?(Class) ? "class" : "module"
-	new_binding = eval("#{keyword} #{mod.name}; binding() end", binding)
+  visited << mod
+  keyword = mod.kind_of?(Class) ? "class" : "module"
+  new_binding = eval("#{keyword} #{mod.name}; binding() end", binding)
   pp.breakable()
-	pp.text("#{keyword} #{mod.name}")
-	pp.group(2) do 
+  pp.text("#{keyword} #{mod.name} #:nodoc:", 80)
+  pp.group(2) do 
     pp.breakable(";")
-		pp.text("include RubyBreaker::Broken")
-		inst_meths = mod.instance_methods(false).sort
-		inst_meths.each {|meth|
+    pp.text("include RubyBreaker::Broken", 80)
+    inst_meths = mod.instance_methods(false).sort
+    inst_meths.each {|meth|
       pp.breakable(";")
-			pp.text("typesig(\"#{meth}(?*) -> basic_object\")")
-		}
-		consts = mod.constants.sort
-		consts.each do |const_name|
-			const = get_const(const_name, new_binding, visited)
-			next unless const
+      pp.text("typesig(\"#{meth}(?*) -> basic_object\")")
+    }
+    consts = mod.constants.sort
+    consts.each do |const_name|
+      const = get_const(const_name, new_binding, visited)
+      next unless const
       pp.breakable()
-			visit(pp, const, new_binding, visited)
-		end
-	end
-	pp.breakable()
-	pp.text("end # of #{mod.name}")
-	pp.breakable(";")
+      visit(pp, const, new_binding, visited)
+    end
+  end
+  pp.breakable()
+  pp.text("end # of #{mod.name}", 80)
 end
 
 def visit_toplevel(pp,visited=[])
-	visited << Object
-	Object.constants.sort.each do |const_name|
-	  const = get_const(const_name, TOPLEVEL_BINDING, visited)
-		next unless const
+  visited << Object
+  Object.constants.sort.each do |const_name|
+    const = get_const(const_name, TOPLEVEL_BINDING, visited)
+    next unless const
     pp.breakable()
-		visit(pp, const, TOPLEVEL_BINDING, visited)
-	end
+    visit(pp, const, TOPLEVEL_BINDING, visited)
+  end
 end
 
 str = ""

data/bin/rubybreaker

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 require "optparse"
 
-dir = File.dirname(__FILE__)
-require "#{dir}/../lib/rubybreaker"
+require_relative "../lib/rubybreaker"
 
 module RubyBreaker
 
@@ -63,5 +62,3 @@ end
 
 RubyBreaker.main()
 
-
-

data/lib/rubybreaker/debug.rb

@@ -12,8 +12,12 @@ module RubyBreaker
 
     OUTPUT = ""
 
+    def self.debug_mode?()
+      return defined?(RubyBreaker::OPTIONS) && RubyBreaker::OPTIONS[:debug]
+    end
+
     def self.msg(text,context=nil)
-      return unless RubyBreaker::OPTIONS[:debug]
+      return unless self.debug_mode?
       pp = PrettyPrint.new(OUTPUT)
       msg = "[DEBUG] #{text}"
       if context
@@ -28,18 +32,18 @@ module RubyBreaker
     end
 
     def self.short_msg(text)
-      return unless RubyBreaker::OPTIONS[:debug]
+      return unless self.debug_mode?
       msg = "[DEBUG] #{text}"
       print msg
     end
 
     def self.token(msg)
-      return unless RubyBreaker::OPTIONS[:debug]
+      return unless self.debug_mode?
       print msg
     end
 
     def self.feed_line()
-      return unless RubyBreaker::OPTIONS[:debug]
+      return unless self.debug_mode?
       puts ""
     end