feat: Add interpolated string support and FormattableString overloads

Added AppendInterpolated/AppendLineInterpolated methods with a custom interpolated string handler for efficient, culture-invariant code generation (C# 10+). Introduced FormattableString overloads for AppendFormat and AppendLineFormat. Added comprehensive unit tests for new features. Improved code formatting and performed minor test cleanup.

Author: samtrion

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Append.cs

@@ -213,14 +213,13 @@ public CSharpCodeBuilder Append(ReadOnlySpan<char> value, int startIndex, int co
         }
 
         EnsureIndented();
-`#if` NETSTANDARD2_0
+#if NETSTANDARD2_0
         _ = _builder.Append(slice.ToString());
-`#else`
+#else
         _ = _builder.Append(slice);
-`#endif`
+#endif
         return this;
     }
-    }
 
     /// <summary>
     /// Appends a subset of a string to the current builder.

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.AppendFormat.cs

@@ -1,4 +1,4 @@
-namespace NetEvolve.CodeBuilder;
+namespace NetEvolve.CodeBuilder;
 
 using System;
 using System.Globalization;
@@ -45,4 +45,68 @@ public CSharpCodeBuilder AppendFormat(IFormatProvider? provider, string format,
         _ = _builder.AppendFormat(provider, format, args);
         return this;
     }
+
+    /// <summary>
+    /// Appends a formattable string to the current builder using invariant culture.
+    /// </summary>
+    /// <param name="formattable">The formattable string to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If <paramref name="formattable"/> is <see langword="null"/>, the method returns without appending anything.</remarks>
+    public CSharpCodeBuilder AppendFormat(FormattableString? formattable)
+    {
+        if (formattable is null)
+        {
+            return this;
+        }
+
+        EnsureIndented();
+        _ = _builder.Append(formattable.ToString(CultureInfo.InvariantCulture));
+        return this;
+    }
+
+    /// <summary>
+    /// Appends a formatted string followed by a line terminator to the current builder using invariant culture.
+    /// </summary>
+    /// <param name="format">A composite format string.</param>
+    /// <param name="arg0">The object to format.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="format"/> is <see langword="null"/>.</exception>
+    /// <exception cref="FormatException">Thrown when <paramref name="format"/> is invalid or the index of a format item is greater than zero.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendLineFormat(string format, object? arg0) =>
+        AppendFormat(CultureInfo.InvariantCulture, format, arg0).AppendLine();
+
+    /// <summary>
+    /// Appends a formatted string followed by a line terminator to the current builder using invariant culture.
+    /// </summary>
+    /// <param name="format">A composite format string.</param>
+    /// <param name="args">An array of objects to format.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="format"/> is <see langword="null"/>.</exception>
+    /// <exception cref="FormatException">Thrown when <paramref name="format"/> is invalid or the index of a format item is greater than the number of elements in <paramref name="args"/> minus 1.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendLineFormat(string format, params object?[] args) =>
+        AppendFormat(CultureInfo.InvariantCulture, format, args).AppendLine();
+
+    /// <summary>
+    /// Appends a formatted string followed by a line terminator to the current builder using the specified format provider.
+    /// </summary>
+    /// <param name="provider">An object that supplies culture-specific formatting information.</param>
+    /// <param name="format">A composite format string.</param>
+    /// <param name="args">An array of objects to format.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="format"/> is <see langword="null"/>.</exception>
+    /// <exception cref="FormatException">Thrown when <paramref name="format"/> is invalid or the index of a format item is greater than the number of elements in <paramref name="args"/> minus 1.</exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendLineFormat(IFormatProvider? provider, string format, params object?[] args) =>
+        AppendFormat(provider, format, args).AppendLine();
+
+    /// <summary>
+    /// Appends a formattable string followed by a line terminator to the current builder using invariant culture.
+    /// </summary>
+    /// <param name="formattable">The formattable string to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If <paramref name="formattable"/> is <see langword="null"/>, only the line terminator is appended.</remarks>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendLineFormat(FormattableString? formattable) => AppendFormat(formattable).AppendLine();
 }

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.AppendInterpolated.cs

