Add docs, cleanup

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

@@ -105,7 +105,16 @@ class CommandDescriptor(
 }
 
 
+/**
+ * 检查指令参数数量是否足够, 类型是否匹配.
+ * @throws IllegalArgumentException
+ */
 fun Command.checkArgs(args: CommandArgs) = this.descriptor.checkArgs(args)
+
+/**
+ * 检查指令参数数量是否足够, 类型是否匹配.
+ * @throws IllegalArgumentException
+ */
 fun CommandDescriptor.checkArgs(args: CommandArgs) {
     require(args.size >= this.params.size) { "No enough args. Required ${params.size}, but given ${args.size}" }
     params.forEachIndexed { index, commandParam ->
@@ -115,22 +124,6 @@ fun CommandDescriptor.checkArgs(args: CommandArgs) {
     }
 }
 
-internal fun Any.flattenCommandComponents(): Sequence<Any> = when (this) {
-    is Array<*> -> this.asSequence().flatMap {
-        it?.flattenCommandComponents() ?: throw java.lang.IllegalArgumentException("unexpected null value")
-    }
-    is String -> splitToSequence(' ').filterNot { it.isBlank() }
-    is PlainText -> content.flattenCommandComponents()
-    is SingleMessage -> sequenceOf(this)
-    is MessageChain -> this.asSequence().flatMap { it.flattenCommandComponents() }
-    else -> throw IllegalArgumentException("Illegal component: $this")
-}
-
-internal fun CommandFullName.checkFullName(errorHint: String): CommandFullName {
-    return flattenCommandComponents().toList().also {
-        require(it.isNotEmpty()) { "$errorHint must not be empty" }
-    }.toTypedArray()
-}
 
 /**
  * 构建一个 [CommandDescriptor]
@@ -245,12 +238,12 @@ class CommandDescriptorBuilder(
     }
 
     @JvmSynthetic
-    fun param(type: KClass<*>): CommandDescriptorBuilder = apply {
-        this.params.add(CommandParam(null, type))
+    fun param(vararg types: KClass<*>): CommandDescriptorBuilder = apply {
+        types.forEach { type -> params.add(CommandParam(null, type)) }
     }
 
-    fun param(type: Class<*>): CommandDescriptorBuilder = apply {
-        this.params.add(CommandParam(null, type.kotlin))
+    fun param(vararg types: Class<*>): CommandDescriptorBuilder = apply {
+        types.forEach { type -> params.add(CommandParam(null, type.kotlin)) }
     }
 
     fun build(): CommandDescriptor =
@@ -270,4 +263,26 @@ inline class ParamBlock internal constructor(@PublishedApi internal val list: Mu
     /** 覆盖 [CommandArgParser] */
     inline infix fun <reified T : Any> String.using(parser: CommandArgParser<T>): CommandParam<T> =
         this typed T::class using parser
+}
+
+
+///////
+/// internal
+
+
+internal fun Any.flattenCommandComponents(): Sequence<Any> = when (this) {
+    is Array<*> -> this.asSequence().flatMap {
+        it?.flattenCommandComponents() ?: throw java.lang.IllegalArgumentException("unexpected null value")
+    }
+    is String -> splitToSequence(' ').filterNot { it.isBlank() }
+    is PlainText -> content.flattenCommandComponents()
+    is SingleMessage -> sequenceOf(this)
+    is MessageChain -> this.asSequence().flatMap { it.flattenCommandComponents() }
+    else -> throw IllegalArgumentException("Illegal component: $this")
+}
+
+internal fun CommandFullName.checkFullName(errorHint: String): CommandFullName {
+    return flattenCommandComponents().toList().also {
+        require(it.isNotEmpty()) { "$errorHint must not be empty" }
+    }.toTypedArray()
 }

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

@@ -1,4 +1,4 @@
-@file:Suppress("NOTHING_TO_INLINE")
+@file:Suppress("NOTHING_TO_INLINE", "unused")
 @file:JvmName("CommandManager")
 
 package net.mamoe.mirai.console.command
@@ -77,18 +77,33 @@ suspend fun MessageChain.executeAsCommand(sender: CommandSender): Boolean {
     return this.flattenCommandComponents().toList().executeCommand(sender)
 }
 
