Add getGuildOrNull to the Kord class (#714)

Previously there was just a getGuild function that called the nullable variant below the hood, but the non-nullable variant also exists. The getGuildOrNull function was added to clearly show it returns a null, getGuild was deprecated in favor of getGuildOrNull and getGuildOrThrow was added as an alternative for getGuildOrNull that throws when the other would return null. getGuildOrThrow will be deprecated in the future when getGuild with null-returning behavior is removed and will be replaced by getGuild with throwing behavior. The functions were also KDoc'd.
kordlib · Nov 6, 2022 · 4e74545 · 4e74545
1 parent 0905089
commit 4e74545
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 9 deletions.
diff --git a/core/api/core.api b/core/api/core.api
@@ -51,6 +51,10 @@ public final class dev/kord/core/Kord : kotlinx/coroutines/CoroutineScope {
 	public final fun getGuildApplicationCommandOrNull (Ldev/kord/common/entity/Snowflake;Ldev/kord/common/entity/Snowflake;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun getGuildApplicationCommands (Ldev/kord/common/entity/Snowflake;Ljava/lang/Boolean;)Lkotlinx/coroutines/flow/Flow;
 	public static synthetic fun getGuildApplicationCommands$default (Ldev/kord/core/Kord;Ldev/kord/common/entity/Snowflake;Ljava/lang/Boolean;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+	public final fun getGuildOrNull (Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun getGuildOrNull$default (Ldev/kord/core/Kord;Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public final fun getGuildOrThrow (Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun getGuildOrThrow$default (Ldev/kord/core/Kord;Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public final fun getGuildPreview (Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun getGuildPreview$default (Ldev/kord/core/Kord;Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 	public final fun getGuildPreviewOrNull (Ldev/kord/common/entity/Snowflake;Ldev/kord/core/supplier/EntitySupplyStrategy;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;

diff --git a/core/src/main/kotlin/Kord.kt b/core/src/main/kotlin/Kord.kt
@@ -36,6 +36,7 @@ import kotlinx.coroutines.flow.*
 import mu.KLogger
 import mu.KotlinLogging
 import kotlin.DeprecationLevel.HIDDEN
+import kotlin.DeprecationLevel.WARNING
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 import kotlin.coroutines.CoroutineContext
@@ -226,8 +227,7 @@ public class Kord(
      */
     public suspend fun getChannel(
         id: Snowflake,
-        strategy: EntitySupplyStrategy<*> =
-            resources.defaultStrategy,
+        strategy: EntitySupplyStrategy<*> = resources.defaultStrategy,
     ): Channel? = strategy.supply(this).getChannelOrNull(id)
 
     /**
@@ -241,12 +241,45 @@ public class Kord(
         strategy: EntitySupplyStrategy<*> = resources.defaultStrategy,
     ): T? = strategy.supply(this).getChannelOfOrNull(id)
 
+    /**
+     * Requests the [Guild] with the given [id], returns `null` when the guild isn't present.
+     *
+     * @throws RequestException if something went wrong while retrieving the guild.
+     */
+    public suspend fun getGuildOrNull(
+        id: Snowflake,
+        strategy: EntitySupplyStrategy<*> = resources.defaultStrategy,
+    ): Guild? = strategy.supply(this).getGuildOrNull(id)
+
+    /**
+     * Requests the [Guild] with the given [id], returns `null` when the guild isn't present.
+     *
+     * @throws RequestException if something went wrong while retrieving the guild.
+     */
+    @Deprecated(
+        "This function has an inconsistent name for its nullable return type and has been deprecated in favour of " +
+                "'getGuildOrNull()'.",
+        ReplaceWith("this.getGuildOrNull(id, strategy)"),
+        level = WARNING,
+    )
     public suspend fun getGuild(
         id: Snowflake,
-        strategy: EntitySupplyStrategy<*> =
-            resources.defaultStrategy,
+        strategy: EntitySupplyStrategy<*> = resources.defaultStrategy,
     ): Guild? = strategy.supply(this).getGuildOrNull(id)
 
+    /**
+     * Requests the [Guild] with the given [id].
+     *
+     * This will be renamed to `getGuild` once the [deprecated function][getGuild] is removed.
+     *
+     * @throws RequestException if something went wrong while retrieving the guild.
+     * @throws EntityNotFoundException if the guild is null.
+     */
+    public suspend fun getGuildOrThrow(
+        id: Snowflake,
+        strategy: EntitySupplyStrategy<*> = resources.defaultStrategy,
+    ): Guild = strategy.supply(this).getGuild(id)
+
     /**
      * Requests to get the [Webhook] in this guild.
      *
@@ -358,7 +391,6 @@ public class Kord(
     public suspend fun getSticker(id: Snowflake): Sticker = defaultSupplier.getSticker(id)
 
 
-
     /**
      * Requests to edit the presence of the bot user configured by the [builder].
      * The new presence will be shown on all shards. Use [MasterGateway.gateways] or [Event.gateway] to
@@ -425,7 +457,11 @@ public class Kord(
     public fun getGlobalApplicationCommands(withLocalizations: Boolean? = null): Flow<GlobalApplicationCommand> {
         return defaultSupplier.getGlobalApplicationCommands(resources.applicationId, withLocalizations)
     }
-    public fun getGuildApplicationCommands(guildId: Snowflake, withLocalizations: Boolean? = null): Flow<GuildApplicationCommand> {
+
+    public fun getGuildApplicationCommands(
+        guildId: Snowflake,
+        withLocalizations: Boolean? = null,
+    ): Flow<GuildApplicationCommand> {
         return defaultSupplier.getGuildApplicationCommands(resources.applicationId, guildId, withLocalizations)
     }
 

diff --git a/core/src/test/kotlin/rest/RestTest.kt b/core/src/test/kotlin/rest/RestTest.kt
@@ -86,7 +86,7 @@ class RestServiceTest {
 
         guildId = guild.id
 
-        this@RestServiceTest.guild = kord.getGuild(guildId)!!
+        this@RestServiceTest.guild = kord.getGuildOrThrow(guildId)
 
         guild.edit {
             name = "Edited Guild Test"
@@ -555,7 +555,7 @@ class RestServiceTest {
     fun `create role with image icon`(): Unit = runBlocking {
         if (!boostEnabled)
             return@runBlocking
-        val guild = kord.getGuild(publicGuildId)!!
+        val guild = kord.getGuildOrThrow(publicGuildId)
         guild.createRole {
             name = "Test Image Icon"
             hoist = true
@@ -567,7 +567,7 @@ class RestServiceTest {
     fun `create role with unicode icon`(): Unit = runBlocking {
         if (!boostEnabled)
             return@runBlocking
-        val guild = kord.getGuild(publicGuildId)!!
+        val guild = kord.getGuildOrThrow(publicGuildId)
         guild.createRole {
             name = "Test Unicode Icon"
             hoist = true