You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
133 lines
5.1 KiB
133 lines
5.1 KiB
ANTLR 3 for Ruby
|
|
by Kyle Yetter (kcy5b@yahoo.com)
|
|
http://antlr.ohboyohboyohboy.org
|
|
http://github.com/ohboyohboyohboy/antlr3
|
|
|
|
== DESCRIPTION:
|
|
|
|
Fully-featured ANTLR 3 parser generation for Ruby.
|
|
|
|
ANTLR (ANother Tool for Language Recognition) is a tool that is used to generate
|
|
code for performing a variety of language recognition tasks: lexing, parsing,
|
|
abstract syntax tree construction and manipulation, tree structure recognition,
|
|
and input translation. The tool operates similarly to other parser generators,
|
|
taking in a grammar specification written in the special ANTLR metalanguage and
|
|
producing source code that implements the recognition functionality.
|
|
|
|
While the tool itself is implemented in Java, it has an extensible design that
|
|
allows for code generation in other programming languages. To implement an
|
|
ANTLR language target, a developer may supply a set of templates written in the
|
|
StringTemplate (http://www.stringtemplate.org) language.
|
|
|
|
ANTLR is currently distributed with a fairly limited Ruby target implementation.
|
|
While it does provide implementation for basic lexer and parser classes, the
|
|
target does not provide any implementation for abstract syntax tree
|
|
construction, tree parser class generation, input translation, or a number of
|
|
the other ANTLR features that give the program an edge over traditional code
|
|
generators.
|
|
|
|
This gem packages together a complete implementation of the majority of features
|
|
ANTLR provides for other language targets, such as Java and Python. It contains:
|
|
|
|
* A customized version of the latest ANTLR program, bundling all necessary
|
|
java code and templates for producing fully featured language recognition
|
|
in ruby code
|
|
|
|
* a ruby run-time library that collects classes used throughout the code that
|
|
ANTLR generates
|
|
|
|
* a wrapper script, `antlr4ruby', which executes the ANTLR command line tool
|
|
after ensuring the ANTLR jar is Java's class path
|
|
|
|
== FEATURES
|
|
|
|
1. generates ruby code capable of:
|
|
* lexing text input
|
|
* parsing lexical output and responding with arbitrary actions
|
|
* constructing Abstract Syntax Trees (ASTs)
|
|
* parsing AST structure and responding with arbitrary actions
|
|
* translating input source to some desired output format
|
|
|
|
2. This package can serve as a powerful assistant when performing tasks
|
|
such as:
|
|
* code compilation
|
|
* source code highlighting and formatting
|
|
* domain-specific language implementation
|
|
* source code extraction and analysis
|
|
|
|
== USAGE
|
|
|
|
1. Write an ANTLR grammar specification for a language
|
|
|
|
grammar SomeLanguage;
|
|
|
|
options {
|
|
language = Ruby; // <- this option must be set to Ruby
|
|
output = AST;
|
|
}
|
|
|
|
top: expr ( ',' expr )*
|
|
;
|
|
|
|
and so on...
|
|
|
|
|
|
2. Run the ANTLR tool with the antlr4ruby command to generate output:
|
|
|
|
antlr4ruby SomeLanguage.g
|
|
# creates:
|
|
# SomeLanguageParser.rb
|
|
# SomeLanguageLexer.rb
|
|
# SomeLanguage.g
|
|
|
|
3. Try out the results directly, if you like:
|
|
|
|
# see how the lexer tokenizes some input
|
|
ruby SomeLanguageLexer.rb < path/to/source-code.xyz
|
|
|
|
# check whether the parser successfully matches some input
|
|
ruby SomeLanguageParser.rb --rule=top < path/to/source-code.xyz
|
|
|
|
-> Read up on the package documentation for more specific details
|
|
about loading the recognizers and using their class definitions
|
|
|
|
== ISSUES
|
|
|
|
* Currently, there are a few nuanced ways in which using the ruby output differs
|
|
from the conventions and examples covered in the ANTLR standard documentation.
|
|
I am still working on documenting these details.
|
|
|
|
* So far, this has only been tested on Linux with ruby 1.8.7 and ruby 1.9.1.
|
|
I'm currently working on verifying behavior on other systems and with
|
|
slightly older versions of ruby.
|
|
|
|
== LICENSE
|
|
|
|
[The "BSD license"]
|
|
Copyright (c) 2009-2010 Kyle Yetter
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
2. Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
3. The name of the author may not be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|