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