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

rubybreaker 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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	-