From 6e4a6747db68c0f07697e1517326d4e8b10aa742 Mon Sep 17 00:00:00 2001
From: tznind <tznind@dundee.ac.uk>
Date: Sat, 26 Oct 2024 17:05:26 +0100
Subject: [PATCH] Refactoring and xmldoc

---
 .../AnsiResponseParser/AnsiResponseParser.cs  | 28 ----------------
 .../AnsiResponseParser/GenericHeld.cs         | 16 +++++++++
 .../AnsiResponseParser/IHeld.cs               | 33 +++++++++++++++++++
 .../AnsiResponseParser/StringHeld.cs          | 15 +++++++++
 4 files changed, 64 insertions(+), 28 deletions(-)
 create mode 100644 Terminal.Gui/ConsoleDrivers/AnsiResponseParser/GenericHeld.cs
 create mode 100644 Terminal.Gui/ConsoleDrivers/AnsiResponseParser/IHeld.cs
 create mode 100644 Terminal.Gui/ConsoleDrivers/AnsiResponseParser/StringHeld.cs

diff --git a/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/AnsiResponseParser.cs b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/AnsiResponseParser.cs
index 8fcac1e02..02a9bfb5e 100644
--- a/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/AnsiResponseParser.cs
+++ b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/AnsiResponseParser.cs
@@ -270,34 +270,6 @@ internal abstract class AnsiResponseParserBase : IAnsiResponseParser
     }
 }
 
-internal interface IHeld
-{
-    void ClearHeld ();
-    string HeldToString ();
-    IEnumerable<object> HeldToObjects ();
-    void AddToHeld (object o);
-}
-
-internal class StringHeld : IHeld
-{
-    private readonly StringBuilder held = new ();
-
-    public void ClearHeld () => held.Clear ();
-    public string HeldToString () => held.ToString ();
-    public IEnumerable<object> HeldToObjects () => held.ToString ().Select (c => (object)c);
-    public void AddToHeld (object o) => held.Append ((char)o);
-}
-
-internal class GenericHeld<T> : IHeld
-{
-    private readonly List<Tuple<char, T>> held = new ();
-
-    public void ClearHeld () => held.Clear ();
-    public string HeldToString () => new (held.Select (h => h.Item1).ToArray ());
-    public IEnumerable<object> HeldToObjects () => held;
-    public void AddToHeld (object o) => held.Add ((Tuple<char, T>)o);
-}
-
 internal class AnsiResponseParser<T> : AnsiResponseParserBase
 {
     public AnsiResponseParser () : base (new GenericHeld<T> ()) { }
diff --git a/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/GenericHeld.cs b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/GenericHeld.cs
new file mode 100644
index 000000000..c81cb6565
--- /dev/null
+++ b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/GenericHeld.cs
@@ -0,0 +1,16 @@
+#nullable enable
+namespace Terminal.Gui;
+
+/// <summary>
+/// Implementation of <see cref="IHeld"/> for <see cref="AnsiResponseParser{T}"/>
+/// </summary>
+/// <typeparam name="T"></typeparam>
+internal class GenericHeld<T> : IHeld
+{
+    private readonly List<Tuple<char, T>> held = new ();
+
+    public void ClearHeld () => held.Clear ();
+    public string HeldToString () => new (held.Select (h => h.Item1).ToArray ());
+    public IEnumerable<object> HeldToObjects () => held;
+    public void AddToHeld (object o) => held.Add ((Tuple<char, T>)o);
+}
diff --git a/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/IHeld.cs b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/IHeld.cs
new file mode 100644
index 000000000..4eb510c16
--- /dev/null
+++ b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/IHeld.cs
@@ -0,0 +1,33 @@
+#nullable enable
+namespace Terminal.Gui;
+
+/// <summary>
+/// Describes a sequence of chars (and optionally T metadata) accumulated
+/// by an <see cref="IAnsiResponseParser"/>
+/// </summary>
+internal interface IHeld
+{
+    /// <summary>
+    /// Clears all held objects
+    /// </summary>
+    void ClearHeld ();
+
+    /// <summary>
+    /// Returns string representation of the held objects
+    /// </summary>
+    /// <returns></returns>
+    string HeldToString ();
+
+    /// <summary>
+    /// Returns the collection objects directly e.g. <see langword="char"/>
+    /// or <see cref="Tuple"/> <see langword="char"/> + metadata T
+    /// </summary>
+    /// <returns></returns>
+    IEnumerable<object> HeldToObjects ();
+
+    /// <summary>
+    /// Adds the given object to the collection.
+    /// </summary>
+    /// <param name="o"></param>
+    void AddToHeld (object o);
+}
diff --git a/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/StringHeld.cs b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/StringHeld.cs
new file mode 100644
index 000000000..b5d8d390c
--- /dev/null
+++ b/Terminal.Gui/ConsoleDrivers/AnsiResponseParser/StringHeld.cs
@@ -0,0 +1,15 @@
+#nullable enable
+namespace Terminal.Gui;
+
+/// <summary>
+/// Implementation of <see cref="IHeld"/> for <see cref="AnsiResponseParser"/>
+/// </summary>
+internal class StringHeld : IHeld
+{
+    private readonly StringBuilder held = new ();
+
+    public void ClearHeld () => held.Clear ();
+    public string HeldToString () => held.ToString ();
+    public IEnumerable<object> HeldToObjects () => held.ToString ().Select (c => (object)c);
+    public void AddToHeld (object o) => held.Append ((char)o);
+}