xref: /external/antlr/antlr-3.4/runtime/C/include/antlr3debugeventlistener.h

/**
 * \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