diff --git a/.wordlist.txt b/.wordlist.txt index 441e9c0..6831e18 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -59,3 +59,5 @@ kotlin iterable Guice GuiceInjectionService +coroutine +coroutines diff --git a/docs/kotlin/annotations.md b/docs/kotlin/annotations.md index e69de29..1aa6506 100644 --- a/docs/kotlin/annotations.md +++ b/docs/kotlin/annotations.md @@ -0,0 +1,54 @@ +# cloud-kotlin-coroutines-annotations + +This module adds coroutine support to [cloud-annotations](../annotations/index.md), allowing you to make +the annotated command methods and suggestion providers suspending. + +The module also adds the ability to use Kotlin default values in both suspending and non-suspending methods. + +```kotlin title="Example of a suspending command method" +@CommandMethod("command [argument]") +suspend fun yourCommand( + argument: String = "default value" +): Unit = withContext(Dispatchers.IO) { + // ... +} +``` + +## Installation + +Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework). + + +=== "Gradle (Kotlin)" + + ```kotlin + implementation("cloud.commandframework:cloud-kotlin-coroutines-annotations:2.0.0-SNAPSHOT") + ``` + +=== "Gradle (Groovy)" + + ```groovy + implementation 'cloud.commandframework:cloud-kotlin-coroutines-annotations:2.0.0-SNAPSHOT' + ``` + +You then need to install the `AnnotationParser` extension: + +```kotlin +annotationParser.installCoroutineSupport() +``` + +You may override the default coroutine scope (`GlobalScope`) and context (`EmptyCoroutineContext`) +when invoking `installCoroutineSupport`. + +## Suggestion Providers + +The coroutine support extends the allowed signatures for `@Suggestions`-annotated methods, letting you return +sequences of `Suggestion` objects as well as strings. + +```kotlin title="Example of a suspending suggestion provider" +@Suggestions("custom-suggestions") +suspend fun suggestionMethod( + context: CommandContext, + input: String +): Sequence = sequenceOf("a", "b", "c").map(Suggestion::simple) +```