BitFlagAttribute.cs

namespace Stardust.Utilities;

/// <summary>
/// Marks a property as a single-bit flag at the specified bit position.
/// </summary>
/// <remarks>
/// <para>
/// The property must be declared as <c>public partial bool</c>.
/// The generator will implement the getter/setter using inline bit manipulation.
/// </para>
/// <example>
/// <code>
/// [BitFields(typeof(byte))]
/// public partial struct StatusRegister
/// {
///     [BitFlag(0)] public partial bool Ready { get; set; }
///     [BitFlag(1)] public partial bool Error { get; set; }
///     [BitFlag(7)] public partial bool Busy { get; set; }
/// }
/// </code>
/// </example>
/// </remarks>
[AttributeUsage(AttributeTargets.Property)]
public sealed class BitFlagAttribute : Attribute
{
    /// <summary>
    /// The bit position (0-based).
    /// </summary>
    public int Bit { get; }

    /// <summary>
    /// Normally set to <see cref="MustBe.Any"/> and has no effect.
    /// When set to <see cref="MustBe.Zero"/> or <see cref="MustBe.One"/>, it overrides the
    /// flag's value. On write and during conversion of the underlying BitFields struct to/from other 
    /// types, the flag's bit will be forced to zero or one respectively.
    /// </summary>
    public MustBe ValueOverride { get; }

    /// <summary>
    /// An optional human-readable description of this flag.
    /// When <see cref="DescriptionResourceType"/> is null, this is a literal string.
    /// When <see cref="DescriptionResourceType"/> is set, this is a resource key
    /// resolved at runtime via the resource type's <c>ResourceManager</c>.
    /// </summary>
    public string? Description { get; set; }

    /// <summary>
    /// When set, <see cref="Description"/> is treated as a resource key and resolved
    /// at runtime via this type's <c>ResourceManager</c> property.
    /// The type must have a static <c>ResourceManager</c> property (as generated by .resx files).
    /// </summary>
    public Type? DescriptionResourceType { get; set; }

    /// <summary>
    /// Creates a new bit flag attribute.
    /// </summary>
    /// <param name="bit">The bit position (0-based).</param>
    /// <param name="mustBe">Optional override for how the bit value is handled. Defaults to <see cref="MustBe.Any"/>.</param>
    public BitFlagAttribute(int bit, MustBe mustBe = MustBe.Any)
    {
        Bit = bit;
        ValueOverride = mustBe;
    }
}