"""ANTLR3 runtime package"""

# begin[licence]

#

# [The "BSD licence"]

# Copyright (c) 2005-2008 Terence Parr

# All rights reserved.

#

# 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.

#

# end[licence]

import codecs

from StringIO import StringIO

from antlr3.constants import DEFAULT_CHANNEL, EOF

from antlr3.tokens import Token, EOF_TOKEN

############################################################################

#

# basic interfaces

#   IntStream

#    +- CharStream

#    \- TokenStream

#

# subclasses must implemented all methods

#

############################################################################

class IntStream(object):

    """

    @brief Base interface for streams of integer values.

    A simple stream of integers used when all I care about is the char

    or token type sequence (such as interpretation).

    """

    def consume(self):

        raise NotImplementedError

    def LA(self, i):

        """Get int at current input pointer + i ahead where i=1 is next int.

        Negative indexes are allowed.  LA(-1) is previous token (token

	just matched).  LA(-i) where i is before first token should

	yield -1, invalid char / EOF.

	"""

        raise NotImplementedError

    def mark(self):

        """

        Tell the stream to start buffering if it hasn't already.  Return

        current input position, index(), or some other marker so that

        when passed to rewind() you get back to the same spot.

        rewind(mark()) should not affect the input cursor.  The Lexer

        track line/col info as well as input index so its markers are

        not pure input indexes.  Same for tree node streams.

        """

        raise NotImplementedError

    def index(self):

        """

        Return the current input symbol index 0..n where n indicates the

        last symbol has been read.  The index is the symbol about to be

        read not the most recently read symbol.

        """

        raise NotImplementedError

    def rewind(self, marker=None):

        """

        Reset the stream so that next call to index would return marker.

        The marker will usually be index() but it doesn't have to be.  It's

        just a marker to indicate what state the stream was in.  This is

        essentially calling release() and seek().  If there are markers

        created after this marker argument, this routine must unroll them

        like a stack.  Assume the state the stream was in when this marker

        was created.

        If marker is None:

        Rewind to the input position of the last marker.

        Used currently only after a cyclic DFA and just

        before starting a sem/syn predicate to get the

        input position back to the start of the decision.

        Do not "pop" the marker off the state.  mark(i)

        and rewind(i) should balance still. It is

        like invoking rewind(last marker) but it should not "pop"

        the marker off.  It's like seek(last marker's input position).       

	"""

        raise NotImplementedError

    def release(self, marker=None):

        """

        You may want to commit to a backtrack but don't want to force the

        stream to keep bookkeeping objects around for a marker that is

        no longer necessary.  This will have the same behavior as

        rewind() except it releases resources without the backward seek.

        This must throw away resources for all markers back to the marker

        argument.  So if you're nested 5 levels of mark(), and then release(2)

        you have to release resources for depths 2..5.

	"""

        raise NotImplementedError

    def seek(self, index):

        """

        Set the input cursor to the position indicated by index.  This is

        normally used to seek ahead in the input stream.  No buffering is

        required to do this unless you know your stream will use seek to

        move backwards such as when backtracking.

        This is different from rewind in its multi-directional

        requirement and in that its argument is strictly an input cursor

        (index).

        For char streams, seeking forward must update the stream state such

        as line number.  For seeking backwards, you will be presumably

        backtracking using the mark/rewind mechanism that restores state and

        so this method does not need to update state when seeking backwards.

        Currently, this method is only used for efficient backtracking using

        memoization, but in the future it may be used for incremental parsing.

        The index is 0..n-1.  A seek to position i means that LA(1) will

        return the ith symbol.  So, seeking to 0 means LA(1) will return the

        first element in the stream. 

        """

        raise NotImplementedError

    def size(self):

        """

        Only makes sense for streams that buffer everything up probably, but

        might be useful to display the entire stream or for testing.  This

        value includes a single EOF.

	"""

        raise NotImplementedError

    def getSourceName(self):

        """

        Where are you getting symbols from?  Normally, implementations will

        pass the buck all the way to the lexer who can ask its input stream

        for the file name or whatever.

        """

        raise NotImplementedError

class CharStream(IntStream):

    """

    @brief A source of characters for an ANTLR lexer.

    This is an abstract class that must be implemented by a subclass.

    """

    # pylint does not realize that this is an interface, too

    #pylint: disable-msg=W0223

    EOF = -1

    def substring(self, start, stop):

        """

        For infinite streams, you don't need this; primarily I'm providing

        a useful interface for action code.  Just make sure actions don't

        use this on streams that don't support it.

        """

        raise NotImplementedError

    def LT(self, i):

        """

        Get the ith character of lookahead.  This is the same usually as

        LA(i).  This will be used for labels in the generated

        lexer code.  I'd prefer to return a char here type-wise, but it's

        probably better to be 32-bit clean and be consistent with LA.

        """

        raise NotImplementedError

    def getLine(self):

        """ANTLR tracks the line information automatically"""

        raise NotImplementedError

    def setLine(self, line):

        """

        Because this stream can rewind, we need to be able to reset the line

        """

        raise NotImplementedError

    def getCharPositionInLine(self):

        """

        The index of the character relative to the beginning of the line 0..n-1

        """

        raise NotImplementedError

    def setCharPositionInLine(self, pos):

        raise NotImplementedError

