feat: 支持CompositeCommand间组合 #2125

hundun000 · 2022-06-30T12:23:42Z

效果：

对于CompositeCommand，其被@ChildCommad注解的CompositeCommand子类成员中的所有子指令，也会成为他的子指令。（见InstanceTestCommand.kt变动）
实际插件开发中可用于“将多个CompositeCommand注册注册到同一个主指令名” (will close 支持多个主指令名相同的CompositeCommand注册的SubCommand均生效 #1804 )

改动说明：

新增注解@ChildCommad。~~也可以考虑继续使用@SubCommad？以及child的命名可能会引起歧义想到继承关系~~
需要将数个CommandReflector的方法改为返回接口类而不是实现类

Him188

请执行 ./gradlew :mirai-console:apiDumpAll 并提交变更的文件

hundun000 · 2022-07-01T02:54:59Z

看了下英文下描述组合模式也会使用child，那就保持@ChildCommad命名。测试里的Parent改名Container减少歧义。

Karlatemp

如果使用 ChildCommand 的话, 她给我的第一印象是

object TopLevel : CompositeCommand("toplevel") {
   val myCommand = object : CompositeCommand() {
       @SubCommand
       suspend fun CommandSender.handle() {}
   }
}

命令会按照 /toplevel myCommand handle 注册, 我个人感觉这个名字会有很大的误解性.
也许可以考虑 @CombinedCommand 或者 @MixinedCommand? @Him188

Him188 · 2022-07-01T12:22:11Z

@Karlatemp 我也是这样想的, 今天忙, 看了没来得及写 review

我认为造一个其他概念而不要用 CompositeCommand 比较好. 比如创造一个 SubCommandGroup, 考虑定义为接口, 也需要考虑与 CompositeCommand 的兼容性 (CompositeCommand 是否能直接使用 SubCommandGroup 的现有指令定义?)

hundun000 · 2022-07-01T13:52:34Z

另外现在这样，CompositeCommand间可以进一步嵌套“父节点-若干子节点”关系形成树状。不知道要不要设计上就禁止，区分出'SubCommandGroup'应该有利于实现这点。

hundun000 · 2022-07-01T14:54:56Z

不过单看“XX助手”场景，有的功能点可能由SimpleCommand提供，所以需要的是能混合组合SimpleCommand和CompositeCommand 的工具。从这个角度来看，SubCommandGroup应该支持组合Command，也就包括支持SubCommandGroup间嵌套成树状。

Him188 · 2022-07-01T16:07:06Z

我考虑了 hierarchy 的, SubCommandGroup 这个命名能体现层级, 你设计的 val 声明语法也适合做到这一点

SimpleCommand 实际上是只有一个子指令的 CompositeCommand. SubCommandGroup 仍然能做到, 这就涉及我说的考虑兼容性(复用的可能性)问题.

hundun000 · 2022-07-02T06:27:49Z

SimpleCommand 实际上是只有一个子指令的 CompositeCommand

看了下代码， SimpleCommand 和 CompositeCommand只是平级的关系啊。是想说SimpleCommandSubCommandAnnotationResolver是一种findSubCommands + validate的结果只有一个子指令的Resolver吗？

另外我还是不太理解你说的兼容性和复用性指什么，能更具体的说明吗？

Him188 · 2022-07-02T08:13:00Z

@hundun000 是的

兼容性指的是有没有可能让开发者用 SubCommandGroup 写, 然后 CompositeCommand 可以使用这个 group 而不需要重新定义

hundun000 · 2022-07-02T10:16:35Z

@Him188

我认为造一个其他概念而不要用 CompositeCommand 比较好

我的理解是要让 CompositeCommand 不变，使其和SubCommandGroup有如下区别

	成员函数作为子指令	得到成员属性提供的子指令
SimpleCommand	√（仅对`@Handler`）	x
CompositeCommand	√（仅对`@SubCommand`）	x
SubCommandGroup	允许 or 不允许？	√（仅对`@CombinedCommand`）

开发者用 SubCommandGroup 写, 然后 CompositeCommand 可以使用这个 group

是指变成这样吗，那不就又没区别了？

	成员函数作为子指令	得到成员属性提供的子指令
CompositeResolver	√（仅对`@SubCommand`）	√
SubCommandGroup	√	√（仅对`@CombinedCommand`）

Him188 · 2022-07-03T04:51:10Z

SubCommandGroup 是对 SubCommand 的集合, 没有主指令名称, 它不能独立使用. CompositeCommand 拥有主指令名称, 包含一个 SubCommandGroup 时就包含了它的所有 SubCommand. 这样拥有最高的实用性?

hundun000 · 2022-07-03T05:40:09Z

SubCommandGroup 是对 SubCommand 的集合, 没有主指令名称, 它不能独立使用. CompositeCommand 拥有主指令名称, 包含一个 SubCommandGroup 时就包含了它的所有 SubCommand. 这样拥有最高的实用性?

懂了

hundun000 · 2022-07-04T09:05:14Z

AbstractSubCommandGroup是接口SubCommandGroup的一种实现，实现方式是交给SubCommandReflector计算；AbstractSubCommandGroup不是Command，即不能独立使用。
@SubCommand是protected于CompositeCommand的，故AbstractSubCommandGroup需要自己的注解，暂时使用@AnotherSubCommand。是否应该让@SubCommand变为public供两者统一使用？其他@AnotherXXX同理。
为了识别各种@AnotherXXX，需要新的Resolver——GroupedCommandSubCommandAnnotationResolver，且SubCommandAnnotationResolver需要变为带泛型参数。
CommandReflector理解成两部分功能：一是反射出子指令，委托给SubCommandReflector；二是反射出子指令以外的Command属性（目前仅Usage）。

Him188

总体来说是很不错的实现, 有一些考虑:

SubCommandGroup 最好要提供一个可选的名称前缀的功能, 就像 CompositeCommand 那样. 我建议在使用注解时
在实现上一点后, CompositeCommand 实际上也是一个 SubCommandGroup. 把 SubCommandGroup 的 provideOverloads 改为 overloads, CompositeCommand 和 AbstractSubCommandGroup 就可以都继承 SubCommandGroup. 这解决了各种类型兼容问题, 但这将会允许 CompositeCommand 和 SubCommandGroup 互相嵌套. 嵌套方案在之后讨论
互相嵌套时 CommandReflector 会不会报错? 需要增加测试
需要增加对 generateUsage 的测试

有关我上面说的设计方案, 由于 console 的指令是定义式的, 我想象了如下使用 group 的方式, 欢迎评论:

// 插件一个模块的部分功能
class ModuleAPart1 : AbstractSubCommandGroup() {
    @SubCommand
    fun function1();
}

// 插件一个模块的另一部分功能
class ModuleAPart2 : AbstractSubCommandGroup() {
    @SubCommand
    fun function2();
    @SubCommand
    fun function3();
}

// 插件的一个模块, 统合上面两个功能
class ModuleACommandGroup: AbstractSubCommandGroup() {
    @SubCommand // 与在函数上标注这个注解类似, 它会带 `part1` 这个名称前缀来注册指令. 需要执行  /base part1 function1, 也可以使用 SubCommand 的参数来覆盖名称
    val part1: ModuleAPart1
    @FlattenSubCommands // 新增, 不带前缀注册指令, 执行 /base function2
    val part1: ModuleAPart1
}

// 插件的总指令, 统合全部模块
class MyUnifiedCommand : CompositeCommand() {
    @SubCommand 
    val moduleA: ModuleACommandGroup

    @SubCommand // 与现有注册方式混合, 看起来也不错
    fun about();
}

注解方案

新设计的 CompositeCommand 与 SubCommandGroup 在定义指令上是一样的, 我希望让它们使用同样的注解. 我觉得可以把那些 @SubCommand 复制到新抽象的 SubCommandGroup 中并 public. 将旧的标注 @Deprecated(level = HIDDEN). 这样 Kotlin 用户只需要修复 import (因为 Kotlin 引用非直接父类的内部类需要带外部类类名), Java 用户无需更新.

嵌套方案

嵌套是否需要增加前缀, 在且只在外层定义中指定.

使用 @SubCommand 时, 增加前缀. 前缀的名称的行为与这个注解标注在指令上时一致——有参数使用参数, 无参数使用指令反射名称
使用新增的 @FlattenSubCommands (这是我建议的名称, 可考虑更好名称) 时, 不增加前缀. 这样的行为类似标准库集合的 flatMap.

有关混合嵌套问题, 我考虑:

允许 AbstractSubCommandGroup 嵌入 CompositeCommand——原 PR 计划的功能
允许 CompositeCommand 嵌入 AbstractSubCommandGroup, 即使这可能导致 confusion, 但这毕竟是用户自己要这么干的. 以后可考虑通过 IDE 插件提供预览来解决这个问题 (指令增加 group 之后变得复杂, 也确实可能需要预览了)

有关用户自己实现接口的考虑:
接口公开, 且容易实现. 我认为可以允许用户实现, 只要符合接口的设计规范.

mirai-console/backend/mirai-console/src/command/SubCommandGroup.kt

mirai-console/backend/mirai-console/src/internal/command/CommandReflector.kt

Him188 · 2022-07-31T08:00:28Z

mirai-console/backend/mirai-console/src/internal/command/CommandReflector.kt

    public constructor(
-        ownerCommand: Command,
+        owner: Any,
        correspondingFunction: KFunction<*>,
        message: String?,
-    ) : super("Illegal command declaration: ${correspondingFunction.name} declared in ${ownerCommand::class.qualifiedName}") {
+    ) : super("Illegal command declaration: ${correspondingFunction.name} declared in ${owner::class.qualifiedName}") {
        this.message = message
    }


增加一个适用于 CommandGroup 的构造器, 而不是修改参数为 Any

hundun000 · 2022-08-02T10:36:14Z

我觉得可以把那些 @SubCommand 复制到新抽象的 SubCommandGroup 中并 public. 将旧的标注 @Deprecated(level = HIDDEN). 这样 Kotlin 用户只需要修复 import (因为 Kotlin 引用非直接父类的内部类需要带外部类类名), Java 用户无需更新.

即使已经(level = HIDDEN)且CompositeCommand extends SubCommandGroup，IDE还是会认为用户在试图使用父类的@SubCommand 并报错。import …SubCommandGroup.SubCommand未被使用，用户需要显式写成@SubCommandGroup.SubCommand。

计划开发期间真实移除CompositeCommand.SubCommand防止增加多处改动，晚些时候再讨论是否恢复为@Deprecated

类似问题的issue已被记录为kotlin bug。

Him188 · 2022-08-02T19:13:47Z

@hundun000 草

真实移除是 ABI 变更，是不可能进行的，只能考虑其他方案了...

Him188 · 2022-08-20T08:04:14Z

@hundun000 @Karlatemp 有什么想法吗，关于新注解

hundun000 · 2022-08-22T03:26:42Z

x Kotlin 用户只需要修复 import
√ Kotlin 用户修复为显式使用@SubCommandGroup.SubCommand

这样？因为我看IDEA自动补全也是选择补全为这样（指以前CompositeCommand.SubCommand还未废弃的时候），是因为这样也更符合编码规范吗？

Him188 · 2022-08-22T04:32:57Z

这个就是 Kotlin 设计问题，不允许用 simple name 引用超过一级继承关系的内部类型。Java 是可以的

…p.kt Co-authored-by: Him188 <Him188@mamoe.net>

…ndReflector.kt Co-authored-by: Him188 <Him188@mamoe.net>

Him188 requested changes Jun 30, 2022

View reviewed changes

Him188 added t:feature 类型: 新特性 s:console 子系统: mirai-console labels Jun 30, 2022

Him188 self-requested a review June 30, 2022 15:18

hundun000 marked this pull request as ready for review July 1, 2022 06:15

Karlatemp reviewed Jul 1, 2022

View reviewed changes

hundun000 force-pushed the hundun/command2 branch from 20a8b8a to df170b9 Compare July 4, 2022 08:26

hundun000 requested a review from Karlatemp July 13, 2022 01:25

Him188 reviewed Jul 31, 2022

View reviewed changes

hundun000 marked this pull request as draft August 2, 2022 10:40

hundun000 added 4 commits August 20, 2024 09:33

rebase dev with solve

db5d0b3

修复反射用法

1851e26

findSubCommds改为返回基类

af47315

rename test; dump new api

208a59c

hundun000 and others added 8 commits August 20, 2024 09:33

add test

22875c1

rebase dev with solve

10364bc

Update CommandReflector.kt

2bafd18

Update SimpleCommand.kt

2e7fef1

Update mirai-console/backend/mirai-console/src/command/SubCommandGrou…

7905555

…p.kt Co-authored-by: Him188 <Him188@mamoe.net>

Update mirai-console/backend/mirai-console/src/internal/command/Comma…

575b7ed

…ndReflector.kt Co-authored-by: Him188 <Him188@mamoe.net>

fix compile error from pr-changes

7ace541

update about SubCommandGroup

8b30851

hundun000 force-pushed the hundun/command2 branch from 9916ce2 to 8b30851 Compare August 20, 2024 01:39

hundun000 closed this Aug 20, 2024

hundun000 deleted the hundun/command2 branch August 20, 2024 03:55

hundun000 mentioned this pull request Aug 20, 2024

feat: 支持CompositeCommand间组合 #2857

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: 支持CompositeCommand间组合 #2125

feat: 支持CompositeCommand间组合 #2125

hundun000 commented Jun 30, 2022 •

edited

Loading

Him188 left a comment

hundun000 commented Jul 1, 2022

Karlatemp left a comment

Him188 commented Jul 1, 2022 •

edited

Loading

hundun000 commented Jul 1, 2022

hundun000 commented Jul 1, 2022

Him188 commented Jul 1, 2022

hundun000 commented Jul 2, 2022 •

edited

Loading

Him188 commented Jul 2, 2022

hundun000 commented Jul 2, 2022

Him188 commented Jul 3, 2022

hundun000 commented Jul 3, 2022

hundun000 commented Jul 4, 2022 •

edited

Loading

Him188 left a comment •

edited

Loading

Him188 Jul 31, 2022

hundun000 commented Aug 2, 2022 •

edited

Loading

Him188 commented Aug 2, 2022

Him188 commented Aug 20, 2022

hundun000 commented Aug 22, 2022 •

edited

Loading

Him188 commented Aug 22, 2022

feat: 支持CompositeCommand间组合 #2125

feat: 支持CompositeCommand间组合 #2125

Conversation

hundun000 commented Jun 30, 2022 • edited Loading

Him188 left a comment

Choose a reason for hiding this comment

hundun000 commented Jul 1, 2022

Karlatemp left a comment

Choose a reason for hiding this comment

Him188 commented Jul 1, 2022 • edited Loading

hundun000 commented Jul 1, 2022

hundun000 commented Jul 1, 2022

Him188 commented Jul 1, 2022

hundun000 commented Jul 2, 2022 • edited Loading

Him188 commented Jul 2, 2022

hundun000 commented Jul 2, 2022

Him188 commented Jul 3, 2022

hundun000 commented Jul 3, 2022

hundun000 commented Jul 4, 2022 • edited Loading

Him188 left a comment • edited Loading

Choose a reason for hiding this comment

注解方案

嵌套方案

Him188 Jul 31, 2022

Choose a reason for hiding this comment

hundun000 commented Aug 2, 2022 • edited Loading

Him188 commented Aug 2, 2022

Him188 commented Aug 20, 2022

hundun000 commented Aug 22, 2022 • edited Loading

Him188 commented Aug 22, 2022

hundun000 commented Jun 30, 2022 •

edited

Loading

Him188 commented Jul 1, 2022 •

edited

Loading

hundun000 commented Jul 2, 2022 •

edited

Loading

hundun000 commented Jul 4, 2022 •

edited

Loading

Him188 left a comment •

edited

Loading

hundun000 commented Aug 2, 2022 •

edited

Loading

hundun000 commented Aug 22, 2022 •

edited

Loading