#30 Support ShouldListenToChildren in CompositeListeners.

Author: MrKWatkins

doc/topics/API/MrKWatkins.Ast.Children-1.md

@@ -4,7 +4,7 @@
 Collection of child nodes for a [Node<TNode>](MrKWatkins.Ast.Node-1.md).
 
 ```c#
-public sealed class Children<TNode> : IList<TNode>, ICollection<TNode>, IEnumerable<TNode>, IEnumerable
+public sealed class Children<TNode> : IList<TNode>, ICollection<TNode>, IEnumerable<TNode>, IEnumerable, IReadOnlyList<TNode>, IReadOnlyCollection<TNode>
    where TNode : Node<TNode>
 ```
 

…ing/CompositeListenerWithContextTests.cs …ests/Listening/CompositeListenerTests.cssrc/MrKWatkins.Ast.Tests/Listening/CompositeListenerWithContextTests.cs renamed to src/MrKWatkins.Ast.Tests/Listening/CompositeListenerTests.cs src/MrKWatkins.Ast.Tests/Listening/CompositeListenerWithContextTests.cs renamed to src/MrKWatkins.Ast.Tests/Listening/CompositeListenerTests.cs

@@ -152,6 +152,35 @@ public void Listen_RootType()
         rootListener.Count.Should().Equal(10);
     }
 
+    [Test]
+    public void Listen_ShouldListenToChildren()
+    {
+        var doListenToChildren = new TestListener<ANode> { ListenToChildren = (_, _) => true };
+        var doNotListenToChildren = new TestListener<BNode> { ListenToChildren = (_, _) => false };
+
+        var tree = new ANode(new ANode(new CNode()), new BNode(new BChild()), new CNode());
+
+        var listener = CompositeListener<TestContext, TestNode>
+            .Build()
+            .With(doListenToChildren)
+            .With(doNotListenToChildren)
+            .ToListener();
+
+        var context = new TestContext();
+        listener.Listen(context, tree);
+
+        context.Count.Should().Equal(3);
+        doListenToChildren.Count.Should().Equal(2);
+        doNotListenToChildren.Count.Should().Equal(1);
+
+        // Repeat to ensure cached handlers work.
+        listener.Listen(context, tree);
+
+        context.Count.Should().Equal(6);
+        doListenToChildren.Count.Should().Equal(4);
+        doNotListenToChildren.Count.Should().Equal(2);
+    }
+
     private class BChild : BNode;
 
     private class BGrandChild : BChild;
@@ -172,13 +201,17 @@ protected internal override void ListenToNode(TestContext context, TestNode _)
     private sealed class TestListener<TNode> : Listener<TestContext, TestNode, TNode>
         where TNode : TestNode
     {
+        public Func<TestContext, TNode, bool>? ListenToChildren { get; init; }
+
         public int Count { get; private set; }
 
         protected override void ListenToNode(TestContext context, TNode _)
         {
             context.Count++;
             Count++;
         }
+
+        protected override bool ShouldListenToChildren(TestContext context, TNode node) => ListenToChildren?.Invoke(context, node) ?? base.ShouldListenToChildren(context, node);
     }
 
     private sealed class TestContext

…ts/Listening/ListenerWithContextTests.cs …ins.Ast.Tests/Listening/ListenerTests.cssrc/MrKWatkins.Ast.Tests/Listening/ListenerWithContextTests.cs renamed to src/MrKWatkins.Ast.Tests/Listening/ListenerTests.cs src/MrKWatkins.Ast.Tests/Listening/ListenerWithContextTests.cs renamed to src/MrKWatkins.Ast.Tests/Listening/ListenerTests.cs

@@ -42,7 +42,7 @@ private sealed class TestListener : Listener<StringBuilder, TestNode>
 
         protected internal override void AfterListenToNode(StringBuilder context, TestNode node) => context.Append(')');
 
-        protected override bool ShouldListenToChildren(StringBuilder context, TestNode node) => ListenToChildren?.Invoke(context, node) ?? base.ShouldListenToChildren(context, node);
+        protected internal override bool ShouldListenToChildren(StringBuilder context, TestNode node) => ListenToChildren?.Invoke(context, node) ?? base.ShouldListenToChildren(context, node);
     }
 
     private sealed class CallsBaseTestListener : Listener<StringBuilder, TestNode>

src/MrKWatkins.Ast/Listening/CompositeListener.cs

@@ -32,6 +32,9 @@ private CompositeListener()
     /// <inheritdoc />
     protected internal override void AfterListenToNode(TContext context, TBaseNode node) => listeners.Get(node)?.AfterListenToNode(context, node);
 
+    /// <inheritdoc />
+    protected internal override bool ShouldListenToChildren(TContext context, TBaseNode node) => listeners.Get(node)?.ShouldListenToChildren(context, node) ?? true;
+
     [MustUseReturnValue]
     ICompositeListenerBuilder<TContext, TBaseNode> ICompositeListenerBuilder<TContext, TBaseNode>.With(Listener<TContext, TBaseNode> listener)
     {

src/MrKWatkins.Ast/Listening/Listener.cs

@@ -68,7 +68,7 @@ protected internal virtual void AfterListenToNode(TContext context, TNode node)
     /// <param name="context">The context object.</param>
     /// <param name="node">The node whose children should be listened to or not.</param>
     /// <returns><c>true</c> if child nodes should be listened to, <c>false</c> otherwise.</returns>
-    protected virtual bool ShouldListenToChildren(TContext context, TNode node) => true;
+    protected internal virtual bool ShouldListenToChildren(TContext context, TNode node) => true;
 }
 
 /// <summary>
@@ -135,4 +135,16 @@ protected internal sealed override void AfterListenToNode(TContext context, TBas
     protected virtual void AfterListenToNode(TContext context, TNode node)
     {
     }
+
+    /// <inheritdoc />
+    protected internal sealed override bool ShouldListenToChildren(TContext context, TBaseNode node) =>
+        node is not TNode typedNode || ShouldListenToChildren(context, typedNode);
+
+    /// <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 whose children should be listened to or not.</param>
+    /// <returns><c>true</c> if child nodes should be listened to, <c>false</c> otherwise.</returns>
+    protected virtual bool ShouldListenToChildren(TContext context, TNode node) => true;
 }