From 0a55743567708e69e51140777f9e25a6c43714d6 Mon Sep 17 00:00:00 2001 From: Him188 Date: Tue, 17 Nov 2020 10:47:50 +0800 Subject: [PATCH] Update docs --- .../command/descriptor/CommandParameter.kt | 21 +++++++++++- .../src/command/descriptor/TypeVariant.kt | 32 +++++++++++++------ .../src/command/parse/CommandCall.kt | 20 ++++++++++-- .../src/command/parse/CommandValueArgument.kt | 6 ++++ .../command/resolve/ResolvedCommandCall.kt | 21 +++++++++++- 5 files changed, 86 insertions(+), 14 deletions(-) diff --git a/backend/mirai-console/src/command/descriptor/CommandParameter.kt b/backend/mirai-console/src/command/descriptor/CommandParameter.kt index 732c56567..54f9d0f3e 100644 --- a/backend/mirai-console/src/command/descriptor/CommandParameter.kt +++ b/backend/mirai-console/src/command/descriptor/CommandParameter.kt @@ -14,6 +14,7 @@ import net.mamoe.mirai.console.command.descriptor.AbstractCommandValueParameter. import net.mamoe.mirai.console.command.descriptor.AbstractCommandValueParameter.UserDefinedType.Companion.createRequired import net.mamoe.mirai.console.command.descriptor.ArgumentAcceptance.Companion.isAcceptable import net.mamoe.mirai.console.command.parse.CommandValueArgument +import net.mamoe.mirai.console.command.resolve.ResolvedCommandValueArgument import net.mamoe.mirai.console.internal.data.classifierAsKClass import net.mamoe.mirai.console.internal.data.classifierAsKClassOrNull import net.mamoe.mirai.console.internal.data.typeOf0 @@ -52,13 +53,31 @@ public abstract class AbstractCommandParameter : CommandParameter { } /** - * Inherited instances must be [AbstractCommandValueParameter] + * Inherited instances must be [AbstractCommandValueParameter]. + * + * ### Implementation details + * + * [CommandValueParameter] should: + * - implement [equals], [hashCode] since used in [ResolvedCommandValueArgument]. + * - implement [toString] to produce user-friendly textual representation of this parameter with type info. + * */ @ExperimentalCommandDescriptors public interface CommandValueParameter : CommandParameter { public val isVararg: Boolean + /** + * Checks whether this [CommandValueParameter] accepts [argument]. + * + * An [argument] can be accepted if: + * - [CommandValueArgument.type] is subtype of, or equals to [CommandValueParameter.type] (nullability considered), or + * - [CommandValueArgument.typeVariants] produces + * + * @return `true` if [argument] may be accepted through any approach mentioned above. + * + * @see accepting + */ public fun accepts(argument: CommandValueArgument, commandArgumentContext: CommandArgumentContext?): Boolean = accepting(argument, commandArgumentContext).isAcceptable diff --git a/backend/mirai-console/src/command/descriptor/TypeVariant.kt b/backend/mirai-console/src/command/descriptor/TypeVariant.kt index 2a4d49a82..322c92d94 100644 --- a/backend/mirai-console/src/command/descriptor/TypeVariant.kt +++ b/backend/mirai-console/src/command/descriptor/TypeVariant.kt @@ -9,8 +9,6 @@ package net.mamoe.mirai.console.command.descriptor -import net.mamoe.mirai.console.command.parse.CommandCall -import net.mamoe.mirai.console.command.parse.CommandCallParser import net.mamoe.mirai.console.command.parse.CommandValueArgument import net.mamoe.mirai.console.internal.data.castOrNull import net.mamoe.mirai.console.internal.data.kClassQualifiedName @@ -19,9 +17,18 @@ import kotlin.reflect.KType import kotlin.reflect.typeOf /** - * Implicit type variant specified by [CommandCallParser]. + * Intrinsic variant of an [CommandValueArgument]. * - * [TypeVariant] is not necessary for all [CommandCall]s. + * The *intrinsic* reveals the independent conversion property of this type. + * Conversion with [TypeVariant] is out of any contextual resource, + * except the [output type][TypeVariant.outType] declared by the [TypeVariant] itself. + * + * + * [TypeVariant] is not necessary for all [CommandValueArgument]s. + * + * @param OutType the type this [TypeVariant] can map a argument [Message] to . + * + * @see CommandValueArgument.typeVariants */ @ExperimentalCommandDescriptors public interface TypeVariant { @@ -31,17 +38,22 @@ public interface TypeVariant { public val outType: KType /** + * Maps an [valueArgument] to [outType] + * * @see CommandValueArgument.value */ - public fun mapValue(valueParameter: Message): OutType + public fun mapValue(valueArgument: Message): OutType public companion object { + /** + * Creates a [TypeVariant] with reified [OutType]. + */ @OptIn(ExperimentalStdlibApi::class) @JvmSynthetic public inline operator fun invoke(crossinline block: (valueParameter: Message) -> OutType): TypeVariant { return object : TypeVariant { override val outType: KType = typeOf() - override fun mapValue(valueParameter: Message): OutType = block(valueParameter) + override fun mapValue(valueArgument: Message): OutType = block(valueArgument) } } } @@ -51,20 +63,20 @@ public interface TypeVariant { public object MessageContentTypeVariant : TypeVariant { @OptIn(ExperimentalStdlibApi::class) override val outType: KType = typeOf() - override fun mapValue(valueParameter: Message): MessageContent = - valueParameter.castOrNull() ?: error("Accepts MessageContent only but given ${valueParameter.kClassQualifiedName}") + override fun mapValue(valueArgument: Message): MessageContent = + valueArgument.castOrNull() ?: error("Accepts MessageContent only but given ${valueArgument.kClassQualifiedName}") } @ExperimentalCommandDescriptors public object MessageChainTypeVariant : TypeVariant { @OptIn(ExperimentalStdlibApi::class) override val outType: KType = typeOf() - override fun mapValue(valueParameter: Message): MessageChain = valueParameter.asMessageChain() + override fun mapValue(valueArgument: Message): MessageChain = valueArgument.asMessageChain() } @ExperimentalCommandDescriptors public object ContentStringTypeVariant : TypeVariant { @OptIn(ExperimentalStdlibApi::class) override val outType: KType = typeOf() - override fun mapValue(valueParameter: Message): String = valueParameter.content + override fun mapValue(valueArgument: Message): String = valueArgument.content } diff --git a/backend/mirai-console/src/command/parse/CommandCall.kt b/backend/mirai-console/src/command/parse/CommandCall.kt index fdc39e079..1ed8b6cef 100644 --- a/backend/mirai-console/src/command/parse/CommandCall.kt +++ b/backend/mirai-console/src/command/parse/CommandCall.kt @@ -12,29 +12,45 @@ package net.mamoe.mirai.console.command.parse import net.mamoe.mirai.console.command.Command +import net.mamoe.mirai.console.command.CommandManager import net.mamoe.mirai.console.command.CommandSender import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors import net.mamoe.mirai.console.command.resolve.CommandCallResolver +import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall +import net.mamoe.mirai.message.data.MessageChain /** * Unresolved [CommandCall]. * + * ### Implementation details + * [CommandCall] should be _immutable_, + * meaning all of its properties must be *pure* and should be implemented as an immutable property, or delegated by a lazy initializer. + * * @see CommandCallParser * @see CommandCallResolver + * + * @see ResolvedCommandCall */ @ExperimentalCommandDescriptors public interface CommandCall { + /** + * The [CommandSender] responsible to this call. + */ public val caller: CommandSender /** - * One of callee [Command]'s [Command.allNames] + * One of callee [Command]'s [Command.allNames]. + * + * Generally [CommandCallResolver] use [calleeName] to find target [Command] registered in [CommandManager] */ public val calleeName: String /** - * Explicit value arguments + * Explicit value arguments parsed from raw [MessageChain] or implicit ones deduced by the [CommandCallResolver]. */ public val valueArguments: List + + // maybe add contextual arguments, i.e. from MessageMetadata } @ExperimentalCommandDescriptors diff --git a/backend/mirai-console/src/command/parse/CommandValueArgument.kt b/backend/mirai-console/src/command/parse/CommandValueArgument.kt index 03b2771d5..eb17fc552 100644 --- a/backend/mirai-console/src/command/parse/CommandValueArgument.kt +++ b/backend/mirai-console/src/command/parse/CommandValueArgument.kt @@ -42,6 +42,12 @@ public interface CommandValueArgument : CommandArgument { * [MessageChain] is vararg */ public val value: Message + + /** + * Intrinsic variants of this argument. + * + * @see TypeVariant + */ public val typeVariants: List> } diff --git a/backend/mirai-console/src/command/resolve/ResolvedCommandCall.kt b/backend/mirai-console/src/command/resolve/ResolvedCommandCall.kt index 56008f5b5..4f10ab59a 100644 --- a/backend/mirai-console/src/command/resolve/ResolvedCommandCall.kt +++ b/backend/mirai-console/src/command/resolve/ResolvedCommandCall.kt @@ -24,10 +24,17 @@ import net.mamoe.mirai.console.util.cast /** * The resolved [CommandCall]. * + * ### Implementation details + * [ResolvedCommandCall] should be _immutable_, + * meaning all of its properties must be *pure* and should be implemented as an immutable property, or delegated by a lazy initializer. + * * @see ResolvedCommandCallImpl */ @ExperimentalCommandDescriptors public interface ResolvedCommandCall { + /** + * The [CommandSender] responsible to this call. + */ public val caller: CommandSender /** @@ -48,7 +55,7 @@ public interface ResolvedCommandCall { /** * Resolved value arguments arranged mapping the [CommandSignature.valueParameters] by index. * - * **Implementation details**: Lazy calculation. + * **Default implementation details**: Lazy calculation. */ @ConsoleExperimentalApi public val resolvedValueArguments: List> @@ -56,18 +63,30 @@ public interface ResolvedCommandCall { public companion object } +/** + * Resolved [CommandValueParameter] for [ResolvedCommandCall.resolvedValueArguments] + */ @ExperimentalCommandDescriptors public data class ResolvedCommandValueArgument( val parameter: CommandValueParameter, + /** + * Argument value expected by the [parameter] + */ val value: T, ) // Don't move into companion, compilation error +/** + * Invoke this resolved call. + */ @ExperimentalCommandDescriptors public suspend inline fun ResolvedCommandCall.call() { return this@call.calleeSignature.call(this@call) } +/** + * Default implementation. + */ @ExperimentalCommandDescriptors public class ResolvedCommandCallImpl( override val caller: CommandSender,