Generate bit flags

[DRSchlaubi]

This PR adds bit flag classes to the code generation in Kord (see #686 for the reasoning of generating boilerplate heavy parts of Kord).

It also tries to unify the API shape of all existing bit flag classes by deprecating some existing declarations and replacing them with declarations that all bit flag classes have in common. They now have this general API shape:

sealed class SomeFlag(val shift: Int) {
    val value: ValueType
    operator fun plus(flag: SomeFlag): SomeFlags
    operator fun plus(flags: SomeFlags): SomeFlags

    class Unknown : SomeFlag
    object Flag1 : SomeFlag
    object Flag2 : SomeFlag
    // ...

    companion object {
        val entries: List<SomeFlag>
        fun fromShift(shift: Int): SomeFlag
    }
}

@Serializable
class SomeFlags(val value: ValueType) {
    val values: Set<SomeFlag>
    operator fun contains(flag: SomeFlag): Boolean
    operator fun contains(flags: SomeFlags): Boolean
    operator fun plus(flag: SomeFlag): SomeFlags
    operator fun plus(flags: SomeFlags): SomeFlags
    operator fun minus(flag: SomeFlag): SomeFlags
    operator fun minus(flags: SomeFlags): SomeFlags
    fun copy(builder: Builder.() -> Unit): SomeFlags

    class Builder(value: ValueType = /* ... */) {
        operator fun SomeFlag.unaryPlus()
        operator fun SomeFlags.unaryPlus()
        operator fun SomeFlag.unaryMinus()
        operator fun SomeFlags.unaryMinus()
        fun build(): SomeFlags
    }
}

fun SomeFlags(builder: SomeFlags.Builder.() -> Unit): SomeFlags
fun SomeFlags(vararg flags: SomeFlag): SomeFlags
fun SomeFlags(vararg flags: SomeFlags): SomeFlags
fun SomeFlags(flags: Iterable<SomeFlag>): SomeFlags
fun SomeFlags(flags: Iterable<SomeFlags>): SomeFlags

This means that flag classes are no longer enum classes. Binary compatibility was preserved as far as possible, but the fact that these classes now no longer have java.lang.Enum as their supertype is a binary incompatible change.

This PR also

• adds ActivityFlag.PartyPrivacyFriends, ActivityFlag.PartyPrivacyVoiceChannel and ActivityFlag.Embedded (these were missing before)
• deprecates UserFlag.System (it was undocumented in 2021)
• renames Intent.GuildBans to Intent.GuildModeration (see here)
• fixes a bug where .copy{ /* ... */ } would also modify the original instance for bit flags based on DiscordBitSet
• fixes some minus functions that would toggle instead of remove bits (this.value xor other.value -> this.value and other.value.inv())

[lukellmann]

i somehow feel like it isn't a good idea to use the same annotation for generation kord enums and flags, although they are really similar, what do you think about this?

[lukellmann]

marked this as a draft for now because i think there is still some significant work needed (e.g. convert all existing flags to be generated while mostly preserving binary compatibility)

[DRSchlaubi]

i somehow feel like it isn't a good idea to use the same annotation for generation kord enums and flags, although they are really similar, what do you think about this?

I thought about this for a while and came to the conclusion that you would have essentially the same annotation twice

[lukellmann]

i think this is ready now, can you take another look @DRSchlaubi?