@@ -0,0 +1,194 @@
+namespace NetEvolve.CodeBuilder;
+
+#if NET6_0_OR_GREATER
+using System.Globalization;
+using System.Runtime.CompilerServices;
+
+public partial class CSharpCodeBuilder
+{
+    /// <summary>
+    /// Appends an interpolated string to the current builder.
+    /// </summary>
+    /// <param name="handler">The interpolated string handler built by the compiler.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <example>
+    /// <code>
+    /// builder.AppendInterpolated($"public {typeName} {memberName}");
+    /// </code>
+    /// </example>
+    public CSharpCodeBuilder AppendInterpolated(
+        [InterpolatedStringHandlerArgument("")] ref CSharpInterpolatedStringHandler handler
+    ) => this;
+
+    /// <summary>
+    /// Appends an interpolated string followed by a line terminator to the current builder.
+    /// </summary>
+    /// <param name="handler">The interpolated string handler built by the compiler.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <example>
+    /// <code>
+    /// builder.AppendLineInterpolated($"public class {className}");
+    /// </code>
+    /// </example>
+    public CSharpCodeBuilder AppendLineInterpolated(
+        [InterpolatedStringHandlerArgument("")] ref CSharpInterpolatedStringHandler handler
+    ) => AppendLine();
+
+    internal void HandlerEnsureIndented() => EnsureIndented();
+
+    internal void HandlerRawAppend(string? value)
+    {
+        if (!string.IsNullOrEmpty(value))
+        {
+            _ = _builder.Append(value);
+        }
+    }
+
+    internal void HandlerRawAppend(ReadOnlySpan<char> value)
+    {
+        if (!value.IsEmpty)
+        {
+            _ = _builder.Append(value);
+        }
+    }
+}
+
+/// <summary>
+/// Custom interpolated string handler for <see cref="CSharpCodeBuilder"/>.
+/// </summary>
+/// <remarks>
+/// This handler is instantiated by the compiler when an interpolated string is passed to
+/// <see cref="CSharpCodeBuilder.AppendInterpolated"/> or <see cref="CSharpCodeBuilder.AppendLineInterpolated"/>.
+/// It appends each literal and formatted part directly to the builder, applying indentation before
+/// the first non-empty part on a new line.
+/// </remarks>
+[InterpolatedStringHandler]
+public ref struct CSharpInterpolatedStringHandler
+{
+    private readonly CSharpCodeBuilder _owner;
+    private bool _indentEnsured;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CSharpInterpolatedStringHandler"/> struct.
+    /// </summary>
+    /// <param name="literalLength">The total length of all literal parts (hint for capacity).</param>
+    /// <param name="formattedCount">The number of formatted holes in the interpolated string.</param>
+    /// <param name="builder">The <see cref="CSharpCodeBuilder"/> to append to.</param>
+    public CSharpInterpolatedStringHandler(int literalLength, int formattedCount, CSharpCodeBuilder builder)
+    {
+        _owner = builder;
+        _indentEnsured = false;
+    }
+
+    private void EnsureIndented()
+    {
+        if (!_indentEnsured)
+        {
+            _owner.HandlerEnsureIndented();
+            _indentEnsured = true;
+        }
+    }
+
+    /// <summary>Appends a literal string part of the interpolated string.</summary>
+    /// <param name="value">The literal string to append.</param>
+    public void AppendLiteral(string? value)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            return;
+        }
+
+        EnsureIndented();
+        _owner.HandlerRawAppend(value);
+    }
+
+    /// <summary>Appends a formatted value from the interpolated string.</summary>
+    /// <typeparam name="T">The type of the value to format.</typeparam>
+    /// <param name="value">The value to append.</param>
+    public void AppendFormatted<T>(T value)
+    {
+        var str = value?.ToString();
+        if (string.IsNullOrEmpty(str))
+        {
+            return;
+        }
+
+        EnsureIndented();
+        _owner.HandlerRawAppend(str);
+    }
+
+    /// <summary>Appends a formatted value with a format string from the interpolated string.</summary>
+    /// <typeparam name="T">The type of the value to format. Must implement <see cref="System.IFormattable"/>.</typeparam>
+    /// <param name="value">The value to append.</param>
+    /// <param name="format">The format string.</param>
+    public void AppendFormatted<T>(T value, string? format)
+        where T : System.IFormattable
+    {
+        var str = value?.ToString(format, CultureInfo.InvariantCulture);
+        if (string.IsNullOrEmpty(str))
+        {
+            return;
+        }
+
+        EnsureIndented();
+        _owner.HandlerRawAppend(str);
+    }
+
+    /// <summary>Appends a formatted value with alignment from the interpolated string.</summary>
+    /// <typeparam name="T">The type of the value to format.</typeparam>
+    /// <param name="value">The value to append.</param>
+    /// <param name="alignment">Minimum width; negative values left-align.</param>
+    public void AppendFormatted<T>(T value, int alignment)
+    {
+        var str = value?.ToString();
+        if (str is null)
+        {
+            return;
+        }
+
+        str = alignment >= 0 ? str.PadLeft(alignment) : str.PadRight(-alignment);
+        EnsureIndented();
+        _owner.HandlerRawAppend(str);
+    }
+
+    /// <summary>Appends a formatted value with alignment and format string from the interpolated string.</summary>
+    /// <typeparam name="T">The type of the value to format. Must implement <see cref="System.IFormattable"/>.</typeparam>
+    /// <param name="value">The value to append.</param>
+    /// <param name="alignment">Minimum width; negative values left-align.</param>
+    /// <param name="format">The format string.</param>
+    public void AppendFormatted<T>(T value, int alignment, string? format)
+        where T : System.IFormattable
+    {
+        var str = value?.ToString(format, CultureInfo.InvariantCulture) ?? string.Empty;
+        str = alignment >= 0 ? str.PadLeft(alignment) : str.PadRight(-alignment);
+        EnsureIndented();
+        _owner.HandlerRawAppend(str);
+    }
+
+    /// <summary>Appends a string value from the interpolated string.</summary>
+    /// <param name="value">The string to append.</param>
+    public void AppendFormatted(string? value)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            return;
+        }
+
+        EnsureIndented();
+        _owner.HandlerRawAppend(value);
+    }
+
+    /// <summary>Appends a <see cref="ReadOnlySpan{T}"/> value from the interpolated string.</summary>
+    /// <param name="value">The span to append.</param>
+    public void AppendFormatted(ReadOnlySpan<char> value)
+    {
+        if (value.IsEmpty)
+        {
+            return;
+        }
+
+        EnsureIndented();
+        _owner.HandlerRawAppend(value);
+    }
+}
+#endif

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Clear.cs

