bundles/org.simantics.databoard/cpp/DataBoardTest/libantlr3c-3.2/include/antlr3debugeventlistener.h

   1 /**\r
   2  * \file\r
   3  * The definition of all debugging events that a recognizer can trigger.\r
   4  *\r
   5  * \remark\r
   6  *  From the java implementation by Terence Parr...\r
   7  *  I did not create a separate AST debugging interface as it would create\r
   8  *  lots of extra classes and DebugParser has a dbg var defined, which makes\r
   9  *  it hard to change to ASTDebugEventListener.  I looked hard at this issue\r
  10  *  and it is easier to understand as one monolithic event interface for all\r
  11  *  possible events.  Hopefully, adding ST debugging stuff won't be bad.  Leave\r
  12  *  for future. 4/26/2006.\r
  13  */\r
  14 \r
  15 #ifndef ANTLR3_DEBUG_EVENT_LISTENER_H\r
  16 #define ANTLR3_DEBUG_EVENT_LISTENER_H\r
  17 \r
  18 // [The "BSD licence"]\r
  19 // Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC\r
  20 // http://www.temporal-wave.com\r
  21 // http://www.linkedin.com/in/jimidle\r
  22 //\r
  23 // All rights reserved.\r
  24 //\r
  25 // Redistribution and use in source and binary forms, with or without\r
  26 // modification, are permitted provided that the following conditions\r
  27 // are met:\r
  28 // 1. Redistributions of source code must retain the above copyright\r
  29 //    notice, this list of conditions and the following disclaimer.\r
  30 // 2. Redistributions in binary form must reproduce the above copyright\r
  31 //    notice, this list of conditions and the following disclaimer in the\r
  32 //    documentation and/or other materials provided with the distribution.\r
  33 // 3. The name of the author may not be used to endorse or promote products\r
  34 //    derived from this software without specific prior written permission.\r
  35 //\r
  36 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR\r
  37 // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES\r
  38 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\r
  39 // IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  40 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT\r
  41 // NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
  42 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
  43 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
  44 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF\r
  45 // THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  46 \r
  47 #include    <antlr3defs.h>\r
  48 #include    <antlr3basetree.h>\r
  49 #include    <antlr3commontoken.h>\r
  50 \r
  51 \r
  52 /// Default debugging port\r
  53 ///\r
  54 #define DEFAULT_DEBUGGER_PORT           0xBFCC;\r
  55 \r
  56 #ifdef __cplusplus\r
  57 extern "C" {\r
  58 #endif\r
  59 \r
  60 /** The ANTLR3 debugging interface for communicating with ANLTR Works. Function comments\r
  61  *  mostly taken from the Java version.\r
  62  */\r
  63 typedef struct ANTLR3_DEBUG_EVENT_LISTENER_struct\r
  64 {\r
  65         /// The port number which the debug listener should listen on for a connection\r
  66         ///\r
  67         ANTLR3_UINT32           port;\r
  68 \r
  69         /// The socket structure we receive after a successful accept on the serverSocket\r
  70         ///\r
  71         SOCKET                          socket;\r
  72 \r
  73         /** The version of the debugging protocol supported by the providing\r
  74          *  instance of the debug event listener.\r
  75          */\r
  76         int                                     PROTOCOL_VERSION;\r
  77 \r
  78         /// The name of the grammar file that we are debugging\r
  79         ///\r
  80         pANTLR3_STRING          grammarFileName;\r
  81 \r
  82         /// Indicates whether we have already connected or not\r
  83         ///\r
  84         ANTLR3_BOOLEAN          initialized;\r
  85 \r
  86         /// Used to serialize the values of any particular token we need to\r
  87         /// send back to the debugger.\r
  88         ///\r
  89         pANTLR3_STRING          tokenString;\r
  90 \r
  91 \r
  92         /// Allows the debug event system to access the adapter in use\r
  93         /// by the recognizer, if this is a tree parser of some sort.\r
  94         ///\r
  95         pANTLR3_BASE_TREE_ADAPTOR       adaptor;\r
  96 \r
  97         /// Wait for a connection from the debugger and initiate the\r
  98         /// debugging session.\r
  99         ///\r
 100         ANTLR3_BOOLEAN  (*handshake)            (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 101 \r
 102         /** The parser has just entered a rule.  No decision has been made about\r
 103          *  which alt is predicted.  This is fired AFTER init actions have been\r
 104          *  executed.  Attributes are defined and available etc...\r
 105          */\r
 106         void                    (*enterRule)            (pANTLR3_DEBUG_EVENT_LISTENER delboy, const char * grammarFileName, const char * ruleName);\r
 107 \r
 108         /** Because rules can have lots of alternatives, it is very useful to\r
 109          *  know which alt you are entering.  This is 1..n for n alts.\r
 110          */\r
 111         void                    (*enterAlt)                     (pANTLR3_DEBUG_EVENT_LISTENER delboy, int alt);\r
 112 \r
 113         /** This is the last thing executed before leaving a rule.  It is\r
 114          *  executed even if an exception is thrown.  This is triggered after\r
 115          *  error reporting and recovery have occurred (unless the exception is\r
 116          *  not caught in this rule).  This implies an "exitAlt" event.\r
 117          */\r
 118         void                    (*exitRule)                     (pANTLR3_DEBUG_EVENT_LISTENER delboy, const char * grammarFileName, const char * ruleName);\r
 119 \r
 120         /** Track entry into any (...) subrule other EBNF construct \r
 121          */\r
 122         void                    (*enterSubRule)         (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);\r
 123         \r
 124         void                    (*exitSubRule)          (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);\r
 125 \r
 126         /** Every decision, fixed k or arbitrary, has an enter/exit event\r
 127          *  so that a GUI can easily track what LT/consume events are\r
 128          *  associated with prediction.  You will see a single enter/exit\r
 129          *  subrule but multiple enter/exit decision events, one for each\r
 130          *  loop iteration.\r
 131          */\r
 132         void                    (*enterDecision)        (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);\r
 133 \r
 134         void                    (*exitDecision)         (pANTLR3_DEBUG_EVENT_LISTENER delboy, int decisionNumber);\r
 135 \r
 136         /** An input token was consumed; matched by any kind of element.\r
 137          *  Trigger after the token was matched by things like match(), matchAny().\r
 138          */\r
 139         void                    (*consumeToken)         (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_COMMON_TOKEN t);\r
 140 \r
 141         /** An off-channel input token was consumed.\r
 142          *  Trigger after the token was matched by things like match(), matchAny().\r
 143          *  (unless of course the hidden token is first stuff in the input stream).\r
 144          */\r
 145         void                    (*consumeHiddenToken)   (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_COMMON_TOKEN t);\r
 146 \r
 147         /** Somebody (anybody) looked ahead.  Note that this actually gets\r
 148          *  triggered by both LA and LT calls.  The debugger will want to know\r
 149          *  which Token object was examined.  Like consumeToken, this indicates\r
 150          *  what token was seen at that depth.  A remote debugger cannot look\r
 151          *  ahead into a file it doesn't have so LT events must pass the token\r
 152          *  even if the info is redundant.\r
 153          */\r
 154         void                    (*LT)                           (pANTLR3_DEBUG_EVENT_LISTENER delboy, int i, pANTLR3_COMMON_TOKEN t);\r
 155 \r
 156         /** The parser is going to look arbitrarily ahead; mark this location,\r
 157          *  the token stream's marker is sent in case you need it.\r
 158          */\r
 159         void                    (*mark)                         (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_MARKER marker);\r
 160 \r
 161         /** After an arbitrarily long lookahead as with a cyclic DFA (or with\r
 162          *  any backtrack), this informs the debugger that stream should be\r
 163          *  rewound to the position associated with marker.\r
 164          */\r
 165         void                    (*rewind)                       (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_MARKER marker);\r
 166 \r
 167         /** Rewind to the input position of the last marker.\r
 168          *  Used currently only after a cyclic DFA and just\r
 169          *  before starting a sem/syn predicate to get the\r
 170          *  input position back to the start of the decision.\r
 171          *  Do not "pop" the marker off the state.  mark(i)\r
 172          *  and rewind(i) should balance still.\r
 173          */\r
 174         void                    (*rewindLast)           (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 175 \r
 176         void                    (*beginBacktrack)       (pANTLR3_DEBUG_EVENT_LISTENER delboy, int level);\r
 177 \r
 178         void                    (*endBacktrack)         (pANTLR3_DEBUG_EVENT_LISTENER delboy, int level, ANTLR3_BOOLEAN successful);\r
 179 \r
 180         /** To watch a parser move through the grammar, the parser needs to\r
 181          *  inform the debugger what line/charPos it is passing in the grammar.\r
 182          *  For now, this does not know how to switch from one grammar to the\r
 183          *  other and back for island grammars etc...\r
 184          *\r
 185          *  This should also allow breakpoints because the debugger can stop\r
 186          *  the parser whenever it hits this line/pos.\r
 187          */\r
 188         void                    (*location)                     (pANTLR3_DEBUG_EVENT_LISTENER delboy, int line, int pos);\r
 189 \r
 190         /** A recognition exception occurred such as NoViableAltException.  I made\r
 191          *  this a generic event so that I can alter the exception hierarchy later\r
 192          *  without having to alter all the debug objects.\r
 193          *\r
 194          *  Upon error, the stack of enter rule/subrule must be properly unwound.\r
 195          *  If no viable alt occurs it is within an enter/exit decision, which\r
 196          *  also must be rewound.  Even the rewind for each mark must be unwound.\r
 197          *  In the Java target this is pretty easy using try/finally, if a bit\r
 198          *  ugly in the generated code.  The rewind is generated in DFA.predict()\r
 199          *  actually so no code needs to be generated for that.  For languages\r
 200          *  w/o this "finally" feature (C++?), the target implementor will have\r
 201          *  to build an event stack or something.\r
 202          *\r
 203          *  Across a socket for remote debugging, only the RecognitionException\r
 204          *  data fields are transmitted.  The token object or whatever that\r
 205          *  caused the problem was the last object referenced by LT.  The\r
 206          *  immediately preceding LT event should hold the unexpected Token or\r
 207          *  char.\r
 208          *\r
 209          *  Here is a sample event trace for grammar:\r
 210          *\r
 211          *  b : C ({;}A|B) // {;} is there to prevent A|B becoming a set\r
 212      *    | D\r
 213      *    ;\r
 214      *\r
 215          *  The sequence for this rule (with no viable alt in the subrule) for\r
 216          *  input 'c c' (there are 3 tokens) is:\r
 217          *\r
 218          *              commence\r
 219          *              LT(1)\r
 220          *              enterRule b\r
 221          *              location 7 1\r
 222          *              enter decision 3\r
 223          *              LT(1)\r
 224          *              exit decision 3\r
 225          *              enterAlt1\r
 226          *              location 7 5\r
 227          *              LT(1)\r
 228          *              consumeToken [c/<4>,1:0]\r
 229          *              location 7 7\r
 230          *              enterSubRule 2\r
 231          *              enter decision 2\r
 232          *              LT(1)\r
 233          *              LT(1)\r
 234          *              recognitionException NoViableAltException 2 1 2\r
 235          *              exit decision 2\r
 236          *              exitSubRule 2\r
 237          *              beginResync\r
 238          *              LT(1)\r
 239          *              consumeToken [c/<4>,1:1]\r
 240          *              LT(1)\r
 241          *              endResync\r
 242          *              LT(-1)\r
 243          *              exitRule b\r
 244          *              terminate\r
 245          */\r
 246         void                    (*recognitionException) (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_EXCEPTION e);\r
 247 \r
 248         /** Indicates the recognizer is about to consume tokens to resynchronize\r
 249          *  the parser.  Any consume events from here until the recovered event\r
 250          *  are not part of the parse--they are dead tokens.\r
 251          */\r
 252         void                    (*beginResync)                  (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 253 \r
 254         /** Indicates that the recognizer has finished consuming tokens in order\r
 255          *  to resynchronize.  There may be multiple beginResync/endResync pairs\r
 256          *  before the recognizer comes out of errorRecovery mode (in which\r
 257          *  multiple errors are suppressed).  This will be useful\r
 258          *  in a gui where you want to probably grey out tokens that are consumed\r
 259          *  but not matched to anything in grammar.  Anything between\r
 260          *  a beginResync/endResync pair was tossed out by the parser.\r
 261          */\r
 262         void                    (*endResync)                    (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 263 \r
 264         /** A semantic predicate was evaluate with this result and action text \r
 265         */\r
 266         void                    (*semanticPredicate)    (pANTLR3_DEBUG_EVENT_LISTENER delboy, ANTLR3_BOOLEAN result, const char * predicate);\r
 267 \r
 268         /** Announce that parsing has begun.  Not technically useful except for\r
 269          *  sending events over a socket.  A GUI for example will launch a thread\r
 270          *  to connect and communicate with a remote parser.  The thread will want\r
 271          *  to notify the GUI when a connection is made.  ANTLR parsers\r
 272          *  trigger this upon entry to the first rule (the ruleLevel is used to\r
 273          *  figure this out).\r
 274          */\r
 275         void                    (*commence)                             (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 276 \r
 277         /** Parsing is over; successfully or not.  Mostly useful for telling\r
 278          *  remote debugging listeners that it's time to quit.  When the rule\r
 279          *  invocation level goes to zero at the end of a rule, we are done\r
 280          *  parsing.\r
 281          */\r
 282         void                    (*terminate)                    (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 283 \r
 284         /// Retrieve acknowledge response from the debugger. in fact this\r
 285         /// response is never used at the moment. So we just read whatever\r
 286         /// is in the socket buffer and throw it away.\r
 287         ///\r
 288         void                    (*ack)                                  (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 289 \r
 290         // T r e e  P a r s i n g\r
 291 \r
 292         /** Input for a tree parser is an AST, but we know nothing for sure\r
 293          *  about a node except its type and text (obtained from the adaptor).\r
 294          *  This is the analog of the consumeToken method.  The ID is usually \r
 295          *  the memory address of the node.\r
 296          *  If the type is UP or DOWN, then\r
 297          *  the ID is not really meaningful as it's fixed--there is\r
 298          *  just one UP node and one DOWN navigation node.\r
 299          *\r
 300          *  Note that unlike the Java version, the node type of the C parsers\r
 301          *  is always fixed as pANTLR3_BASE_TREE because all such structures\r
 302          *  contain a super pointer to their parent, which is generally COMMON_TREE and within\r
 303          *  that there is a super pointer that can point to a user type that encapsulates it.\r
 304          *  Almost akin to saying that it is an interface pointer except we don't need to\r
 305          *  know what the interface is in full, just those bits that are the base.\r
 306          * @param t\r
 307          */\r
 308         void                    (*consumeNode)                  (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);\r
 309 \r
 310         /** The tree parser looked ahead.  If the type is UP or DOWN,\r
 311          *  then the ID is not really meaningful as it's fixed--there is\r
 312          *  just one UP node and one DOWN navigation node.\r
 313          */\r
 314         void                    (*LTT)                                  (pANTLR3_DEBUG_EVENT_LISTENER delboy, int i, pANTLR3_BASE_TREE t);\r
 315 \r
 316 \r
 317         // A S T  E v e n t s\r
 318 \r
 319         /** A nil was created (even nil nodes have a unique ID...\r
 320          *  they are not "null" per se).  As of 4/28/2006, this\r
 321          *  seems to be uniquely triggered when starting a new subtree\r
 322          *  such as when entering a subrule in automatic mode and when\r
 323          *  building a tree in rewrite mode.\r
 324      *\r
 325          *  If you are receiving this event over a socket via\r
 326          *  RemoteDebugEventSocketListener then only t.ID is set.\r
 327          */\r
 328         void                    (*nilNode)                              (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);\r
 329 \r
 330         /** If a syntax error occurs, recognizers bracket the error\r
 331          *  with an error node if they are building ASTs. This event\r
 332          *  notifies the listener that this is the case\r
 333          */\r
 334         void                    (*errorNode)                    (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);\r
 335 \r
 336         /** Announce a new node built from token elements such as type etc...\r
 337          * \r
 338          *  If you are receiving this event over a socket via\r
 339          *  RemoteDebugEventSocketListener then only t.ID, type, text are\r
 340          *  set.\r
 341          */\r
 342         void                    (*createNode)                   (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t);\r
 343 \r
 344         /** Announce a new node built from an existing token.\r
 345          *\r
 346          *  If you are receiving this event over a socket via\r
 347          *  RemoteDebugEventSocketListener then only node.ID and token.tokenIndex\r
 348          *  are set.\r
 349          */\r
 350         void                    (*createNodeTok)                (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE node, pANTLR3_COMMON_TOKEN token);\r
 351 \r
 352         /** Make a node the new root of an existing root.  See\r
 353          *\r
 354          *  Note: the newRootID parameter is possibly different\r
 355          *  than the TreeAdaptor.becomeRoot() newRoot parameter.\r
 356          *  In our case, it will always be the result of calling\r
 357          *  TreeAdaptor.becomeRoot() and not root_n or whatever.\r
 358          *\r
 359          *  The listener should assume that this event occurs\r
 360          *  only when the current subrule (or rule) subtree is\r
 361          *  being reset to newRootID.\r
 362          * \r
 363          *  If you are receiving this event over a socket via\r
 364          *  RemoteDebugEventSocketListener then only IDs are set.\r
 365          *\r
 366          *  @see org.antlr.runtime.tree.TreeAdaptor.becomeRoot()\r
 367          */\r
 368         void                    (*becomeRoot)                   (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE newRoot, pANTLR3_BASE_TREE oldRoot);\r
 369 \r
 370         /** Make childID a child of rootID.\r
 371          *\r
 372          *  If you are receiving this event over a socket via\r
 373          *  RemoteDebugEventSocketListener then only IDs are set.\r
 374          * \r
 375          *  @see org.antlr.runtime.tree.TreeAdaptor.addChild()\r
 376          */\r
 377         void                    (*addChild)                             (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE root, pANTLR3_BASE_TREE child);\r
 378 \r
 379         /** Set the token start/stop token index for a subtree root or node.\r
 380          *\r
 381          *  If you are receiving this event over a socket via\r
 382          *  RemoteDebugEventSocketListener then only t.ID is set.\r
 383          */\r
 384         void                    (*setTokenBoundaries)   (pANTLR3_DEBUG_EVENT_LISTENER delboy, pANTLR3_BASE_TREE t, ANTLR3_MARKER tokenStartIndex, ANTLR3_MARKER tokenStopIndex);\r
 385 \r
 386         /// Free up the resources allocated to this structure\r
 387         ///\r
 388         void                    (*free)                                 (pANTLR3_DEBUG_EVENT_LISTENER delboy);\r
 389 \r
 390 }\r
 391         ANTLR3_DEBUG_EVENT_LISTENER;\r
 392 \r
 393 #ifdef __cplusplus\r
 394 }\r
 395 #endif\r
 396 \r
 397 #endif\r
 398 \r