• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1#!/usr/bin/ruby
2# encoding: utf-8
3
4=begin LICENSE
5
6[The "BSD licence"]
7Copyright (c) 2009-2010 Kyle Yetter
8All rights reserved.
9
10Redistribution and use in source and binary forms, with or without
11modification, are permitted provided that the following conditions
12are 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
22THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
23IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
25IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
26INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
27NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
31THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32
33=end
34
35=begin rdoc ANTLR3
36
37The main namespace for the ANTLR runtime libraries, which are used by
38Ruby-targeted recognizers generated by ANTLR. The entire library is segmented
39into several main components, as well as a few additional utility components,
40each contained within a separate script.
41
42== Library Components
43
44Not all components of the ANTLR3 library are necessary within ANTLR generated
45code. Some components are only used within specific types of recognizers and
46some are simply extra utilities for use by anyone working with ANTLR code. Thus,
47when requiring 'antlr3', only the essential core components are loaded
48immediately. The rest are configured to autoload when any of the constant names
49they define are referenced.
50
51The following list gives a brief introduction to each component of the ANTLR3
52runtime library. The items are loosely ordered by importance.
53
54antlr3/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
57antlr3/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
60antlr3/streams.rb::
61  defines the stream classes used by ANTLR recognizers to walk sequentially
62  through strings, tokens, and tree nodes loaded by default
63antlr3/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
67antlr3/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
71antlr3/constants.rb::
72  just a module used as a namespace for the named constant values used
73  throughout the library. loaded by default
74antlr3/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
79antlr3/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
84antlr3/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
89antlr3/tree-wizard.rb::
90  contains extra tools to easily construct ASTs by parsing descriptions written
91  in a special DSL
92antlr3/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
100module 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
198end  # module ANTLR3
199
200
201require 'set'
202require 'antlr3/util'
203require 'antlr3/version'
204
205unless $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'
212end
213