Allow listeners to skip listening to children.

Author: MrKWatkins

src/MrKWatkins.Ast.Tests/Listening/ListenerTests.cs

@@ -6,7 +6,7 @@ namespace MrKWatkins.Ast.Tests.Listening;
 public sealed class ListenerTests : TreeTestFixture
 {
     [TestCase(typeof(TestListener), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")]
-    [TestCase(typeof(CallsBaseTestListener), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")]    // Explicitly test the base methods do nothing.
+    [TestCase(typeof(CallsBaseTestListener), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")] // Explicitly test the base methods do nothing.
     [TestCase(typeof(TypedTestListener), "(N1(N11(N111))(N121))")]
     [TestCase(typeof(CallsBaseTypedTestListener), "(N1(N11(N111))(N121))")]
     public void Listen(Type listenerType, string expected)
@@ -18,16 +18,33 @@ public void Listen(Type listenerType, string expected)
         listener.ToString().Should().Be(expected);
     }
 
+    [Test]
+    public void ShouldListenToChildren()
+    {
+        var listener = new TestListener { ListenToChildren = node => node is not BNode };
+
+        listener.Listen(N1);
+
+        listener.ToString().Should().Be("(N1(N11(N111))(N12)(N13))");
+    }
+
     private sealed class TestListener : Listener<TestNode>
     {
         private readonly StringBuilder stringBuilder = new();
 
+        public Func<TestNode, bool>? ListenToChildren { get; init; }
+
         protected internal override void BeforeListenToNode(TestNode node) => stringBuilder.Append('(');
 
         protected internal override void ListenToNode(TestNode node) => stringBuilder.Append(node.Name);
 
         protected internal override void AfterListenToNode(TestNode node) => stringBuilder.Append(')');
 
+        protected override bool ShouldListenToChildren(TestNode node)
+        {
+            return ListenToChildren?.Invoke(node) ?? base.ShouldListenToChildren(node);
+        }
+
         public override string ToString() => stringBuilder.ToString();
     }
 

src/MrKWatkins.Ast.Tests/Listening/ListenerWithContextTests.cs

@@ -6,7 +6,7 @@ namespace MrKWatkins.Ast.Tests.Listening;
 public sealed class ListenerWithContextTests : TreeTestFixture
 {
     [TestCase(typeof(TestListenerWithContext), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")]
-    [TestCase(typeof(CallsBaseTestListenerWithContext), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")]    // Explicitly test the base methods do nothing.
+    [TestCase(typeof(CallsBaseTestListenerWithContext), "(N1(N11(N111))(N12(N121)(N122)(N123))(N13))")] // Explicitly test the base methods do nothing.
     [TestCase(typeof(TypedTestListenerWithContext), "(N1(N11(N111))(N121))")]
     [TestCase(typeof(CallsBaseTypedTestListenerWithContext), "(N1(N11(N111))(N121))")]
     public void Listen(Type listenerType, string expected)
@@ -20,13 +20,32 @@ public void Listen(Type listenerType, string expected)
         context.ToString().Should().Be(expected);
     }
 
+    [Test]
+    public void ShouldListenToChildren()
+    {
+        var listener = new TestListenerWithContext { ListenToChildren = (_, node) => node is not BNode };
+
+        var context = new StringBuilder();
+
+        listener.Listen(context, N1);
+
+        context.ToString().Should().Be("(N1(N11(N111))(N12)(N13))");
+    }
+
     private sealed class TestListenerWithContext : ListenerWithContext<StringBuilder, TestNode>
     {
+        public Func<StringBuilder, TestNode, bool>? ListenToChildren { get; init; }
+
         protected internal override void BeforeListenToNode(StringBuilder context, TestNode node) => context.Append('(');
 
         protected internal override void ListenToNode(StringBuilder context, TestNode node) => context.Append(node.Name);
 
         protected internal override void AfterListenToNode(StringBuilder context, TestNode node) => context.Append(')');
+
+        protected override bool ShouldListenToChildren(StringBuilder context, TestNode node)
+        {
+            return ListenToChildren?.Invoke(context, node) ?? base.ShouldListenToChildren(context, node);
+        }
     }
 
     private sealed class CallsBaseTestListenerWithContext : ListenerWithContext<StringBuilder, TestNode>

src/MrKWatkins.Ast/Listening/Listener.cs

@@ -22,9 +22,9 @@ public void Listen(TNode node)
 
         ListenToNode(node);
 
-        foreach (var child in node.Children)
+        if (ShouldListenToChildren(node))
         {
-            Listen(child);
+            foreach (var child in node.Children) Listen(child);
         }
 
         AfterListenToNode(node);
@@ -53,6 +53,15 @@ protected internal virtual void ListenToNode(TNode node)
     protected internal virtual void AfterListenToNode(TNode node)
     {
     }
+
+    /// <summary>
+    ///     Return a value indicating whether child nodes should be listened to or not. Defaults to <c>true</c>.
+    /// </summary>
+    /// <param name="node">The node who's children should be listened to or not.</param>
+    protected virtual bool ShouldListenToChildren(TNode node)
+    {
+        return true;
+    }
 }
 
 /// <summary>

src/MrKWatkins.Ast/Listening/ListenerWithContext.cs

@@ -24,10 +24,9 @@ public void Listen(TContext context, TNode node)
 
         ListenToNode(context, node);
 
-        foreach (var child in node.Children)
-        {
-            Listen(context, child);
-        }
+        if (ShouldListenToChildren(context, node))
+            foreach (var child in node.Children)
+                Listen(context, child);
 
         AfterListenToNode(context, node);
     }
@@ -58,6 +57,16 @@ protected internal virtual void ListenToNode(TContext context, TNode node)
     protected internal virtual void AfterListenToNode(TContext context, TNode node)
     {
     }
+
+    /// <summary>
+    ///     Return a value indicating whether child nodes should be listened to or not. Defaults to <c>true</c>.
+    /// </summary>
+    /// <param name="context">The context object.</param>
+    /// <param name="node">The node who's children should be listened to or not.</param>
+    protected virtual bool ShouldListenToChildren(TContext context, TNode node)
+    {
+        return true;
+    }
 }
 
 /// <summary>