From ce162842f8589b8668fc3a9bae51baf4b1c876c8 Mon Sep 17 00:00:00 2001 From: lukellmann Date: Mon, 21 Aug 2023 15:20:23 +0200 Subject: [PATCH] Add documentation for Builder and fix build for BIT_SET_FLAGS --- .../dev/kord/common/entity/ActivityFlag.kt | 16 ++++ .../dev/kord/common/entity/ApplicationFlag.kt | 16 ++++ .../dev/kord/common/entity/ChannelFlag.kt | 16 ++++ .../dev/kord/common/entity/GuildMemberFlag.kt | 16 ++++ .../dev/kord/common/entity/MessageFlag.kt | 16 ++++ .../dev/kord/common/entity/Permission.kt | 18 +++- .../kord/common/entity/SystemChannelFlag.kt | 16 ++++ .../kotlin/dev/kord/common/entity/UserFlag.kt | 16 ++++ .../kotlin/entity/PermissionTest.kt | 12 +++ .../kotlin/dev/kord/gateway/Intent.kt | 18 +++- .../kotlin/generation/bitflags/Builder.kt | 95 +++++++++---------- .../kotlin/dev/kord/voice/SpeakingFlag.kt | 16 ++++ 12 files changed, 219 insertions(+), 52 deletions(-) diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt index 685bc1e98b1d..b95a00199a43 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ActivityFlag.kt @@ -430,22 +430,38 @@ public class ActivityFlags internal constructor( public class Builder( private var `value`: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [ActivityFlag]. + */ public operator fun ActivityFlag.unaryPlus() { this@Builder.value = this@Builder.value or this.value } + /** + * Sets all bits in the [Builder] that are set in this [ActivityFlags]. + */ public operator fun ActivityFlags.unaryPlus() { this@Builder.value = this@Builder.value or this.value } + /** + * Unsets all bits in the [Builder] that are set in this [ActivityFlag]. + */ public operator fun ActivityFlag.unaryMinus() { this@Builder.value = this@Builder.value and this.value.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [ActivityFlags]. + */ public operator fun ActivityFlags.unaryMinus() { this@Builder.value = this@Builder.value and this.value.inv() } + /** + * Returns an instance of [ActivityFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): ActivityFlags = ActivityFlags(value) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt index 4eeecf932e74..fc1670bc70c5 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ApplicationFlag.kt @@ -508,22 +508,38 @@ public class ApplicationFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [ApplicationFlag]. + */ public operator fun ApplicationFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [ApplicationFlags]. + */ public operator fun ApplicationFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [ApplicationFlag]. + */ public operator fun ApplicationFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [ApplicationFlags]. + */ public operator fun ApplicationFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [ApplicationFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): ApplicationFlags = ApplicationFlags(code) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt index cd345f309e76..5e5be98d0937 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/ChannelFlag.kt @@ -360,22 +360,38 @@ public class ChannelFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [ChannelFlag]. + */ public operator fun ChannelFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [ChannelFlags]. + */ public operator fun ChannelFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [ChannelFlag]. + */ public operator fun ChannelFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [ChannelFlags]. + */ public operator fun ChannelFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [ChannelFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): ChannelFlags = ChannelFlags(code) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt index ed47d5b7d4ff..97af247f49e1 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/GuildMemberFlag.kt @@ -388,22 +388,38 @@ public class GuildMemberFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [GuildMemberFlag]. + */ public operator fun GuildMemberFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [GuildMemberFlags]. + */ public operator fun GuildMemberFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [GuildMemberFlag]. + */ public operator fun GuildMemberFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [GuildMemberFlags]. + */ public operator fun GuildMemberFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [GuildMemberFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): GuildMemberFlags = GuildMemberFlags(code) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt index 89bc5e0eba94..52ceb6d99603 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/MessageFlag.kt @@ -503,22 +503,38 @@ public class MessageFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [MessageFlag]. + */ public operator fun MessageFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [MessageFlags]. + */ public operator fun MessageFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [MessageFlag]. + */ public operator fun MessageFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [MessageFlags]. + */ public operator fun MessageFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [MessageFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): MessageFlags = MessageFlags(code) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt index c2d583b3b769..ff1f1c988e3e 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/Permission.kt @@ -561,23 +561,39 @@ public class Permissions internal constructor( public class Builder( private val code: DiscordBitSet = EmptyBitSet(), ) { + /** + * Sets all bits in the [Builder] that are set in this [Permission]. + */ public operator fun Permission.unaryPlus() { this@Builder.code.add(this.code) } + /** + * Sets all bits in the [Builder] that are set in this [Permissions]. + */ public operator fun Permissions.unaryPlus() { this@Builder.code.add(this.code) } + /** + * Unsets all bits in the [Builder] that are set in this [Permission]. + */ public operator fun Permission.unaryMinus() { this@Builder.code.remove(this.code) } + /** + * Unsets all bits in the [Builder] that are set in this [Permissions]. + */ public operator fun Permissions.unaryMinus() { this@Builder.code.remove(this.code) } - public fun build(): Permissions = Permissions(code) + /** + * Returns an instance of [Permissions] that has all bits set that are currently set in this + * [Builder]. + */ + public fun build(): Permissions = Permissions(code.copy()) /** * @suppress diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt index 18e739067e16..faf583230d41 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/SystemChannelFlag.kt @@ -426,22 +426,38 @@ public class SystemChannelFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [SystemChannelFlag]. + */ public operator fun SystemChannelFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [SystemChannelFlags]. + */ public operator fun SystemChannelFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [SystemChannelFlag]. + */ public operator fun SystemChannelFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [SystemChannelFlags]. + */ public operator fun SystemChannelFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [SystemChannelFlags] that has all bits set that are currently set + * in this [Builder]. + */ public fun build(): SystemChannelFlags = SystemChannelFlags(code) /** diff --git a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt index 8c70fd716036..24beef34f2e0 100644 --- a/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt +++ b/common/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/common/entity/UserFlag.kt @@ -575,22 +575,38 @@ public class UserFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [UserFlag]. + */ public operator fun UserFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [UserFlags]. + */ public operator fun UserFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [UserFlag]. + */ public operator fun UserFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [UserFlags]. + */ public operator fun UserFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [UserFlags] that has all bits set that are currently set in this + * [Builder]. + */ public fun build(): UserFlags = UserFlags(code) /** diff --git a/common/src/commonTest/kotlin/entity/PermissionTest.kt b/common/src/commonTest/kotlin/entity/PermissionTest.kt index d21ff5de60fd..1eed68d0a19f 100644 --- a/common/src/commonTest/kotlin/entity/PermissionTest.kt +++ b/common/src/commonTest/kotlin/entity/PermissionTest.kt @@ -37,4 +37,16 @@ class PermissionTest { assertNotEquals(a, c) assertNotEquals(b, c) } + + @Test + fun modifying_Builder_after_build_does_not_affect_built_instances() { + val builder = Permissions.Builder() + val a = builder.build() + builder.apply { +Permission.Administrator } + val b = builder.build() + val c = builder.build() + assertNotEquals(a, b) + assertNotEquals(a, c) + assertEquals(b, c) + } } diff --git a/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt b/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt index bf8618721c3a..8ec125ee21d6 100644 --- a/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt +++ b/gateway/build/generated/ksp/metadata/commonMain/kotlin/dev/kord/gateway/Intent.kt @@ -449,23 +449,39 @@ public class Intents internal constructor( public class Builder( private val code: DiscordBitSet = EmptyBitSet(), ) { + /** + * Sets all bits in the [Builder] that are set in this [Intent]. + */ public operator fun Intent.unaryPlus() { this@Builder.code.add(this.code) } + /** + * Sets all bits in the [Builder] that are set in this [Intents]. + */ public operator fun Intents.unaryPlus() { this@Builder.code.add(this.code) } + /** + * Unsets all bits in the [Builder] that are set in this [Intent]. + */ public operator fun Intent.unaryMinus() { this@Builder.code.remove(this.code) } + /** + * Unsets all bits in the [Builder] that are set in this [Intents]. + */ public operator fun Intents.unaryMinus() { this@Builder.code.remove(this.code) } - public fun build(): Intents = Intents(code) + /** + * Returns an instance of [Intents] that has all bits set that are currently set in this + * [Builder]. + */ + public fun build(): Intents = Intents(code.copy()) /** * @suppress diff --git a/ksp-processors/src/main/kotlin/generation/bitflags/Builder.kt b/ksp-processors/src/main/kotlin/generation/bitflags/Builder.kt index 2625074da6d0..64252e91b33c 100644 --- a/ksp-processors/src/main/kotlin/generation/bitflags/Builder.kt +++ b/ksp-processors/src/main/kotlin/generation/bitflags/Builder.kt @@ -1,5 +1,6 @@ package dev.kord.ksp.generation.bitflags +import com.squareup.kotlinpoet.ClassName import com.squareup.kotlinpoet.DelicateKotlinPoetApi import com.squareup.kotlinpoet.KModifier.* import com.squareup.kotlinpoet.TypeSpec @@ -29,59 +30,23 @@ internal fun TypeSpec.Builder.addBuilder() = addClass(builderCN) { ) initializer(valueName) } - - val builder = builderCN.simpleName - addFunction("unaryPlus") { - addModifiers(PUBLIC, OPERATOR) - receiver(entityCN) - - addStatement( - when (valueType) { - INT -> "this@$builder.$valueName = this@$builder.$valueName or this.$valueName" - BIT_SET -> "this@$builder.$valueName.add(this.$valueName)" - } - ) - } - addFunction("unaryPlus") { - addModifiers(PUBLIC, OPERATOR) - receiver(collectionCN) - - addStatement( - when (valueType) { - INT -> "this@$builder.$valueName = this@$builder.$valueName or this.$valueName" - BIT_SET -> "this@$builder.$valueName.add(this.$valueName)" - } - ) - } - - addFunction("unaryMinus") { - addModifiers(PUBLIC, OPERATOR) - receiver(entityCN) - - addStatement( - when (valueType) { - INT -> "this@$builder.$valueName = this@$builder.$valueName and this.$valueName.inv()" - BIT_SET -> "this@$builder.$valueName.remove(this.$valueName)" - } - ) - } - addFunction("unaryMinus") { - addModifiers(PUBLIC, OPERATOR) - receiver(collectionCN) - - addStatement( - when (valueType) { - INT -> "this@$builder.$valueName = this@$builder.$valueName and this.$valueName.inv()" - BIT_SET -> "this@$builder.$valueName.remove(this.$valueName)" - } - ) - } - + addUnaryPlus(receiver = entityCN) + addUnaryPlus(receiver = collectionCN) + addUnaryMinus(receiver = entityCN) + addUnaryMinus(receiver = collectionCN) addFunction("build") { + addKdoc( + "Returns an instance of [%T] that has all bits set that are currently set in this [%T].", + collectionCN, builderCN, + ) + addModifiers(PUBLIC) returns(collectionCN) - addStatement("return %T($valueName)", collectionCN) + val valueCopy = when (valueType) { + INT -> "" + BIT_SET -> ".copy()" + } + addStatement("return %T($valueName$valueCopy)", collectionCN) } - addFunction("flags") { addKdoc("@suppress") @OptIn(DelicateKotlinPoetApi::class) @@ -96,3 +61,33 @@ internal fun TypeSpec.Builder.addBuilder() = addClass(builderCN) { addStatement("return build()") } } + +context(GenerationContext) +private val BitFlags.builder + get() = builderCN.simpleName + +context(BitFlags, GenerationContext) +private fun TypeSpec.Builder.addUnaryPlus(receiver: ClassName) = addFunction("unaryPlus") { + addKdoc("Sets all bits in the [%T] that are set in this [%T].", builderCN, receiver) + addModifiers(PUBLIC, OPERATOR) + receiver(receiver) + addStatement( + when (valueType) { + INT -> "this@$builder.$valueName·=·this@$builder.$valueName·or·this.$valueName" + BIT_SET -> "this@$builder.$valueName.add(this.$valueName)" + } + ) +} + +context(BitFlags, GenerationContext) +private fun TypeSpec.Builder.addUnaryMinus(receiver: ClassName) = addFunction("unaryMinus") { + addKdoc("Unsets all bits in the [%T] that are set in this [%T].", builderCN, receiver) + addModifiers(PUBLIC, OPERATOR) + receiver(receiver) + addStatement( + when (valueType) { + INT -> "this@$builder.$valueName·=·this@$builder.$valueName·and·this.$valueName.inv()" + BIT_SET -> "this@$builder.$valueName.remove(this.$valueName)" + } + ) +} diff --git a/voice/build/generated/ksp/main/kotlin/dev/kord/voice/SpeakingFlag.kt b/voice/build/generated/ksp/main/kotlin/dev/kord/voice/SpeakingFlag.kt index 7fc75f63b144..bdd616e35815 100644 --- a/voice/build/generated/ksp/main/kotlin/dev/kord/voice/SpeakingFlag.kt +++ b/voice/build/generated/ksp/main/kotlin/dev/kord/voice/SpeakingFlag.kt @@ -360,22 +360,38 @@ public class SpeakingFlags internal constructor( public class Builder( private var code: Int = 0, ) { + /** + * Sets all bits in the [Builder] that are set in this [SpeakingFlag]. + */ public operator fun SpeakingFlag.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Sets all bits in the [Builder] that are set in this [SpeakingFlags]. + */ public operator fun SpeakingFlags.unaryPlus() { this@Builder.code = this@Builder.code or this.code } + /** + * Unsets all bits in the [Builder] that are set in this [SpeakingFlag]. + */ public operator fun SpeakingFlag.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Unsets all bits in the [Builder] that are set in this [SpeakingFlags]. + */ public operator fun SpeakingFlags.unaryMinus() { this@Builder.code = this@Builder.code and this.code.inv() } + /** + * Returns an instance of [SpeakingFlags] that has all bits set that are currently set in + * this [Builder]. + */ public fun build(): SpeakingFlags = SpeakingFlags(code) /**