Command descriptors

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/descriptor/CommandDescriptor.kt

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.descriptor
+
+import net.mamoe.mirai.console.util.safeCast
+import kotlin.reflect.KClass
+import kotlin.reflect.KType
+import kotlin.reflect.typeOf
+
+@ExperimentalCommandDescriptors
+public interface CommandDescriptor {
+    public val overloads: List<CommandSignatureVariant>
+}
+
+@ExperimentalCommandDescriptors
+public interface CommandSignatureVariant {
+    public val valueParameters: List<CommandValueParameter<*>>
+}
+
+
+/**
+ * Inherited instances must be [CommandValueParameter]
+ */
+@ExperimentalCommandDescriptors
+public interface ICommandParameter<T : Any?> {
+    public val name: String
+    public val type: KType
+    public val defaultValue: T?
+
+    public companion object {
+        @get:JvmStatic
+        @ExperimentalCommandDescriptors
+        public val ICommandParameter<*>.isOptional: Boolean
+            get() = this.defaultValue != null
+
+    }
+}
+
+@ExperimentalCommandDescriptors
+public sealed class CommandValueParameter<T> : ICommandParameter<T> {
+    init {
+        @Suppress("LeakingThis")
+        require(type.classifier?.safeCast<KClass<*>>()?.isInstance(defaultValue) == true) {
+            "defaultValue is not instance of type"
+        }
+    }
+
+    public class StringConstant(
+        public override val name: String,
+        public override val defaultValue: String,
+    ) : CommandValueParameter<String>() {
+        override val type: KType get() = STRING_TYPE
+
+        private companion object {
+            @OptIn(ExperimentalStdlibApi::class)
+            val STRING_TYPE = typeOf<String>()
+        }
+    }
+
+    /**
+     * Extended by [CommandArgumentParser]
+     */
+    public abstract class Extended<T> : CommandValueParameter<T>()
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/descriptor/Exceptions.kt

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+@file:Suppress("MemberVisibilityCanBePrivate", "unused")
+
+package net.mamoe.mirai.console.command.descriptor
+
+import net.mamoe.mirai.console.command.parse.CommandCall
+import net.mamoe.mirai.console.command.parse.CommandValueArgument
+import net.mamoe.mirai.console.internal.command.qualifiedNameOrTip
+import net.mamoe.mirai.console.internal.data.classifierAsKClassOrNull
+import kotlin.reflect.KType
+
+
+internal val KType.qualifiedName: String
+    get() = this.classifierAsKClassOrNull()?.qualifiedNameOrTip ?: classifier.toString()
+
+@ExperimentalCommandDescriptors
+public open class NoValueArgumentMappingException(
+    public val argument: CommandValueArgument,
+    public val forType: KType,
+) : CommandResolutionException("Cannot find a CommandArgument mapping for ${forType.qualifiedName}")
+
+@ExperimentalCommandDescriptors
+public open class UnresolvedCommandCallException(
+    public val call: CommandCall,
+) : CommandResolutionException("Unresolved call: $call")
+
+public open class CommandResolutionException : RuntimeException {
+    public constructor() : super()
+    public constructor(message: String?) : super(message)
+    public constructor(message: String?, cause: Throwable?) : super(message, cause)
+    public constructor(cause: Throwable?) : super(cause)
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/descriptor/ExperimentalCommandDescriptors.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.descriptor
+
+import net.mamoe.mirai.console.util.ConsoleExperimentalApi
+import kotlin.annotation.AnnotationTarget.*
+
+/**
+ * 标记一个实验性的指令解释器 API.
+ *
+ * 这些 API 不具有稳定性, 且可能会在任意时刻更改.
+ * 不建议在发行版本中使用这些 API.
+ *
+ * @since 1.0-RC
+ */
+@Retention(AnnotationRetention.BINARY)
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+@Target(CLASS, TYPEALIAS, FUNCTION, PROPERTY, FIELD, CONSTRUCTOR)
+@MustBeDocumented
+@ConsoleExperimentalApi
+@ExperimentalCommandDescriptors
+public annotation class ExperimentalCommandDescriptors(
+    val message: String = "Command descriptors are an experimental API.",
+)

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/descriptor/TypeVariant.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.descriptor
+
+import kotlin.reflect.KType
+import kotlin.reflect.typeOf
+
+@ExperimentalCommandDescriptors
+public interface TypeVariant<out OutType> {
+    public val outType: KType
+
+    public fun mapValue(valueParameter: String): OutType
+
+    public companion object {
+        @OptIn(ExperimentalStdlibApi::class)
+        @JvmSynthetic
+        public inline operator fun <reified OutType> invoke(crossinline block: (valueParameter: String) -> OutType): TypeVariant<OutType> {
+            return object : TypeVariant<OutType> {
+                override val outType: KType = typeOf<OutType>()
+                override fun mapValue(valueParameter: String): OutType = block(valueParameter)
+            }
+        }
+    }
+}
+
+@ExperimentalCommandDescriptors
+public object StringTypeVariant : TypeVariant<String> {
+    @OptIn(ExperimentalStdlibApi::class)
+    override val outType: KType = typeOf<String>()
+    override fun mapValue(valueParameter: String): String = valueParameter
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandCall.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+@file:OptIn(ExperimentalStdlibApi::class)
+
+package net.mamoe.mirai.console.command.parse
+
+import net.mamoe.mirai.console.command.CommandSender
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.descriptor.UnresolvedCommandCallException
+import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall
+import net.mamoe.mirai.console.extensions.CommandCallResolverProvider
+import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
+
+@ExperimentalCommandDescriptors
+public interface CommandCall {
+    public val caller: CommandSender
+
+    public val calleeName: String
+    public val valueArguments: List<CommandValueArgument>
+
+    public companion object {
+        @JvmStatic
+        public fun CommandCall.resolveOrNull(): ResolvedCommandCall? {
+            GlobalComponentStorage.run {
+                CommandCallResolverProvider.useExtensions { provider ->
+                    provider.instance.resolve(this@resolveOrNull)?.let { return it }
+                }
+            }
+            return null
+        }
+
+        @JvmStatic
+        public fun CommandCall.resolve(): ResolvedCommandCall {
+            return resolveOrNull() ?: throw UnresolvedCommandCallException(this)
+        }
+    }
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandCallParser.kt

@@ -0,0 +1,29 @@
+package net.mamoe.mirai.console.command.parse
+
+import net.mamoe.mirai.console.command.CommandSender
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.extensions.CommandCallParserProvider
+import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
+import net.mamoe.mirai.console.util.ConsoleExperimentalApi
+import net.mamoe.mirai.message.data.MessageChain
+
+/**
+ * @see CommandCallParserProvider
+ */
+@ConsoleExperimentalApi
+@ExperimentalCommandDescriptors
+public interface CommandCallParser {
+    public fun parse(sender: CommandSender, message: MessageChain): CommandCall?
+
+    public companion object {
+        @JvmStatic
+        public fun MessageChain.parseCommandCall(sender: CommandSender): CommandCall? {
+            GlobalComponentStorage.run {
+                CommandCallParserProvider.useExtensions { provider ->
+                    provider.instance.parse(sender, this@parseCommandCall)?.let { return it }
+                }
+            }
+            return null
+        }
+    }
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/parse/CommandValueArgument.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.parse
+
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.descriptor.NoValueArgumentMappingException
+import net.mamoe.mirai.console.command.descriptor.StringTypeVariant
+import net.mamoe.mirai.console.command.descriptor.TypeVariant
+import kotlin.reflect.full.isSubtypeOf
+import kotlin.reflect.typeOf
+
+@ExperimentalCommandDescriptors
+public interface CommandValueArgument {
+    public val value: String
+    public val typeVariants: List<TypeVariant<*>>
+}
+
+@ExperimentalCommandDescriptors
+public data class InvariantCommandValueArgument(
+    public override val value: String,
+) : CommandValueArgument {
+    override val typeVariants: List<TypeVariant<*>> = listOf(StringTypeVariant)
+}
+
+@ExperimentalCommandDescriptors
+public fun <T> CommandValueArgument.mapValue(typeVariant: TypeVariant<T>): T = typeVariant.mapValue(this.value)
+
+
+@OptIn(ExperimentalStdlibApi::class)
+@ExperimentalCommandDescriptors
+public inline fun <reified T> CommandValueArgument.mapToType(): T =
+    mapToTypeOrNull() ?: throw  NoValueArgumentMappingException(this, typeOf<T>())
+
+@ExperimentalCommandDescriptors
+public inline fun <reified T> CommandValueArgument.mapToTypeOrNull(): T? {
+    @OptIn(ExperimentalStdlibApi::class)
+    val expectingType = typeOf<T>()
+    val result = typeVariants
+        .filter { it.outType.isSubtypeOf(expectingType) }
+        .also {
+            if (it.isEmpty()) return null
+        }
+        .reduce { acc, typeVariant ->
+            if (acc.outType.isSubtypeOf(typeVariant.outType))
+                acc
+            else typeVariant
+        }
+    return result.mapValue(value) as T
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/resolve/CommandCallResolver.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.resolve
+
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.parse.CommandCall
+
+public interface CommandCallResolver {
+    @ExperimentalCommandDescriptors
+    public fun resolve(call: CommandCall): ResolvedCommandCall?
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/resolve/ResolvedCommandCall.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.command.resolve;
+
+import net.mamoe.mirai.console.command.Command
+import net.mamoe.mirai.console.command.CommandSender
+import net.mamoe.mirai.console.command.descriptor.CommandDescriptor
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.parse.CommandValueArgument
+
+@ExperimentalCommandDescriptors
+public interface ResolvedCommandCall {
+    public val caller: CommandSender
+
+    public val callee: Command
+    public val calleeDescriptor: CommandDescriptor
+    public val valueArguments: List<CommandValueArgument>
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandParser.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.extensions
+
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.parse.CommandCallParser
+import net.mamoe.mirai.console.extension.AbstractExtensionPoint
+import net.mamoe.mirai.console.extension.InstanceExtension
+
+@ExperimentalCommandDescriptors
+public interface CommandCallParserProvider : InstanceExtension<CommandCallParser> {
+    public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallParserProvider>(CommandCallParserProvider::class)
+}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandResolverExtension.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.extensions
+
+import net.mamoe.mirai.console.command.resolve.CommandCallResolver
+import net.mamoe.mirai.console.extension.AbstractExtensionPoint
+import net.mamoe.mirai.console.extension.InstanceExtension
+
+public interface CommandCallResolverProvider : InstanceExtension<CommandCallResolver> {
+    public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallResolverProvider>(CommandCallResolverProvider::class)
+}
+

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/data/reflectionUtils.kt

@@ -54,6 +54,12 @@ internal fun KType.classifierAsKClass() = when (val t = classifier) {
     else -> error("Only KClass supported as classifier, got $t")
 } as KClass<Any>
 
+@Suppress("UNCHECKED_CAST")
+internal fun KType.classifierAsKClassOrNull() = when (val t = classifier) {
+    is KClass<*> -> t
+    else -> null
+} as KClass<Any>?
+
 @JvmSynthetic
 internal fun <T : Any> KClass<T>.createInstanceOrNull(): T? {
     val noArgsConstructor = constructors.singleOrNull { it.parameters.all(KParameter::isOptional) }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/StandardUtils.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
+package net.mamoe.mirai.console.util
+
+import kotlin.contracts.contract
+
+public inline fun <reified T : Any> Any?.safeCast(): T? {
+    contract {
+        returnsNotNull() implies (this@safeCast is T)
+    }
+    return this as? T
+}
+
+public inline fun <reified T : Any> Any?.cast(): T {
+    contract {
+        returns() implies (this@cast is T)
+    }
+    return this as T
+}

tools/gradle-plugin/src/main/kotlin/net/mamoe/mirai/console/gradle/VersionConstants.kt

@@ -10,6 +10,6 @@
 package net.mamoe.mirai.console.gradle
 
 internal object VersionConstants {
-    const val CONSOLE_VERSION = "1.0-RC-dev-28" // value is written here automatically during build
+    const val CONSOLE_VERSION = "1.0-RC-dev-29" // value is written here automatically during build
     const val CORE_VERSION = "1.3.0" // value is written here automatically during build
 }