1 ANTLR 3 for Ruby 2 by Kyle Yetter (kcy5b (a] yahoo.com) 3 http://antlr.ohboyohboyohboy.org 4 http://github.com/ohboyohboyohboy/antlr3 5 6 == DESCRIPTION: 7 8 Fully-featured ANTLR 3 parser generation for Ruby. 9 10 ANTLR (ANother Tool for Language Recognition) is a tool that is used to generate 11 code for performing a variety of language recognition tasks: lexing, parsing, 12 abstract syntax tree construction and manipulation, tree structure recognition, 13 and input translation. The tool operates similarly to other parser generators, 14 taking in a grammar specification written in the special ANTLR metalanguage and 15 producing source code that implements the recognition functionality. 16 17 While the tool itself is implemented in Java, it has an extensible design that 18 allows for code generation in other programming languages. To implement an 19 ANTLR language target, a developer may supply a set of templates written in the 20 StringTemplate (http://www.stringtemplate.org) language. 21 22 ANTLR is currently distributed with a fairly limited Ruby target implementation. 23 While it does provide implementation for basic lexer and parser classes, the 24 target does not provide any implementation for abstract syntax tree 25 construction, tree parser class generation, input translation, or a number of 26 the other ANTLR features that give the program an edge over traditional code 27 generators. 28 29 This gem packages together a complete implementation of the majority of features 30 ANTLR provides for other language targets, such as Java and Python. It contains: 31 32 * A customized version of the latest ANTLR program, bundling all necessary 33 java code and templates for producing fully featured language recognition 34 in ruby code 35 36 * a ruby run-time library that collects classes used throughout the code that 37 ANTLR generates 38 39 * a wrapper script, `antlr4ruby', which executes the ANTLR command line tool 40 after ensuring the ANTLR jar is Java's class path 41 42 == FEATURES 43 44 1. generates ruby code capable of: 45 * lexing text input 46 * parsing lexical output and responding with arbitrary actions 47 * constructing Abstract Syntax Trees (ASTs) 48 * parsing AST structure and responding with arbitrary actions 49 * translating input source to some desired output format 50 51 2. This package can serve as a powerful assistant when performing tasks 52 such as: 53 * code compilation 54 * source code highlighting and formatting 55 * domain-specific language implementation 56 * source code extraction and analysis 57 58 == USAGE 59 60 1. Write an ANTLR grammar specification for a language 61 62 grammar SomeLanguage; 63 64 options { 65 language = Ruby; // <- this option must be set to Ruby 66 output = AST; 67 } 68 69 top: expr ( ',' expr )* 70 ; 71 72 and so on... 73 74 75 2. Run the ANTLR tool with the antlr4ruby command to generate output: 76 77 antlr4ruby SomeLanguage.g 78 # creates: 79 # SomeLanguageParser.rb 80 # SomeLanguageLexer.rb 81 # SomeLanguage.g 82 83 3. Try out the results directly, if you like: 84 85 # see how the lexer tokenizes some input 86 ruby SomeLanguageLexer.rb < path/to/source-code.xyz 87 88 # check whether the parser successfully matches some input 89 ruby SomeLanguageParser.rb --rule=top < path/to/source-code.xyz 90 91 -> Read up on the package documentation for more specific details 92 about loading the recognizers and using their class definitions 93 94 == ISSUES 95 96 * Currently, there are a few nuanced ways in which using the ruby output differs 97 from the conventions and examples covered in the ANTLR standard documentation. 98 I am still working on documenting these details. 99 100 * So far, this has only been tested on Linux with ruby 1.8.7 and ruby 1.9.1. 101 I'm currently working on verifying behavior on other systems and with 102 slightly older versions of ruby. 103 104 == LICENSE 105 106 [The "BSD license"] 107 Copyright (c) 2009-2010 Kyle Yetter 108 All rights reserved. 109 110 Redistribution and use in source and binary forms, with or without 111 modification, are permitted provided that the following conditions 112 are met: 113 114 1. Redistributions of source code must retain the above copyright 115 notice, this list of conditions and the following disclaimer. 116 2. Redistributions in binary form must reproduce the above copyright 117 notice, this list of conditions and the following disclaimer in the 118 documentation and/or other materials provided with the distribution. 119 3. The name of the author may not be used to endorse or promote products 120 derived from this software without specific prior written permission. 121 122 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 123 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 124 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 125 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 126 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 127 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 128 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 129 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 130 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 131 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 132 133
