refactor: simplify several logics; clarify docs

Author: Aliorpse

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplicationSSE.kt

@@ -41,8 +41,7 @@ public class SaltifyApplicationSSE(config: SaltifyApplicationConfig) : SaltifyAp
                         incoming.collect { sseEvent ->
                             if (sseEvent.event == "milky_event") {
                                 sseEvent.data?.let { data ->
-                                    val event = milkyJsonModule.decodeFromString<Event>(data)
-                                    events.emit(event)
+                                    events.emit(milkyJsonModule.decodeFromString<Event>(data))
                                 }
                             }
                         }

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplicationWebSocket.kt

@@ -41,8 +41,7 @@ public class SaltifyApplicationWebSocket(config: SaltifyApplicationConfig) : Sal
                         )
 
                         while (isActive) {
-                            val event = receiveDeserialized<Event>()
-                            events.emit(event)
+                            events.emit(receiveDeserialized<Event>())
                         }
                     }
                 }

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/SaltifyPluginContext.kt

@@ -85,8 +85,8 @@ public class SaltifyPluginContext internal constructor(
      */
     @ContextParametersMigrationNeeded
     public suspend fun Event.MessageReceive.respond(
-        text: String
-    ): SendMessageOutput = respond { text(text) }
+        text: Any?
+    ): SendMessageOutput = respond { text(text.toString()) }
 
     /**
      * 响应事件，并在指定延迟后撤回消息。

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/ApplicationExtension.kt

@@ -46,7 +46,8 @@ public inline fun SaltifyApplication.regex(
     val regex = Regex(regex)
 
     return on<Event.MessageReceive>(scope) { event ->
-        val text = event.segments.plainText
+        val text = event.segments.filterIsInstance<IncomingSegment.Text>()
+            .joinToString("") { it.text }
 
         val matches = regex.findAll(text)
         if (matches.any()) block(event, matches)
@@ -71,12 +72,10 @@ public fun SaltifyApplication.command(
             .joinToString("") { it.text }
             .trim()
 
-        if (rawText != "$prefix$name" && !rawText.startsWith("$prefix$name ")) return@on
-
-        val content = rawText.removePrefix("$prefix$name").trim()
-        val tokens = if (content.isEmpty()) emptyList() else content.split(spaceRegex)
+        val tokens = if (rawText.isEmpty()) emptyList() else rawText.split(spaceRegex)
+        if (tokens.isEmpty() || tokens[0] != "$prefix$name") return@on
 
-        executeCommand(rootDsl, tokens, this, event, name)
+        executeCommand(rootDsl, tokens.drop(1), this, event, name)
     }
 }
 
@@ -87,21 +86,28 @@ private suspend fun executeCommand(
     event: Event.MessageReceive,
     name: String
 ) {
+    val argumentMap = mutableMapOf<SaltifyCommandParamDef<*>, ParameterParseResult<Any>>()
+    val execution = SaltifyCommandExecutionContext(client, event, name, argumentMap)
+
+    dsl.requirementBlock?.let { block ->
+        val requirement = SaltifyCommandRequirementContext(execution).block()
+        if (!requirement.satisfies()) return
+    }
+
     if (tokens.isNotEmpty()) {
         val subName = tokens[0]
         val subCommand = dsl.subCommands.find { it.first == subName }
         if (subCommand != null) {
-            executeCommand(subCommand.second, tokens.drop(1), client, event, name)
+            executeCommand(subCommand.second, tokens.drop(1), client, event, "$name $subName")
             return
         }
     }
 
-    val argumentMap = mutableMapOf<SaltifyCommandParamDef<*>, ParameterParseResult<Any>>()
     val errors = mutableListOf<CommandError>()
     val currentTokens = tokens.toMutableList()
 
     for (param in dsl.parameters) {
-        argumentMap[param] = when {
+        val result = when {
             currentTokens.isEmpty() -> ParameterParseResult.MissingParam
             param.isGreedy -> {
                 val value = currentTokens.joinToString(" ")
@@ -113,24 +119,18 @@ private suspend fun executeCommand(
                 convertValue(rawValue, param.type)?.let { ParameterParseResult.Success(it) }
                     ?: ParameterParseResult.InvalidParam(rawValue)
             }
-        }.also { res ->
-            when (res) {
-                is ParameterParseResult.MissingParam -> errors.add(CommandError.MissingParam(param))
-                is ParameterParseResult.InvalidParam -> errors.add(CommandError.InvalidParam(param, res.rawValue))
-                else -> {}
-            }
         }
-    }
 
-    if (currentTokens.isNotEmpty()) {
-        errors.add(CommandError.TooManyArguments(currentTokens))
+        argumentMap[param] = result
+        if (result is ParameterParseResult.MissingParam) errors.add(CommandError.MissingParam(param))
+        if (result is ParameterParseResult.InvalidParam) errors.add(CommandError.InvalidParam(param, result.rawValue))
     }
 
-    val execution = SaltifyCommandExecutionContext(client, event, name, argumentMap)
+    if (currentTokens.isNotEmpty()) errors.add(CommandError.TooManyArguments(currentTokens))
 
-    dsl.requirementBlock?.let { block ->
-        val requirement = SaltifyCommandRequirementContext(execution).block()
-        if (!requirement.satisfies()) return
+    if (errors.isNotEmpty()) {
+        dsl.failureBlock?.invoke(execution, errors.first())
+        return
     }
 
     val startInstant = Clock.System.now()

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/CommandContextExtension.kt

@@ -18,5 +18,5 @@ public inline fun <reified T : Any> SaltifyCommandContext.parameter(
  * 响应事件。这是用于返回纯文本的简写。
  */
 public suspend inline fun SaltifyCommandExecutionContext.respond(
-    text: String
-): SendMessageOutput = respond { text(text) }
+    text: Any?
+): SendMessageOutput = respond { text(text.toString()) }

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/EventExtension.kt

