1324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverANTLR 3 for Ruby 2324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver by Kyle Yetter (kcy5b@yahoo.com) 3324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver http://antlr.ohboyohboyohboy.org 4324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver http://github.com/ohboyohboyohboy/antlr3 5324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 6324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver== DESCRIPTION: 7324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 8324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverFully-featured ANTLR 3 parser generation for Ruby. 9324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 10324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverANTLR (ANother Tool for Language Recognition) is a tool that is used to generate 11324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruvercode for performing a variety of language recognition tasks: lexing, parsing, 12324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverabstract syntax tree construction and manipulation, tree structure recognition, 13324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverand input translation. The tool operates similarly to other parser generators, 14324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruvertaking in a grammar specification written in the special ANTLR metalanguage and 15324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverproducing source code that implements the recognition functionality. 16324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 17324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverWhile the tool itself is implemented in Java, it has an extensible design that 18324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverallows for code generation in other programming languages. To implement an 19324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverANTLR language target, a developer may supply a set of templates written in the 20324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverStringTemplate (http://www.stringtemplate.org) language. 21324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 22324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverANTLR is currently distributed with a fairly limited Ruby target implementation. 23324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverWhile it does provide implementation for basic lexer and parser classes, the 24324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruvertarget does not provide any implementation for abstract syntax tree 25324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverconstruction, tree parser class generation, input translation, or a number of 26324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverthe other ANTLR features that give the program an edge over traditional code 27324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruvergenerators. 28324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 29324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverThis gem packages together a complete implementation of the majority of features 30324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverANTLR provides for other language targets, such as Java and Python. It contains: 31324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 32324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver* A customized version of the latest ANTLR program, bundling all necessary 33324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver java code and templates for producing fully featured language recognition 34324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver in ruby code 35324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 36324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver* a ruby run-time library that collects classes used throughout the code that 37324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver ANTLR generates 38324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 39324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver* a wrapper script, `antlr4ruby', which executes the ANTLR command line tool 40324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver after ensuring the ANTLR jar is Java's class path 41324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 42324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver== FEATURES 43324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 44324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver1. generates ruby code capable of: 45324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * lexing text input 46324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * parsing lexical output and responding with arbitrary actions 47324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * constructing Abstract Syntax Trees (ASTs) 48324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * parsing AST structure and responding with arbitrary actions 49324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * translating input source to some desired output format 50324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 51324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver2. This package can serve as a powerful assistant when performing tasks 52324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver such as: 53324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * code compilation 54324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * source code highlighting and formatting 55324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * domain-specific language implementation 56324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver * source code extraction and analysis 57324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 58324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver== USAGE 59324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 60324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver1. Write an ANTLR grammar specification for a language 61324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 62324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver grammar SomeLanguage; 63324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 64324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver options { 65324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver language = Ruby; // <- this option must be set to Ruby 66324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver output = AST; 67324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver } 68324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 69324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver top: expr ( ',' expr )* 70324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver ; 71324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 72324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver and so on... 73324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 74324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 75324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver2. Run the ANTLR tool with the antlr4ruby command to generate output: 76324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 77324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver antlr4ruby SomeLanguage.g 78324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # creates: 79324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # SomeLanguageParser.rb 80324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # SomeLanguageLexer.rb 81324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # SomeLanguage.g 82324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 83324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver3. Try out the results directly, if you like: 84324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 85324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # see how the lexer tokenizes some input 86324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver ruby SomeLanguageLexer.rb < path/to/source-code.xyz 87324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 88324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver # check whether the parser successfully matches some input 89324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver ruby SomeLanguageParser.rb --rule=top < path/to/source-code.xyz 90324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 91324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver-> Read up on the package documentation for more specific details 92324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver about loading the recognizers and using their class definitions 93324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 94324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver== ISSUES 95324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 96324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver* Currently, there are a few nuanced ways in which using the ruby output differs 97324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver from the conventions and examples covered in the ANTLR standard documentation. 98324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver I am still working on documenting these details. 99324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 100324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver* So far, this has only been tested on Linux with ruby 1.8.7 and ruby 1.9.1. 101324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver I'm currently working on verifying behavior on other systems and with 102324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver slightly older versions of ruby. 103324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 104324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver== LICENSE 105324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 106324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver[The "BSD license"] 107324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverCopyright (c) 2009-2010 Kyle Yetter 108324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverAll rights reserved. 109324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 110324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverRedistribution and use in source and binary forms, with or without 111324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruvermodification, are permitted provided that the following conditions 112324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruverare met: 113324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 114324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 1. Redistributions of source code must retain the above copyright 115324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver notice, this list of conditions and the following disclaimer. 116324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 2. Redistributions in binary form must reproduce the above copyright 117324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver notice, this list of conditions and the following disclaimer in the 118324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver documentation and/or other materials provided with the distribution. 119324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 3. The name of the author may not be used to endorse or promote products 120324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver derived from this software without specific prior written permission. 121324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 122324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverTHIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 123324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 124324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverOF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 125324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverIN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 126324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverINCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 127324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverNOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 128324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 129324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 130324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 131324c4644fee44b9898524c09511bd33c3f12e2dfBen GruverTHIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 132324c4644fee44b9898524c09511bd33c3f12e2dfBen Gruver 133