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) +``` diff --git a/docs/kotlin/coroutines.md b/docs/kotlin/coroutines.md index e69de29..62204dd 100644 --- a/docs/kotlin/coroutines.md +++ b/docs/kotlin/coroutines.md @@ -0,0 +1,68 @@ +# cloud-kotlin-coroutines + +This module adds coroutine support to commands using builders. +For suspending commands methods, see [cloud-kotlin-coroutines-annotations](./annotations.md). + +## Installation + +Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework). + + +=== "Gradle (Kotlin)" + + ```kotlin + implementation("cloud.commandframework:cloud-kotlin-coroutines:2.0.0-SNAPSHOT") + ``` + +=== "Gradle (Groovy)" + + ```groovy + implementation 'cloud.commandframework:cloud-kotlin-coroutines:2.0.0-SNAPSHOT' + ``` + +## Suspending command execution handlers + +You may create a suspending command execution handler by implementing `SuspendingExecutionHandler`. +The `SuspendingExecutionHandler` interface does not extend `CommandExecutionHandler`, but you can convert +it to a `CommandExecutionHandler` by using `SuspendingExecutionHandler.asCommandExecutionHandler`. + +There are extensions for both `Command.Builder` and `MutableCommandBuilder` that allow you to make direct +use of suspending execution handlers. + +```kotlin title="Example" +manager.commandBuilder("command") + .suspendingHandler { context -> + // ... + } +``` + +## Suspending parsers + +You may create a suspending argument parser by implementing `SuspendingArgumentParser`. +The `SuspendingArgumentParser` interface does not extend `ArgumentParser`, but you can convert +it to an `ArgumentParser` by using `SuspendingArgumentParser.asArgumentParser`. + +You may also create a suspending argument parser by making use of the global factory function: + +```kotlin title="Creating a suspending parser" +suspendingArgumentParser { ctx, input -> + ArgumentParseResult.success(input.readInteger()) +} +``` + +## Suspending suggestion providers + +You may create a suspending suggestion provider by implementing `SuspendingSuggestionProvider`. +The `SuspendingSuggestionProvider` interface does not extend `SuggestionProvider`, but you can convert +it to a `SuggestionProvider` by using `SuspendingSuggestionProvider.asSuggestionProvider`. + +You may also create a suspending suggestion provider by making use of the global factory function: + +```kotlin title="Creating a suspending suggestion provider" +suspendingSuggestionProvider { ctx, input -> + (1..3).asSequence() + .map(Number::toString) + .map(Suggestion::simple) + .asIterable() +} +``` diff --git a/docs/kotlin/index.md b/docs/kotlin/index.md index 2bde9b4..6d82929 100644 --- a/docs/kotlin/index.md +++ b/docs/kotlin/index.md @@ -1 +1,7 @@ # cloud-kotlin + +Cloud has three different modules for Kotlin: + +- [cloud-kotlin-coroutines-annotations](./annotations.md) +- [cloud-kotlin-coroutines](./coroutines.md) +- [cloud-kotlin-extensions](./extensions.md) diff --git a/mkdocs.yml b/mkdocs.yml index 010e608..d2a4b29 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,7 +45,7 @@ theme: - navigation.sections - navigation.indexes - navigation.top - # - navigation.footer + - navigation.footer - toc.follow - search.suggest - search.highlight