@@ -32,5 +32,5 @@ public suspend fun Event.MessageReceive.respond(
  */
 public suspend inline fun Event.MessageReceive.respond(
     client: SaltifyApplication,
-    text: String
-): SendMessageOutput = respond(client) { text(text) }
+    text: Any?
+): SendMessageOutput = respond(client) { text(text.toString()) }

saltify-docs/content/docs-core/application.md

@@ -75,4 +75,4 @@ launch {
 }
 ```
 
-需要注意的是，由连接状态断开引起的异常不会出现在 Application 异常流，而是会在这个流中出现。
+需要注意的是，由连接状态断开引起的异常不会出现在 Application 异常流，而是出现在此流中。

saltify-docs/content/docs-core/command.md

@@ -26,7 +26,7 @@ client.command("order", prefix = "/") {
 
 onFailure 块是**解析**失败的处理，注意这里不是异常，而是指令参数类型不匹配、过多参数、参数缺失等预期内错误。
 
-这里的 error 是一个 `Typed error`，说的简单点，密封类。你可以用 when 判断到底是什么问题，并加以处理。
+这里的 error 是一个 `Typed error`，简单来说就是密封类。你可以用 when 判断具体是什么问题，并加以处理。
 
 默认情况下，如果不定义这个块，会忽视所有解析错误，并对指令不做回复。
 
@@ -71,7 +71,7 @@ command("math") {
 
         onExecute {
             val result = a.value + b.value
-            respond("$result")
+            respond(result)
         }
     }
 
@@ -109,7 +109,7 @@ client.command("shutdown") {
 
 ## Requirements
 
-Requirements 是一个用于指令鉴权的语法，妥当使用可以减少很多 onExecute 块内的判断条件。
+Requirements 是用于指令鉴权的语法，合理使用可以减少很多 onExecute 块内的判断逻辑。
 
 ```kotlin
 client.command("stop") {
@@ -125,7 +125,7 @@ client.command("stop") {
 }
 ```
 
-相信效果是什么不需要解释，自定义这么一个 requirement 函数也很简单：
+效果不言自明，自定义这样的 requirement 函数也很简单：
 
 ```kotlin
 fun SaltifyCommandRequirementContext.user(vararg targetId: Long) =

saltify-docs/content/docs-core/logging.md

@@ -4,7 +4,7 @@ Saltify 使用 KtorSimpleLogger 输出运行时日志。
 
 ## JVM 平台
 
-这里依照快速开始中的日志配置，使用 Logback 框架。
+以快速开始中的日志配置为例，这里使用 Logback 框架。
 
 ### 配置日志
 

saltify-docs/content/docs-core/permission.md

@@ -25,4 +25,4 @@ client.on<Event.MessageReceive> { event ->
 }
 ```
 
-需要注意的是，requirements 判定失败是静默返回的，所以上例1所示适用情况可能较少。
+需要注意的是，requirements 判定失败时会静默返回，因此上述第一种用法的适用场景可能相对有限。