Add support for expressive code in snippets (#717)

* Add support for expressive code blocks in snippets

This update introduces the handling of expressive code metadata for code snippets, enabling enhanced representation and functionality. Changes include parsing, storing, and rendering expressive attributes in snippets, along with updates to tests and relevant components to validate the new feature. Additionally, a package dependency (Argon) is updated for compatibility.

Only works for comment snippets currently.

* Add ExpressiveCode class and integrate Pattern handling

Introduced the `ExpressiveCode` class to centralize regex pattern handling, supporting both .NET 8.0+ generated regex and static regex for older versions. Updated `StartEndTester` to utilize the shared `ExpressiveCode.Instance.Pattern` for consistency and maintainability. Expanded documentation with examples of snippet metadata and its rendering.

* Refactor Regex initialization with conditional compilation.

Reorganized Regex initialization using `#if NET8_0_OR_GREATER` to leverage `GeneratedRegex` for .NET 8+ and fallback to static initialization otherwise instance is null.

* Refactor snippet language declaration handling.

Simplified the logic for generating the language declaration by checking for empty `ExpressiveCode`. No more TrimEnd.

Author: khalidabuhakmeh

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/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;