From 2049a9d5af4a01ff2d6df819ba20b60eac8f2b92 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Fri, 8 Jan 2021 10:10:45 +0800
Subject: [PATCH] Update docs
---
.../kotlin/event/subscribeMessages.kt | 69 +++++++++++++++++--
1 file changed, 63 insertions(+), 6 deletions(-)
diff --git a/mirai-core-api/src/commonMain/kotlin/event/subscribeMessages.kt b/mirai-core-api/src/commonMain/kotlin/event/subscribeMessages.kt
index 1671269ca..d4949e2bb 100644
--- a/mirai-core-api/src/commonMain/kotlin/event/subscribeMessages.kt
+++ b/mirai-core-api/src/commonMain/kotlin/event/subscribeMessages.kt
@@ -14,6 +14,8 @@
package net.mamoe.mirai.event
import net.mamoe.mirai.Bot
+import net.mamoe.mirai.contact.OtherClient
+import net.mamoe.mirai.contact.Stranger
import net.mamoe.mirai.event.Listener.ConcurrencyKind.CONCURRENT
import net.mamoe.mirai.event.events.*
import net.mamoe.mirai.message.data.content
@@ -25,9 +27,44 @@ import kotlin.coroutines.EmptyCoroutineContext
public typealias MessageEventSubscribersBuilder = MessageSubscribersBuilder<MessageEvent, Listener<MessageEvent>, Unit, Unit>
/**
- * 订阅来自所有 [Bot] 的所有联系人的消息事件. 联系人可以是任意群或任意好友或临时会话.
+ * 通过 DSL 订阅来自所有 [Bot] 的所有联系人的消息事件.
*
- * @see subscribe 事件监听基础
+ * ```
+ * eventChannel.subscribeMessages {
+ * "test" {
+ * // 当消息内容为 "test" 时执行
+ * // this: MessageEvent
+ * reply("test!")
+ * }
+ *
+ * "Hello" reply "Hi" // 当消息内容为 "Hello" 时回复 "Hi"
+ * "quote me" quoteReply "ok" // 当消息内容为 "quote me" 时引用该消息并回复 "ok"
+ * "quote me2" quoteReply {
+ * // lambda 也是允许的：
+ * // 返回值接受 Any?
+ * // 为 Unit 时不发送任何内容；
+ * // 为 Message 时直接发送；
+ * // 为 String 时发送为 PlainText；
+ * // 否则 toString 并发送为 PlainText
+ *
+ * "ok"
+ * }
+ *
+ * case("iGNorECase", ignoreCase=true) reply "OK" // 忽略大小写
+ * startsWith("-") reply { cmd ->
+ * // 当消息内容以 "-" 开头时执行
+ * // cmd 为消息去除开头 "-" 的内容
+ * }
+ *
+ *
+ * val listener: Listener<MessageEvent> = "1" reply "2"
+ * // 每个语句都会被注册为事件监听器，可以这样获取监听器
+ *
+ * listener.complete() // 停止 "1" reply "2" 这个事件监听
+ * }
+ * ```
+ *
+ * @see EventChannel.subscribe 事件监听基础
* @see EventChannel 事件通道
*/
public fun <R> EventChannel<*>.subscribeMessages(
@@ -43,7 +80,7 @@ public fun <R> EventChannel<*>.subscribeMessages(
public typealias GroupMessageSubscribersBuilder = MessageSubscribersBuilder<GroupMessageEvent, Listener<GroupMessageEvent>, Unit, Unit>
/**
- * 订阅来自所有 [Bot] 的所有群消息事件
+ * 通过 DSL 订阅来自所有 [Bot] 的所有群会话消息事件. DSL 语法查看 [subscribeMessages].
*
* @see subscribe 事件监听基础
* @see EventChannel 事件通道
@@ -61,7 +98,7 @@ public fun <R> EventChannel<*>.subscribeGroupMessages(
public typealias FriendMessageSubscribersBuilder = MessageSubscribersBuilder<FriendMessageEvent, Listener<FriendMessageEvent>, Unit, Unit>
/**
- * 订阅来自所有 [Bot] 的所有好友消息事件
+ * 通过 DSL 订阅来自所有 [Bot] 的所有好友消息事件. DSL 语法查看 [subscribeMessages].
*
* @see subscribe 事件监听基础
* @see EventChannel 事件通道
@@ -79,7 +116,7 @@ public fun <R> EventChannel<*>.subscribeFriendMessages(
public typealias TempMessageSubscribersBuilder = MessageSubscribersBuilder<TempMessageEvent, Listener<TempMessageEvent>, Unit, Unit>
/**
- * 订阅来自所有 [Bot] 的所有临时会话消息事件
+ * 通过 DSL 订阅来自所有 [Bot] 的所有临时会话消息事件. DSL 语法查看 [subscribeMessages].
*
* @see subscribe 事件监听基础
* @see EventChannel 事件通道
@@ -98,7 +135,7 @@ public fun <R> EventChannel<*>.subscribeTempMessages(
public typealias StrangerMessageSubscribersBuilder = MessageSubscribersBuilder<StrangerMessageEvent, Listener<StrangerMessageEvent>, Unit, Unit>
/**
- * 订阅来自所有 [Bot] 的所有陌生人消息事件
+ * 通过 DSL 订阅来自所有 [Bot] 的所有 [Stranger] 消息事件. DSL 语法查看 [subscribeMessages].
*
* @see subscribe 事件监听基础
* @see EventChannel 事件通道
@@ -114,6 +151,26 @@ public fun <R> EventChannel<*>.subscribeStrangerMessages(
.run(listeners)
}
+
+public typealias OtherClientMessageSubscribersBuilder = MessageSubscribersBuilder<OtherClientMessageEvent, Listener<OtherClientMessageEvent>, Unit, Unit>
+
+/**
+ * 通过 DSL 订阅来自所有 [Bot] 的所有 [OtherClient] 消息事件. DSL 语法查看 [subscribeMessages].
+ *
+ * @see subscribe 事件监听基础
+ * @see EventChannel 事件通道
+ */
+public fun <R> EventChannel<*>.subscribeOtherClientMessages(
+ coroutineContext: CoroutineContext = EmptyCoroutineContext,
+ concurrencyKind: Listener.ConcurrencyKind = CONCURRENT,
+ priority: Listener.EventPriority = EventPriority.MONITOR,
+ listeners: OtherClientMessageSubscribersBuilder.() -> R
+): R {
+ contract { callsInPlace(listeners, InvocationKind.EXACTLY_ONCE) }
+ return createBuilder(::OtherClientMessageSubscribersBuilder, coroutineContext, concurrencyKind, priority)
+ .run(listeners)
+}
+
private typealias MessageSubscriberBuilderConstructor<E> = (
Unit,
(E.(String) -> Boolean, MessageListener<E, Unit>) -> Listener<E>