Add SerializeWithSourceMap<T>

Author: xPaw

ValveKeyValue/ValveKeyValue.Test/SourceMapTestCase.cs

@@ -99,6 +99,55 @@ public void Kv1SerializerSpansLineUpWithEmittedText()
             Assert.That(spans.Any(s => s.TokenType == KVTokenType.ObjectEnd && text[s.Start] == '}'), Is.True);
         }
 
+        [Test]
+        public void Kv1TypedSerializerSpansLineUpWithEmittedText()
+        {
+            var person = new Person { FirstName = "Alice", Age = 30 };
+
+            var (text, spans) = KVSerializer.Create(KVSerializationFormat.KeyValues1Text)
+                .SerializeWithSourceMap(person, name: "person");
+
+            AssertSpansAreWellFormed(text, spans);
+
+            AssertSpanExists(text, spans, KVTokenType.Key, "\"person\"");
+            AssertSpanExists(text, spans, KVTokenType.Key, "\"FirstName\"");
+            AssertSpanExists(text, spans, KVTokenType.Key, "\"Age\"");
+            AssertSpanExists(text, spans, KVTokenType.String, "\"Alice\"");
+            AssertSpanExists(text, spans, KVTokenType.String, "\"30\"");
+
+            Assert.That(spans.Any(s => s.TokenType == KVTokenType.ObjectStart && text[s.Start] == '{'), Is.True);
+            Assert.That(spans.Any(s => s.TokenType == KVTokenType.ObjectEnd && text[s.Start] == '}'), Is.True);
+        }
+
+        [Test]
+        public void Kv3TypedSerializerSpansLineUpWithEmittedText()
+        {
+            var person = new Person { FirstName = "Alice", Age = 30 };
+
+            var (text, spans) = KVSerializer.Create(KVSerializationFormat.KeyValues3Text)
+                .SerializeWithSourceMap(person, name: "person");
+
+            AssertSpansAreWellFormed(text, spans);
+
+            // Header is emitted by the KV3 serializer regardless of input shape.
+            Assert.That(spans[0].TokenType, Is.EqualTo(KVTokenType.Header));
+            Assert.That(text.AsSpan(spans[0].Start, spans[0].End - spans[0].Start).StartsWith("<!--"), Is.True);
+
+            AssertSpanExists(text, spans, KVTokenType.Key, "FirstName");
+            AssertSpanExists(text, spans, KVTokenType.Key, "Age");
+            AssertSpanExists(text, spans, KVTokenType.String, "\"Alice\"");
+            AssertSpanExists(text, spans, KVTokenType.Identifier, "30");
+
+            Assert.That(spans.Any(s => s.TokenType == KVTokenType.ObjectStart && text[s.Start] == '{'), Is.True);
+            Assert.That(spans.Any(s => s.TokenType == KVTokenType.ObjectEnd && text[s.Start] == '}'), Is.True);
+        }
+
+        class Person
+        {
+            public required string FirstName { get; set; }
+            public int Age { get; set; }
+        }
+
         [Test]
         public void Kv1ParserSpansLineUpWithInputText()
         {

ValveKeyValue/ValveKeyValue.Test/Test Data/apisurface.txt

@@ -267,6 +267,7 @@ public class ValveKeyValue.KVSerializer
     public void Serialize<ValveKeyValue.TData>(System.IO.Stream stream, ValveKeyValue.TData data, string name, ValveKeyValue.KVSerializerOptions options);
     public ValueTuple`2[[string, System.Collections.Generic.IReadOnlyList`1[[ValveKeyValue.KvSourceSpan]]]] SerializeWithSourceMap(ValveKeyValue.KVDocument data, ValveKeyValue.KVSerializerOptions options);
     public ValueTuple`2[[string, System.Collections.Generic.IReadOnlyList`1[[ValveKeyValue.KvSourceSpan]]]] SerializeWithSourceMap(ValveKeyValue.KVObject data, string name, ValveKeyValue.KVSerializerOptions options);
+    public ValueTuple`2[[string, System.Collections.Generic.IReadOnlyList`1[[ValveKeyValue.KvSourceSpan]]]] SerializeWithSourceMap<ValveKeyValue.TData>(ValveKeyValue.TData data, string name, ValveKeyValue.KVSerializerOptions options);
     public string ToString();
 }
 

ValveKeyValue/ValveKeyValue/KVSerializer.cs

@@ -186,6 +186,25 @@ IVisitingReader MakeSourceMapReader(TextReader textReader, IParsingVisitationLis
             return SerializeWithSourceMapCore(data, name, header: null, options);
         }
 
+        /// <summary>
+        /// Serializes a typed object to KeyValues text and produces a per-token source map alongside it.
+        /// Intended for syntax highlighters that want exact token boundaries instead of regex
+        /// approximations. Only text formats are supported.
+        /// </summary>
+        /// <param name="data">The object to serialize.</param>
+        /// <param name="name">The top-level object name.</param>
+        /// <param name="options">Options to use that can influence the serialization process.</param>
+        /// <typeparam name="TData">The type of object to serialize.</typeparam>
+        /// <returns>The serialized text and a list of <see cref="KvSourceSpan"/> records covering each token.</returns>
+        public (string Text, IReadOnlyList<KvSourceSpan> Spans) SerializeWithSourceMap<[DynamicallyAccessedMembers(Trimming.Properties)] TData>(TData data, string name, KVSerializerOptions? options = null)
+        {
+            ArgumentNullException.ThrowIfNull(data);
+            ArgumentNullException.ThrowIfNull(name);
+
+            var kvObjectTree = ObjectCopier.FromObject(typeof(TData), data);
+            return SerializeWithSourceMapCore(kvObjectTree, name, header: null, options);
+        }
+
         (string Text, IReadOnlyList<KvSourceSpan> Spans) SerializeWithSourceMapCore(KVObject root, string? name, KVHeader? header, KVSerializerOptions? options)
         {
             var resolvedOptions = options ?? KVSerializerOptions.DefaultOptions;