Rulator - RUby LAnguage TOols in Ruby
=====================================
Version:          0.1.0
Release date:     2001-12-07
Home page:        http://rockit.sf.net/
Tarball:          http://prdownloads.sf.net/rockit/rockit-0-3-9.tar.gz
Authors:          Robert Feldt and Rich Kilmer
Email:            feldt@ce.chalmers.se

What is it?
-----------
A Ruby parser written in Ruby. 

Gives you an abstract syntax tree (AST) of a Ruby program but can also 
be used as an "event parser" and call methods of an object you supply 
in response to tokens and parse events.

When building an AST the parser retains the comments as attributes on the
AST nodes/terms.

Why?
----
Having a Ruby parser is required in many applications that work on Ruby
code such as interpreters, compilers, documenters, pretty-printers, 
analysers etc.

It can be a base for experiments with Ruby and its syntax.

Installation?
-------------
1. Unpack tarball (if you haven't already)
2. Install Rockit (see its README)
2. Run tests: ruby -I./lib tests/runtests.rb       (OPTIONAL)
3. Install Rulator:   ruby install.rb

You can uninstall with: ruby install.rb --uninstall

NOTE: Right now Rulator and Rockit is not fully ready for distribution so
you'll need to do

cd lib/rulator
make
cd ../..
ruby -I../../lib -Ilib -Itests tests/alltests.rb

in order to run the tests when standing in the Rulator root dir. This is
temporary and will be solved for the 0.4 release.

Example of use?
---------------
Coming up... ;-)

For now check out the tests.

Requirements?
-------------
Ruby >= 1.7.0, Rockit >= 0.3.9. 

You will need Racc >= 1.4.0 if you want to rebuild the parser.

Rulator is a part of Rockit and is not distributed separately. This might
change as it matures. It currently requires that you have installed
Racc if you want to rebuld the parser. However, this should not be 
necessary since a pre-built version is included. The pre-built version
includes the needed Racc code so if you're only planning to use the
parser you should not need Racc.

NOTE THAT THIS IS AN ALPHA RELEASE SO THERE WILL LIKELY BE BUGS. And the API 
will probably change in future versions.

Documentation?
--------------
None yet. But you can look at the tests.

CVS archives?
-------------
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/rockit/examples/ruby

License and legal issues?
-------------------------
Rulator is

Copyright (c) 2001 Robert Feldt, feldt@ce.chalmers.se.
All rights reserved.

and is distributed under GPL. See LICENSE. But note that the parser is
a modified copy of Matz parse.y so the credits should be his.

Acknowledgements?
-----------------
Thanks to matz for Ruby.

Thanks to Rich Kilmer for writing test code. Without you, Rich, this would
have taken forever...

Thanks to Marcus Liedl and Mathieu Bouchard for discussions and code
relating to RubyInRuby parsers. The parser.y file is very much based on Matz
parse.y and very similar Marcus Liedls raccification of it since we took
the same approach: translating Matz parse.y so that it could be used with
Racc. However, I used Rockit to build the lexer while Marcus ported Matz
yylex function.

Thanks to Dave Thomas for ideas on the API for a RiR parser.

Special things to note?
-----------------------
This has been based on Ruby 1.6.5 so probably small variations to later
Ruby versions. Please report anything you find so that we can update it!

The parser and lexer is currently slow but there are a number of known
inefficiences with known solutions so don't worry too much about that.
They will be in there in time. I figured its better to release sooner than
later.

Do you have comments or questions?
----------------------------------
I'd appreciate if you drop me a note if you're successfully using 
Rulator. 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, feldt@ce.chalmers.se
