RubyGems - rubybreaker - Versions diffs - 0.0.5 → 0.0.6 - Mend

rubybreaker 0.0.5 → 0.0.6

Files changed (90) hide show

data/ABOUT.md +20 -0
data/NEWS +5 -0
data/README.md +16 -352
data/Rakefile +30 -16
data/TOPICS.md +55 -0
data/TUTORIAL.md +291 -0
data/VERSION +1 -1
data/bin/rubybreaker +32 -14
data/lib/rubybreaker/runtime/monitor.rb +1 -1
data/lib/rubybreaker/runtime.rb +41 -21
data/lib/rubybreaker/task.rb +15 -9
data/lib/rubybreaker/test/rspec.rb +3 -3
data/lib/rubybreaker/test/testcase.rb +3 -3
data/lib/rubybreaker.rb +31 -16
data/test/integrated/{tc_both_broken_breakable.rb → tc_both_documented_and_undocumented.rb} +3 -4
data/test/integrated/tc_class_methods.rb +1 -1
data/test/integrated/tc_inherit_broken.rb +1 -1
data/test/integrated/tc_method_missing.rb +1 -1
data/test/integrated/tc_namespace.rb +1 -1
data/test/integrated/tc_simple1.rb +1 -1
data/test/testtask/tc_testtask.rb +2 -2
data/test/ts_integrated.rb +1 -1
data/test/ts_rspec.rb +1 -1
data/webpage/about.html +50 -0
data/webpage/footer.html +6 -1
data/webpage/header.html +9 -3
data/webpage/images/logo.png +0 -0
data/webpage/images/title.png +0 -0
data/webpage/index.html +31 -367
data/webpage/rdoc/Object.html +3 -103
data/webpage/rdoc/Rake/RubyBreakerTestTask.html +80 -18
data/webpage/rdoc/Rake.html +3 -7
data/webpage/rdoc/RubyBreaker/Breakable.html +4 -8
data/webpage/rdoc/RubyBreaker/Broken.html +4 -8
data/webpage/rdoc/RubyBreaker/Context.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/InternalError.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/InvalidSubtypeCheck.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/InvalidTypeConstruction.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/SubtypeFailure.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/TypeError.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors/UserError.html +3 -7
data/webpage/rdoc/RubyBreaker/Errors.html +3 -7
data/webpage/rdoc/RubyBreaker/ObjectPosition.html +3 -7
data/webpage/rdoc/RubyBreaker/Position.html +3 -7
data/webpage/rdoc/RubyBreaker/RDocSupport.html +3 -7
data/webpage/rdoc/RubyBreaker/RubyTypeUtils.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/Inspector.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/MethodInfo.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/Monitor.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/MonitorInstaller.html +10 -14
data/webpage/rdoc/RubyBreaker/Runtime/MonitorSwitch.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/MonitorUtils.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/ObjectWrapper.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/Pluggable.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/TypeSigParser.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/TypeSigUnparser.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime/TypeSystem.html +3 -7
data/webpage/rdoc/RubyBreaker/Runtime.html +42 -39
data/webpage/rdoc/RubyBreaker/TypeComparer.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/AnyType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/BlockType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/DuckType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/FusionType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/MethodListType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/MethodType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/NilType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/NominalType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/OptionalType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/OrType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/SelfType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/Type.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs/VarLengthType.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeDefs.html +3 -7
data/webpage/rdoc/RubyBreaker/TypeUnparser.html +3 -7
data/webpage/rdoc/RubyBreaker/Typing.html +3 -7
data/webpage/rdoc/RubyBreaker/Util.html +3 -7
data/webpage/rdoc/RubyBreaker.html +48 -15
data/webpage/rdoc/Test/Unit.html +3 -7
data/webpage/rdoc/Test.html +3 -7
data/webpage/rdoc/created.rid +18 -17
data/webpage/rdoc/index.html +3 -7
data/webpage/rdoc/js/search_index.js +1 -1
data/webpage/rdoc/table_of_contents.html +28 -36
data/webpage/rubybreaker.css +8 -6
data/webpage/topics.html +85 -0
data/webpage/tutorial.html +331 -0
metadata +14 -8
data/lib/rubybreaker/doc.rb +0 -3
data/webpage/rdoc/Kernel.html +0 -286
data/webpage/rdoc/Test/Unit/TestCase.html +0 -309

