1 #!/usr/bin/ruby 2 # encoding: utf-8 3 4 =begin LICENSE 5 6 [The "BSD licence"] 7 Copyright (c) 2009-2010 Kyle Yetter 8 All rights reserved. 9 10 Redistribution and use in source and binary forms, with or without 11 modification, are permitted provided that the following conditions 12 are met: 13 14 1. Redistributions of source code must retain the above copyright 15 notice, this list of conditions and the following disclaimer. 16 2. Redistributions in binary form must reproduce the above copyright 17 notice, this list of conditions and the following disclaimer in the 18 documentation and/or other materials provided with the distribution. 19 3. The name of the author may not be used to endorse or promote products 20 derived from this software without specific prior written permission. 21 22 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 33 =end 34 35 =begin rdoc ANTLR3 36 37 The main namespace for the ANTLR runtime libraries, which are used by 38 Ruby-targeted recognizers generated by ANTLR. The entire library is segmented 39 into several main components, as well as a few additional utility components, 40 each contained within a separate script. 41 42 == Library Components 43 44 Not all components of the ANTLR3 library are necessary within ANTLR generated 45 code. Some components are only used within specific types of recognizers and 46 some are simply extra utilities for use by anyone working with ANTLR code. Thus, 47 when requiring 'antlr3', only the essential core components are loaded 48 immediately. The rest are configured to autoload when any of the constant names 49 they define are referenced. 50 51 The following list gives a brief introduction to each component of the ANTLR3 52 runtime library. The items are loosely ordered by importance. 53 54 antlr3/recognizers.rb:: 55 contains the base classes for ANTLR-generated recognizers, and thus, is one of 56 the most important components of the runtime library. loaded by default 57 antlr3/dfa.rb:: 58 defines a single DFA class that is used to simulate state machines for certain 59 decisions recognizers must make in code generated by ANTLR 60 antlr3/streams.rb:: 61 defines the stream classes used by ANTLR recognizers to walk sequentially 62 through strings, tokens, and tree nodes loaded by default 63 antlr3/token.rb:: 64 contains all modules and classes concerned with making tokens, the chunks of 65 text and symbol information produced by lexers and used by parsers and ASTs 66 loaded by default 67 antlr3/error.rb:: 68 defines the Error module, which contains definitions for most of the many 69 error classes used through the runtime library and ANTLR generated 70 recognizers. loaded by default 71 antlr3/constants.rb:: 72 just a module used as a namespace for the named constant values used 73 throughout the library. loaded by default 74 antlr3/tree.rb:: 75 contains everything pertaining to Abstract Syntax Trees (ASTs). This script is 76 not loaded by default when 'antlr3' is required, but it is autloaded on demand 77 when any constant defined in the script is referenced. contents are autoloaded 78 on demand 79 antlr3/debug.rb:: 80 when code is generated by ANTLR using the '-debug' option, all of the 81 additional classes and mixins required by the debug code are contained within 82 the Debug module defined by this library. the Debug module is autoloaded on 83 demand 84 antlr3/main.rb:: 85 defines the Main module. When ANTLR-generated recognizer code is run directly 86 as a script (not loaded as a module), the code will behave as a full 87 command-line script by using functionality implemented in the Main module. the 88 Main module is autloaded on demand 89 antlr3/tree-wizard.rb:: 90 contains extra tools to easily construct ASTs by parsing descriptions written 91 in a special DSL 92 antlr3/dot.rb:: 93 extra utilities to generate DOT map specifications for graphical. 94 representations of ASTs 95 96 @author Kyle Yetter 97 98 =end 99 100 module ANTLR3 101 102 # :stopdoc: 103 # BEGIN PATHS -- do not modify 104 105 LIBRARY_PATH = ::File.expand_path( ::File.dirname( __FILE__ ) ).freeze 106 PROJECT_PATH = ::File.dirname( LIBRARY_PATH ).freeze 107 DATA_PATH = ::File.join( PROJECT_PATH, 'java' ).freeze 108 109 # END PATHS 110 # :startdoc: 111 112 # Returns the library path for the module. If any arguments are given, 113 # they will be joined to the end of the libray path using 114 # <tt>File.join</tt>. 115 # 116 def self.library_path( *args ) 117 ::File.expand_path( ::File.join( LIBRARY_PATH, *args ) ) 118 end 119 120 # Returns the lpath for the module. If any arguments are given, 121 # they will be joined to the end of the path using 122 # <tt>File.join</tt>. 123 # 124 def self.data_path( *args ) 125 ::File.expand_path( ::File.join( DATA_PATH, *args ) ) 126 end 127 128 # This is used internally in a handful of locations in the runtime library 129 # where assumptions have been made that a condition will never happen 130 # under normal usage conditions and thus an ANTLR3::Bug error will be 131 # raised if the condition does occur. 132 def self.bug!( message = nil ) 133 bug = Bug.new( message ) 134 bug.set_backtrace( caller ) 135 raise( bug ) 136 end 137 138 @antlr_jar = nil 139 140 def self.antlr_jar=( path ) 141 @antlr_jar = path ? File.expand_path( path.to_s ) : path 142 end 143 144 def self.antlr_jar 145 @antlr_jar and return( @antlr_jar ) 146 147 path = data_path "antlr-full-#{ ANTLR_VERSION_STRING }.jar" 148 if env_path = ENV[ 'RUBY_ANTLR_JAR' ] 149 if File.file?( env_path ) then return File.expand_path( env_path ) end 150 151 warn( 152 "#{ __FILE__ }:#{ __LINE__ }: " << 153 "ignoring environmental variable RUBY_ANTLR_JAR (=%p) " % env_path << 154 "as it is not the path to an existing file\n" << 155 " -> trying default jar path %p instead" % path 156 ) 157 end 158 159 File.exists?( path ) ? path : nil 160 end 161 162 ############################################################################################## 163 ############################### Namespace and Load Path Setup ################################ 164 ############################################################################################## 165 166 # Tree classes are only used by tree parsers or AST-building parsers 167 # Thus, they're not essential for everything ANTLR generates and 168 # are autoloaded on-demand 169 autoload :AST, 'antlr3/tree' 170 171 tree_classes = [ 172 :Tree, :TreeAdaptor, :BaseTree, :BaseTreeAdaptor, 173 :CommonTree, :CommonErrorNode, :CommonTreeAdaptor, 174 :TreeNodeStream, :CommonTreeNodeStream, :TreeParser, 175 :TreeVisitor, :RewriteRuleElementStream, 176 :RewriteRuleTokenStream, :RewriteRuleSubtreeStream, 177 :RewriteRuleNodeStream 178 ] 179 180 for klass in tree_classes 181 autoload klass, 'antlr3/tree' 182 end 183 184 # Set up non-essential components to be loaded on-demand 185 autoload :TokenRewriteStream, 'antlr3/streams/rewrite' 186 autoload :FilterMode, 'antlr3/modes/filter' 187 autoload :ASTBuilder, 'antlr3/modes/ast-builder' 188 autoload :Main, 'antlr3/main' 189 autoload :Debug, 'antlr3/debug' 190 autoload :Profile, 'antlr3/profile' 191 autoload :DOT, 'antlr3/dot' 192 autoload :InteractiveStringStream, 'antlr3/streams/interactive' 193 194 autoload :Template, 'antlr3/template' 195 196 $LOAD_PATH.include?( library_path ) or $LOAD_PATH.unshift( library_path ) 197 198 end # module ANTLR3 199 200 201 require 'set' 202 require 'antlr3/util' 203 require 'antlr3/version' 204 205 unless $0 == 'antlr4ruby' 206 require 'antlr3/constants' 207 require 'antlr3/error' 208 require 'antlr3/token' 209 require 'antlr3/recognizers' 210 require 'antlr3/dfa' 211 require 'antlr3/streams' 212 end 213
