Add support for expressive code in snippets

readme.md

@@ -366,6 +366,50 @@ Windows Registry Editor Version 5.00
 <sup><a href='/src/context-menu.reg#L1-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-context-menu.reg' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
+## Expressive Code / Snippet Metadata
+
+When defining snippets, you can add additional metadata at the source to the rendered snippet using the following syntax.
+
+```csharp
+// begin-snippet: HelloWorld(title=Program.cs {1})
+Console.WriteLine("Hello, World");
+// end-snippet
+```
+
+Note the text within the parenthesis; this is metadata we want to add to the rendered Markdown block immediately after the language declaration.
+The metadata is stripped and the key remains `HelloWorld`. The feature produces the following output at your target destination (will vary based on your configuration):
+
+````markdown
+<-- begin-snippet: HelloWorld -->
+```csharp title=Program.cs {1}
+Console.WriteLine("Hello, World");
+```
+<-- end-snippet -->
+````
+
+This syntax is known as [Expressive Code](https://expressive-code.com/) and is supported in documentation systems such
+as [Astro Starlight](https://github.com/withastro/starlight/) but can be installed in any Markdown-powered tool
+that supports [reHype](https://github.com/rehypejs/rehype).
+
+It is important to note, the metadata is not explicitly limited to Expressive code. Any text within the `()` will be rendered after
+the language block. This can be useful for adding additional information based on your specific rendering engine. For example, if
+you use a presentation tool such as [Sli.dev](https://sli.dev/), you can use this feature to apply [magic-move animations](https://sli.dev/features/shiki-magic-move).
+
+```csharp
+// begin-snippet: EncapsulateVariable({*|2})
+Console.WriteLine("Hello, World");
+// end-snippet
+```
+
+The above snippet will render as follows:
+
+````markdown
+<-- begin-snippet: EncapsulateVariable -->
+```csharp {*|2}
+Console.WriteLine("Hello, World");
+```
+<-- end-snippet -->
+````
 
 ## More Documentation
 

src/Directory.Packages.props

@@ -4,7 +4,7 @@
     <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
   </PropertyGroup>
   <ItemGroup>
-    <PackageVersion Include="Argon" Version="0.27.0" />
+    <PackageVersion Include="Argon" Version="0.28.0" />
     <PackageVersion Include="CommandLineParser" Version="2.9.1" />
     <PackageVersion Include="Microsoft.Build.Tasks.Core" Version="17.13.9" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />

src/MarkdownSnippets/Processing/MarkdownProcessor.cs

@@ -353,7 +353,8 @@ Snippet FileToSnippet(string key, string file, string? path)
             value: text,
             key: key,
             language: Path.GetExtension(file)[1..],
-            path: path);
+            path: path,
+            expressiveCode: null);
     }
 
     (string text, int lineCount) ReadNonStartEndLines(string file)

src/MarkdownSnippets/Processing/SimpleSnippetMarkdownHandling.cs

@@ -15,7 +15,11 @@ public static void Append(string key, IEnumerable<Snippet> snippets, Action<stri
 
     static void WriteSnippet(Action<string> appendLine, Snippet snippet)
     {
-        appendLine($"```{snippet.Language}");
+        var declaration =
+            string.IsNullOrWhiteSpace(snippet.ExpressiveCode)
+                ? snippet.Language
+                : $"{snippet.Language} {snippet.ExpressiveCode}";
+        appendLine($"```{declaration}");
         appendLine(snippet.Value);
         appendLine("```");
     }

src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs

@@ -86,7 +86,11 @@ string GetSupText(Snippet snippet, string anchor)
 
     static void WriteSnippetValueAndLanguage(Action<string> appendLine, Snippet snippet)
     {
-        appendLine($"```{snippet.Language}");
+        var declaration =
+            string.IsNullOrWhiteSpace(snippet.ExpressiveCode)
+                ? snippet.Language
+                : $"{snippet.Language} {snippet.ExpressiveCode}";
+        appendLine($"```{declaration}");
         appendLine(snippet.Value);
         appendLine("```");
     }

src/MarkdownSnippets/Reading/ExpressiveCode.cs

@@ -0,0 +1,17 @@
+internal partial class ExpressiveCode
+{
+#if NET8_0_OR_GREATER
+    [GeneratedRegex(@"([a-zA-Z0-9\-_]+)(?:\((.*?)\))?")]
+    protected partial Regex KeyPatternRegex();
+#else
+    protected static readonly Regex KeyPatternRegex = new(@"([a-zA-Z0-9\-_]+)(?:\((.*?)\))?");
+#endif
+    public ExpressiveCode() =>
+#if NET8_0_OR_GREATER
+        Pattern = KeyPatternRegex();
+#else
+        Pattern = KeyPatternRegex;
+#endif
+    public static ExpressiveCode Instance { get; } = new();
+    public Regex Pattern { get; }
+}

src/MarkdownSnippets/Reading/FileSnippetExtractor.cs

@@ -43,7 +43,7 @@ public static async Task AppendUrlAsSnippet(ICollection<Snippet> snippets, strin
             throw new SnippetException($"Unable to get UrlAsSnippet: {url}");
         }
 
-        var snippet = Snippet.Build(1, content!.LineCount(), content!, key, GetLanguageFromPath(url), url);
+        var snippet = Snippet.Build(1, content!.LineCount(), content!, key, GetLanguageFromPath(url), url, null);
         snippets.Add(snippet);
 
         using var reader = new StringReader(content!);
@@ -71,7 +71,7 @@ public static void AppendFileAsSnippet(ICollection<Snippet> snippets, string fil
     {
         Guard.FileExists(filePath, nameof(filePath));
         var text = File.ReadAllText(filePath);
-        var snippet = Snippet.Build(1, text.LineCount(), text, key, GetLanguageFromPath(filePath), filePath);
+        var snippet = Snippet.Build(1, text.LineCount(), text, key, GetLanguageFromPath(filePath), filePath, null);
         snippets.Add(snippet);
     }
 
@@ -153,9 +153,9 @@ static IEnumerable<Snippet> GetSnippets(TextReader stringReader, string path, in
 
             var trimmedLine = line.Trim();
 
-            if (StartEndTester.IsStart(trimmedLine, path, out var key, out var endFunc))
+            if (StartEndTester.IsStart(trimmedLine, path, out var key, out var endFunc, out var expressive))
             {
-                loopStack.Push(endFunc, key, index, maxWidth, newLine);
+                loopStack.Push(endFunc, key, index, maxWidth, newLine, expressive);
                 continue;
             }
 
@@ -207,7 +207,8 @@ static Snippet BuildSnippet(string path, LoopStack loopStack, string language, i
             key: loopState.Key,
             value: value,
             path: path,
-            language: language.ToLowerInvariant()
+            language: language.ToLowerInvariant(),
+            expressiveCode: loopState.ExpressiveCode
         );
     }
 }

src/MarkdownSnippets/Reading/LoopStack.cs

@@ -15,9 +15,9 @@ public void AppendLine(string line)
 
     public void Pop() => stack.Pop();
 
-    public void Push(EndFunc endFunc, string key, int startLine, int maxWidth, string newLine)
+    public void Push(EndFunc endFunc, string key, int startLine, int maxWidth, string newLine, string? block)
     {
-        var state = new LoopState(key, endFunc, startLine, maxWidth, newLine);
+        var state = new LoopState(key, endFunc, startLine, maxWidth, newLine, block);
         stack.Push(state);
     }
 

src/MarkdownSnippets/Reading/LoopState.cs

@@ -1,5 +1,5 @@
 [DebuggerDisplay("Key={Key}")]
-class LoopState(string key, EndFunc endFunc, int startLine, int maxWidth, string newLine)
+class LoopState(string key, EndFunc endFunc, int startLine, int maxWidth, string newLine, string? expressiveCode = null)
 {
     public string GetLines()
     {
@@ -85,4 +85,5 @@ void CheckWhiteSpace(string line, char whiteSpace)
     public EndFunc EndFunc { get; } = endFunc;
     public int StartLine { get; } = startLine;
     int newlineCount;
+    public string? ExpressiveCode { get; } = expressiveCode;
 }

src/MarkdownSnippets/Reading/Snippet.cs

@@ -26,7 +26,7 @@ public static Snippet BuildError(string key, int lineNumberInError, string path,
     /// <summary>
     /// Initialise a new instance of <see cref="Snippet"/>.
     /// </summary>
-    public static Snippet Build(int startLine, int endLine, string value, string key, string language, string? path)
+    public static Snippet Build(int startLine, int endLine, string value, string key, string language, string? path, string? expressiveCode)
     {
         Guard.AgainstNullAndEmpty(key, nameof(key));
         Guard.AgainstEmpty(path, nameof(path));
@@ -46,6 +46,7 @@ public static Snippet Build(int startLine, int endLine, string value, string key
             Key = key,
             language = language,
             Path = path,
+            ExpressiveCode = expressiveCode,
             Error = ""
         };
     }
@@ -59,6 +60,12 @@ public static Snippet Build(int startLine, int endLine, string value, string key
     /// </summary>
     public string Key { get; private init; } = null!;
 
+    /// <summary>
+    /// An associated expressive code block with the snippet
+    /// See https://expressive-code.com/
+    /// </summary>
+    public string? ExpressiveCode { get; private init; }
+
     /// <summary>
     /// The language of the snippet, extracted from the file extension of the input file.
     /// </summary>
@@ -70,6 +77,7 @@ public string Language
             return language!;
         }
     }
+
     string? language;
 
     /// <summary>
@@ -98,6 +106,7 @@ public string? FileLocation
             {
                 return null;
             }
+
             return $"{Path}({StartLine}-{EndLine})";
         }
     }

src/MarkdownSnippets/Reading/StartEndTester.cs

@@ -1,6 +1,6 @@
 public delegate bool EndFunc(string line);
 
-static class StartEndTester
+static partial class StartEndTester
 {
     internal static bool IsStartOrEnd(string trimmedLine) =>
         IsBeginSnippet(trimmedLine) ||
@@ -12,21 +12,28 @@ internal static bool IsStart(
         string trimmedLine,
         string path,
         [NotNullWhen(true)] out string? currentKey,
-        [NotNullWhen(true)] out EndFunc? endFunc)
+        [NotNullWhen(true)] out EndFunc? endFunc,
+        out string? expressiveCode
+    )
     {
-        if (IsBeginSnippet(trimmedLine, path, out currentKey))
+        if (IsBeginSnippet(trimmedLine, path, out currentKey, out var block))
         {
             endFunc = IsEndSnippet;
+            expressiveCode = block;
             return true;
         }
 
         if (IsStartRegion(trimmedLine, out currentKey))
         {
             endFunc = IsEndRegion;
+            // not supported for regions
+            expressiveCode = null;
             return true;
         }
 
+        expressiveCode = null;
         endFunc = throwFunc;
+
         return false;
     }
 
@@ -78,8 +85,11 @@ static bool IsBeginSnippet(string line)
     internal static bool IsBeginSnippet(
         string line,
         string path,
-        [NotNullWhen(true)] out string? key)
+        [NotNullWhen(true)] out string? key,
+        [NotNullWhen(true)] out string? expressiveCode
+    )
     {
+        expressiveCode = null;
         var beginSnippetIndex = IndexOf(line, "begin-snippet: ");
         if (beginSnippetIndex == -1)
         {
@@ -90,8 +100,10 @@ internal static bool IsBeginSnippet(
         var startIndex = beginSnippetIndex + 15;
         var substring = line
             .TrimBackCommentChars(startIndex);
-        var split = substring.SplitBySpace();
-        if (split.Length == 0)
+
+        var match = ExpressiveCode.Instance.Pattern.Match(substring);
+
+        if (match.Length == 0)
         {
             throw new SnippetReadingException(
                 $"""
@@ -101,7 +113,8 @@ No Key could be derived.
                  """);
         }
 
-        key = split[0];
+        var partOne = match.Groups[1].Value;
+        var split = partOne.SplitBySpace();
         if (split.Length != 1)
         {
             throw new SnippetReadingException(
@@ -112,6 +125,9 @@ Too many parts.
                  """);
         }
 
+        key = split[0];
+        expressiveCode = match.Groups[2].Value;
+
         if (KeyValidator.IsValidKey(key.AsSpan()))
         {
             return true;

src/Tests/DirectoryMarkdownProcessorTests.cs

@@ -507,5 +507,6 @@ static Snippet SnippetBuild(string key, string? path = null) =>
             endLine: 2,
             value: "the code from " + key,
             key: key,
-            path: path);
+            path: path,
+            expressiveCode: null);
 }

src/Tests/MarkdownProcessor/MarkdownProcessorTests.cs

@@ -204,7 +204,8 @@ public Task WithTwoLineSnippet()
                            Snippet
                            """,
                     key: "theKey",
-                    path: "thePath")
+                    path: "thePath",
+                    expressiveCode: null),
             ]);
     }
 
