Add delegation extensions, rearrange code, add docs

2025-03-23 22:00:10 +08:00 · 2020-03-01 14:41:19 +08:00 · 2020-03-01 14:41:19 +08:00 · f2843df162
commit f2843df162
parent bbf991103d
1 changed files with 252 additions and 106 deletions
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
@ -9,9 +9,11 @@

@file:JvmMultifileClass
@file:JvmName("MessageUtils")
+@file:Suppress("unused")

 package net.mamoe.mirai.message.data

+import net.mamoe.mirai.message.data.NullMessageChain.equals
 import net.mamoe.mirai.message.data.NullMessageChain.toString
 import kotlin.js.JsName
 import kotlin.jvm.JvmMultifileClass
@ -21,11 +23,20 @@ import kotlin.reflect.KProperty

 /**
 * 消息链.
- * 它的一般实现为 [MessageChainImpl], `null` 实现为 [NullMessageChain]
+ * 它的一般实现为 [MessageChainImplByIterable] 或 [MessageChainImplBySequence],
+ * 替代 `null` 情况的实现为 [NullMessageChain],
+ * 空的实现为 [EmptyMessageChain]
 *
 * 要获取更多信息, 请查看 [Message]
 *
 * @see buildMessageChain 构造一个 [MessageChain]
+ * @see toChain 将单个 [Message] 转换为 [MessageChain]
+ * @see asMessageChain 将 [Iterable] 或 [Sequence] 委托为 [MessageChain]
+ *
+ * @see orNull 属性委托扩展
+ * @see orElse 属性委托扩展
+ * @see getValue 属性委托扩展
+ * @see flatten 扁平化
 */
 interface MessageChain : Message, Iterable<SingleMessage> {
    override operator fun contains(sub: String): Boolean
@ -35,17 +46,27 @@ interface MessageChain : Message, Iterable<SingleMessage> {
     * 获取第一个类型为 [key] 的 [Message] 实例
     *
     * @param key 由各个类型消息的伴生对象持有. 如 [PlainText.Key]
+     * @throws NoSuchElementException 当找不到这个类型的 [Message] 时
     */
    operator fun <M : Message> get(key: Message.Key<M>): M = first(key)
+
+    /**
+     * 获取第一个类型为 [key] 的 [Message] 实例, 找不到则返回 `null`
+     *
+     * @param key 由各个类型消息的伴生对象持有. 如 [PlainText.Key]
+     */
+    fun <M : Message> getOrNull(key: Message.Key<M>): M? = firstOrNull(key)
 }

+// region accessors
+
 /**
 * 遍历每一个有内容的消息, 即 [At], [AtAll], [PlainText], [Image], [Face], [XMLMessage]
 */
 inline fun MessageChain.foreachContent(block: (Message) -> Unit) {
    var last: Message? = null
    this.forEach { message: Message ->
-        if (message is At) {
+        if (message is At) { // 筛除因 QuoteReply 导致的多余的 At
            if (last != null || last !is QuoteReply) {
                block(message)
            }
@ -56,100 +77,10 @@ inline fun MessageChain.foreachContent(block: (Message) -> Unit) {
    }
 }

-/**
- * 提供一个类型的值. 若不存在则会抛出异常 [NoSuchElementException]
- */
-inline operator fun <reified T : Message> MessageChain.getValue(thisRef: Any?, property: KProperty<*>): T = this.first()
-
-/**
- * 构造无初始元素的可修改的 [MessageChain]. 初始大小将会被设定为 8
- */
-@JvmName("newChain")
-@JsName("newChain")
-@Suppress("FunctionName")
-fun MessageChain(): MessageChain = EmptyMessageChain
-
-/**
- * 构造 [MessageChain]
- * 若仅提供一个参数, 请考虑使用 [Message.toChain] 以优化性能
- */
-@JvmName("newChain")
-@JsName("newChain")
-@Suppress("FunctionName")
-fun MessageChain(vararg messages: Message): MessageChain =
-    if (messages.isEmpty()) EmptyMessageChain
-    else MessageChainImpl(messages.asSequence().flatten())
-
-/**
- * 构造 [MessageChain] 的快速途径 (无 [Array] 创建)
- * 若仅提供一个参数, 请考虑使用 [Message.toChain] 以优化性能
- */
-@JvmName("newChain")
-@JsName("newChain")
-@Suppress("FunctionName")
-fun MessageChain(message: Message): MessageChain =
-    when (message) {
-        is SingleMessage -> SingleMessageChainImpl(message)
-        else -> MessageChainImpl(message.flatten().asIterable())
-    }
-
-/**
- * 构造 [MessageChain]
- */
-@JvmName("newChain")
-@JsName("newChain")
-@Suppress("FunctionName")
-fun MessageChain(messages: Iterable<Message>): MessageChain =
-    MessageChainImpl(messages.flatten().asIterable())
-
-/**
- * 构造 [MessageChain]
- */
-@JvmName("newChain")
-@JsName("newChain")
-@Suppress("FunctionName")
-fun MessageChain(messages: List<Message>): MessageChain =
-    MessageChainImpl(messages.flatten().asIterable())
-
-
-/**
- * 得到包含 [this] 的 [MessageChain].
- * 若 [this] 为 [MessageChain] 将直接返回 this
- * 否则将调用 [MessageChain] 构造一个 [MessageChainImpl]
- */
-@Suppress("NOTHING_TO_INLINE", "UNCHECKED_CAST")
-@JvmSynthetic
-fun Message.toChain(): MessageChain = when (this) {
-    is MessageChain -> this
-    is CombinedMessage -> MessageChainImpl((this as Iterable<Message>).flatten().asIterable())
-    else -> SingleMessageChainImpl(this as SingleMessage)
-}
-
-@JvmName("asMessageChain1")
-@JvmSynthetic
-@Suppress("unused", "NOTHING_TO_INLINE")
-fun Iterable<SingleMessage>.asMessageChain(): MessageChain = MessageChainImpl(this)
-
-@JvmSynthetic
-@Suppress("unused", "NOTHING_TO_INLINE")
-fun Iterable<Message>.asMessageChain(): MessageChain = MessageChainImpl(this.flatten())
-
-fun Iterable<Message>.flatten(): Sequence<SingleMessage> = asSequence().flatten()
-
-fun Sequence<Message>.flatten(): Sequence<SingleMessage> = flatMap { it.flatten() }
-
-fun Message.flatten(): Sequence<SingleMessage> {
-    return when (this) {
-        is MessageChain -> this.asSequence()
-        is CombinedMessage -> this.asSequence().flatten()
-        else -> sequenceOf(this as SingleMessage)
-    }
-}
-
 /**
 * 获取第一个 [M] 类型的 [Message] 实例
 */
-inline fun <reified M : Message> MessageChain.firstOrNull(): M? = this.firstOrNull { it is M } as M?
+inline fun <reified M : Message?> MessageChain.firstOrNull(): M? = this.firstOrNull { it is M } as M?

 /**
 * 获取第一个 [M] 类型的 [Message] 实例
@ -183,7 +114,8 @@ fun <M : Message> MessageChain.firstOrNull(key: Message.Key<M>): M? = when (key)
 * @throws [NoSuchElementException] 如果找不到该类型的实例
 */
@Suppress("UNCHECKED_CAST")
-fun <M : Message> MessageChain.first(key: Message.Key<M>): M = firstOrNull(key) ?: throw NoSuchElementException("no such element: $key")
+fun <M : Message> MessageChain.first(key: Message.Key<M>): M =
+    firstOrNull(key) ?: throw NoSuchElementException("no such element: $key")

 /**
 * 获取第一个 [M] 类型的 [Message] 实例
@ -191,36 +123,250 @@ fun <M : Message> MessageChain.first(key: Message.Key<M>): M = firstOrNull(key)
@Suppress("UNCHECKED_CAST")
 fun <M : Message> MessageChain.any(key: Message.Key<M>): Boolean = firstOrNull(key) != null

-object EmptyMessageChain : MessageChain by MessageChainImpl(emptyList())
+// endregion accessors
+
+
+// region delegate
+
+/**
+ * 提供一个类型的值的委托. 若不存在则会抛出异常 [NoSuchElementException]
+ *
+ * 用法:
+ * ```
+ * val message: MessageChain
+ *
+ * val at: At by message
+ * val image: Image by message
+ */
+inline operator fun <reified T : Message> MessageChain.getValue(thisRef: Any?, property: KProperty<*>): T = this.first()
+
+/**
+ * 可空的委托
+ * @see orNull
+ */
+inline class OrNullDelegate<out R : Message?>(private val value: Any?) {
+    @Suppress("UNCHECKED_CAST")
+    operator fun getValue(thisRef: Any?, property: KProperty<*>): R = value as R
+}
+
+/**
+ * 提供一个类型的 [Message] 的委托, 若不存在这个类型的 [Message] 则委托会提供 `null`
+ *
+ * 用法:
+ * ```
+ * val message: MessageChain
+ *
+ * val at: At? by message.orNull()
+ * ```
+ * @see orNull 提供一个不存在则 null 的委托
+ * @see orElse 提供一个不存在则使用默认值的委托
+ */
+inline fun <reified T : Message> MessageChain.orNull(): OrNullDelegate<T?> = OrNullDelegate(this.firstOrNull<T>())
+
+/**
+ * 提供一个类型的 [Message] 的委托, 若不存在这个类型的 [Message] 则委托会提供 `null`
+ *
+ * 用法:
+ * ```
+ * val message: MessageChain
+ *
+ * val at: At by message.orElse { /* 返回一个 At */  }
+ * val atNullable: At? by message.orElse { /* 返回一个 At? */  }
+ * ```
+ * @see orNull 提供一个不存在则 null 的委托
+ */
+inline fun <reified T : Message?> MessageChain.orElse(
+    lazyDefault: () -> T
+): OrNullDelegate<T> =
+    OrNullDelegate<T>(this.firstOrNull<T>() ?: lazyDefault())
+
+// endregion delegate
+
+
+// region converters
+
+/**
+ * 返回 [EmptyMessageChain]
+ */
+@JvmName("newChain")
+@JsName("newChain")
+@Suppress("FunctionName")
+fun MessageChain(): MessageChain = EmptyMessageChain
+
+/**
+ * 构造 [MessageChain]
+ * 若仅提供一个参数, 请考虑使用 [Message.toChain] 以优化性能
+ */
+@JvmName("newChain")
+@JsName("newChain")
+@Suppress("FunctionName")
+fun MessageChain(vararg messages: Message): MessageChain =
+    if (messages.isEmpty()) EmptyMessageChain
+    else MessageChainImplBySequence(messages.asSequence().flatten())
+
+/**
+ * 构造 [MessageChain] 的快速途径 (无 [Array] 创建)
+ * 若仅提供一个参数, 请考虑使用 [Message.toChain] 以优化性能
+ */
+@JvmName("newChain")
+@JsName("newChain")
+@Suppress("FunctionName")
+fun MessageChain(message: Message): MessageChain =
+    when (message) {
+        is SingleMessage -> SingleMessageChainImpl(message)
+        else -> MessageChainImplBySequence(message.flatten())
+    }
+
+/**
+ * 构造 [MessageChain]
+ */
+@JvmName("newChain")
+@JsName("newChain")
+@Suppress("FunctionName")
+fun MessageChain(messages: Iterable<Message>): MessageChain =
+    MessageChainImplBySequence(messages.flatten())
+
+/**
+ * [扁平化][flatten] [messages] 然后构造 [MessageChain]
+ */
+@JvmName("newChain")
+@JsName("newChain")
+@Suppress("FunctionName")
+fun MessageChain(messages: List<Message>): MessageChain =
+    MessageChainImplByIterable(messages.flatten().asIterable())
+
+
+/**
+ * 得到包含 [this] 的 [MessageChain].
+ *
+ * 若 [this] 为 [MessageChain] 将直接返回 this,
+ * 若 [this] 为 [CombinedMessage] 将 [扁平化][flatten] 后委托为 [MessageChain],
+ * 否则将调用 [MessageChain] 构造一个 [MessageChainImplByIterable]
+ */
+@Suppress("NOTHING_TO_INLINE", "UNCHECKED_CAST")
+@JvmSynthetic
+fun Message.toChain(): MessageChain = when (this) {
+    is MessageChain -> this
+    is CombinedMessage -> MessageChainImplByIterable((this as Iterable<Message>).flatten().asIterable())
+    else -> SingleMessageChainImpl(this as SingleMessage)
+}
+
+/**
+ * 直接将 [this] 委托为一个 [MessageChain]
+ */
+@JvmName("asMessageChain1")
+@JvmSynthetic
+@Suppress("unused", "NOTHING_TO_INLINE")
+fun Iterable<SingleMessage>.asMessageChain(): MessageChain = MessageChainImplByIterable(this)
+
+/**
+ * 将 [this] [扁平化后][flatten] 委托为一个 [MessageChain]
+ */
+@JvmSynthetic
+@Suppress("unused", "NOTHING_TO_INLINE")
+fun Iterable<Message>.asMessageChain(): MessageChain = MessageChainImplBySequence(this.flatten())
+
+/**
+ * 扁平化消息序列.
+ *
+ * 原 [this]:
+ * ```
+ * A <- CombinedMessage(B, C) <- D <- MessageChain(E, F, G)
+ * ```
+ * 结果 [Sequence]:
+ * ```
+ * A <- B <- C <- D <- E <- F <- G
+ * ```
+ */
+fun Iterable<Message>.flatten(): Sequence<SingleMessage> = asSequence().flatten()
+
+/**
+ * 扁平化消息序列.
+ *
+ * 原 [this]:
+ * ```
+ * A <- CombinedMessage(B, C) <- D <- MessageChain(E, F, G)
+ * ```
+ * 结果 [Sequence]:
+ * ```
+ * A <- B <- C <- D <- E <- F <- G
+ * ```
+ */
+fun Sequence<Message>.flatten(): Sequence<SingleMessage> = flatMap { it.flatten() }
+
+/**
+ * 扁平化 [Message]
+ *
+ * 对于不同类型的接收者（receiver）:
+ * - `CombinedMessage(A, B)` 返回 `A <- B`
+ * - `MessageChain(E, F, G)` 返回 `E <- F <- G`
+ * - 其他: 返回 `sequenceOf(this)`
+ */
+fun Message.flatten(): Sequence<SingleMessage> {
+    return when (this) {
+        is MessageChain -> this.asSequence()
+        is CombinedMessage -> this.asSequence().flatten()
+        else -> sequenceOf(this as SingleMessage)
+    }
+}
+
+// endregion converters
+
+// region implementations
+
+/**
+ * 不含任何元素的 [MessageChain]
+ */
+object EmptyMessageChain : MessageChain by MessageChainImplByIterable(emptyList())

 /**
 * Null 的 [MessageChain].
 * 它不包含任何元素, 也没有创建任何 list.
 *
- * 除 [toString] 外, 其他方法均 [error]
+ * 除 [toString] 和 [equals] 外, 其他方法均 [error]
 */
 object NullMessageChain : MessageChain {
-    override fun toString(): String = "null"
+    override fun toString(): String = "NullMessageChain"
+    override fun equals(other: Any?): Boolean = other == null
    override fun contains(sub: String): Boolean = error("accessing NullMessageChain")
    override fun followedBy(tail: Message): CombinedMessage = CombinedMessage(left = EmptyMessageChain, element = tail)
    override fun iterator(): MutableIterator<SingleMessage> = error("accessing NullMessageChain")
 }

+/**
+ * 使用 [Iterable] 作为委托的 [MessageChain]
+ */
@PublishedApi
-internal class MessageChainImpl constructor(
+internal inline class MessageChainImplByIterable constructor(
    private val delegate: Iterable<SingleMessage>
-) : Message, Iterable<SingleMessage> by delegate, MessageChain {
-    constructor(delegate: Sequence<SingleMessage>) : this(delegate.asIterable())
-
+) : Message, Iterable<SingleMessage>, MessageChain {
+    override fun iterator(): Iterator<SingleMessage> = delegate.iterator()
    override fun toString(): String = this.delegate.joinToString("") { it.toString() }
    override operator fun contains(sub: String): Boolean = delegate.any { it.contains(sub) }
 }

+/**
+ * 使用 [Iterable] 作为委托的 [MessageChain]
+ */
@PublishedApi
-internal class SingleMessageChainImpl constructor(
-    private val delegate: SingleMessage
-) : Message, Iterable<SingleMessage> by listOf(delegate), MessageChain {
-    override fun toString(): String = this.delegate.toString()
+internal inline class MessageChainImplBySequence constructor(
+    private val delegate: Sequence<SingleMessage>
+) : Message, Iterable<SingleMessage>, MessageChain {
+    override fun iterator(): Iterator<SingleMessage> = delegate.iterator()
+    override fun toString(): String = this.delegate.joinToString("") { it.toString() }
+    override operator fun contains(sub: String): Boolean = delegate.any { it.contains(sub) }
+}

+/**
+ * 单个 [SingleMessage] 作为 [MessageChain]
+ */
+@PublishedApi
+internal inline class SingleMessageChainImpl constructor(
+    private val delegate: SingleMessage
+) : Message, Iterable<SingleMessage>, MessageChain {
+    override fun toString(): String = this.delegate.toString()
+    override fun iterator(): Iterator<SingleMessage> = iterator { yield(delegate) }
    override operator fun contains(sub: String): Boolean = sub in delegate
-}
+}
+
+// endregion