live_ast 0.2.3 → 0.5.0
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/CHANGES.rdoc +13 -0
- data/MANIFEST +1 -3
- data/README.rdoc +47 -49
- data/Rakefile +7 -8
- data/devel/jumpstart.rb +101 -192
- data/lib/live_ast/base.rb +6 -1
- data/lib/live_ast/linker.rb +1 -1
- data/lib/live_ast/to_ruby.rb +1 -12
- data/lib/live_ast/version.rb +1 -1
- data/test/ast_eval_feature_test.rb +1 -1
- data/test/ast_load_feature_test.rb +1 -1
- data/test/backtrace_test.rb +1 -1
- data/test/covert_define_method_test.rb +2 -2
- data/test/def_test.rb +1 -1
- data/test/define_method_test.rb +1 -1
- data/test/define_singleton_method_test.rb +1 -1
- data/test/encoding_test.rb +3 -3
- data/test/error_test.rb +4 -4
- data/test/eval_test.rb +1 -1
- data/test/flush_cache_test.rb +4 -4
- data/test/lambda_test.rb +1 -1
- data/test/load_path_test.rb +3 -3
- data/test/load_test.rb +2 -2
- data/test/{shared/main.rb → main.rb} +26 -16
- data/test/noninvasive_test.rb +1 -1
- data/test/readme_test.rb +10 -8
- data/test/recursive_eval_test.rb +1 -1
- data/test/redefine_method_test.rb +1 -1
- data/test/reload_test.rb +1 -1
- data/test/stdlib_test.rb +1 -1
- data/test/thread_test.rb +1 -1
- data/test/to_ast_feature_test.rb +1 -1
- data/test/to_ruby_feature_test.rb +1 -1
- data/test/to_ruby_test.rb +4 -2
- metadata +8 -95
- data/lib/live_ast/parser.rb +0 -48
- data/test/shared/ast_generators.rb +0 -124
data/CHANGES.rdoc
CHANGED
@@ -1,6 +1,19 @@
|
|
1
1
|
|
2
2
|
= LiveAST ChangeLog
|
3
3
|
|
4
|
+
== Version 0.5.0
|
5
|
+
|
6
|
+
* use non-stupid parser plugin API
|
7
|
+
|
8
|
+
== Version 0.4.0 X yanked
|
9
|
+
|
10
|
+
* new parser plugin design to work around obscure autoload failure
|
11
|
+
|
12
|
+
== Version 0.3.0 X yanked
|
13
|
+
|
14
|
+
* parser is now an external plugin
|
15
|
+
* default parser has been moved to live_ast_ruby_parser gem
|
16
|
+
|
4
17
|
== Version 0.2.3
|
5
18
|
|
6
19
|
* fix a utf-8 BOM issue
|
data/MANIFEST
CHANGED
@@ -11,7 +11,6 @@ lib/live_ast/error.rb
|
|
11
11
|
lib/live_ast/evaler.rb
|
12
12
|
lib/live_ast/linker.rb
|
13
13
|
lib/live_ast/loader.rb
|
14
|
-
lib/live_ast/parser.rb
|
15
14
|
lib/live_ast/reader.rb
|
16
15
|
lib/live_ast/replace_load.rb
|
17
16
|
lib/live_ast/replace_raise.rb
|
@@ -44,13 +43,12 @@ test/flush_cache_test.rb
|
|
44
43
|
test/lambda_test.rb
|
45
44
|
test/load_path_test.rb
|
46
45
|
test/load_test.rb
|
46
|
+
test/main.rb
|
47
47
|
test/noninvasive_test.rb
|
48
48
|
test/readme_test.rb
|
49
49
|
test/recursive_eval_test.rb
|
50
50
|
test/redefine_method_test.rb
|
51
51
|
test/reload_test.rb
|
52
|
-
test/shared/ast_generators.rb
|
53
|
-
test/shared/main.rb
|
54
52
|
test/stdlib_test.rb
|
55
53
|
test/thread_test.rb
|
56
54
|
test/to_ast_feature_test.rb
|
data/README.rdoc
CHANGED
@@ -56,7 +56,8 @@ methods and procs.
|
|
56
56
|
|
57
57
|
% gem install live_ast
|
58
58
|
|
59
|
-
|
59
|
+
Or from inside an unpacked .tgz download, <code>rake install</code> /
|
60
|
+
<code>rake uninstall</code>.
|
60
61
|
|
61
62
|
== Description
|
62
63
|
|
@@ -74,26 +75,30 @@ the parser outputs).
|
|
74
75
|
Note that RubyParser does not currently support the newer Ruby 1.9
|
75
76
|
syntax features (<code>Racc::ParseError</code> will be raised).
|
76
77
|
|
78
|
+
To use the Ripper parser instead, <code>gem install
|
79
|
+
live_ast_ripper</code> and then <code>require
|
80
|
+
'live_ast_ripper'</code>.
|
81
|
+
|
77
82
|
LiveAST is thread-safe.
|
78
83
|
|
79
84
|
Ruby 1.9.2 or higher is required.
|
80
85
|
|
81
86
|
== Links
|
82
87
|
|
83
|
-
* Home:
|
84
|
-
* Documentation: http://quix.github.com/live_ast
|
88
|
+
* Home: http://quix.github.com/live_ast
|
85
89
|
* Feature Requests, Bug Reports: http://github.com/quix/live_ast/issues
|
90
|
+
* Manual Download: http://github.com/quix/live_ast/archives/master
|
91
|
+
* Repository: http://github.com/quix/live_ast
|
86
92
|
|
87
93
|
== +to_ruby+
|
88
94
|
|
89
|
-
Although
|
90
|
-
not an official dependency of LiveAST, for convenience
|
95
|
+
Although +ruby2ruby+ is not required by default,
|
91
96
|
|
92
97
|
require 'live_ast/to_ruby'
|
93
98
|
|
94
|
-
will require ruby2ruby and define the +to_ruby+ method for +Method+,
|
99
|
+
will require +ruby2ruby+ and define the +to_ruby+ method for +Method+,
|
95
100
|
+UnboundMethod+, and +Proc+. These methods are one-liners which pass
|
96
|
-
the extracted ASTs to ruby2ruby
|
101
|
+
the extracted ASTs to +ruby2ruby+.
|
97
102
|
|
98
103
|
require 'live_ast'
|
99
104
|
require 'live_ast/to_ruby'
|
@@ -108,6 +113,9 @@ the extracted ASTs to ruby2ruby.
|
|
108
113
|
|
109
114
|
p A.instance_method(:f).to_ruby # => "def f\n \"A#f\"\nend"
|
110
115
|
|
116
|
+
In general, +to_ruby+ will hook into the unparser provided by the
|
117
|
+
parser, if one is found.
|
118
|
+
|
111
119
|
== Loading Source
|
112
120
|
|
113
121
|
Objects created via +require+ and +load+ will be AST-accessible.
|
@@ -154,41 +162,30 @@ or blocks in order for its AST to be available.
|
|
154
162
|
a = lambda { } ; b = lambda { }
|
155
163
|
a.to_ast # => raises LiveAST::MultipleDefinitionsOnSameLineError
|
156
164
|
|
157
|
-
|
158
|
-
|
159
|
-
http://github.com/quix/live_ast/archives/master
|
165
|
+
----
|
160
166
|
|
161
|
-
|
162
|
-
% cd live_ast-x.x.x
|
163
|
-
% rake install
|
167
|
+
== <em>Technical Issues</em>
|
164
168
|
|
165
|
-
|
169
|
+
You can probably skip these next sections. Goodbye.
|
166
170
|
|
167
|
-
|
171
|
+
----
|
168
172
|
|
169
|
-
==
|
170
|
-
|
171
|
-
You can probably ignore this section. Goodbye.
|
172
|
-
|
173
|
-
=== Replacing the Parser
|
173
|
+
== Replacing the Parser
|
174
174
|
|
175
175
|
Despite its name, LiveAST knows nothing about ASTs. It merely reports
|
176
|
-
what it finds in the line-to-AST hash
|
177
|
-
|
178
|
-
|
179
|
-
return such a hash.
|
176
|
+
what it finds in the line-to-AST hash returned by the parser's +parse+
|
177
|
+
method. Replacing the parser class is therefore easy: the only
|
178
|
+
specification is that the +parse+ instance method return such a hash.
|
180
179
|
|
181
|
-
|
182
|
-
<code>/path/to/my/code/live_ast/parser.rb</code>,
|
180
|
+
To override the default parser,
|
183
181
|
|
184
|
-
|
185
|
-
require 'live_ast'
|
182
|
+
LiveAST.parser = YourParser
|
186
183
|
|
187
|
-
|
188
|
-
|
189
|
-
|
184
|
+
To test it, provide some examples of what the ASTs look like in
|
185
|
+
<code>YourParser::TestForms</code>. See the +live_ast_ruby_parser+ gem
|
186
|
+
for reference.
|
190
187
|
|
191
|
-
|
188
|
+
== Noninvasive Mode
|
192
189
|
|
193
190
|
For safety purposes, <code>require 'live_ast'</code> performs the
|
194
191
|
invasive act of redefining +load+ (but not +require+); otherwise bad
|
@@ -210,7 +207,7 @@ To select features individually,
|
|
210
207
|
require 'live_ast/ast_load' # define Kernel#ast_load (mentioned below)
|
211
208
|
require 'live_ast/replace_load' # redefine Kernel#load
|
212
209
|
|
213
|
-
|
210
|
+
== Noninvasive Interface
|
214
211
|
|
215
212
|
The following alternative interface is available.
|
216
213
|
|
@@ -235,7 +232,7 @@ The following alternative interface is available.
|
|
235
232
|
|
236
233
|
ast_eval # => raises NameError
|
237
234
|
|
238
|
-
|
235
|
+
== Reloading Files In Noninvasive Mode
|
239
236
|
|
240
237
|
Use +ast_load+ or (equivalently) <code>LiveAST.load</code> when
|
241
238
|
reloading an AST-aware file.
|
@@ -261,16 +258,16 @@ Realize that <code>foo.rb</code> may be referenced by an unknown
|
|
261
258
|
number of methods and blocks. If the original <code>foo.rb</code>
|
262
259
|
source were dumped in favor of the modified <code>foo.rb</code>, then
|
263
260
|
an unknown number of those references would be invalidated (and some
|
264
|
-
may even point to the wrong AST
|
261
|
+
may even point to the wrong AST).
|
265
262
|
|
266
263
|
This is the reason for the caching that results in the stale AST
|
267
264
|
above. It should now be clear why the default behavior of
|
268
265
|
<code>require 'live_ast'</code> is to redefine +load+: doing so
|
269
266
|
prevents this problem entirely. On the other hand if it is fully known
|
270
|
-
where
|
271
|
-
|
267
|
+
where files are being reloaded (if at all) then there's no need for
|
268
|
+
paranoia; the noninvasive option may be the most appropriate.
|
272
269
|
|
273
|
-
|
270
|
+
== The Source/AST Cache
|
274
271
|
|
275
272
|
+ast_eval+ and +load+ cache all incoming code, while
|
276
273
|
<code>require</code>d files are cached on a need-to-know basis. When
|
@@ -297,13 +294,13 @@ files will never be flushed. However a method redefined via +ast_eval+
|
|
297
294
|
or +load+ is susceptible to +flush_cache+ even when its original
|
298
295
|
definition pointed to a <code>require</code>d file.
|
299
296
|
|
300
|
-
|
297
|
+
== About +require+
|
301
298
|
|
302
299
|
No measures have been taken to detect manipulations of
|
303
300
|
<code>$LOADED_FEATURES</code> which would cause +require+ to load the
|
304
301
|
same file twice. Though +require+ <em>could</em> be replaced in
|
305
|
-
similar fashion to +load
|
306
|
-
"raw" reloads
|
302
|
+
similar fashion to +load+---heading off problems arising from such
|
303
|
+
"raw" reloads---the overhead would seem inappropriate in relation to
|
307
304
|
the rarity of this case.
|
308
305
|
|
309
306
|
Therefore the working assumption is that +require+ will load a file
|
@@ -311,10 +308,11 @@ only once. Furthermore, if a file has not been reloaded then it is
|
|
311
308
|
assumed that the file is unmodified between the moment it is
|
312
309
|
<code>require</code>d and the moment the first AST is pulled from it.
|
313
310
|
|
314
|
-
|
311
|
+
== Backtraces
|
315
312
|
|
316
313
|
+ast_eval+ is meant to be compatible with +eval+. For instance the
|
317
|
-
first line of
|
314
|
+
first line of +ast_eval+'s backtrace should be identical to that of
|
315
|
+
+eval+:
|
318
316
|
|
319
317
|
require 'live_ast'
|
320
318
|
|
@@ -329,17 +327,17 @@ Let's make a slight change,
|
|
329
327
|
f.call
|
330
328
|
# => test.rb|ast@a:3:in `block in <main>': boom (RuntimeError)
|
331
329
|
|
332
|
-
|
330
|
+
What the heck is '<code>|ast@a</code>' doing there? LiveAST's
|
333
331
|
implementation has just been exposed: each source input is assigned a
|
334
|
-
unique key
|
332
|
+
unique key which enables a Ruby object to find its own definition.
|
335
333
|
|
336
334
|
In the first case above, +ast_eval+ has removed the key from the
|
337
335
|
exception backtrace. But in the second case there is no opportunity to
|
338
336
|
remove it since +ast_eval+ has already returned.
|
339
337
|
|
340
|
-
If you find this to be problem
|
341
|
-
for the jump-to-location feature in your editor
|
342
|
-
redefined to strip these tokens,
|
338
|
+
If you find this to be problem---for example if you cannot add a
|
339
|
+
filter for the jump-to-location feature in your editor---then +raise+
|
340
|
+
may be redefined to strip these tokens,
|
343
341
|
|
344
342
|
require 'live_ast'
|
345
343
|
require 'live_ast/replace_raise'
|
@@ -355,7 +353,7 @@ by <code>1/0</code> comes from C). In principle this could be fixed by
|
|
355
353
|
having the Ruby interpreter dynamically call +raise+.
|
356
354
|
|
357
355
|
|
358
|
-
|
356
|
+
== Replacing +eval+
|
359
357
|
|
360
358
|
If +ast_eval+ did not require a binding argument then it could assume
|
361
359
|
the role of +eval+, thereby making LiveAST fully transparent to the
|
data/Rakefile
CHANGED
@@ -1,21 +1,20 @@
|
|
1
1
|
require_relative 'devel/jumpstart'
|
2
2
|
|
3
3
|
Jumpstart.new "live_ast" do |s|
|
4
|
-
s.
|
4
|
+
s.developers << ["James M. Lawrence", "quixoticsycophant@gmail.com"]
|
5
5
|
s.github_user = "quix"
|
6
|
+
s.rubyforge_info = ["quix", "liveast"]
|
6
7
|
s.camel_name = "LiveAST"
|
7
|
-
s.rdoc_title = "LiveAST: Live Abstract Syntax Trees"
|
8
|
-
s.extra_rdoc_options = ["-a"]
|
9
|
-
|
10
|
-
# my code compensates for a ruby_parser bug; make this equal for now
|
11
|
-
s.dependency("ruby_parser", "= 2.0.6")
|
12
8
|
|
9
|
+
s.rdoc_title = "LiveAST: Live Abstract Syntax Trees"
|
13
10
|
s.rdoc_files = %w[
|
14
|
-
README.rdoc
|
15
11
|
lib/live_ast/ast_eval.rb
|
12
|
+
lib/live_ast/base.rb
|
16
13
|
lib/live_ast/to_ast.rb
|
17
14
|
lib/live_ast/to_ruby.rb
|
18
|
-
lib/live_ast/base.rb
|
19
15
|
lib/live_ast/version.rb
|
20
16
|
]
|
17
|
+
s.rdoc_options << "-a"
|
18
|
+
|
19
|
+
s.dependencies = ["live_ast_ruby_parser"]
|
21
20
|
end
|