From 0475cbb841e391fe244260072703916c1d8b23ab Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Sat, 9 May 2020 21:04:54 +0800
Subject: [PATCH] Rename listener to handler
---
.../net.mamoe.mirai/event/subscriber.kt | 68 +++++++++----------
1 file changed, 34 insertions(+), 34 deletions(-)
diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt
index 01bbfdf9b..118f4f173 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt
@@ -133,7 +133,7 @@ interface Listener<in E : Event> : CompletableJob {
/**
* 在指定的 [协程作用域][CoroutineScope] 下创建一个事件监听器, 监听所有 [E] 及其子类事件.
*
- * 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
+ * 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
*
*
* ### 创建监听
@@ -165,7 +165,7 @@ interface Listener<in E : Event> : CompletableJob {
* ```
*
* #### 在监听器内部停止后续监听
- * 当 [listener] 返回 [ListeningStatus.STOPPED] 时停止监听.
+ * 当 [handler] 返回 [ListeningStatus.STOPPED] 时停止监听.
* 或 [Listener.complete] 后结束.
*
* ### 子类监听
@@ -174,23 +174,23 @@ interface Listener<in E : Event> : CompletableJob {
* ### 异常处理
* 事件处理时的 [CoroutineContext] 为调用本函数时的 [receiver][this] 的 [CoroutineScope.coroutineContext].
* 因此:
- * - 当参数 [listener] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
+ * - 当参数 [handler] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
* 1. 参数 [coroutineContext]
* 2. 接收者 [this] 的 [CoroutineScope.coroutineContext]
* 3. [Event.broadcast] 调用者的 [coroutineContext]
* 4. 若事件为 [BotEvent], 则从 [BotEvent.bot] 获取到 [Bot], 进而在 [Bot.coroutineContext] 中寻找
* 5. 若以上四个步骤均无法获取 [CoroutineExceptionHandler], 则使用 [MiraiLogger.Companion] 通过日志记录. 但这种情况理论上不应发生.
* - 事件处理时抛出异常不会停止监听器.
- * - 建议在事件处理中 (即 [listener] 里) 处理异常,
+ * - 建议在事件处理中 (即 [handler] 里) 处理异常,
* 或在参数 [coroutineContext] 中添加 [CoroutineExceptionHandler].
*
*
* @param coroutineContext 给事件监听协程的额外的 [CoroutineContext].
* @param concurrency 并发类型. 查看 [Listener.ConcurrencyKind]
* @param priority 监听优先级，优先级越高越先执行
- * @param listener 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
+ * @param handler 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
*
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
*
* @see syncFromEvent 挂起当前协程, 监听一个事件, 并尝试从这个事件中**同步**一个值
* @see asyncFromEvent 异步监听一个事件, 并尝试从这个事件中获取一个值.
@@ -212,27 +212,27 @@ inline fun <reified E : Event> CoroutineScope.subscribe(
coroutineContext: CoroutineContext = EmptyCoroutineContext,
concurrency: Listener.ConcurrencyKind = LOCKED,
priority: Listener.EventPriority = NORMAL,
- noinline listener: suspend E.(E) -> ListeningStatus
-): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, listener)
+ noinline handler: suspend E.(E) -> ListeningStatus
+): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, handler)
/**
* 与 [subscribe] 的区别是接受 [eventClass] 参数, 而不使用 `reified` 泛型
*
* @see CoroutineScope.subscribe
*
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
*/
fun <E : Event> CoroutineScope.subscribe(
eventClass: KClass<E>,
coroutineContext: CoroutineContext = EmptyCoroutineContext,
concurrency: Listener.ConcurrencyKind = LOCKED,
priority: Listener.EventPriority = NORMAL,
- listener: suspend E.(E) -> ListeningStatus
-): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.listener(it); })
+ handler: suspend E.(E) -> ListeningStatus
+): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.handler(it); })
/**
* 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
- * 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
+ * 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
*
* 可在任意时候通过 [Listener.complete] 来主动停止监听.
* [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
@@ -241,7 +241,7 @@ fun <E : Event> CoroutineScope.subscribe(
* @param coroutineContext 给事件监听协程的额外的 [CoroutineContext]
* @param priority 处理优先级, 优先级高的先执行
*
- * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
+ * @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
*
* @see CoroutineScope.subscribe 获取更多说明
*/
@@ -249,8 +249,8 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlways(
coroutineContext: CoroutineContext = EmptyCoroutineContext,
concurrency: Listener.ConcurrencyKind = CONCURRENT,
priority: Listener.EventPriority = NORMAL,
- noinline listener: suspend E.(E) -> Unit
-): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, listener)
+ noinline handler: suspend E.(E) -> Unit
+): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, handler)
/**
@@ -262,14 +262,14 @@ fun <E : Event> CoroutineScope.subscribeAlways(
coroutineContext: CoroutineContext = EmptyCoroutineContext,
concurrency: Listener.ConcurrencyKind = CONCURRENT,
priority: Listener.EventPriority = NORMAL,
- listener: suspend E.(E) -> Unit
+ handler: suspend E.(E) -> Unit
): Listener<E> = eventClass.subscribeInternal(
- Handler(coroutineContext, concurrency, priority) { it.listener(it); ListeningStatus.LISTENING }
+ Handler(coroutineContext, concurrency, priority) { it.handler(it); ListeningStatus.LISTENING }
)
/**
* 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
- * 仅在第一次 [事件广播][Event.broadcast] 时, [listener] 会被执行.
+ * 仅在第一次 [事件广播][Event.broadcast] 时, [handler] 会被执行.
*
* 可在任意时候通过 [Listener.complete] 来主动停止监听.
* [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
@@ -283,8 +283,8 @@ fun <E : Event> CoroutineScope.subscribeAlways(
inline fun <reified E : Event> CoroutineScope.subscribeOnce(
coroutineContext: CoroutineContext = EmptyCoroutineContext,
priority: Listener.EventPriority = NORMAL,
- noinline listener: suspend E.(E) -> Unit
-): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, listener)
+ noinline handler: suspend E.(E) -> Unit
+): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, handler)
/**
* @see CoroutineScope.subscribeOnce
@@ -293,9 +293,9 @@ fun <E : Event> CoroutineScope.subscribeOnce(
eventClass: KClass<E>,
coroutineContext: CoroutineContext = EmptyCoroutineContext,
priority: Listener.EventPriority = NORMAL,
- listener: suspend E.(E) -> Unit
+ handler: suspend E.(E) -> Unit
): Listener<E> = eventClass.subscribeInternal(
- Handler(coroutineContext, LOCKED, priority) { it.listener(it); ListeningStatus.STOPPED }
+ Handler(coroutineContext, LOCKED, priority) { it.handler(it); ListeningStatus.STOPPED }
)
//
@@ -462,7 +462,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = handler
+ handler = handler
)
@PlannedRemoval("1.2.0")
@@ -480,7 +480,7 @@ fun <E : Event> CoroutineScope.subscribeDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = handler
+ handler = handler
)
@PlannedRemoval("1.2.0")
@@ -496,7 +496,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlwaysDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -514,7 +514,7 @@ fun <E : Event> CoroutineScope.subscribeAlwaysDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -528,7 +528,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeOnceDeprecated(
): Listener<E> = subscribeOnce(
coroutineContext = coroutineContext,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -544,7 +544,7 @@ fun <E : Event> CoroutineScope.subscribeOnceDeprecated(
eventClass = eventClass,
coroutineContext = coroutineContext,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -561,7 +561,7 @@ inline fun <reified E : BotEvent> Bot.subscribeDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = handler
+ handler = handler
)
@PlannedRemoval("1.2.0")
@@ -579,7 +579,7 @@ fun <E : BotEvent> Bot.subscribeDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = handler
+ handler = handler
)
@PlannedRemoval("1.2.0")
@@ -596,7 +596,7 @@ inline fun <reified E : BotEvent> Bot.subscribeAlwaysDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -614,7 +614,7 @@ fun <E : BotEvent> Bot.subscribeAlwaysDeprecated(
coroutineContext = coroutineContext,
concurrency = concurrency,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -628,7 +628,7 @@ inline fun <reified E : BotEvent> Bot.subscribeOnceDeprecated(
): Listener<E> = subscribeOnce(
coroutineContext = coroutineContext,
priority = MONITOR,
- listener = listener
+ handler = listener
)
@PlannedRemoval("1.2.0")
@@ -644,6 +644,6 @@ fun <E : BotEvent> Bot.subscribeOnceDeprecated(
eventClass = eventClass,
coroutineContext = coroutineContext,
priority = MONITOR,
- listener = listener
+ handler = listener
)
// endregion
\ No newline at end of file