data/webpage/tutorial.html ADDED Viewed

@@ -0,0 +1,331 @@
+<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/title.png" border="0">
+    </div>
+		<center>
+			<a href="index.html">Introduction</a> |
+			<a href="tutorial.html">Tutorial</a> |
+			<a href="topics.html">Advanced Topics</a> |
+			<a href="about.html">About</a>
+		</center>
+		<hr />
+		<!--<div id="generated-toc"></div>-->
+<h1>Tutorial</h1>
+<p>This tutorial will describe the basic usage of the tool, the RubyBreaker
+Type Annotation Language, and the RubyBreaker Type System.</p>
+<h2>Usage</h2>
+<p>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
+does require a minimum change in the Rakefile (but no code change in the
+source program) but is better for a long-term maintenance. Regardless of the
+mode you choose to run, no source code change is required.</p>
+<p>Let us briefly see how RubyBreaker can be run directly as a command-line
+program to understand the overall concept of the tool. We will explain how
+to use RubyBreaker in a Rakefile later.</p>
+<pre><code>$ rubybreaker -v -s -l lib.rb -b A,B prog.rb
+</code></pre>
+<p>The above command runs RubyBreaker in verbose mode (<code>-v</code>) and will display
+the output on the screen (<code>-s</code>). Before RubyBreaker runs <code>prog.rb</code>, it will
+import (<code>-l</code>) <code>lib.rb</code> and instrument (<code>-b</code>) classes <code>A</code> and <code>B</code>.
+Here is <code>lib.rb</code>:</p>
+<pre><code>class A
+  def foo(x)
+    x.to_s
+  end
+end
+class B
+  def bar(y,z)
+    y.foo(z)
+  end
+end
+</code></pre>
+<p>And, <code>prog.rb</code> simply imports the library file and executes it:</p>
+<pre><code>require "lib"
+A.new.foo(1)
+</code></pre>
+<p>This example will show how <code>A#foo</code> method is given a type by RubyBreaker.
+After running the command shown above, the following output will be
+generated and displayed on the screen:</p>
+<pre><code>class A
+  typesig("foo(fixnum[to_s]) -&gt; string")
+end
+</code></pre>
+<p>Here, the <code>typesig</code> method call registers <code>foo</code> as a method type that takes
+an object that has <code>Fixnum#to_s</code> method and returns a <code>String</code>. This
+method is made available simply by importing <code>rubybreaker</code>.  Now, assume
+that an additional code, <code>B.new.bar(A.new,1)</code>, is added at the end of
+<code>prog.rb</code>. The subsequent run will generate the following result:</p>
+<pre><code>class A
+  typesig("foo(fixnum[to_s]) -&gt; string")
+end
+class B
+  typesig("bar(a[foo], fixnum[to_s]) -&gt; string")
+end
+</code></pre>
+<p>Keep in mind that RubyBreaker is designed to gather type information based
+on the <em>actual</em> 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.</p>
+<h3>Using Ruby Unit Testing Framework</h3>
+<p>Instead of manually inserting the entry point indicator in the source
+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.</p>
+<pre><code>require "test/unit"
+require "rubybreaker" # This should come after test/unit.
+class TestClassA &lt; Test::Unit::TestCase
+  def setup()
+     RubyBreaker.break(Class1, Class2, ...)
+     ...
+  end
+  # ...tests!...
+end
+</code></pre>
+<p>That's it! The only requirements are to indicate to RubyBreaker which modules
+and classes to "break" and to place <code>require rubybreaker</code> <em>after</em>
+<code>require test/unit</code>.</p>
+<h3>Using RSpec</h3>
+<p>The requirement is same for RSpec but use <code>before</code> instead of <code>setup</code> to
+specify which modules and classes to "break".</p>
+<pre><code>require "rspec"
+require "rubybreaker"
+describe "TestClassA Test"
+  before { RubyBreaker.break(Class1, Class2, ...) }
+  ...
+  # ...tests!...
+end
+</code></pre>
+<h3>Using Rakefile</h3>
+<p>By running RubyBreaker along with the Rakefile, you can avoid modifying the
+source program at all. (You no longer need to import <code>rubybreaker</code> in the
+test cases neither.) Therefore, this is the recommended way to use
+RubyBreaker.  The following code snippet describes how it can be done:</p>
+<pre><code>require "rubybreaker/task"
+...
+desc "Run RubyBreaker"
+Rake::RubyBreakerTestTask.new(:"rubybreaker") do |t|
+  t.libs &lt;&lt; "lib"
+  t.test_files = ["test/foo/tc_foo1.rb"]
+  # ...Other test task options..
+  t.rubybreaker_opts &lt;&lt; "-v"               # run in verbose mode
+  t.break = ["Class1", "Class2", ...]  # specify what to monitor
+end
+</code></pre>
+<p>Note that <code>RubyBrakerTestTask</code> can simply replace your <code>TestTask</code> 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
+<code>rubybreaker_opts</code> which is RubyBreaker's command-line options and
+<code>break</code> which specifies which modules and classes to monitor.  Since
+<code>Class1</code> and <code>Class2</code> are not <em>recognized</em> by this Rakefile, you must use
+string literals to specify modules and classes (and with full namespace).</p>
+<p>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.</p>
+<h2>Type Annotation</h2>
+<p>The annotation language used in RubyBreaker resembles the method
+documentation used by Ruby Core Library Doc. Each type signature
+defines a method type using the name, argument types, block type, and return
+type. But, let us consider a simple case where there is one argument type
+and a return type.</p>
+<pre><code>class A
+  ...
+  typesig("foo(fixnum) -&gt; string")
+end
+</code></pre>
+<p>In RubyBreaker, a type signature is recognized by the meta-class level
+method <code>typesig</code> which takes a string as an argument.  This string is the
+actual type signature written in the Ruby Type Annotation Language. This
+language is designed to reflect the common documentation practice used by
+Ruby Core Library Doc. It starts with the name of the method. In the
+above example, <code>foo</code> is currently being given a type. The rest of the
+signature takes a typical method type symbol, <code>(x) -&gt; y</code> where <code>x</code> is the
+argument type and <code>y</code> is the return type. In the example shown above, the
+method takes a <code>Fixnum</code> object and returns a <code>String</code> object. Note that
+these types are in lowercase, indicating they are objects and not modules or
+classes themselves.</p>
+<p>There are several types that represent an object: nominal, duck, fusion,
+nil, 'any', 'or', optional, variable-length, and block. Each type signature
+itself represents a method type or a method list type (explained below).</p>
+<h3>Nominal Type</h3>
+<p>This is the simplest and most intuitive way to represent an object. For
+instance, <code>fixnum</code> is an object of type <code>Fixnum</code>. Use lower-case letters and
+underscores instead of <em>camelized</em> name. <code>MyClass</code>, for example would be
+<code>my_class</code> in RubyBreaker type signatures. There is no particular
+reason for this convention other than it is the common practice used in
+RubyDoc. Use <code>/</code> to indicate the namespace delimiter <code>::</code>. For example,
+<code>NamspaceA::ClassB</code> would be represented by <code>namespace_a/class_b</code> in
+a RubyBreaker type signature.</p>
+<h3>Self Type</h3>
+<p>This type is similar to the nominal type but is referring to the current
+object--that is, the receiver of the method being typed. RubyBreaker will
+auto-document the return type as a self type if the return value is the same
+as the receiver of that call. It is also recommended to use this type over
+a nominal type (if the return value is <code>self</code>) since it depicts more
+precise return type.</p>
+<h3>Duck Type</h3>
+<p>This type is inspired by the Ruby Language's duck typing, <em>"if it
+walks like a duck and quacks like a duck, it must be a duck."</em> Using this
+type, an object can be represented simply by a list of method names. For
+example <code>[walks, quacks]</code> is an object that has <code>walks</code> and <code>quacks</code>
+methods. Note that these method names do <em>not</em> reveal any type
+information for themselves.</p>
+<h3>Fusion Type</h3>
+<p>Duck type is very flexible but can be too lenient when trying to restrict
+the type of an object. RubyBreaker provides a type called <em>the fusion type</em>
+which lists method names but with respect to a nominal type. For
+example, <code>fixnum[to_f, to_s]</code> represents an object that has methods <code>to_f</code>
+and <code>to_s</code> whose types are same as those of <code>Fixnum</code>. This is more
+restrictive (precise) than <code>[to_f, to_s]</code> because the two methods must have
+the same types as <code>to_f</code> and <code>to_s</code> methods, respectively, in <code>Fixnum</code>.</p>
+<h3>Nil Type</h3>
+<p>A nil type represents a value of nil and is denoted by <code>nil</code>.</p>
+<h3>Any Type</h3>
+<p>RubyBreaker also provides a way to represent an object that is compatible with
+any type. This type is denoted by <code>?</code>. Use caution with this type because
+it should be only used for an object that requires an arbitrary yet most
+specific type--that is, <code>?</code> is a subtype of any other type, but any
+other type is not a subtype of <code>?</code>. This becomes a bit complicated for
+method or block argument types because of their contra-variance
+characteristic. Please refer to the section <em>Subtyping</em>.</p>
+<h3>Or Type</h3>
+<p>Any above types can be "or"ed together, using <code>||</code>, to represent an object
+that can be either one or the other. It <em>does</em> not represent an object that
+has to be both (which is not supported by RubyBreaker).</p>
+<h3>Optional Argument Type and Variable-Length Argument Type</h3>
+<p>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, <code>?</code> and <code>*</code>, respectively.</p>
+<h3>Block Type</h3>
+<p>One of the Ruby's prominent features is the block argument. It allows
+the caller to pass in a piece of code to be executed inside the callee. This
+code block can be executed by the Ruby construct, <code>yield</code>, or by directly
+calling the <code>call</code> method of the block object. In RubyBreaker, this type can
+be respresented by curly brackets. For instance, <code>{|fixnum,string| -&gt;
+string}</code> represents a block that takes two arguments--one <code>Fixnum</code> and one
+<code>String</code>--and returns a <code>String</code>.</p>
+<p>RubyBreaker does supports nested blocks as Ruby 1.9 finally allows them.
+However, <em>keep in mind</em> that RubyBreaker <em>cannot</em> automatically document the
+block types due to <code>yield</code> being a language construct rather than a method,
+which means it cannot be captured by meta-programming!</p>
+<h3>Method Type and Method List Types</h3>
+<p>Method type is similar to the block type, but it represents an actual method
+and not a block object. It is the "root" type that the type annotation
+language supports, along with method list types. Method <em>list</em> type is a
+collection of method types to represent more than one type information for
+the given method. Why would this type be needed? Consider the following Ruby
+code:</p>
+<pre><code>def foo(x)
+  case x
+  when Fixnum
+    1
+  when String
+    "1"
+  end
+end
+</code></pre>
+<p>There is no way to document the type of <code>foo</code> without using a method list
+type. Let's try to give a method type to <code>foo</code> without a method list. The
+closest we can come up with would be <code>foo(fixnum or string) -&gt; fixnum and
+string</code>. But RubyBreaker does not have the "and" type in the type annotation
+language because it gives me an headache! (By the way, it needs to be an
+"and" type because the caller must handle both <code>Fixnum</code> and <code>String</code> return
+values.)</p>
+<p>It is a dilemma because Ruby programmers actually enjoy using this kind of
+dynamic type checks in their code. To alleviate this headache, RubyBreaker
+supports the method list type to represent different scenarios depending on
+the argument types. Thus, the <code>foo</code> method shown above can be given the
+following method list type:</p>
+<pre><code>typesig("foo(fixnum) -&gt; fixnum")
+typesig("foo(string) -&gt; string")
+</code></pre>
+<p>These two type signatures simply tell RubyBreaker that <code>foo</code> has two method
+types--one for a <code>Fixnum</code> argument and another for a <code>String</code> argument.
+Depending on the argument type, the return type is determined. In this
+example, a <code>Fixnum</code> is returned when the argument is also a <code>Fixnum</code> and a
+<code>String</code> is returned when the argument is also a <code>String</code>. When
+automatically documenting such a type, RubyBreaker looks for the (subtyping)
+compatibility between the return types and "promote" the method type to a
+method list type by spliting the type signature into two (or more in
+subsequent "promotions").</p>
+    <hr />
+		<center style="font-size:smaller; padding:0px;">
+			Copyright (C) 2012 Jong-hoon (David) An. All Rights Reserved.<br />
+			Contact David An at rockalizer at gmail<br />
+			<a href="http://rockalizer.com">rockalizer.com</a>
+		</center>
+  </div>
+  </center>
+</body>
+</html>

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubybreaker
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease:
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2012-06-11 00:00:00.000000000 Z
+date: 2012-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: treetop
@@ -43,7 +43,6 @@ files:
 - lib/rubybreaker/debug/error.rb
 - lib/rubybreaker/debug.rb
 - lib/rubybreaker/doc/rdoc.rb
