Merge pull request #14 from bmazzarol/no-replace

feat: add ability to save non-deterministic examples [ci]
bmazzarol · Jun 7, 2023 · 55faae2 · 55faae2
2 parents 4288223 + dac2502
commit 55faae2
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 5 deletions.
diff --git a/Docfx.ResultSnippets.Docs/articles/save-result.md b/Docfx.ResultSnippets.Docs/articles/save-result.md
@@ -14,3 +14,14 @@ the following name format relative to the code that produced the result,
 ```shell
 ./__examples__/{ClassName}.{MemberName}(.{PartName}).md
 ```
+
+## Non Deterministic Examples
+
+If the generated result is non-deterministic
+@Docfx.ResultSnippets.ResultExtensions.SaveResults* can be called with the
+`replaceExisting` flag set to `false`.
+
+This will ensure the file is only created the first time and its only replaced
+once the file is removed.
+
+[!code-csharp[](../../Docfx.ResultSnippets.Tests/ResultExtensionsTests.cs#SaveResultsExample2)]
diff --git a/Docfx.ResultSnippets.Tests/ResultExtensionsTests.cs b/Docfx.ResultSnippets.Tests/ResultExtensionsTests.cs
@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using FluentAssertions;
@@ -140,4 +141,18 @@ public static void Case8()
         var value = "this is a test".AsFencedResult();
         value.Should().Be("```\nthis is a test\n```");
     }
+
+    [Fact(DisplayName = "Save results skip files if they already exist")]
+    public static void Case9()
+    {
+        #region SaveResultsExample2
+
+        // some non-deterministic value
+        var result = Guid.NewGuid();
+        // now it can be saved as an example the first time only
+        result.SaveResults(replaceExisting: false);
+        #endregion
+
+        result.Should().NotBeEmpty();
+    }
 }
diff --git a/Docfx.ResultSnippets.Tests/__examples__/ResultExtensionsTests.Case9.md b/Docfx.ResultSnippets.Tests/__examples__/ResultExtensionsTests.Case9.md
@@ -0,0 +1 @@
+2e8d500a-31e3-4c50-b919-46099b99eda8
diff --git a/Docfx.ResultSnippets/ResultExtensions.cs b/Docfx.ResultSnippets/ResultExtensions.cs
@@ -26,6 +26,7 @@ public static class ResultExtensions
     /// <param name="folder">folder to save it under, default is `__examples__`</param>
     /// <param name="extension">extension to use for the example file, default is `md`</param>
     /// <param name="partName">optional part name</param>
+    /// <param name="replaceExisting">flag to indicate that existing example files are to be replaced, default is `true`</param>
     /// <param name="sourceFilePath">source file path of the calling code</param>
     /// <param name="memberName">member name of the calling code</param>
     /// <typeparam name="T">some T to `ToString` and save</typeparam>
@@ -34,6 +35,7 @@ public static void SaveResults<T>(
         string folder = "__examples__",
         string extension = "md",
         string partName = "",
+        bool replaceExisting = true,
         [CallerFilePath] string sourceFilePath = "",
         [CallerMemberName] string memberName = ""
     )
@@ -44,11 +46,14 @@ public static void SaveResults<T>(
         var root = Path.GetDirectoryName(sourceFilePath);
         var name = Path.GetFileNameWithoutExtension(sourceFilePath);
         var path = $"{root}/{folder}";
+        var examplePath =
+            $"{path}/{name}.{memberName}{(string.IsNullOrWhiteSpace(partName) ? string.Empty : $".{partName}")}.{extension}";
+
+        if (!replaceExisting && File.Exists(examplePath))
+            return;
+
         Directory.CreateDirectory(path);
-        File.WriteAllText(
-            $"{path}/{name}.{memberName}{(string.IsNullOrWhiteSpace(partName) ? string.Empty : $".{partName}")}.{extension}",
-            data
-        );
+        File.WriteAllText(examplePath, data);
     }
 
     /// <summary>