-suspend fun CommandSender.execute(command: Command, args: CommandArgs): Boolean = with(command) {
+/**
+ * 检查指令参数并直接执行一个指令.
+ */
+suspend inline fun CommandSender.execute(command: Command, args: CommandArgs): Boolean = with(command) {
     checkArgs(args)
-    return onCommand(this@execute, args)
+    return this@execute.onCommand(args)
 }
 
-suspend fun Command.execute(sender: CommandSender, args: CommandArgs): Boolean = sender.execute(this, args)
+/**
+ * 检查指令参数并直接执行一个指令.
+ */
+suspend inline fun Command.execute(sender: CommandSender, args: CommandArgs): Boolean = sender.execute(this, args)
+
+/**
+ * 解析并执行一个指令.
+ * @param args 接受 [String] 或 [Message]
+ */
 suspend fun CommandSender.execute(vararg args: Any): Boolean = args.toList().executeCommand(this)
 
 
 internal suspend fun List<Any>.executeCommand(sender: CommandSender): Boolean {
     val command = InternalCommandManager.matchCommand(this) ?: return false
-    return command.onCommand(sender, CommandArgs.parseFrom(command, sender, this.drop(command.fullName.size)))
+    return command.run {
+        sender.onCommand(
+            CommandArgs.parseFrom(command, sender, this@executeCommand.drop(command.fullName.size))
+        )
+    }
 }
 
 internal infix fun CommandFullName.matchesBeginning(list: List<Any>): Boolean {

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

@@ -12,6 +12,10 @@
 package net.mamoe.mirai.console.command
 
 import net.mamoe.mirai.Bot
+import net.mamoe.mirai.console.utils.isManager
+import net.mamoe.mirai.contact.isAdministrator
+import net.mamoe.mirai.contact.isOperator
+import net.mamoe.mirai.contact.isOwner
 
 /**
  * 指令权限
@@ -44,7 +48,7 @@ abstract class CommandPermission {
     }
 
     /**
-     * 任何人都不能使用这个指令. 指令只能通过代码在 [CommandManager] 使用
+     * 任何人都不能使用这个指令. 指令只能通过代码在 [execute] 使用
      */
     object None : CommandPermission() {
         override fun CommandSender.hasPermission(): Boolean = false
@@ -62,7 +66,7 @@ abstract class CommandPermission {
         constructor(vararg fromBot: Bot) : this(*fromBot.map { it.id }.toLongArray())
 
         override fun CommandSender.hasPermission(): Boolean {
-            return this is MemberCommandSender && this.bot.id in fromBot && this.realSender.isOperator()
+            return this is MemberCommandSender && this.bot.id in fromBot && this.user.isOperator()
         }
 
         /**
@@ -70,7 +74,7 @@ abstract class CommandPermission {
          */
         companion object Any : CommandPermission() {
             override fun CommandSender.hasPermission(): Boolean {
-                return this is MemberCommandSender && this.realSender.isOperator()
+                return this is MemberCommandSender && this.user.isOperator()
             }
         }
     }
@@ -87,7 +91,7 @@ abstract class CommandPermission {
         constructor(vararg fromBot: Bot) : this(*fromBot.map { it.id }.toLongArray())
 
         override fun CommandSender.hasPermission(): Boolean {
-            return this is MemberCommandSender && this.bot.id in fromBot && this.realSender.isOwner()
+            return this is MemberCommandSender && this.bot.id in fromBot && this.user.isOwner()
         }
 
         /**
@@ -95,7 +99,7 @@ abstract class CommandPermission {
          */
         companion object Any : CommandPermission() {
             override fun CommandSender.hasPermission(): Boolean {
-                return this is MemberCommandSender && this.realSender.isOwner()
+                return this is MemberCommandSender && this.user.isOwner()
             }
         }
     }
@@ -112,7 +116,7 @@ abstract class CommandPermission {
         constructor(vararg fromBot: Bot) : this(*fromBot.map { it.id }.toLongArray())
 
         override fun CommandSender.hasPermission(): Boolean {
-            return this is MemberCommandSender && this.bot.id in fromBot && this.realSender.isAdministrator()
+            return this is MemberCommandSender && this.bot.id in fromBot && this.user.isAdministrator()
         }
 
         /**
@@ -120,7 +124,7 @@ abstract class CommandPermission {
          */
         companion object Any : CommandPermission() {
             override fun CommandSender.hasPermission(): Boolean {
-                return this is MemberCommandSender && this.realSender.isAdministrator()
+                return this is MemberCommandSender && this.user.isAdministrator()
             }
         }
     }
@@ -137,7 +141,7 @@ abstract class CommandPermission {
         constructor(vararg fromBot: Bot) : this(*fromBot.map { it.id }.toLongArray())
 
         override fun CommandSender.hasPermission(): Boolean {
-            return this is MemberCommandSender && this.bot.id in fromBot && this.realSender.isManager
+            return this is MemberCommandSender && this.bot.id in fromBot && this.user.isManager
         }
 
         /**
@@ -145,7 +149,7 @@ abstract class CommandPermission {
          */
         companion object Any : CommandPermission() {
             override fun CommandSender.hasPermission(): Boolean {
-                return this is MemberCommandSender && this.realSender.isManager
+                return this is MemberCommandSender && this.user.isManager
             }
         }
     }

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

@@ -9,15 +9,6 @@
 
 package net.mamoe.mirai.console.command
 
-suspend fun main() {
-
-    if (ConsoleCommandSender.execute("test")) {
-
-    }
-}
-
-internal object DefaultCommands
-
 /*
 
 /**