/**
|
* \file
|
* The definition of all debugging events that a recognizer can trigger.
|
*
|
* \remark
|
* From the java implementation by Terence Parr...
|
* I did not create a separate AST debugging interface as it would create
|
* lots of extra classes and DebugParser has a dbg var defined, which makes
|
* it hard to change to ASTDebugEventListener. I looked hard at this issue
|
* and it is easier to understand as one monolithic event interface for all
|
* possible events. Hopefully, adding ST debugging stuff won't be bad. Leave
|
* for future. 4/26/2006.
|
*/
|
|
#ifndef ANTLR3_DEBUG_EVENT_LISTENER_H
|
#define ANTLR3_DEBUG_EVENT_LISTENER_H
|
|
// [The "BSD licence"]
|
// Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC
|
// http://www.temporal-wave.com
|
// http://www.linkedin.com/in/jimidle
|
//
|
// 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.
|
|
#include <antlr3defs.h>
|
#include <antlr3basetree.h>
|
#include <antlr3commontoken.h>
|
|
|
/// Default debugging port
|
///
|
#define DEFAULT_DEBUGGER_PORT 0xBFCC;
|
|
#ifdef __cplusplus
|
extern "C" {
|
#endif
|
|
/** The ANTLR3 debugging interface for communicating with ANLTR Works. Function comments
|
* mostly taken from the Java version.
|
*/
|
typedef struct ANTLR3_DEBUG_EVENT_LISTENER_struct
|
{
|
/// The port number which the debug listener should listen on for a connection
|
///
|
ANTLR3_UINT32 port;
|
|
/// The socket structure we receive after a successful accept on the serverSocket
|
///
|
SOCKET socket;
|
|
/** The version of the debugging protocol supported by the providing
|
* instance of the debug event listener.
|
*/
|
int PROTOCOL_VERSION;
|
|
/// The name of the grammar file that we are debugging
|
///
|
pANTLR3_STRING grammarFileName;
|
|
/// Indicates whether we have already connected or not
|
///
|
ANTLR3_BOOLEAN initialized;
|
|
/// Used to serialize the values of any particular token we need to
|
/// send back to the debugger.
|
///
|
pANTLR3_STRING tokenString;
|
|
|
/// Allows the debug event system to access the adapter in use
|
/// by the recognizer, if this is a tree parser of some sort.
|
///
|
pANTLR3_BASE_TREE_ADAPTOR adaptor;
|
|
/// Wait for a connection from the debugger and initiate the
|
/// debugging session.
|
///
|
ANTLR3_BOOLEAN (*handshake) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
/** The parser has just entered a rule. No decision has been made about
|
* which alt is predicted. This is fired AFTER init actions have been
|
* executed. Attributes are defined and available etc...
|
*/
|
void (*enterRule) (pANTLR3_DEBUG_EVENT_LISTENER delboy, const char * grammarFileName, const char * ruleName);
|
|
/** Because rules can have lots of alternatives, it is very useful to
|
* know which alt you are entering. This is 1..n for n alts.
|
*/
|
void (*enterAlt) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int alt);
|
|
/** This is the last thing executed before leaving a rule. It is
|
* executed even if an exception is thrown. This is triggered after
|
* error reporting and recovery have occurred (unless the exception is
|
* not caught in this rule). This implies an "exitAlt" event.
|
*/
|
void (*exitRule) (pANTLR3_DEBUG_EVENT_LISTENER delboy, const char * grammarFileName, const char * ruleName);
|
|
/** Track entry into any (...) subrule other EBNF construct
|
*/
|
void (*enterSubRule) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);
|
|
void (*exitSubRule) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);
|
|
/** Every decision, fixed k or arbitrary, has an enter/exit event
|
* so that a GUI can easily track what LT/consume events are
|
* associated with prediction. You will see a single enter/exit
|
* subrule but multiple enter/exit decision events, one for each
|
* loop iteration.
|
*/
|
void (*enterDecision) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);
|
|
void (*exitDecision) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);
|
|
/** An input token was consumed; matched by any kind of element.
|
* Trigger after the token was matched by things like match(), matchAny().
|
*/
|
void (*consumeToken) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_COMMON_TOKEN t);
|
|
/** An off-channel input token was consumed.
|
* Trigger after the token was matched by things like match(), matchAny().
|
* (unless of course the hidden token is first stuff in the input stream).
|
*/
|
void (*consumeHiddenToken) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_COMMON_TOKEN t);
|
|
/** Somebody (anybody) looked ahead. Note that this actually gets
|
* triggered by both LA and LT calls. The debugger will want to know
|
* which Token object was examined. Like consumeToken, this indicates
|
* what token was seen at that depth. A remote debugger cannot look
|
* ahead into a file it doesn't have so LT events must pass the token
|
* even if the info is redundant.
|
*/
|
void (*LT) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int i, pANTLR3_COMMON_TOKEN t);
|
|
/** The parser is going to look arbitrarily ahead; mark this location,
|
* the token stream's marker is sent in case you need it.
|
*/
|
void (*mark) (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_MARKER marker);
|
|
/** After an arbitrarily long lookahead as with a cyclic DFA (or with
|
* any backtrack), this informs the debugger that stream should be
|
* rewound to the position associated with marker.
|
*/
|
void (*rewind) (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_MARKER marker);
|
|
/** 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.
|
*/
|
void (*rewindLast) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
void (*beginBacktrack) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int level);
|
|
void (*endBacktrack) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int level, ANTLR3_BOOLEAN successful);
|
|
/** To watch a parser move through the grammar, the parser needs to
|
* inform the debugger what line/charPos it is passing in the grammar.
|
* For now, this does not know how to switch from one grammar to the
|
* other and back for island grammars etc...
|
*
|
* This should also allow breakpoints because the debugger can stop
|
* the parser whenever it hits this line/pos.
|
*/
|
void (*location) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int line, int pos);
|
|
/** A recognition exception occurred such as NoViableAltException. I made
|
* this a generic event so that I can alter the exception hierarchy later
|
* without having to alter all the debug objects.
|
*
|
* Upon error, the stack of enter rule/subrule must be properly unwound.
|
* If no viable alt occurs it is within an enter/exit decision, which
|
* also must be rewound. Even the rewind for each mark must be unwound.
|
* In the Java target this is pretty easy using try/finally, if a bit
|
* ugly in the generated code. The rewind is generated in DFA.predict()
|
* actually so no code needs to be generated for that. For languages
|
* w/o this "finally" feature (C++?), the target implementor will have
|
* to build an event stack or something.
|
*
|
* Across a socket for remote debugging, only the RecognitionException
|
* data fields are transmitted. The token object or whatever that
|
* caused the problem was the last object referenced by LT. The
|
* immediately preceding LT event should hold the unexpected Token or
|
* char.
|
*
|
* Here is a sample event trace for grammar:
|
*
|
* b : C ({;}A|B) // {;} is there to prevent A|B becoming a set
|
* | D
|
* ;
|
*
|
* The sequence for this rule (with no viable alt in the subrule) for
|
* input 'c c' (there are 3 tokens) is:
|
*
|
* commence
|
* LT(1)
|
* enterRule b
|
* location 7 1
|
* enter decision 3
|
* LT(1)
|
* exit decision 3
|
* enterAlt1
|
* location 7 5
|
* LT(1)
|
* consumeToken [c/<4>,1:0]
|
* location 7 7
|
* enterSubRule 2
|
* enter decision 2
|
* LT(1)
|
* LT(1)
|
* recognitionException NoViableAltException 2 1 2
|
* exit decision 2
|
* exitSubRule 2
|
* beginResync
|
* LT(1)
|
* consumeToken [c/<4>,1:1]
|
* LT(1)
|
* endResync
|
* LT(-1)
|
* exitRule b
|
* terminate
|
*/
|
void (*recognitionException) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_EXCEPTION e);
|
|
/** Indicates the recognizer is about to consume tokens to resynchronize
|
* the parser. Any consume events from here until the recovered event
|
* are not part of the parse--they are dead tokens.
|
*/
|
void (*beginResync) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
/** Indicates that the recognizer has finished consuming tokens in order
|
* to resynchronize. There may be multiple beginResync/endResync pairs
|
* before the recognizer comes out of errorRecovery mode (in which
|
* multiple errors are suppressed). This will be useful
|
* in a gui where you want to probably grey out tokens that are consumed
|
* but not matched to anything in grammar. Anything between
|
* a beginResync/endResync pair was tossed out by the parser.
|
*/
|
void (*endResync) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
/** A semantic predicate was evaluate with this result and action text
|
*/
|
void (*semanticPredicate) (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_BOOLEAN result, const char * predicate);
|
|
/** Announce that parsing has begun. Not technically useful except for
|
* sending events over a socket. A GUI for example will launch a thread
|
* to connect and communicate with a remote parser. The thread will want
|
* to notify the GUI when a connection is made. ANTLR parsers
|
* trigger this upon entry to the first rule (the ruleLevel is used to
|
* figure this out).
|
*/
|
void (*commence) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
/** Parsing is over; successfully or not. Mostly useful for telling
|
* remote debugging listeners that it's time to quit. When the rule
|
* invocation level goes to zero at the end of a rule, we are done
|
* parsing.
|
*/
|
void (*terminate) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
/// Retrieve acknowledge response from the debugger. in fact this
|
/// response is never used at the moment. So we just read whatever
|
/// is in the socket buffer and throw it away.
|
///
|
void (*ack) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
// T r e e P a r s i n g
|
|
/** Input for a tree parser is an AST, but we know nothing for sure
|
* about a node except its type and text (obtained from the adaptor).
|
* This is the analog of the consumeToken method. The ID is usually
|
* the memory address of the node.
|
* If the type is UP or DOWN, then
|
* the ID is not really meaningful as it's fixed--there is
|
* just one UP node and one DOWN navigation node.
|
*
|
* Note that unlike the Java version, the node type of the C parsers
|
* is always fixed as pANTLR3_BASE_TREE because all such structures
|
* contain a super pointer to their parent, which is generally COMMON_TREE and within
|
* that there is a super pointer that can point to a user type that encapsulates it.
|
* Almost akin to saying that it is an interface pointer except we don't need to
|
* know what the interface is in full, just those bits that are the base.
|
* @param t
|
*/
|
void (*consumeNode) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);
|
|
/** The tree parser looked ahead. If the type is UP or DOWN,
|
* then the ID is not really meaningful as it's fixed--there is
|
* just one UP node and one DOWN navigation node.
|
*/
|
void (*LTT) (pANTLR3_DEBUG_EVENT_LISTENER delboy, int i, pANTLR3_BASE_TREE t);
|
|
|
// A S T E v e n t s
|
|
/** A nil was created (even nil nodes have a unique ID...
|
* they are not "null" per se). As of 4/28/2006, this
|
* seems to be uniquely triggered when starting a new subtree
|
* such as when entering a subrule in automatic mode and when
|
* building a tree in rewrite mode.
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only t.ID is set.
|
*/
|
void (*nilNode) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);
|
|
/** If a syntax error occurs, recognizers bracket the error
|
* with an error node if they are building ASTs. This event
|
* notifies the listener that this is the case
|
*/
|
void (*errorNode) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);
|
|
/** Announce a new node built from token elements such as type etc...
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only t.ID, type, text are
|
* set.
|
*/
|
void (*createNode) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);
|
|
/** Announce a new node built from an existing token.
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only node.ID and token.tokenIndex
|
* are set.
|
*/
|
void (*createNodeTok) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE node, pANTLR3_COMMON_TOKEN token);
|
|
/** Make a node the new root of an existing root. See
|
*
|
* Note: the newRootID parameter is possibly different
|
* than the TreeAdaptor.becomeRoot() newRoot parameter.
|
* In our case, it will always be the result of calling
|
* TreeAdaptor.becomeRoot() and not root_n or whatever.
|
*
|
* The listener should assume that this event occurs
|
* only when the current subrule (or rule) subtree is
|
* being reset to newRootID.
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only IDs are set.
|
*
|
* @see org.antlr.runtime.tree.TreeAdaptor.becomeRoot()
|
*/
|
void (*becomeRoot) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE newRoot, pANTLR3_BASE_TREE oldRoot);
|
|
/** Make childID a child of rootID.
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only IDs are set.
|
*
|
* @see org.antlr.runtime.tree.TreeAdaptor.addChild()
|
*/
|
void (*addChild) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE root, pANTLR3_BASE_TREE child);
|
|
/** Set the token start/stop token index for a subtree root or node.
|
*
|
* If you are receiving this event over a socket via
|
* RemoteDebugEventSocketListener then only t.ID is set.
|
*/
|
void (*setTokenBoundaries) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t, ANTLR3_MARKER tokenStartIndex, ANTLR3_MARKER tokenStopIndex);
|
|
/// Free up the resources allocated to this structure
|
///
|
void (*free) (pANTLR3_DEBUG_EVENT_LISTENER delboy);
|
|
}
|
ANTLR3_DEBUG_EVENT_LISTENER;
|
|
#ifdef __cplusplus
|
}
|
#endif
|
|
#endif
|
