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.
- 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
|
@@ -8,14 +8,14 @@ end
|
|
|
8
8
|
|
|
9
9
|
class RubyBreakerTestTaskTest < Test::Unit::TestCase
|
|
10
10
|
|
|
11
|
-
def
|
|
11
|
+
def test_break()
|
|
12
12
|
SampleClassA.new.foo(2)
|
|
13
13
|
t = RubyBreaker::Runtime::Inspector.inspect_meth(SampleClassA, :foo)
|
|
14
14
|
str = t.unparse()
|
|
15
15
|
assert_equal("foo(fixnum[to_s]) -> string", str)
|
|
16
16
|
end
|
|
17
17
|
|
|
18
|
-
def
|
|
18
|
+
def test_documented()
|
|
19
19
|
t = RubyBreaker::Runtime::Inspector.inspect_meth(SampleClassB, :foo)
|
|
20
20
|
str = t.unparse()
|
|
21
21
|
assert_equal("foo(fixnum[to_s]) -> string", str)
|
data/test/ts_integrated.rb
CHANGED
|
@@ -4,5 +4,5 @@ require_relative "integrated/tc_method_missing"
|
|
|
4
4
|
require_relative "integrated/tc_simple1"
|
|
5
5
|
require_relative "integrated/tc_inherit_broken"
|
|
6
6
|
require_relative "integrated/tc_class_methods"
|
|
7
|
-
require_relative "integrated/
|
|
7
|
+
require_relative "integrated/tc_both_documented_and_undocumented"
|
|
8
8
|
require_relative "integrated/tc_namespace"
|
data/test/ts_rspec.rb
CHANGED
data/webpage/about.html
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>RubyBreaker</title>
|
|
4
|
+
<LINK REL=StyleSheet HREF="rubybreaker.css" TYPE="text/css">
|
|
5
|
+
<script type="text/javascript" src="generated_toc.js"> </script>
|
|
6
|
+
</head>
|
|
7
|
+
<body onLoad="createTOC()">
|
|
8
|
+
<center>
|
|
9
|
+
<div id="content">
|
|
10
|
+
<div id="logo">
|
|
11
|
+
<img src="images/title.png" border="0">
|
|
12
|
+
</div>
|
|
13
|
+
<center>
|
|
14
|
+
<a href="index.html">Introduction</a> |
|
|
15
|
+
<a href="tutorial.html">Tutorial</a> |
|
|
16
|
+
<a href="topics.html">Advanced Topics</a> |
|
|
17
|
+
<a href="about.html">About</a>
|
|
18
|
+
</center>
|
|
19
|
+
<hr />
|
|
20
|
+
<!--<div id="generated-toc"></div>-->
|
|
21
|
+
<h1>About</h1>
|
|
22
|
+
|
|
23
|
+
<p>RubyBreaker has its root in Rubydust (which stands for Ruby Dynamic
|
|
24
|
+
Unraveling of Static Types), an academic research project designed and
|
|
25
|
+
implemented at University of Maryland. However, unlike Rubydust,
|
|
26
|
+
RubyBreaker aims to be a practical documentation tool for Ruby rather than a
|
|
27
|
+
full-scale type inference tool. Although it is certainly possible that
|
|
28
|
+
RubyBreaker evolves into something more solid in its type system, the
|
|
29
|
+
primary goal of this project is to help Ruby programmers practically as much
|
|
30
|
+
as possible.</p>
|
|
31
|
+
|
|
32
|
+
<h2>Acknowledgment</h2>
|
|
33
|
+
|
|
34
|
+
<p>The term, "Fusion Type," is first coined by Professor Michael W. Hicks at
|
|
35
|
+
University of Maryland and represents an object using a structural type with
|
|
36
|
+
respect to a nominal type.</p>
|
|
37
|
+
|
|
38
|
+
<h2>Copyright</h2>
|
|
39
|
+
|
|
40
|
+
<p>Copyright (c) 2012 Jong-hoon (David) An. All Rights Reserved.</p>
|
|
41
|
+
<hr />
|
|
42
|
+
<center style="font-size:smaller; padding:0px;">
|
|
43
|
+
Copyright (C) 2012 Jong-hoon (David) An. All Rights Reserved.<br />
|
|
44
|
+
Contact David An at rockalizer at gmail<br />
|
|
45
|
+
<a href="http://rockalizer.com">rockalizer.com</a>
|
|
46
|
+
</center>
|
|
47
|
+
</div>
|
|
48
|
+
</center>
|
|
49
|
+
</body>
|
|
50
|
+
</html>
|
data/webpage/footer.html
CHANGED
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
|
|
1
|
+
<hr />
|
|
2
|
+
<center style="font-size:smaller; padding:0px;">
|
|
3
|
+
Copyright (C) 2012 Jong-hoon (David) An. All Rights Reserved.<br />
|
|
4
|
+
Contact David An at rockalizer at gmail<br />
|
|
5
|
+
<a href="http://rockalizer.com">rockalizer.com</a>
|
|
6
|
+
</center>
|
|
2
7
|
</div>
|
|
3
8
|
</center>
|
|
4
9
|
</body>
|
data/webpage/header.html
CHANGED
|
@@ -8,7 +8,13 @@
|
|
|
8
8
|
<center>
|
|
9
9
|
<div id="content">
|
|
10
10
|
<div id="logo">
|
|
11
|
-
<img src="images/
|
|
11
|
+
<img src="images/title.png" border="0">
|
|
12
12
|
</div>
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
<center>
|
|
14
|
+
<a href="index.html">Introduction</a> |
|
|
15
|
+
<a href="tutorial.html">Tutorial</a> |
|
|
16
|
+
<a href="topics.html">Advanced Topics</a> |
|
|
17
|
+
<a href="about.html">About</a>
|
|
18
|
+
</center>
|
|
19
|
+
<hr />
|
|
20
|
+
<!--<div id="generated-toc"></div>-->
|
data/webpage/images/logo.png
CHANGED
|
Binary file
|
|
Binary file
|
data/webpage/index.html
CHANGED
|
@@ -8,43 +8,49 @@
|
|
|
8
8
|
<center>
|
|
9
9
|
<div id="content">
|
|
10
10
|
<div id="logo">
|
|
11
|
-
<img src="images/
|
|
11
|
+
<img src="images/title.png" border="0">
|
|
12
12
|
</div>
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
<
|
|
16
|
-
|
|
13
|
+
<center>
|
|
14
|
+
<a href="index.html">Introduction</a> |
|
|
15
|
+
<a href="tutorial.html">Tutorial</a> |
|
|
16
|
+
<a href="topics.html">Advanced Topics</a> |
|
|
17
|
+
<a href="about.html">About</a>
|
|
18
|
+
</center>
|
|
19
|
+
<hr />
|
|
20
|
+
<!--<div id="generated-toc"></div>-->
|
|
17
21
|
<h1>Introduction</h1>
|
|
18
22
|
|
|
19
23
|
<p>RubyBreaker is a dynamic type documentation tool written in pure Ruby. It
|
|
20
24
|
provides the framework for dynamically instrumenting a Ruby program to
|
|
21
|
-
monitor objects during
|
|
25
|
+
monitor objects during the execution and document the observed type
|
|
22
26
|
information. In other words, RubyBreaker "breaks" Ruby code out of its
|
|
23
|
-
obscurity and wildness (as in "code breaking" or "horse
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
obscurity and wildness (as in "code breaking" or "horse breaking") by
|
|
28
|
+
auto-documenting type information. The type documentation generated by
|
|
29
|
+
RubyBreaker is also an executable Ruby code that can be used as an input to
|
|
30
|
+
subsequent analyses.</p>
|
|
27
31
|
|
|
28
32
|
<p>The primary goal of RubyBreaker is to assign a type signature to every
|
|
29
33
|
method in selected modules and classes. A type signature is written in the
|
|
30
34
|
RubyBreaker Type Annotation Language which resembles the documentation style
|
|
31
|
-
used in Ruby
|
|
32
|
-
|
|
33
|
-
|
|
35
|
+
used in Ruby Core Library Doc. No manual code change is required. Overall,
|
|
36
|
+
this tool should help Ruby programmers document their code more rigorously
|
|
37
|
+
and effectively.</p>
|
|
34
38
|
|
|
35
|
-
<p>
|
|
39
|
+
<p>Currently, RubyBreaker <em>cannot</em></p>
|
|
36
40
|
|
|
37
41
|
<ul>
|
|
38
|
-
<li>Auto-
|
|
39
|
-
<li>
|
|
40
|
-
<li>
|
|
42
|
+
<li>Auto-document block arguments (inherent)</li>
|
|
43
|
+
<li>Perform early dynamic type checks</li>
|
|
44
|
+
<li>Support parametric polymorphic types</li>
|
|
45
|
+
<li>Support RDoc or YARD output format</li>
|
|
41
46
|
</ul>
|
|
42
47
|
|
|
43
48
|
|
|
44
49
|
<p>To contribute to the project, visit RubyBreaker's
|
|
45
50
|
<a href="http://github.com/rockalizer/rubybreaker">GitHub page</a> and
|
|
46
|
-
<a href="http://rubygems.org/gems/rubybreaker">RubyGems page</a>.
|
|
47
|
-
|
|
51
|
+
<a href="http://rubygems.org/gems/rubybreaker">RubyGems page</a>. The web version of
|
|
52
|
+
this document can be found
|
|
53
|
+
<a href="http://rockalizer.webfactional.com/projects/rubybreaker">here</a>.</p>
|
|
48
54
|
|
|
49
55
|
<h2>Requirements</h2>
|
|
50
56
|
|
|
@@ -60,354 +66,12 @@ following URL: <a href="http://treetop.rubyforge.org/">TreeTop</a></p>
|
|
|
60
66
|
|
|
61
67
|
<pre><code>$ gem install rubybreaker
|
|
62
68
|
</code></pre>
|
|
63
|
-
|
|
64
|
-
<
|
|
65
|
-
|
|
66
|
-
<
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
Type Annotation Language, and the RubyBreaker Type System.</p>
|
|
70
|
-
|
|
71
|
-
<h2>Usage</h2>
|
|
72
|
-
|
|
73
|
-
<p>RubyBreaker takes advantage of test cases that already come with the source
|
|
74
|
-
program. It is recommended that RubyBreaker is run as a Rake task, which
|
|
75
|
-
requires a minimum code change in the Rakefile and no code change in the
|
|
76
|
-
source program. If not used as a Rake task, it requires a minimum code
|
|
77
|
-
change in each test case or the source program but should not affect the
|
|
78
|
-
development process much. Let's briefly see how RubyBreaker can be run
|
|
79
|
-
directly as a command-line program to understand the general concept of the
|
|
80
|
-
tool. We will explain how to use RubyBreaker in a Rakefile later.</p>
|
|
81
|
-
|
|
82
|
-
<pre><code>$ rubybreaker -v prog.rb
|
|
83
|
-
</code></pre>
|
|
84
|
-
|
|
85
|
-
<p>This runs RubyBreaker in verbose mode on <code>prog.rb</code>. Note that RubyBreaker
|
|
86
|
-
will actually run <code>prog.rb</code> (by simply <code>require</code>ing the program file).
|
|
87
|
-
Somewhere in the program, there has to be a <em>program entry point</em> to
|
|
88
|
-
indicate where the <em>monitoring</em> of objects starts. Let's assume <code>prog.rb</code>
|
|
89
|
-
as the following:</p>
|
|
90
|
-
|
|
91
|
-
<pre><code>require "rubybreaker" # required if using "ruby" instead
|
|
92
|
-
class A
|
|
93
|
-
def foo(x)
|
|
94
|
-
x.to_s
|
|
95
|
-
end
|
|
96
|
-
end
|
|
97
|
-
class B
|
|
98
|
-
def bar(y,z)
|
|
99
|
-
y.foo(z)
|
|
100
|
-
end
|
|
101
|
-
end
|
|
102
|
-
RubyBreaker.run(A, B)
|
|
103
|
-
A.new.foo(1)
|
|
104
|
-
</code></pre>
|
|
105
|
-
|
|
106
|
-
<p>This example will show how <code>A#foo</code> method is given a type by RubyBreaker.
|
|
107
|
-
After running <code>rubybreaker -v prog.rb</code>, the following output will be
|
|
108
|
-
generated and saved into <code>prog.rubybreaker.rb</code>.</p>
|
|
109
|
-
|
|
110
|
-
<pre><code># This file is auto-generated by RubyBreaker
|
|
111
|
-
require "rubybreaker"
|
|
112
|
-
class A
|
|
113
|
-
typesig("foo(fixnum[to_s]) -> string")
|
|
114
|
-
end
|
|
115
|
-
</code></pre>
|
|
116
|
-
|
|
117
|
-
<p>Here, the <code>typesig</code> method call registers <code>foo</code> as a method type that takes
|
|
118
|
-
an object that has <code>Fixnum#to_s</code> method and returns a <code>String</code>. This
|
|
119
|
-
method is made available by importing <code>rubybreaker</code>. Now, assume that an
|
|
120
|
-
additional code, <code>B.new.bar(A.new,1)</code>, is added at the end of <code>prog.rb</code>. The
|
|
121
|
-
subsequent run will generate the following result:</p>
|
|
122
|
-
|
|
123
|
-
<pre><code># This file is auto-generated by RubyBreaker
|
|
124
|
-
require "rubybreaker"
|
|
125
|
-
class A
|
|
126
|
-
typesig("foo(fixnum[to_s]) -> string")
|
|
127
|
-
end
|
|
128
|
-
class B
|
|
129
|
-
typesig("bar(a[foo], fixnum[to_s]) -> string")
|
|
130
|
-
end
|
|
131
|
-
</code></pre>
|
|
132
|
-
|
|
133
|
-
<p>Keep in mind that RubyBreaker is designed to gather type information based
|
|
134
|
-
on the <em>actual</em> execution of the source program. This means the program
|
|
135
|
-
should be equipped with test cases that have a reasonable program path
|
|
136
|
-
coverage. Additionally, RubyBreaker assumes that test runs are correct and
|
|
137
|
-
the program behaves correctly (for those test runs) as intended by the
|
|
138
|
-
programmer. This assumption is not a strong requirement, but is necessary to
|
|
139
|
-
obtain precise and accurate type information.</p>
|
|
140
|
-
|
|
141
|
-
<h3>Using Ruby Unit Testing Framework</h3>
|
|
142
|
-
|
|
143
|
-
<p>Instead of manually inserting the entry point indicator into the program,
|
|
144
|
-
you can take advantage of Ruby's built-in testing framework. This is
|
|
145
|
-
preferred to modifying the source program directly, especially for the long
|
|
146
|
-
term program maintainability. But no worries! This method is as simple as
|
|
147
|
-
the previous one.</p>
|
|
148
|
-
|
|
149
|
-
<pre><code>require "test/unit"
|
|
150
|
-
require "rubybreaker" # This should come after test/unit.
|
|
151
|
-
class TestClassA < Test::Unit::TestCase
|
|
152
|
-
def setup()
|
|
153
|
-
RubyBreaker.breakable(Class1, Class2, ...)
|
|
154
|
-
...
|
|
155
|
-
end
|
|
156
|
-
# ...tests!...
|
|
157
|
-
end
|
|
158
|
-
</code></pre>
|
|
159
|
-
|
|
160
|
-
<p>That's it! The only requirements are to indicate to RubyBreaker which modules
|
|
161
|
-
and classes to "break" and to place <code>require rubybreaker</code> <em>after</em>
|
|
162
|
-
<code>require test/unit</code>.</p>
|
|
163
|
-
|
|
164
|
-
<h3>Using RSpec</h3>
|
|
165
|
-
|
|
166
|
-
<p>The requirement is same for RSpec but use <code>before</code> instead of <code>setup</code> to
|
|
167
|
-
specify which modules and classes to "break".</p>
|
|
168
|
-
|
|
169
|
-
<pre><code>require "rspec"
|
|
170
|
-
require "rubybreaker"
|
|
171
|
-
|
|
172
|
-
describe "TestClassA Test"
|
|
173
|
-
before { RubyBreaker.breakable(Class1, Class2, ...) }
|
|
174
|
-
...
|
|
175
|
-
# ...tests!...
|
|
176
|
-
end
|
|
177
|
-
</code></pre>
|
|
178
|
-
|
|
179
|
-
<h3>Using Rakefile</h3>
|
|
180
|
-
|
|
181
|
-
<p>By running RubyBreaker along with the Rakefile, you can avoid modifying the
|
|
182
|
-
source program at all. (You no longer need to import <code>rubybreaker</code> in the
|
|
183
|
-
test cases neither.) Therefore, this is the recommended way to use
|
|
184
|
-
RubyBreaker. The following code snippet describes how it can be done:</p>
|
|
185
|
-
|
|
186
|
-
<pre><code>require "rubybreaker/task"
|
|
187
|
-
...
|
|
188
|
-
desc "Run RubyBreaker"
|
|
189
|
-
Rake::RubyBreakerTestTask.new(:"rubybreaker") do |t|
|
|
190
|
-
t.libs << "lib"
|
|
191
|
-
t.test_files = ["test/foo/tc_foo1.rb"]
|
|
192
|
-
# ...Other test task options..
|
|
193
|
-
t.rubybreaker_opts << "-v" # run in verbose mode
|
|
194
|
-
t.breakable = ["Class1", "Class2", ...] # specify what to monitor
|
|
195
|
-
end
|
|
196
|
-
</code></pre>
|
|
197
|
-
|
|
198
|
-
<p>Note that <code>RubyBrakerTestTask</code> can simply replace your <code>TestTask</code> block in
|
|
199
|
-
Rakefile. In fact, the former is a subclass of the latter and includes all
|
|
200
|
-
features supported by the latter. The only additional options are
|
|
201
|
-
<code>rubybreaker_opts</code> which is RubyBreaker's command-line options and
|
|
202
|
-
<code>breakable</code> which specifies which modules and classes to monitor. Since
|
|
203
|
-
<code>Class1</code> and <code>Class2</code> are not <em>recognized</em> by this Rakefile, you must use
|
|
204
|
-
string literals to specify modules and classes (and with full namespace).</p>
|
|
205
|
-
|
|
206
|
-
<p>If this is the route you are taking, there needs no editing of the source
|
|
207
|
-
program whatsoever. This task will take care of instrumenting the specified
|
|
208
|
-
modules and classes at proper moments.</p>
|
|
209
|
-
|
|
210
|
-
<h2>Type Annotation</h2>
|
|
211
|
-
|
|
212
|
-
<p>The annotation language used in RubyBreaker resembles the method
|
|
213
|
-
documentation used by Ruby Standard Library Doc. Each type signature
|
|
214
|
-
defines a method type using the name, argument types, block type, and return
|
|
215
|
-
type. But, let us consider a simple case where there is one argument type
|
|
216
|
-
and a return type.</p>
|
|
217
|
-
|
|
218
|
-
<pre><code>class A
|
|
219
|
-
...
|
|
220
|
-
typesig("foo(fixnum) -> string")
|
|
221
|
-
end
|
|
222
|
-
</code></pre>
|
|
223
|
-
|
|
224
|
-
<p>In RubyBreaker, a type signature is recognized by the meta-class level
|
|
225
|
-
method <code>typesig</code> which takes a string as an argument. This string is the
|
|
226
|
-
actual type signature written in the Ruby Type Annotation Language. This
|
|
227
|
-
language is designed to reflect the common documentation practice used by
|
|
228
|
-
RubyDoc. It starts with the name of the method. In the above example, <code>foo</code>
|
|
229
|
-
is currently being given a type. The rest of the signature takes a typical
|
|
230
|
-
method type symbol, <code>(x) -> y</code> where <code>x</code> is the argument type and <code>y</code> is the
|
|
231
|
-
return type. In the example shown above, the method takes a <code>Fixnum</code> object
|
|
232
|
-
and returns a <code>String</code> object. Note that these types are in lowercase,
|
|
233
|
-
indicating they are objects and not modules or classes themselves.</p>
|
|
234
|
-
|
|
235
|
-
<p>There are several types that represent an object: nominal, duck, fusion,
|
|
236
|
-
nil, 'any', 'or', optional, variable-length, and block. Each type signature
|
|
237
|
-
itself represents a method type or a method list type (explained below).</p>
|
|
238
|
-
|
|
239
|
-
<h3>Nominal Type</h3>
|
|
240
|
-
|
|
241
|
-
<p>This is the simplest and most intuitive way to represent an object. For
|
|
242
|
-
instance, <code>fixnum</code> is an object of type <code>Fixnum</code>. Use lower-case letters and
|
|
243
|
-
underscores instead of <em>camelized</em> name. <code>MyClass</code>, for example would be
|
|
244
|
-
<code>my_class</code> in RubyBreaker type signatures. There is no particular
|
|
245
|
-
reason for this convention other than it is the common practice used in
|
|
246
|
-
RubyDoc. Use <code>/</code> to indicate the namespace delimiter <code>::</code>. For example,
|
|
247
|
-
<code>NamspaceA::ClassB</code> would be represented by <code>namespace_a/class_b</code> in
|
|
248
|
-
a RubyBreaker type signature.</p>
|
|
249
|
-
|
|
250
|
-
<h3>Self Type</h3>
|
|
251
|
-
|
|
252
|
-
<p>This type is similar to the nominal type but is referring to the current
|
|
253
|
-
object--that is, the receiver of the method being typed. RubyBreaker will
|
|
254
|
-
auto-document the return type as a self type if the return value is the same
|
|
255
|
-
as the receiver of that call. It is also recommended to use this type over
|
|
256
|
-
a nominal type (if the return value is <code>self</code>) since it depicts more
|
|
257
|
-
precise return type.</p>
|
|
258
|
-
|
|
259
|
-
<h3>Duck Type</h3>
|
|
260
|
-
|
|
261
|
-
<p>This type is inspired by the Ruby Language's duck typing, <em>"if it
|
|
262
|
-
walks like a duck and quacks like a duck, it must be a duck."</em> Using this
|
|
263
|
-
type, an object can be represented simply by a list of method names. For
|
|
264
|
-
example <code>[walks, quacks]</code> is an object that has <code>walks</code> and <code>quacks</code>
|
|
265
|
-
methods. Note that these method names do <em>not</em> reveal any type
|
|
266
|
-
information for themselves.</p>
|
|
267
|
-
|
|
268
|
-
<h3>Fusion Type</h3>
|
|
269
|
-
|
|
270
|
-
<p>Duck type is very flexible but can be too lenient when trying to restrict
|
|
271
|
-
the type of an object. RubyBreaker provides a type called <em>the fusion type</em>
|
|
272
|
-
which lists method names but with respect to a nominal type. For
|
|
273
|
-
example, <code>fixnum[to_f, to_s]</code> represents an object that has methods <code>to_f</code>
|
|
274
|
-
and <code>to_s</code> whose types are same as those of <code>Fixnum</code>. This is more
|
|
275
|
-
restrictive (precise) than <code>[to_f, to_s]</code> because the two methods must have
|
|
276
|
-
the same types as <code>to_f</code> and <code>to_s</code> methods, respectively, in <code>Fixnum</code>.</p>
|
|
277
|
-
|
|
278
|
-
<h3>Nil Type</h3>
|
|
279
|
-
|
|
280
|
-
<p>A nil type represents a value of nil and is denoted by <code>nil</code>.</p>
|
|
281
|
-
|
|
282
|
-
<h3>Any Type</h3>
|
|
283
|
-
|
|
284
|
-
<p>RubyBreaker also provides a way to represent an object that is compatible with
|
|
285
|
-
any type. This type is denoted by <code>?</code>. Use caution with this type because
|
|
286
|
-
it should be only used for an object that requires an arbitrary yet most
|
|
287
|
-
specific type--that is, <code>?</code> is a subtype of any other type, but any
|
|
288
|
-
other type is not a subtype of <code>?</code>. This becomes a bit complicated for
|
|
289
|
-
method or block argument types because of their contra-variance
|
|
290
|
-
characteristic. Please refer to the section <em>Subtyping</em>.</p>
|
|
291
|
-
|
|
292
|
-
<h3>Or Type</h3>
|
|
293
|
-
|
|
294
|
-
<p>Any above types can be "or"ed together, using <code>||</code>, to represent an object
|
|
295
|
-
that can be either one or the other. It <em>does</em> not represent an object that
|
|
296
|
-
has to be both (which is not supported by RubyBreaker).</p>
|
|
297
|
-
|
|
298
|
-
<h3>Optional Argument Type and Variable-Length Argument Type</h3>
|
|
299
|
-
|
|
300
|
-
<p>Another useful features of Ruby are the optional argument type and the
|
|
301
|
-
variable-length argument type. The former represents an argument that has a
|
|
302
|
-
default value (and therefore does not have to be provided). The latter
|
|
303
|
-
represents zero or more arguments of the same type. These are denoted by
|
|
304
|
-
suffices, <code>?</code> and <code>*</code>, respectively.</p>
|
|
305
|
-
|
|
306
|
-
<h3>Block Type</h3>
|
|
307
|
-
|
|
308
|
-
<p>One of the Ruby's prominent features is the block argument. It allows
|
|
309
|
-
the caller to pass in a piece of code to be executed inside the callee. This
|
|
310
|
-
code block can be executed by the Ruby construct, <code>yield</code>, or by directly
|
|
311
|
-
calling the <code>call</code> method of the block object. In RubyBreaker, this type can
|
|
312
|
-
be respresented by curly brackets. For instance, <code>{|fixnum,string| ->
|
|
313
|
-
string}</code> represents a block that takes two arguments--one <code>Fixnum</code> and one
|
|
314
|
-
<code>String</code>--and returns a <code>String</code>.</p>
|
|
315
|
-
|
|
316
|
-
<p>RubyBreaker does supports nested blocks as Ruby 1.9 finally allows them.
|
|
317
|
-
However, <em>keep in mind</em> that RubyBreaker <em>cannot</em> automatically document the
|
|
318
|
-
block types due to <code>yield</code> being a language construct rather than a method,
|
|
319
|
-
which means it cannot be captured by meta-programming!</p>
|
|
320
|
-
|
|
321
|
-
<h3>Method Type and Method List Types</h3>
|
|
322
|
-
|
|
323
|
-
<p>Method type is similar to the block type, but it represents an actual method
|
|
324
|
-
and not a block object. It is the "root" type that the type annotation
|
|
325
|
-
language supports, along with method list types. Method <em>list</em> type is a
|
|
326
|
-
collection of method types to represent more than one type information for
|
|
327
|
-
the given method. Why would this type be needed? Consider the following Ruby
|
|
328
|
-
code:</p>
|
|
329
|
-
|
|
330
|
-
<pre><code>def foo(x)
|
|
331
|
-
case x
|
|
332
|
-
when Fixnum
|
|
333
|
-
1
|
|
334
|
-
when String
|
|
335
|
-
"1"
|
|
336
|
-
end
|
|
337
|
-
end
|
|
338
|
-
</code></pre>
|
|
339
|
-
|
|
340
|
-
<p>There is no way to document the type of <code>foo</code> without using a method list
|
|
341
|
-
type. Let's try to give a method type to <code>foo</code> without a method list. The
|
|
342
|
-
closest we can come up with would be <code>foo(fixnum or string) -> fixnum and
|
|
343
|
-
string</code>. But RubyBreaker does not have the "and" type in the type annotation
|
|
344
|
-
language because it gives me an headache! (By the way, it needs to be an
|
|
345
|
-
"and" type because the caller must handle both <code>Fixnum</code> and <code>String</code> return
|
|
346
|
-
values.)</p>
|
|
347
|
-
|
|
348
|
-
<p>It is a dilemma because Ruby programmers actually enjoy using this kind of
|
|
349
|
-
dynamic type checks in their code. To alleviate this headache, RubyBreaker
|
|
350
|
-
supports the method list type to represent different scenarios depending on
|
|
351
|
-
the argument types. Thus, the <code>foo</code> method shown above can be given the
|
|
352
|
-
following method list type:</p>
|
|
353
|
-
|
|
354
|
-
<pre><code>typesig("foo(fixnum) -> fixnum")
|
|
355
|
-
typesig("foo(string) -> string")
|
|
356
|
-
</code></pre>
|
|
357
|
-
|
|
358
|
-
<p>These two type signatures simply tell RubyBreaker that <code>foo</code> has two method
|
|
359
|
-
types--one for a <code>Fixnum</code> argument and another for a <code>String</code> argument.
|
|
360
|
-
Depending on the argument type, the return type is determined. In this
|
|
361
|
-
example, a <code>Fixnum</code> is returned when the argument is also a <code>Fixnum</code> and a
|
|
362
|
-
<code>String</code> is returned when the argument is also a <code>String</code>. When
|
|
363
|
-
automatically documenting such a type, RubyBreaker looks for the (subtyping)
|
|
364
|
-
compatibility between the return types and "promote" the method type to a
|
|
365
|
-
method list type by spliting the type signature into two (or more in
|
|
366
|
-
subsequent "promotions").</p>
|
|
367
|
-
|
|
368
|
-
<h2>Type System</h2>
|
|
369
|
-
|
|
370
|
-
<p>RubyBreaker comes with its own type system to auto-document the type
|
|
371
|
-
information. Each method in a "breakable" module is dynamically instrumented
|
|
372
|
-
to be monitored during runtime. This monitoring code observes the types of
|
|
373
|
-
the arguments, block, and return value of each method. Once this information
|
|
374
|
-
is gathered, RubyBreaker will compare it to the information gathered so far.
|
|
375
|
-
If these two types are "compatiable", RubyBreaker will choose more general
|
|
376
|
-
type of the two. Otherwise, RubyBreaker will use the method list type to
|
|
377
|
-
accommodate two "incompatible" types.</p>
|
|
378
|
-
|
|
379
|
-
<h3>Subtyping and Subclassing</h3>
|
|
380
|
-
|
|
381
|
-
<p>RubyBreaker uses subtyping to choose one from the two "compatible" types.
|
|
382
|
-
Two types are "compatible" if one is subtype of another. This means that the
|
|
383
|
-
<em>subtype</em> can be represented using the <em>supertype</em> instead. This is why
|
|
384
|
-
RubyBrekaer chooses the latter to document both types. RubyBreaker relies on
|
|
385
|
-
subclassing of Ruby to determine a subtyping relationship between two types.
|
|
386
|
-
For example, <code>Fixnum</code> is considered to be subtype of <code>Numeric</code> since the
|
|
387
|
-
former is subclass of the latter. (Strictly speaking, <code>Fixnum</code> is not really
|
|
388
|
-
subtype of <code>Numeric</code> because some methods are overriden in <code>Fixnum</code> with
|
|
389
|
-
method types that are not subtype of the counterparts in <code>Numeric</code>. But,
|
|
390
|
-
RubyBreaker is lenient and considers them compatible--that is, <code>Numeric</code> can
|
|
391
|
-
represent any <code>Fixnum</code>.</p>
|
|
392
|
-
|
|
393
|
-
<h3>Pluggable Type System (Advanced)</h3>
|
|
394
|
-
|
|
395
|
-
<p>Yes, RubyBreaker was designed with the replaceable type system in mind. In
|
|
396
|
-
other words, anyone can write his own type system and plug it into
|
|
397
|
-
RubyBreaker. <em>Technical documentation coming soon...</em></p>
|
|
398
|
-
|
|
399
|
-
<hr />
|
|
400
|
-
|
|
401
|
-
<h1>Acknowledgment</h1>
|
|
402
|
-
|
|
403
|
-
<p>The term, "Fusion Type," is first coined by Professor Michael W. Hicks at
|
|
404
|
-
University of Maryland and represents an object using a structural type with
|
|
405
|
-
respect to a nominal type.</p>
|
|
406
|
-
|
|
407
|
-
<h1>Copyright</h1>
|
|
408
|
-
|
|
409
|
-
<p>Copyright (c) 2012 Jong-hoon (David) An. All Rights Reserved.</p>
|
|
410
|
-
|
|
69
|
+
<hr />
|
|
70
|
+
<center style="font-size:smaller; padding:0px;">
|
|
71
|
+
Copyright (C) 2012 Jong-hoon (David) An. All Rights Reserved.<br />
|
|
72
|
+
Contact David An at rockalizer at gmail<br />
|
|
73
|
+
<a href="http://rockalizer.com">rockalizer.com</a>
|
|
74
|
+
</center>
|
|
411
75
|
</div>
|
|
412
76
|
</center>
|
|
413
77
|
</body>
|