module ANTLR3

The main namespace for the ANTLR runtime libraries, which are used by Ruby-targeted recognizers generated by ANTLR. The entire library is segmented into several main components, as well as a few additional utility components, each contained within a separate script.

Library Components¶ ↑

Not all components of the ANTLR3 library are necessary within ANTLR generated code. Some components are only used within specific types of recognizers and some are simply extra utilities for use by anyone working with ANTLR code. Thus, when requiring ‘antlr3’, only the essential core components are loaded immediately. The rest are configured to autoload when any of the constant names they define are referenced.

The following list gives a brief introduction to each component of the ANTLR3 runtime library. The items are loosely ordered by importance.

antlr3/recognizers.rb: contains the base classes for ANTLR-generated recognizers, and thus, is one of the most important components of the runtime library. loaded by default
antlr3/dfa.rb: defines a single DFA class that is used to simulate state machines for certain decisions recognizers must make in code generated by ANTLR
antlr3/streams.rb: defines the stream classes used by ANTLR recognizers to walk sequentially through strings, tokens, and tree nodes loaded by default
antlr3/token.rb: contains all modules and classes concerned with making tokens, the chunks of text and symbol information produced by lexers and used by parsers and ASTs loaded by default
antlr3/error.rb: defines the Error module, which contains definitions for most of the many error classes used through the runtime library and ANTLR generated recognizers. loaded by default
antlr3/constants.rb: just a module used as a namespace for the named constant values used throughout the library. loaded by default
antlr3/tree.rb: contains everything pertaining to Abstract Syntax Trees (ASTs). This script is not loaded by default when ‘antlr3’ is required, but it is autloaded on demand when any constant defined in the script is referenced. contents are autoloaded on demand
antlr3/debug.rb: when code is generated by ANTLR using the ‘-debug’ option, all of the additional classes and mixins required by the debug code are contained within the Debug module defined by this library. the Debug module is autoloaded on demand
antlr3/main.rb: defines the Main module. When ANTLR-generated recognizer code is run directly as a script (not loaded as a module), the code will behave as a full command-line script by using functionality implemented in the Main module. the Main module is autloaded on demand
antlr3/tree-wizard.rb: contains extra tools to easily construct ASTs by parsing descriptions written in a special DSL
antlr3/dot.rb: extra utilities to generate DOT map specifications for graphical. representations of ASTs

@author Kyle Yetter

The “BSD licence”

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.

The “BSD licence”

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.

The “BSD licence”

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.

ANTLR3 exception hierarchy

ported from the ANTLR3 Python Runtime library by Kyle Yetter (kcy5b@yahoo.com)

The “BSD licence”

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.

The “BSD licence”

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.

The “BSD licence”

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.

The “BSD licence”

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.

author: Kyle Yetter <kcy5b@yahoo.com> created on: October 22, 2011 purpose: (program | library | utility script | ?) summary:

loads: files required by this autoloads: autoload entries in this (e.g. YAML(yaml))

- - - - begin action @lexer::header - - - - - -

GroupFile.g

- - - - begin action @parser::header - - - - - -

GroupFile.g

The “BSD licence”

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.

The “BSD licence”

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.

Constants

ANTLR_MAJOR_VERSION

The version of the ANTLR tool used while designing and testing the current version of this library

ANTLR_MINOR_VERSION

ANTLR_PATCH_VERSION

ANTLR_VERSION

ANTLR_VERSION_STRING

BaseRecognizer

`Recognizer`¶ ↑

As the base class of all ANTLR-generated recognizers, Recognizer provides much of the shared functionality and structure used in the recognition process. For all effective purposes, the class and its immediate subclasses Lexer, Parser, and TreeParser are abstract classes. They can be instantiated, but they’re pretty useless on their own. Instead, to make useful code, you write an ANTLR grammar and ANTLR will generate classes which inherit from one of the recognizer base classes, providing the implementation of the grammar rules itself. this group of classes to implement necessary tasks. Recognizer defines methods related to:

token and character matching
prediction and recognition strategy
recovering from errors
reporting errors
memoization
simple rule tracing and debugging

CommonToken

MAJOR_VERSION

The version data for the current state the library itself

MINOR_VERSION

PATCH_VERSION

RecognizerSharedState

StopIteration

VERSION

VERSION_STRING

Public Class Methods

antlr_jar() click to toggle source

# File lib/antlr3.rb, line 144
def self.antlr_jar
  @antlr_jar and return( @antlr_jar )
  
  path = data_path "antlr-full-#{ ANTLR_VERSION_STRING }.jar"
  if env_path = ENV[ 'RUBY_ANTLR_JAR' ]
    if File.file?( env_path ) then return File.expand_path( env_path ) end
    
    warn( 
      "#{ __FILE__ }:#{ __LINE__ }: " <<
      "ignoring environmental variable RUBY_ANTLR_JAR (=%p) " % env_path <<
      "as it is not the path to an existing file\n" <<
      "  -> trying default jar path %p instead" % path
    )
  end
  
  File.exists?( path ) ? path : nil
end

antlr_jar=( path ) click to toggle source

# File lib/antlr3.rb, line 140
def self.antlr_jar=( path )
  @antlr_jar = path ? File.expand_path( path.to_s ) : path
end

bug!( message = nil ) click to toggle source

This is used internally in a handful of locations in the runtime library where assumptions have been made that a condition will never happen under normal usage conditions and thus an ANTLR3::Bug error will be raised if the condition does occur.

# File lib/antlr3.rb, line 132
def self.bug!( message = nil )
  bug = Bug.new( message )
  bug.set_backtrace( caller )
  raise( bug )
end

data_path( *args ) click to toggle source

Returns the lpath for the module. If any arguments are given, they will be joined to the end of the path using File.join.

# File lib/antlr3.rb, line 124
def self.data_path( *args )
  ::File.expand_path( ::File.join( DATA_PATH, *args ) )
end

library_path( *args ) click to toggle source

Returns the library path for the module. If any arguments are given, they will be joined to the end of the libray path using File.join.

# File lib/antlr3.rb, line 116
def self.library_path( *args )
  ::File.expand_path( ::File.join( LIBRARY_PATH, *args ) )
end

module ANTLR3

Library Components¶ ↑

Recognizer¶ ↑

`Recognizer`¶ ↑