gui-cs.Terminal.Gui/Terminal.Gui/Drawing/ColorParseException.cs

#nullable enable
using System.Diagnostics.CodeAnalysis;

namespace Terminal.Gui;

/// <summary>
///   An exception thrown when something goes wrong when trying to parse a <see cref="Color" />.
/// </summary>
/// <remarks>
///   Contains additional information to help locate the problem.
///   <br />
///   Not intended to be thrown by consumers.
/// </remarks>
public sealed class ColorParseException : FormatException {

	internal const string DefaultMessage = "Failed to parse text as Color.";
	internal ColorParseException (string colorString, string? message, Exception? innerException = null) : base (message ?? DefaultMessage, innerException)
	{
		ColorString = colorString;
	}

	internal ColorParseException (string colorString, string? message = DefaultMessage) : base (message)
	{
		ColorString = colorString;
	}

	/// <summary>
	///   Creates a new instance of a <see cref="ColorParseException" /> populated with the provided values.
	/// </summary>
	/// <param name="colorString">The text that caused this exception, as a <see langword="string" />.</param>
	/// <param name="badValue">
	///   The specific value in <paramref name="colorString" /> that caused this exception.
	/// </param>
	/// <param name="badValueName">
	///   The name of the value (red, green, blue, alpha) that <paramref name="badValue" /> represents.
	/// </param>
	/// <param name="reason">The reason that <paramref name="badValue" /> failed to parse.</param>
	internal ColorParseException (in ReadOnlySpan<char> colorString, string reason, in ReadOnlySpan<char> badValue = default, in ReadOnlySpan<char> badValueName = default) : base (DefaultMessage)
	{
		ColorString = colorString.ToString ();
		BadValue = badValue.ToString ();
		BadValueName = badValueName.ToString ();
		Reason = reason;
	}

	/// <summary>
	///   Creates a new instance of a <see cref="ColorParseException" /> populated with the provided values.
	/// </summary>
	/// <param name="colorString">The text that caused this exception, as a <see langword="string" />.</param>
	/// <param name="badValue">
	///   The specific value in <paramref name="colorString" /> that caused this exception.
	/// </param>
	/// <param name="badValueName">
	///   The name of the value (red, green, blue, alpha) that <paramref name="badValue" /> represents.
	/// </param>
	/// <param name="reason">The reason that <paramref name="badValue" /> failed to parse.</param>
	internal ColorParseException (in ReadOnlySpan<char> colorString, string? badValue = null, string? badValueName = null, string? reason = null) : base (DefaultMessage)
	{
		ColorString = colorString.ToString ();
		BadValue = badValue;
		BadValueName = badValueName;
		Reason = reason;
	}

	/// <summary>Gets the text that failed to parse, as a <see langword="string" /></summary>
	/// <remarks>
	///   Is marked <see langword="required" />, so must be set by a constructor or initializer.
	/// </remarks>
	public string ColorString { get; }

	/// <summary>
	///   Gets the substring of <see cref="ColorString" /> caused this exception, as a <see langword="string" />
	/// </summary>
	/// <remarks>May be null or empty - only set if known.</remarks>
	public string? BadValue { get; }

	/// <summary>
	///   Gets the name of the color component corresponding to <see cref="BadValue" />, if known.
	/// </summary>
	/// <remarks>May be null or empty - only set if known.</remarks>
	public string? BadValueName { get; }

	/// <summary>Gets the reason that <see cref="BadValue" /> failed to parse, if known.</summary>
	/// <remarks>May be null or empty - only set if known.</remarks>
	public string? Reason { get; }

	[DoesNotReturn]
	internal static void Throw (in ReadOnlySpan<char> colorString, string reason, in ReadOnlySpan<char> badValue = default, in ReadOnlySpan<char> badValueName = default) => throw new ColorParseException (in colorString, reason, in badValue, in badValueName);

	[DoesNotReturn]
	internal static void ThrowIfNotAsciiDigits (in ReadOnlySpan<char> valueText, string reason, in ReadOnlySpan<char> badValue = default, in ReadOnlySpan<char> badValueName = default) => throw new ColorParseException (in valueText, reason, in badValue, in badValueName);
}