feat: Addedd ReadOnlySpan, Refactor to class, improve XML docs (#187)

* feat: Addedd ReadOnlySpan, Refactor to class, improve XML docs

- Refactored CSharpCodeBuilder and CodeBuilderBase from record to class, clarifying lack of thread-safety.
- Added Append, AppendIf, AppendLine, and AppendLineIf overloads for ReadOnlySpan<char> (and slices), with .NET Standard 2.0 compatibility.
- Expanded and clarified XML documentation, especially for special character handling and collection-based doc methods.
- Refined XML doc comment generation to use Append/AppendLine for consistency.
- Renamed Intend() to Indent(); marked Intend() as obsolete.
- Improved Clear() and indentation level management (no longer uses Interlocked).
- Enhanced handling of closing braces/brackets in Append(string).
- Updated .editorconfig with static readonly naming rules and other fixes.
- Various minor code and documentation cleanups for clarity and consistency.

* fix: Update src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Append.cs

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Martin Stühmer <me@samtrion.net>

* 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.

* fix: Remove AppendFormatted(string?) from interpolated handler

Removed the AppendFormatted(string?) method from CSharpInterpolatedStringHandler, as its functionality is now redundant. Also updated the #if NET6_0_OR_GREATER directive to wrap the namespace declaration for improved clarity and consistency.

---------

Signed-off-by: Martin Stühmer <me@samtrion.net>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: samtrion

.editorconfig

@@ -87,10 +87,6 @@ insert_final_newline = false
 [*.sln]
 indent_style = tab
 
-[*.{received,verified}.txt]
-insert_final_newline = false
-trim_trailing_whitespace = false
-
 [*.{cs,csx,vb,vbx}]
 # .NET Code Style Settings
 # See https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference
@@ -132,9 +128,16 @@ dotnet_naming_style.all_const.capitalization                            = pascal
 dotnet_naming_symbols.all_const.applicable_kinds                        = field
 dotnet_naming_symbols.all_const.required_modifiers                      = const
 dotnet_naming_rule.all_const.severity                                   = error
-dotnet_naming_rule.all_const.style                                      = all_elements
+dotnet_naming_rule.all_const.style                                      = all_const
 dotnet_naming_rule.all_const.symbols                                    = all_const
 
+dotnet_naming_style.all_static_readonly.capitalization                  = pascal_case
+dotnet_naming_symbols.all_static_readonly.applicable_kinds              = field
+dotnet_naming_symbols.all_static_readonly.required_modifiers            = static, readonly
+dotnet_naming_rule.all_static_readonly.severity                         = error
+dotnet_naming_rule.all_static_readonly.style                            = all_static_readonly
+dotnet_naming_rule.all_static_readonly.symbols                          = all_static_readonly
+
 dotnet_naming_style.all_fields.required_prefix                          = _
 dotnet_naming_style.all_fields.capitalization                           = camel_case
 dotnet_naming_symbols.all_fields.applicable_kinds                       = field
@@ -267,18 +270,6 @@ dotnet_diagnostic.IDE0290.severity                                      = sugges
 # [CSharpier] Incompatible rules deactivated
 # https://csharpier.com/docs/IntegratingWithLinters#code-analysis-rules
 dotnet_diagnostic.IDE0055.severity                                      = none
-dotnet_diagnostic.SA1000.severity                                       = none
-dotnet_diagnostic.SA1009.severity                                       = none
-dotnet_diagnostic.SA1111.severity                                       = none
-dotnet_diagnostic.SA1118.severity                                       = none
-dotnet_diagnostic.SA1137.severity                                       = none
-dotnet_diagnostic.SA1413.severity                                       = none
-dotnet_diagnostic.SA1500.severity                                       = none
-dotnet_diagnostic.SA1501.severity                                       = none
-dotnet_diagnostic.SA1502.severity                                       = none
-dotnet_diagnostic.SA1504.severity                                       = none
-dotnet_diagnostic.SA1515.severity                                       = none
-dotnet_diagnostic.SA1516.severity                                       = none
 
 # Support for NetEvolve.Arguments Methods
 # https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1062#null-check-validation-methods

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.Append.cs

@@ -1,15 +1,15 @@
-namespace NetEvolve.CodeBuilder;
+namespace NetEvolve.CodeBuilder;
 
 using System;
 
-public partial record CSharpCodeBuilder
+public partial class CSharpCodeBuilder
 {
     /// <summary>
     /// Appends a boolean value to the current builder.
     /// </summary>
     /// <param name="value">The boolean value to append.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
-    /// <remarks>Appends either "True" or "False" based on the value.</remarks>
+    /// <remarks>Appends either <see langword="true"/> or <see langword="false"/> based on the value.</remarks>
     public CSharpCodeBuilder Append(bool value)
     {
         EnsureIndented();
@@ -36,6 +36,16 @@ public CSharpCodeBuilder Append(char value, int repeatCount)
     /// </summary>
     /// <param name="value">The character to append.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>
+    /// The following characters receive special treatment:
+    /// <list type="bullet">
+    /// <item><description><c>'\0'</c> — ignored; the method returns without appending.</description></item>
+    /// <item><description><c>'\n'</c> or <c>'\r'</c> — treated as a line terminator; equivalent to calling <see cref="AppendLine()"/>.</description></item>
+    /// <item><description><c>'{'</c> or <c>'['</c> — appended with the current indentation, then the indentation level is incremented and a line terminator is added.</description></item>
+    /// <item><description><c>'}'</c> or <c>']'</c> — the indentation level is decremented first, then the character is appended with the new indentation level, followed by a line terminator.</description></item>
+    /// </list>
+    /// All other characters are appended after applying the current indentation at the start of a new line.
+    /// </remarks>
     public CSharpCodeBuilder Append(char value)
     {
         if (value is '\0')
@@ -164,6 +174,53 @@ public CSharpCodeBuilder Append(ReadOnlyMemory<char> value, int startIndex, int
         return this;
     }
 
+    /// <summary>
+    /// Appends a read-only span of characters to the current builder.
+    /// </summary>
+    /// <param name="value">The read-only span containing the characters to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If the span is empty, the method returns without appending anything.</remarks>
+    public CSharpCodeBuilder Append(ReadOnlySpan<char> value)
+    {
+        if (value.IsEmpty)
+        {
+            return this;
+        }
+
+        EnsureIndented();
+#if NETSTANDARD2_0
+        _ = _builder.Append(value.ToString());
+#else
+        _ = _builder.Append(value);
+#endif
+        return this;
+    }
+
+    /// <summary>
+    /// Appends a subset of a read-only span of characters to the current builder.
+    /// </summary>
+    /// <param name="value">The read-only span containing the characters to append.</param>
+    /// <param name="startIndex">The starting position in the span.</param>
+    /// <param name="count">The number of characters to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If the span is empty, the method returns without appending anything.</remarks>
+    public CSharpCodeBuilder Append(ReadOnlySpan<char> value, int startIndex, int count)
+    {
+        var slice = value.Slice(startIndex, count);
+        if (slice.IsEmpty)
+        {
+            return this;
+        }
+
+        EnsureIndented();
+#if NETSTANDARD2_0
+        _ = _builder.Append(slice.ToString());
+#else
+        _ = _builder.Append(slice);
+#endif
+        return this;
+    }
+
     /// <summary>
     /// Appends a subset of a string to the current builder.
     /// </summary>
@@ -189,7 +246,16 @@ public CSharpCodeBuilder Append(string? value, int startIndex, int count)
     /// </summary>
     /// <param name="value">The string to append.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
-    /// <remarks>If the string is null or empty, the method returns without appending anything.</remarks>
+    /// <remarks>
+    /// <c>null</c>, an empty string, or <c>"\0"</c> are ignored; the method returns without appending.
+    /// The following single-character strings receive special treatment:
+    /// <list type="bullet">
+    /// <item><description><c>"\n"</c>, <c>"\r"</c>, or <c>"\r\n"</c> — treated as a line terminator; equivalent to calling <see cref="AppendLine()"/>.</description></item>
+    /// <item><description><c>"{"</c> or <c>"["</c> — appended with the current indentation, then the indentation level is incremented and a line terminator is added.</description></item>
+    /// <item><description><c>"}"</c> or <c>"]"</c> — the indentation level is decremented first; if the current position is mid-line, a line terminator is inserted before the character. The character is then appended with the new indentation level, followed by a line terminator. This behavior is consistent with <see cref="Append(char)"/>.</description></item>
+    /// </list>
+    /// All other strings are appended after applying the current indentation at the start of a new line.
+    /// </remarks>
     public CSharpCodeBuilder Append(string? value)
     {
         if (string.IsNullOrEmpty(value) || value is "\0")
@@ -205,7 +271,10 @@ public CSharpCodeBuilder Append(string? value)
         if (value is "}" or "]")
         {
             DecrementIndent();
-            _ = AppendLine();
+            if (!_isNewline)
+            {
+                _ = AppendLine(); // Ensure we start a new line before the closing brace
+            }
         }
 
         EnsureIndented();
@@ -216,6 +285,10 @@ public CSharpCodeBuilder Append(string? value)
             IncrementIndent();
             _ = AppendLine();
         }
+        else if (value is "}" or "]")
+        {
+            _ = AppendLine(); // Newline after closing brace, consistent with char overload
+        }
 
         return this;
     }

src/NetEvolve.CodeBuilder/CSharpCodeBuilder.AppendFormat.cs

@@ -4,7 +4,7 @@
 using System.Globalization;
 using System.Runtime.CompilerServices;
 
-public partial record CSharpCodeBuilder
+public partial class CSharpCodeBuilder
 {
     /// <summary>
     /// Appends a formatted string to the current builder using invariant culture.
@@ -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.AppendIf.cs

@@ -1,17 +1,17 @@
-namespace NetEvolve.CodeBuilder;
+namespace NetEvolve.CodeBuilder;
 
 using System;
 using System.Runtime.CompilerServices;
 
-public partial record CSharpCodeBuilder
+public partial class CSharpCodeBuilder
 {
     /// <summary>
     /// Appends a boolean value to the current builder if the specified condition is true.
     /// </summary>
     /// <param name="condition">The condition that determines whether to append the value.</param>
     /// <param name="value">The boolean value to append.</param>
     /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
-    /// <remarks>Appends either "true" or "false" based on the value if the condition is true.</remarks>
+    /// <remarks>Appends either <see langword="true"/> or <see langword="false"/> based on the value if the condition is <see langword="true"/>.</remarks>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public CSharpCodeBuilder AppendIf(bool condition, bool value) => condition ? Append(value) : this;
 
@@ -94,6 +94,29 @@ public unsafe CSharpCodeBuilder AppendIf(bool condition, char* value, int length
     public CSharpCodeBuilder AppendIf(bool condition, ReadOnlyMemory<char> value, int startIndex, int count) =>
         condition ? Append(value, startIndex, count) : this;
 
+    /// <summary>
+    /// Appends a read-only span of characters to the current builder if the specified condition is <see langword="true"/>.
+    /// </summary>
+    /// <param name="condition">The condition that determines whether to append the value.</param>
+    /// <param name="value">The read-only span containing the characters to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If the span is empty, the method returns without appending anything.</remarks>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendIf(bool condition, ReadOnlySpan<char> value) => condition ? Append(value) : this;
+
+    /// <summary>
+    /// Appends a subset of a read-only span of characters to the current builder if the specified condition is <see langword="true"/>.
+    /// </summary>
+    /// <param name="condition">The condition that determines whether to append the value.</param>
+    /// <param name="value">The read-only span containing the characters to append.</param>
+    /// <param name="startIndex">The starting position in the span.</param>
+    /// <param name="count">The number of characters to append.</param>
+    /// <returns>The current <see cref="CSharpCodeBuilder"/> instance to allow for method chaining.</returns>
+    /// <remarks>If the span is empty, the method returns without appending anything.</remarks>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public CSharpCodeBuilder AppendIf(bool condition, ReadOnlySpan<char> value, int startIndex, int count) =>
+        condition ? Append(value, startIndex, count) : this;
+
     /// <summary>
     /// Appends a subset of a string to the current builder if the specified condition is true.
     /// </summary>