-- lib/rubybreaker/doc.rb
 - lib/rubybreaker/runtime/inspector.rb
 - lib/rubybreaker/runtime/monitor.rb
 - lib/rubybreaker/runtime/object_wrapper.rb
@@ -70,6 +69,7 @@ files:
 - lib/rubybreaker.rb
 - bin/gen_stub_rubylib
 - bin/rubybreaker
+- ABOUT.md
 - AUTHORS
 - LICENSE
 - NEWS
@@ -77,8 +77,10 @@ files:
 - Rakefile
 - README.md
 - TODO
+- TOPICS.md
+- TUTORIAL.md
 - VERSION
-- test/integrated/tc_both_broken_breakable.rb
+- test/integrated/tc_both_documented_and_undocumented.rb
 - test/integrated/tc_class_methods.rb
 - test/integrated/tc_inherit_broken.rb
 - test/integrated/tc_method_missing.rb
@@ -100,10 +102,12 @@ files:
 - test/type/tc_unparser.rb
 - test/typing/tc_rubytype.rb
 - test/typing/tc_typing.rb
+- webpage/about.html
 - webpage/footer.html
 - webpage/generated_toc.js
 - webpage/header.html
 - webpage/images/logo.png
+- webpage/images/title.png
 - webpage/index.html
 - webpage/rdoc/created.rid
 - webpage/rdoc/images/add.png
@@ -137,7 +141,6 @@ files:
 - webpage/rdoc/js/search.js
 - webpage/rdoc/js/search_index.js
 - webpage/rdoc/js/searcher.js
-- webpage/rdoc/Kernel.html
 - webpage/rdoc/Object.html
 - webpage/rdoc/Rake/RubyBreakerTestTask.html
 - webpage/rdoc/Rake.html
@@ -188,17 +191,20 @@ files:
 - webpage/rdoc/RubyBreaker/Util.html
 - webpage/rdoc/RubyBreaker.html
 - webpage/rdoc/table_of_contents.html
-- webpage/rdoc/Test/Unit/TestCase.html
 - webpage/rdoc/Test/Unit.html
 - webpage/rdoc/Test.html
 - webpage/rubybreaker.css
+- webpage/topics.html
+- webpage/tutorial.html
 homepage: http://github.com/rockalizer/rubybreaker
 licenses:
 - BSD
 post_install_message:
 rdoc_options:
-- -x
-- lib/rubybreaker/rubylib/core.rb
+- README.md
+- TUTORIAL.md
+- TOPICS.md
+- ABOUT.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement

data/lib/rubybreaker/doc.rb DELETED Viewed

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