From: Robert Feldt Date: 2003-08-22T23:09:47+09:00 Subject: [ANN] Ruth 0.10 Here is a new version of ruth. Please see README below for more info. Regards, -- Robert Feldt ============================== = Ruth - Ruby Under The Hood = = version 0.10 = ============================== Date: $Date: 2003-08-22 11:17:26 +0200 (Fri, 22 Aug 2003) $ Version: 0.10 Svn revision: $Rev: 36 $ Available from: http://pronovomundo.dyndns.org/temp/ruth Author: Robert Feldt, robert@pronovomundo.com NOTE! The link is temporary until I get my server setup properly. NOTE! I don't use the CVS on sourceforge anymore so the code in the CVS repository there is OBSOLETE! Since the version on sf has wrongly been assigned the version number 0.8.0 I jumped to version 0.9 at one point even though its not yet very close to a 1.0 release. What is it? ----------- Ruby extension giving classes and functions to access Ruby internals. Currently includes: * ruby/interpreter/parse, Ruby::Interpreter.parse Gives a tree representing the internal parse tree used to execute a Ruby program. * ruby/interpreter/parse, Ruby::Interpreter.method_body Returns the tree for the body of a method. And an incomplete: * ruby/parse, Ruby.parse Parse Ruby source code into an abstract syntax tree. Its a cheato-RubyInRuby parser since it looks like one but actually uses Ruby::Interpreter.parse and then simply transforms the output. Advantage of this is that it parses exactly the same programs as matz Ruby interpreter parses (since it uses the same parser). Disadvantage is that it relies on C code, returns nil on parse error, isn't customizable etc. Note that the Ruby.parse can never be "complete" since irrelevant info is dropped by matz interpreter and is not available in the internal parse tree (and thus cannot be "resurrected" later). An example is def m(a) 1 end in which the internal parse tree does not contain any reference to the argument named "a" since it is never used (at least this was the behavior least time I looked which was a couple of months back so it might have changed...). All information that is relevant to executing the code must be available though so should be enough for many uses. Why? ---- To learn about MRI (Matz Ruby Interpreter) internals its good to be able to dump and view its internal representation of Ruby programs. To write tools that work with Ruby source code its good to have a parser. To develop a parser its good to have a reference to compare to; Ruby.parse is a good such reference (once its completed). Installation? ------------- 1. unpack tarball (if you haven't already) 2. ruby helpers/make.rb 3. ruby helpers/install.rb 4. ruby tests/run_all_tests.rb (optional) Example of use? --------------- require 'ruby/parse' p Ruby.parse("a = 1") # => LocalAssign[:a, IntegerLiteral[1]] Requirements? ------------- ANSI C compiler and Ruby. I've successfully compiled and used Ruth with * Ruby 1.8.0 (2003-08-04) + cygwin 1.3.22 (gcc version 3.2 20020927) on Windows XP Pro. * Ruby 1.8.0 (2003-08-04) + gcc 3.2.3 20030422 on Linux 2.4.22 (Gentoo) If it works for you on other platforms/setups I'd appreciate if you drop me a note. However, it should work on most Ruby-enabled platforms having a C compiler. NOTE THAT THIS IS AN ALPHA RELEASE SO THERE WILL LIKELY BE BUGS. Please report bugs to ruth@pronovomundo.com Documentation? -------------- None yet. License and legal issues? ------------------------- All files in this package are coyrighted free software Copyright (c) 2001, 2002, 2003 Robert Feldt, robert@pronovomundo.com All rights reserved. and they are distributed under LGPL. See LICENSE. Acknowledgements for ruth/mri should go to Dave Thomas and Andy Hunt since I've basically generalized their NodeDump extension. I'd also like to thank George Marrows and Rich Kilmer for patches and encouragement. Special things to note? ----------------------- Most of this package is highly implementation specific. If matz changes the internals of the interpreter things might stop working. Beware! There might be safety issues with accessing the internals... There are known bugs (for example the line number counting is faulty) and the tests are *VERY* incomplete. This was a hack that has grown so (unfortunately) I didn't do any test-first development. I've since learned that its always a good idea to write things test-first... ;) Plans for the future? --------------------- See TODO. This is an alpha release so there will probably be changes to the API. Do you have comments or questions? ---------------------------------- I'd appreciate if you drop me a note if you're successfully using Ruth. If there are some known users I'll be more motivated to packing up additions / new versions and post them to RAA. Happy coding! Robert Feldt, robert@pronovomundo.com