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