= Rockit -- Ruby Object-oriented Compiler construction toolKIT

This package contains Rockit an object-oriented compiler construction 
toolKIT in/for Ruby.

NOTE! This README is incomplete and will be updated for the 0.7 release!!

Rockit has the following features:

* Scannerless Generalized LR Parsing with a fast C backend
   * Means: Can parse any context-free grammar and is still pretty fast
* Grammars are specified in Ruby so no special Grammar file format
   * Means: You can use your ordinary Ruby skills when writing grammars (=>
            shorter, more easily understandable, and powerful grammars)
* The actions taken during parsing can be easily changed by specifying Handler
    objects.
* Rockit can directly build the AST (Abstract Syntax Tree) for you
* AST classes can be pattern matched
* Rockit has a library for pretty-printing AST's

Svn id: $Id: README 131 2004-09-03 12:11:29Z robert_feldt $

== Download

The latest version of rockit can be found at

* http://www.pronovomundo.com/projects/rockit

Documentation can be found at 

* http://www.pronovomundo.com/projects/rockit/svn/doc

== Installation

=== Normal Installation

You can install rake with the following command.

  % rake install

from the top of its distribution directory. For this to work you need to have
rake installed and a C compiler (that Ruby knows of). If you don't have the 
latter you can install from prebuilt binaries, see below.

=== Installation from prebuilt binaries

To simplify installation rockit comes with prebuilt extensions so that you
can use it even if you have no C compiler installed. Rockit currently
comes with prebuilt extensions for cygwin and mingw32. Since the mswin32
platform uses the same format as the mingw32 platform you can use the
mingw32 files with the Ruby one-click installer.

To install from the prebuilt binaries for your platform and ruby version:

  % rake install_prebuilt
  % rake install_lib

Be sure to test your installation and report any problems since these
prebuilt installations have not had extensive testing.

=== Test the installation

You can test the installed rockit with the following command:

  % rake test

from the top of its distribution directory. For this to work you need to have
rake installed.

== Roadmap

* If you want to see how to invoke rockit to generate your own parsers, read on.
* If you want to see the format of a Rockit grammar file
  doc/rockitfile.rdoc[http://rockit.rubyforge.org/files/doc/rockitfile_rdoc.html].
* If you want to see a glossary of terms, see
  doc/glossary.rdoc[http://rockit.rubyforge.org/files/doc/glossary_rdoc.html].

== Simple Example

Once installed, you can use rockit as follows:

== Other Parser generators...

There are a large number of parser generators available for Ruby.
Here are links to other projects with similar (and not so similar) goals.

* Racc

== Credits

[<b>asdsad</b>] For the .

== License

Rockit is available under the GPL2 license.

:include: LICENSE

== Support

The Rockit homepage is http://.

For other information, feel free to ask on the ruby-talk mailing list
(which is mirrored to comp.lang.ruby) or contact
mailto:robert.feldt@pronovomundo.com.

----

= Usage

Rockit is invoked from the command line using:

   % rockit <options> [targets...]

Options are:

[<tt>--help</tt>  (-H)]
    Display some help text and exit.

[<tt>--quiet</tt> (-q)]
    Do not echo Sys commands.

[<tt>--trace</tt> (-t)]
    Turn on invoke/execute tracing.

[<tt>--usage</tt> (-h)]
    Display a usage message and exit.

[<tt>--verbose</tt> (-v)]
    Echo the Sys commands to standard output.

[<tt>--version</tt> (-V)]
    Display the program version and exit.

---

= Rockit grammar Format

See doc/grammar.rdoc[http://www.pronovomundo.com/projects/rockit/doc/grammar_rdoc.html]
for details on the Rockit grammar format.

---

= Other stuff

Author::   Robert Feldt <robert.feldt@pronovomundo.com>
Address::  Robert Feldt c/o ProNovoMundo
           Brolyckan 1
           433 69 Sävedalen
Requires:: Ruby 1.8.2 or later (might work but not tested with earlier version)
License::  Copyright (C) 2001-2004 by Robert Feldt
           Released under GNU General Public License 2. See the LICENSE file
           included in this distribution.

== License and Warranty

    Rockit - Ruby Object-oriented Compiler construction toolKIT
    Copyright (C) 2001-2004 by Robert Feldt

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA