Allow a stream target for a text extension

docs/converter.md

@@ -184,6 +184,26 @@ Verify("the source text", "texttoconvert");
 <sup><a href='/src/Verify.Tests/Converters/ExtensionConverterTests.cs#L30-L32' title='Snippet source file'>snippet source</a> | <a href='#snippet-TextExtensionConverterVerify' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
+A target for a text extension can also be built from a stream. The stream is read as text, so a converter can re-emit its source without converting it back to a string:
+
+<!-- snippet: RegisterStreamConverterTextExtensionStream -->
+<a id='snippet-RegisterStreamConverterTextExtensionStream'></a>
+```cs
+// A target for a text extension can be built from a stream, eg to re-emit the
+// source of the conversion. The stream is read as text.
+VerifierSettings.RegisterStreamConverter(
+    "streamtoconvert",
+    (_, stream, _) =>
+        new(
+            null,
+            [
+                new("streamtoconvert", stream),
+                new("txt", "derived from text")
+            ]));
+```
+<sup><a href='/src/Verify.Tests/Converters/ExtensionConverterTests.cs#L39-L53' title='Snippet source file'>snippet source</a> | <a href='#snippet-RegisterStreamConverterTextExtensionStream' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
 
 ### Cleanup
 

docs/mdsource/converter.source.md

@@ -62,6 +62,10 @@ snippet: RegisterStreamConverterTextExtension
 
 snippet: TextExtensionConverterVerify
 
+A target for a text extension can also be built from a stream. The stream is read as text, so a converter can re-emit its source without converting it back to a string:
+
+snippet: RegisterStreamConverterTextExtensionStream
+
 
 ### Cleanup
 

src/Verify.Tests/Converters/ExtensionConverterTests.TextSplitterStream.verified.streamtoconvert

@@ -0,0 +1 @@
+the source text

src/Verify.Tests/Converters/ExtensionConverterTests.TextSplitterStream.verified.txt

@@ -0,0 +1 @@
+derived from text

src/Verify.Tests/Converters/ExtensionConverterTests.cs

@@ -31,6 +31,33 @@ public Task TextSplitter() =>
         Verify("the source text", "texttoconvert");
         #endregion
 
+    [ModuleInitializer]
+    public static void TextSplitterStreamInit()
+    {
+        FileExtensions.AddTextExtension("streamtoconvert");
+
+        #region RegisterStreamConverterTextExtensionStream
+
+        // A target for a text extension can be built from a stream, eg to re-emit the
+        // source of the conversion. The stream is read as text.
+        VerifierSettings.RegisterStreamConverter(
+            "streamtoconvert",
+            (_, stream, _) =>
+                new(
+                    null,
+                    [
+                        new("streamtoconvert", stream),
+                        new("txt", "derived from text")
+                    ]));
+
+        #endregion
+    }
+
+    // a conversion splitter for a text extension that re-emits its source stream
+    [Fact]
+    public Task TextSplitterStream() =>
+        Verify("the source text", "streamtoconvert");
+
     [ModuleInitializer]
     public static void RecursiveInit() =>
         VerifierSettings.RegisterStreamConverter(

src/Verify.Tests/InnerVerifyChecksTests/VerifyChecksTests.GetExtensions.verified.txt

@@ -6,6 +6,7 @@
   nuspec,
   props,
   staticComparerExt,
+  streamtoconvert,
   texttoconvert,
   txt,
   xml

src/Verify/IoHelpers.cs

@@ -160,6 +160,11 @@ public static async Task<StringBuilder> ReadStringBuilderWithFixedLines(this Str
     internal static async Task<StringBuilder> ReadStringBuilderWithFixedLines(TextReader reader)
     {
         var contents = await reader.ReadToEndAsync();
+        return contents.ToStringBuilderWithFixedLines();
+    }
+
+    internal static StringBuilder ToStringBuilderWithFixedLines(this string contents)
+    {
         var builder = new StringBuilder(contents);
         if (contents.Contains('\r'))
         {

src/Verify/Target.cs

@@ -57,23 +57,31 @@ public Target(string extension, Stream data, string? name = null, bool performCo
     {
         Guards.AgainstBadExtension(extension);
 
+        Extension = extension;
+        Name = FileNameCleaner.SanitizeFilePath(name);
+        PerformConversion = performConversion;
+
+        // text is always stored as text, so for a text extension the stream is read here.
+        // eg a converter registered against a text extension re-emitting its source stream.
         if (FileExtensions.IsTextExtension(extension))
         {
-            throw new(
-                $"""
-                 Don't pass a stream for text.
-                 If {extension} is not a text extension then use `FileExtensions.RemoveTextExtensions(\"{extension}\")` at initialization;
-                 Otherwise use `Target(string extension, string data)` or `Target(string extension, StringBuilder data, string? name)`.
-                 """);
+            streamData = null;
+            stringBuilderData = ReadText(data);
+            return;
         }
 
-        Extension = extension;
-        Name = FileNameCleaner.SanitizeFilePath(name);
-        PerformConversion = performConversion;
         streamData = data;
         stringBuilderData = null;
     }
 
+    // the stream is owned by the target, so it is consumed here
+    static StringBuilder ReadText(Stream stream)
+    {
+        stream.MoveToStart();
+        using var reader = new StreamReader(stream);
+        return reader.ReadToEnd().ToStringBuilderWithFixedLines();
+    }
+
     public Target(string extension, StringBuilder data, string? name = null)
     {
         ValidateExtension(extension);