@@ -1,4 +1,4 @@
-namespace NetEvolve.CodeBuilder;
+namespace NetEvolve.CodeBuilder;
 
 public partial class CSharpCodeBuilder
 {

tests/NetEvolve.CodeBuilder.Tests.Unit/CSharpCodeBuilderTests.AppendFormat.cs

@@ -1,4 +1,4 @@
-namespace NetEvolve.CodeBuilder.Tests.Unit;
+namespace NetEvolve.CodeBuilder.Tests.Unit;
 
 using System;
 using System.Diagnostics.CodeAnalysis;
@@ -603,4 +603,61 @@ public async Task AppendFormat_ParamsArgs_NoProvider_Single_Element_Array_Should
     }
 
 #pragma warning restore CA1305
+
+    [Test]
+    public async Task AppendFormat_FormattableString_Should_Format_Correctly()
+    {
+        var builder = new CSharpCodeBuilder(10);
+        var typeName = "string";
+        var memberName = "Name";
+
+        _ = builder.AppendFormat((FormattableString)$"public {typeName} {memberName}");
+
+        _ = await Assert.That(builder.ToString()).IsEqualTo("public string Name");
+    }
+
+    [Test]
+    public async Task AppendFormat_FormattableString_Should_Apply_Indentation()
+    {
+        var builder = new CSharpCodeBuilder(10);
+        builder.IncrementIndent();
+        var value = 42;
+
+        _ = builder.AppendLine().AppendFormat((FormattableString)$"Value: {value}");
+
+        _ = await Assert.That(builder.ToString()).IsEqualTo(Environment.NewLine + "    Value: 42");
+    }
+
+    [Test]
+    public async Task AppendFormat_FormattableString_Null_Should_Return_Same_Instance_Without_Appending()
+    {
+        var builder = new CSharpCodeBuilder(10);
+
+        var result = builder.AppendFormat((FormattableString?)null);
+
+        _ = await Assert.That(result).IsEqualTo(builder);
+        _ = await Assert.That(builder.ToString()).IsEqualTo(string.Empty);
+    }
+
+    [Test]
+    public async Task AppendFormat_FormattableString_Should_Use_InvariantCulture()
+    {
+        var builder = new CSharpCodeBuilder(10);
+        var value = 1234.56m;
+
+        _ = builder.AppendFormat((FormattableString)$"{value:N2}");
+
+        _ = await Assert.That(builder.ToString()).IsEqualTo("1,234.56");
+    }
+
+    [Test]
+    public async Task AppendFormat_FormattableString_Should_Return_Same_Instance()
+    {
+        var builder = new CSharpCodeBuilder(10);
+        var text = "Hello";
+
+        var result = builder.AppendFormat((FormattableString)$"{text}");
+
+        _ = await Assert.That(result).IsEqualTo(builder);
+    }
 }