class TokenStream(IntStream):

    """

    @brief A stream of tokens accessing tokens from a TokenSource

    This is an abstract class that must be implemented by a subclass.

    """

    # pylint does not realize that this is an interface, too

    #pylint: disable-msg=W0223

    def LT(self, k):

        """

        Get Token at current input pointer + i ahead where i=1 is next Token.

        i<0 indicates tokens in the past.  So -1 is previous token and -2 is

        two tokens ago. LT(0) is undefined.  For i>=n, return Token.EOFToken.

        Return null for LT(0) and any index that results in an absolute address

        that is negative.

	"""

        raise NotImplementedError

    def get(self, i):

        """

        Get a token at an absolute index i; 0..n-1.  This is really only

        needed for profiling and debugging and token stream rewriting.

        If you don't want to buffer up tokens, then this method makes no

        sense for you.  Naturally you can't use the rewrite stream feature.

        I believe DebugTokenStream can easily be altered to not use

        this method, removing the dependency.

        """

        raise NotImplementedError

    def getTokenSource(self):

        """

        Where is this stream pulling tokens from?  This is not the name, but

        the object that provides Token objects.

	"""

        raise NotImplementedError

    def toString(self, start=None, stop=None):

        """

        Return the text of all tokens from start to stop, inclusive.

        If the stream does not buffer all the tokens then it can just

        return "" or null;  Users should not access $ruleLabel.text in

        an action of course in that case.

        Because the user is not required to use a token with an index stored

        in it, we must provide a means for two token objects themselves to

        indicate the start/end location.  Most often this will just delegate

        to the other toString(int,int).  This is also parallel with

        the TreeNodeStream.toString(Object,Object).

	"""

        raise NotImplementedError

############################################################################

#

# character streams for use in lexers

#   CharStream

#   \- ANTLRStringStream

#

############################################################################

class ANTLRStringStream(CharStream):

    """

    @brief CharStream that pull data from a unicode string.

    A pretty quick CharStream that pulls all data from an array

    directly.  Every method call counts in the lexer.

    """

    def __init__(self, data):

        """

        @param data This should be a unicode string holding the data you want

           to parse. If you pass in a byte string, the Lexer will choke on

           non-ascii data.

        """

        CharStream.__init__(self)

  	# The data being scanned

        self.strdata = unicode(data)

        self.data = [ord(c) for c in self.strdata]

	# How many characters are actually in the buffer

        self.n = len(data)

 	# 0..n-1 index into string of next char

        self.p = 0

	# line number 1..n within the input

        self.line = 1

 	# The index of the character relative to the beginning of the

        # line 0..n-1

        self.charPositionInLine = 0

	# A list of CharStreamState objects that tracks the stream state

        # values line, charPositionInLine, and p that can change as you

        # move through the input stream.  Indexed from 0..markDepth-1.

        self._markers = [ ]

        self.lastMarker = None

        self.markDepth = 0

        # What is name or source of this char stream?

        self.name = None

    def reset(self):

        """

        Reset the stream so that it's in the same state it was

        when the object was created *except* the data array is not

        touched.

        """

        self.p = 0

        self.line = 1

        self.charPositionInLine = 0

        self._markers = [ ]

    def consume(self):

        try:

            if self.data[self.p] == 10: # \n

                self.line += 1

                self.charPositionInLine = 0

            else:

                self.charPositionInLine += 1

            self.p += 1

        except IndexError:

            # happend when we reached EOF and self.data[self.p] fails

            # just do nothing

            pass

    def LA(self, i):

        if i == 0:

            return 0 # undefined

        if i < 0:

            i += 1 # e.g., translate LA(-1) to use offset i=0; then data[p+0-1]

        try:

            return self.data[self.p+i-1]

        except IndexError:

            return EOF

    def LT(self, i):

        if i == 0:

            return 0 # undefined

        if i < 0:

            i += 1 # e.g., translate LA(-1) to use offset i=0; then data[p+0-1]

        try:

            return self.strdata[self.p+i-1]

        except IndexError:

            return EOF

    def index(self):

        """

        Return the current input symbol index 0..n where n indicates the

        last symbol has been read.  The index is the index of char to

        be returned from LA(1).

        """

        return self.p

    def size(self):

        return self.n

    def mark(self):

        state = (self.p, self.line, self.charPositionInLine)

        try:

            self._markers[self.markDepth] = state

        except IndexError:

            self._markers.append(state)

        self.markDepth += 1

        self.lastMarker = self.markDepth

        return self.lastMarker

    def rewind(self, marker=None):

        if marker is None:

            marker = self.lastMarker

        p, line, charPositionInLine = self._markers[marker-1]

        self.seek(p)

        self.line = line

        self.charPositionInLine = charPositionInLine

        self.release(marker)

    def release(self, marker=None):

        if marker is None:

            marker = self.lastMarker

        self.markDepth = marker-1

    def seek(self, index):

        """

        consume() ahead until p==index; can't just set p=index as we must

        update line and charPositionInLine.

        """

        if index <= self.p:

            self.p = index # just jump; don't update stream state (line, ...)

            return

        # seek forward, consume until p hits index

        while self.p < index:

            self.consume()

    def substring(self, start, stop):

        return self.strdata[start:stop+1]

    def getLine(self):

        """Using setter/getter methods is deprecated. Use o.line instead."""

        return self.line

    def getCharPositionInLine(self):

        """

        Using setter/getter methods is deprecated. Use o.charPositionInLine

        instead.

        """

        return self.charPositionInLine

    def setLine(self, line):

        """Using setter/getter methods is deprecated. Use o.line instead."""

        self.line = line

    def setCharPositionInLine(self, pos):

        """

        Using setter/getter methods is deprecated. Use o.charPositionInLine

        instead.

        """

        self.charPositionInLine = pos

    def getSourceName(self):

        return self.name

class ANTLRFileStream(ANTLRStringStream):

    """

    @brief CharStream that opens a file to read the data.

    This is a char buffer stream that is loaded from a file

    all at once when you construct the object.

    """

    def __init__(self, fileName, encoding=None):

        """

        @param fileName The path to the file to be opened. The file will be

           opened with mode 'rb'.

        @param encoding If you set the optional encoding argument, then the

           data will be decoded on the fly.