Copy documentation to all non-Java languages

This commit is contained in:
Song Yang 2020-03-17 16:03:29 -04:00
parent d832f90a70
commit 575271020f
7 changed files with 132 additions and 25 deletions

View File

@ -9,6 +9,16 @@ namespace Antlr4.Runtime.Tree
{ {
public static readonly ParseTreeWalker Default = new ParseTreeWalker(); public static readonly ParseTreeWalker Default = new ParseTreeWalker();
/// <summary>
/// Performs a walk on the given parse tree starting at the root and going down recursively
/// with depth-first search. On each node,
/// <see cref="ParseTreeWalker.EnterRule(IParseTreeListener, IRuleNode)"/> is called before
/// recursively walking down into child nodes, then
/// <see cref="ParseTreeWalker.ExitRule(IParseTreeListener, IRuleNode)"/>
/// is called after the recursive call to wind up.
/// </summary>
/// <param name="listener">The listener used by the walker to process grammar rules</param>
/// <param name="t">The parse tree to be walked on</param>
public virtual void Walk(IParseTreeListener listener, IParseTree t) public virtual void Walk(IParseTreeListener listener, IParseTree t)
{ {
if (t is IErrorNode) if (t is IErrorNode)
@ -35,13 +45,12 @@ namespace Antlr4.Runtime.Tree
} }
/// <summary> /// <summary>
/// The discovery of a rule node, involves sending two events: the generic /// Enters a grammar rule by first triggering the generic event
/// <see cref="IParseTreeListener.EnterEveryRule(Antlr4.Runtime.ParserRuleContext)"/> /// <see cref="IParseTreeListener.EnterEveryRule"/>
/// and a /// then by triggering the event specific to the given parse tree node
/// <see cref="Antlr4.Runtime.RuleContext"/>
/// -specific event. First we trigger the generic and then
/// the rule specific. We to them in reverse order upon finishing the node.
/// </summary> /// </summary>
/// <param name="listener"> The listener responding to the trigger events </param>
/// <param name="r">The grammar rule containing the rule context</param>
protected internal virtual void EnterRule(IParseTreeListener listener, IRuleNode r) protected internal virtual void EnterRule(IParseTreeListener listener, IRuleNode r)
{ {
ParserRuleContext ctx = (ParserRuleContext)r.RuleContext; ParserRuleContext ctx = (ParserRuleContext)r.RuleContext;
@ -49,6 +58,13 @@ namespace Antlr4.Runtime.Tree
ctx.EnterRule(listener); ctx.EnterRule(listener);
} }
/// <summary>
/// Exits a grammar rule by first triggering the event specific to the given parse tree node
/// then by triggering the generic event
/// <see cref="IParseTreeListener.ExitEveryRule"/>
/// </summary>
/// <param name="listener"> The listener responding to the trigger events </param>
/// <param name="r">The grammar rule containing the rule context</param>
protected internal virtual void ExitRule(IParseTreeListener listener, IRuleNode r) protected internal virtual void ExitRule(IParseTreeListener listener, IRuleNode r)
{ {
ParserRuleContext ctx = (ParserRuleContext)r.RuleContext; ParserRuleContext ctx = (ParserRuleContext)r.RuleContext;

View File

@ -16,14 +16,31 @@ namespace tree {
virtual ~ParseTreeWalker(); virtual ~ParseTreeWalker();
/// <summary>
/// Performs a walk on the given parse tree starting at the root and going down recursively
/// with depth-first search. On each node, <seealso cref="ParseTreeWalker#enterRule"/> is called before
/// recursively walking down into child nodes, then
/// <seealso cref="ParseTreeWalker#exitRule"/> is called after the recursive call to wind up.
/// </summary>
/// <param name='listener'> The listener used by the walker to process grammar rules </param>
/// <param name='t'> The parse tree to be walked on </param>
virtual void walk(ParseTreeListener *listener, ParseTree *t) const; virtual void walk(ParseTreeListener *listener, ParseTree *t) const;
protected: protected:
/// The discovery of a rule node, involves sending two events: the generic /// <summary>
/// <seealso cref="ParseTreeListener#enterEveryRule"/> and a /// Enters a grammar rule by first triggering the generic event <seealso cref="ParseTreeListener#enterEveryRule"/>
/// <seealso cref="RuleContext"/>-specific event. First we trigger the generic and then /// then by triggering the event specific to the given parse tree node
/// the rule specific. We do them in reverse order upon finishing the node. /// </summary>
/// <param name='listener'> The listener responding to the trigger events </param>
/// <param name='r'> The grammar rule containing the rule context </param>
virtual void enterRule(ParseTreeListener *listener, ParseTree *r) const; virtual void enterRule(ParseTreeListener *listener, ParseTree *r) const;
/// <summary>
/// Exits a grammar rule by first triggering the event specific to the given parse tree node
/// then by triggering the generic event <seealso cref="ParseTreeListener#exitEveryRule"/>
/// </summary>
/// <param name='listener'> The listener responding to the trigger events </param>
/// <param name='r'> The grammar rule containing the rule context </param>
virtual void exitRule(ParseTreeListener *listener, ParseTree *r) const; virtual void exitRule(ParseTreeListener *listener, ParseTree *r) const;
}; };

View File

@ -214,6 +214,10 @@ func NewParseTreeWalker() *ParseTreeWalker {
return new(ParseTreeWalker) return new(ParseTreeWalker)
} }
// Performs a walk on the given parse tree starting at the root and going down recursively
// with depth-first search. On each node, EnterRule is called before
// recursively walking down into child nodes, then
// ExitRule is called after the recursive call to wind up.
func (p *ParseTreeWalker) Walk(listener ParseTreeListener, t Tree) { func (p *ParseTreeWalker) Walk(listener ParseTreeListener, t Tree) {
switch tt := t.(type) { switch tt := t.(type) {
case ErrorNode: case ErrorNode:
@ -231,10 +235,8 @@ func (p *ParseTreeWalker) Walk(listener ParseTreeListener, t Tree) {
} }
// //
// The discovery of a rule node, involves sending two events: the generic // Enters a grammar rule by first triggering the generic event {@link ParseTreeListener//EnterEveryRule}
// {@link ParseTreeListener//EnterEveryRule} and a // then by triggering the event specific to the given parse tree node
// {@link RuleContext}-specific event. First we trigger the generic and then
// the rule specific. We to them in reverse order upon finishing the node.
// //
func (p *ParseTreeWalker) EnterRule(listener ParseTreeListener, r RuleNode) { func (p *ParseTreeWalker) EnterRule(listener ParseTreeListener, r RuleNode) {
ctx := r.GetRuleContext().(ParserRuleContext) ctx := r.GetRuleContext().(ParserRuleContext)
@ -242,6 +244,9 @@ func (p *ParseTreeWalker) EnterRule(listener ParseTreeListener, r RuleNode) {
ctx.EnterRule(listener) ctx.EnterRule(listener)
} }
// Exits a grammar rule by first triggering the event specific to the given parse tree node
// then by triggering the generic event {@link ParseTreeListener//ExitEveryRule}
//
func (p *ParseTreeWalker) ExitRule(listener ParseTreeListener, r RuleNode) { func (p *ParseTreeWalker) ExitRule(listener ParseTreeListener, r RuleNode) {
ctx := r.GetRuleContext().(ParserRuleContext) ctx := r.GetRuleContext().(ParserRuleContext)
ctx.ExitRule(listener) ctx.ExitRule(listener)

View File

@ -158,6 +158,15 @@ class ErrorNodeImpl extends TerminalNodeImpl {
} }
class ParseTreeWalker { class ParseTreeWalker {
/**
* Performs a walk on the given parse tree starting at the root and going down recursively
* with depth-first search. On each node, {@link ParseTreeWalker//enterRule} is called before
* recursively walking down into child nodes, then
* {@link ParseTreeWalker//exitRule} is called after the recursive call to wind up.
* @param listener The listener used by the walker to process grammar rules
* @param t The parse tree to be walked on
*/
walk(listener, t) { walk(listener, t) {
const errorNode = t instanceof ErrorNode || const errorNode = t instanceof ErrorNode ||
(t.isErrorNode !== undefined && t.isErrorNode()); (t.isErrorNode !== undefined && t.isErrorNode());
@ -176,10 +185,10 @@ class ParseTreeWalker {
} }
/** /**
* The discovery of a rule node, involves sending two events: the generic * Enters a grammar rule by first triggering the generic event {@link ParseTreeListener//enterEveryRule}
* {@link ParseTreeListener//enterEveryRule} and a * then by triggering the event specific to the given parse tree node
* {@link RuleContext}-specific event. First we trigger the generic and then * @param listener The listener responding to the trigger events
* the rule specific. We to them in reverse order upon finishing the node. * @param r The grammar rule containing the rule context
*/ */
enterRule(listener, r) { enterRule(listener, r) {
const ctx = r.getRuleContext(); const ctx = r.getRuleContext();
@ -187,6 +196,12 @@ class ParseTreeWalker {
ctx.enterRule(listener); ctx.enterRule(listener);
} }
/**
* Exits a grammar rule by first triggering the event specific to the given parse tree node
* then by triggering the generic event {@link ParseTreeListener//exitEveryRule}
* @param listener The listener responding to the trigger events
* @param r The grammar rule containing the rule context
*/
exitRule(listener, r) { exitRule(listener, r) {
const ctx = r.getRuleContext(); const ctx = r.getRuleContext();
ctx.exitRule(listener); ctx.exitRule(listener);

View File

@ -136,6 +136,14 @@ class ParseTreeWalker(object):
DEFAULT = None DEFAULT = None
def walk(self, listener, t): def walk(self, listener, t):
"""
Performs a walk on the given parse tree starting at the root and going down recursively
with depth-first search. On each node, {@link ParseTreeWalker#enterRule} is called before
recursively walking down into child nodes, then
{@link ParseTreeWalker#exitRule} is called after the recursive call to wind up.
@param listener The listener used by the walker to process grammar rules
@param t The parse tree to be walked on
"""
if isinstance(t, ErrorNode): if isinstance(t, ErrorNode):
listener.visitErrorNode(t) listener.visitErrorNode(t)
return return
@ -154,11 +162,23 @@ class ParseTreeWalker(object):
# the rule specific. We to them in reverse order upon finishing the node. # the rule specific. We to them in reverse order upon finishing the node.
# #
def enterRule(self, listener, r): def enterRule(self, listener, r):
"""
Enters a grammar rule by first triggering the generic event {@link ParseTreeListener#enterEveryRule}
then by triggering the event specific to the given parse tree node
@param listener The listener responding to the trigger events
@param r The grammar rule containing the rule context
"""
ctx = r.getRuleContext() ctx = r.getRuleContext()
listener.enterEveryRule(ctx) listener.enterEveryRule(ctx)
ctx.enterRule(listener) ctx.enterRule(listener)
def exitRule(self, listener, r): def exitRule(self, listener, r):
"""
Exits a grammar rule by first triggering the event specific to the given parse tree node
then by triggering the generic event {@link ParseTreeListener#exitEveryRule}
@param listener The listener responding to the trigger events
@param r The grammar rule containing the rule context
"""
ctx = r.getRuleContext() ctx = r.getRuleContext()
ctx.exitRule(listener) ctx.exitRule(listener)
listener.exitEveryRule(ctx) listener.exitEveryRule(ctx)

View File

@ -140,6 +140,14 @@ class ParseTreeWalker(object):
DEFAULT = None DEFAULT = None
def walk(self, listener:ParseTreeListener, t:ParseTree): def walk(self, listener:ParseTreeListener, t:ParseTree):
"""
Performs a walk on the given parse tree starting at the root and going down recursively
with depth-first search. On each node, {@link ParseTreeWalker#enterRule} is called before
recursively walking down into child nodes, then
{@link ParseTreeWalker#exitRule} is called after the recursive call to wind up.
@param listener The listener used by the walker to process grammar rules
@param t The parse tree to be walked on
"""
if isinstance(t, ErrorNode): if isinstance(t, ErrorNode):
listener.visitErrorNode(t) listener.visitErrorNode(t)
return return
@ -158,11 +166,23 @@ class ParseTreeWalker(object):
# the rule specific. We to them in reverse order upon finishing the node. # the rule specific. We to them in reverse order upon finishing the node.
# #
def enterRule(self, listener:ParseTreeListener, r:RuleNode): def enterRule(self, listener:ParseTreeListener, r:RuleNode):
"""
Enters a grammar rule by first triggering the generic event {@link ParseTreeListener#enterEveryRule}
then by triggering the event specific to the given parse tree node
@param listener The listener responding to the trigger events
@param r The grammar rule containing the rule context
"""
ctx = r.getRuleContext() ctx = r.getRuleContext()
listener.enterEveryRule(ctx) listener.enterEveryRule(ctx)
ctx.enterRule(listener) ctx.enterRule(listener)
def exitRule(self, listener:ParseTreeListener, r:RuleNode): def exitRule(self, listener:ParseTreeListener, r:RuleNode):
"""
Exits a grammar rule by first triggering the event specific to the given parse tree node
then by triggering the generic event {@link ParseTreeListener#exitEveryRule}
@param listener The listener responding to the trigger events
@param r The grammar rule containing the rule context
"""
ctx = r.getRuleContext() ctx = r.getRuleContext()
ctx.exitRule(listener) ctx.exitRule(listener)
listener.exitEveryRule(ctx) listener.exitEveryRule(ctx)

View File

@ -10,6 +10,14 @@ public class ParseTreeWalker {
public init() { public init() {
} }
/**
* Performs a walk on the given parse tree starting at the root and going down recursively
* with depth-first search. On each node, ParseTreeWalker.enterRule is called before
* recursively walking down into child nodes, then
* ParseTreeWalker.exitRule is called after the recursive call to wind up.
* - Parameter listener: The listener used by the walker to process grammar rules
* - Parameter t: The parse tree to be walked on
*/
public func walk(_ listener: ParseTreeListener, _ t: ParseTree) throws { public func walk(_ listener: ParseTreeListener, _ t: ParseTree) throws {
if let errNode = t as? ErrorNode { if let errNode = t as? ErrorNode {
listener.visitErrorNode(errNode) listener.visitErrorNode(errNode)
@ -30,18 +38,24 @@ public class ParseTreeWalker {
} }
} }
/// /**
/// The discovery of a rule node, involves sending two events: the generic * Enters a grammar rule by first triggering the generic event ParseTreeListener.enterEveryRule
/// _org.antlr.v4.runtime.tree.ParseTreeListener#enterEveryRule_ and a * then by triggering the event specific to the given parse tree node
/// _org.antlr.v4.runtime.RuleContext_-specific event. First we trigger the generic and then * - Parameter listener: The listener responding to the trigger events
/// the rule specific. We to them in reverse order upon finishing the node. * - Parameter r: The grammar rule containing the rule context
/// */
internal func enterRule(_ listener: ParseTreeListener, _ r: RuleNode) throws { internal func enterRule(_ listener: ParseTreeListener, _ r: RuleNode) throws {
let ctx = r.getRuleContext() as! ParserRuleContext let ctx = r.getRuleContext() as! ParserRuleContext
try listener.enterEveryRule(ctx) try listener.enterEveryRule(ctx)
ctx.enterRule(listener) ctx.enterRule(listener)
} }
/**
* Exits a grammar rule by first triggering the event specific to the given parse tree node
* then by triggering the generic event ParseTreeListener.exitEveryRule
* - Parameter listener: The listener responding to the trigger events
* - Parameter r: The grammar rule containing the rule context
*/
internal func exitRule(_ listener: ParseTreeListener, _ r: RuleNode) throws { internal func exitRule(_ listener: ParseTreeListener, _ r: RuleNode) throws {
let ctx = r.getRuleContext() as! ParserRuleContext let ctx = r.getRuleContext() as! ParserRuleContext
ctx.exitRule(listener) ctx.exitRule(listener)