From a0e6ea47f385be021ab91dea11f2347a167700ed Mon Sep 17 00:00:00 2001
From: Jon Manning <jon@secretlab.com.au>
Date: Thu, 19 Dec 2024 13:34:55 +1100
Subject: [PATCH] Add GetHeaders and GetHeaderValue; deprecate GetTagsForNode

---
 CHANGELOG.md                       |  4 ++
 YarnSpinner.Tests/DialogueTests.cs |  2 +-
 YarnSpinner/Dialogue.cs            | 80 +++++++++++++++++++++++++++---
 3 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 609041a9e..5c1334936 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - The compiler will now warn if additional text is present on the same line before or after commands and other statements.
   - For example, the following code will emit a warning, because the last `>` character is likely a typo: `<<wait 5>>>`
+- Added a new method, `Dialogue.GetHeaders`, which returns the collection of headers present on a node.
+- Added a new method, `Dialogue.GetHeaderValue`, which returns the value of the specified header on a node.
 
 ### Changed
 
@@ -17,6 +19,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Removed
 
+- Removed `GetTagsForNode`. This method is replaced with `GetHeaderValue(nodeName, "tags")`.
+
 ## [3.0.0-beta1] 2024-11-29
 
 ### Added
diff --git a/YarnSpinner.Tests/DialogueTests.cs b/YarnSpinner.Tests/DialogueTests.cs
index 87ff4a0ab..91af776be 100644
--- a/YarnSpinner.Tests/DialogueTests.cs
+++ b/YarnSpinner.Tests/DialogueTests.cs
@@ -159,7 +159,7 @@ public void TestGettingTags()
 
             dialogue.SetProgram(result.Program);
 
-            var source = dialogue.GetTagsForNode("LearnMore");
+            var source = dialogue.GetHeaderValue("LearnMore", "tags").Split(' ');
 
             source.Should().NotBeNull();
 
diff --git a/YarnSpinner/Dialogue.cs b/YarnSpinner/Dialogue.cs
index 413a25fb7..0692ffc98 100644
--- a/YarnSpinner/Dialogue.cs
+++ b/YarnSpinner/Dialogue.cs
@@ -947,22 +947,88 @@ public string GetStringIDForNode(string nodeName)
         /// <param name="nodeName">The name of the node.</param>
         /// <returns>The node's tags, or <see langword="null"/> if the node is
         /// not present in the Program.</returns>
+        [Obsolete("Use GetHeaderValue(nodeName, \"tags\"), and split the result by spaces", true)]
         public IEnumerable<string> GetTagsForNode(string nodeName)
         {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        /// Gets the value of the header named <paramref name="headerName"/> on
+        /// the node named <paramref name="nodeName"/>, or <see
+        /// langword="null"/> if the header can't be found.
+        /// </summary>
+        /// <remarks>If the node has more than one header named <paramref
+        /// name="headerName"/>, the first one is used.</remarks>
+        /// <param name="nodeName">The name of the node.</param>
+        /// <param name="headerName">The name of the header.</param>
+        /// <returns>The value of the first header on the node with the
+        /// specified header value.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when the program
+        /// is not loaded, the program contains no nodes, or the program does
+        /// not contain a node named <paramref name="nodeName"/>.</exception>
+        public string? GetHeaderValue(string nodeName, string headerName)
+        {
+            if (this.Program == null)
+            {
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}, because no program is set");
+            }
+
             if (this.Program.Nodes.Count == 0)
             {
-                this.LogErrorMessage?.Invoke("No nodes are loaded!");
-                return null;
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}, because the program contains no nodes");
             }
-            else if (this.Program.Nodes.ContainsKey(nodeName))
+
+            if (this.Program.Nodes.TryGetValue(nodeName, out var node) == false)
             {
-                return this.Program.GetTagsForNode(nodeName);
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}: no node with this name was found");
             }
-            else
+
+            foreach (var header in node.Headers)
             {
-                this.LogErrorMessage?.Invoke("No node named " + nodeName);
-                return null;
+                if (header.Key == nodeName)
+                {
+                    return header.Value.Trim();
+                }
             }
+            return null;
+        }
+
+        /// <summary>
+        /// Gets the collection of headers present on the node named <paramref
+        /// name="nodeName"/>.
+        /// </summary>
+        /// <param name="nodeName">The name of the node to get headers
+        /// for.</param>
+        /// <returns>A collection of key-values pairs, each one representing a
+        /// header on the node.</returns>
+        /// <exception cref="InvalidOperationException">Thrown when the program
+        /// is not loaded, the program contains no nodes, or the program does
+        /// not contain a node named <paramref name="nodeName"/>.</exception>
+        public IEnumerable<KeyValuePair<string, string>> GetHeaders(string nodeName)
+        {
+            if (this.Program == null)
+            {
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}, because no program is set");
+            }
+
+            if (this.Program.Nodes.Count == 0)
+            {
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}, because the program contains no nodes");
+            }
+
+            if (this.Program.Nodes.TryGetValue(nodeName, out var node) == false)
+            {
+                throw new InvalidOperationException($"Can't get headers for node {nodeName}: no node with this name was found");
+            }
+            var result = new List<KeyValuePair<string, string>>(node.Headers.Count);
+
+            foreach (var header in node.Headers)
+            {
+                result.Add(new KeyValuePair<string, string>(header.Key.Trim(), header.Value.Trim()));
+            }
+
+            return result;
         }
 
         /// <summary>