1""" @package antlr3
2@brief ANTLR3 runtime package
3
4This module contains all support classes, which are needed to use recognizers
5generated by ANTLR3.
6
7@mainpage
8
9\\note Please be warned that the line numbers in the API documentation do not
10match the real locations in the source code of the package. This is an
11unintended artifact of doxygen, which I could only convince to use the
12correct module names by concatenating all files from the package into a single
13module file...
14
15Here is a little overview over the most commonly used classes provided by
16this runtime:
17
18@section recognizers Recognizers
19
20These recognizers are baseclasses for the code which is generated by ANTLR3.
21
22- BaseRecognizer: Base class with common recognizer functionality.
23- Lexer: Base class for lexers.
24- Parser: Base class for parsers.
25- tree.TreeParser: Base class for %tree parser.
26
27@section streams Streams
28
29Each recognizer pulls its input from one of the stream classes below. Streams
30handle stuff like buffering, look-ahead and seeking.
31
32A character stream is usually the first element in the pipeline of a typical
33ANTLR3 application. It is used as the input for a Lexer.
34
35- ANTLRStringStream: Reads from a string objects. The input should be a unicode
36  object, or ANTLR3 will have trouble decoding non-ascii data.
37- ANTLRFileStream: Opens a file and read the contents, with optional character
38  decoding.
39- ANTLRInputStream: Reads the date from a file-like object, with optional
40  character decoding.
41
42A Parser needs a TokenStream as input (which in turn is usually fed by a
43Lexer):
44
45- CommonTokenStream: A basic and most commonly used TokenStream
46  implementation.
47- TokenRewriteStream: A modification of CommonTokenStream that allows the
48  stream to be altered (by the Parser). See the 'tweak' example for a usecase.
49
50And tree.TreeParser finally fetches its input from a tree.TreeNodeStream:
51
52- tree.CommonTreeNodeStream: A basic and most commonly used tree.TreeNodeStream
53  implementation.
54
55
56@section tokenstrees Tokens and Trees
57
58A Lexer emits Token objects which are usually buffered by a TokenStream. A
59Parser can build a Tree, if the output=AST option has been set in the grammar.
60
61The runtime provides these Token implementations:
62
63- CommonToken: A basic and most commonly used Token implementation.
64- ClassicToken: A Token object as used in ANTLR 2.x, used to %tree
65  construction.
66
67Tree objects are wrapper for Token objects.
68
69- tree.CommonTree: A basic and most commonly used Tree implementation.
70
71A tree.TreeAdaptor is used by the parser to create tree.Tree objects for the
72input Token objects.
73
74- tree.CommonTreeAdaptor: A basic and most commonly used tree.TreeAdaptor
75implementation.
76
77
78@section Exceptions
79
80RecognitionException are generated, when a recognizer encounters incorrect
81or unexpected input.
82
83- RecognitionException
84  - MismatchedRangeException
85  - MismatchedSetException
86    - MismatchedNotSetException
87    .
88  - MismatchedTokenException
89  - MismatchedTreeNodeException
90  - NoViableAltException
91  - EarlyExitException
92  - FailedPredicateException
93  .
94.
95
96A tree.RewriteCardinalityException is raised, when the parsers hits a
97cardinality mismatch during AST construction. Although this is basically a
98bug in your grammar, it can only be detected at runtime.
99
100- tree.RewriteCardinalityException
101  - tree.RewriteEarlyExitException
102  - tree.RewriteEmptyStreamException
103  .
104.
105
106"""
107
108# tree.RewriteRuleElementStream
109# tree.RewriteRuleSubtreeStream
110# tree.RewriteRuleTokenStream
111# CharStream
112# DFA
113# TokenSource
114
115# [The "BSD licence"]
116# Copyright (c) 2005-2012 Terence Parr
117# All rights reserved.
118#
119# Redistribution and use in source and binary forms, with or without
120# modification, are permitted provided that the following conditions
121# are met:
122# 1. Redistributions of source code must retain the above copyright
123#    notice, this list of conditions and the following disclaimer.
124# 2. Redistributions in binary form must reproduce the above copyright
125#    notice, this list of conditions and the following disclaimer in the
126#    documentation and/or other materials provided with the distribution.
127# 3. The name of the author may not be used to endorse or promote products
128#    derived from this software without specific prior written permission.
129#
130# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
131# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
132# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
133# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
134# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
135# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
136# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
137# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
138# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
139# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
140
141__version__ = '3.4'
142
143# This runtime is compatible with generated parsers using the
144# API versions listed in constants.compatible_api_versions.
145# 'HEAD' is only used by unittests.
146
147from .constants import *
148from .dfa import *
149from .exceptions import *
150from .recognizers import *
151from .streams import *
152from .tokens import *
153