@@ -236,7 +237,8 @@ public Task WithMultiLineSnippet()
                            Snippet
                            """,
                     key: "theKey",
-                    path: "thePath")
+                    path: "thePath",
+                    expressiveCode: null)
             ]);
     }
 
@@ -669,5 +671,6 @@ static Snippet SnippetBuild(string language, string key) =>
             endLine: 2,
             value: "Snippet",
             key: key,
-            path: "thePath");
+            path: "thePath",
+            expressiveCode: null);
 }

src/Tests/SimpleSnippetMarkdownHandlingTests.ExpressiveCode.verified.txt

@@ -0,0 +1,3 @@
+```cs title="HelloWorld.cs" {1}
+Console.WriteLine("Hello World");
+```

src/Tests/SimpleSnippetMarkdownHandlingTests.cs

@@ -4,7 +4,20 @@
     public Task Append()
     {
         var builder = new StringBuilder();
-        var snippets = new List<Snippet> {Snippet.Build(1, 2, "theValue", "thekey", "thelanguage", "thePath")};
+        var snippets = new List<Snippet> {Snippet.Build(1, 2, "theValue", "thekey", "thelanguage", "thePath", null)};
+        using (var writer = new StringWriter(builder))
+        {
+            SimpleSnippetMarkdownHandling.Append("key1", snippets, writer.WriteLine);
+        }
+
+        return Verify(builder.ToString());
+    }
+
+    [Fact]
+    public Task ExpressiveCode()
+    {
+        var builder = new StringBuilder();
+        var snippets = new List<Snippet> {Snippet.Build(1, 2, """Console.WriteLine("Hello World");""", "thekey", "cs", "thePath", """title="HelloWorld.cs" {1}""")};
         using (var writer = new StringWriter(builder))
         {
             SimpleSnippetMarkdownHandling.Append("key1", snippets, writer.WriteLine);

src/Tests/SnippetExtensionsTests.cs

@@ -30,5 +30,6 @@ static Snippet SnippetBuild(string key, string? path) =>
             endLine: 2,
             value: "Snippet",
             key: key,
-            path: path);
+            path: path,
+            expressiveCode: null);
 }

src/Tests/SnippetExtractor/SnippetExtractorTests.CanExtractWithExpressiveCode.verified.txt

@@ -0,0 +1,10 @@
+[
+  {
+    Key: CodeKey,
+    Language: cs,
+    Value: Console.WriteLine("Hello World");,
+    Error: ,
+    FileLocation: path.cs(1-3),
+    IsInError: false
+  }
+]