Update ExportManager

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/plugin/ExportManagerImpl.kt

@@ -28,6 +28,8 @@ internal class ExportManagerImpl(
     companion object {
         @JvmStatic
         fun parse(lines: Iterator<String>): ExportManagerImpl {
+            fun Boolean.without(value: Boolean) = if (this == value) null else this
+
             val rules = ArrayList<(String) -> Boolean?>()
             lines.asSequence().map { it.trim() }.filter { it.isNotBlank() }.filterNot {
                 it[0] == '#'
@@ -36,36 +38,24 @@ internal class ExportManagerImpl(
                 val argument = line.substringAfter(' ', missingDelimiterValue = "").trim()
 
                 when (command) {
-                    "export" -> {
+                    "exports", "export-package" -> rules.add {
-                        when {
+                        it.startsWith(argument).without(false)
-                            // export-all
-                            argument.isBlank() -> rules.add { true }
-                            // export package
-                            argument.endsWith(".") -> rules.add {
-                                if (it.startsWith(argument)) true else null
                     }
-                            // export class
+                    "export", "export-class" -> rules.add {
-                            else -> rules.add {
+                        (it == argument).without(false)
-                                if (it == argument) true else null
                     }
+                    "protects", "protect-package" -> rules.add {
+                        if (it.startsWith(argument))
+                            false
+                        else null
                     }
+                    "protect", "protect-class" -> rules.add {
+                        if (it == argument)
+                            false
+                        else null
                     }
-                    "deny", "internal", "hidden" -> {
+                    "export-all", "export-plugin", "export-system" -> rules.add { true }
-                        when {
+                    "protect-all", "protect-plugin", "protect-system" -> rules.add { false }
-                            // deny-all
-                            argument.isBlank() -> rules.add { false }
-                            // deny package
-                            argument.endsWith(".") -> rules.add {
-                                if (it.startsWith(argument)) false else null
-                            }
-                            // deny class
-                            else -> rules.add {
-                                if (it == argument) false else null
-                            }
-                        }
-                    }
-                    "export-all" -> rules.add { true }
-                    "deny-all", "hidden-all" -> rules.add { false }
                 }
             }
             return ExportManagerImpl(rules)

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/ExportManager.kt

@@ -10,72 +10,83 @@
 package net.mamoe.mirai.console.plugin.jvm
 
 import net.mamoe.mirai.console.internal.plugin.ExportManagerImpl
+import net.mamoe.mirai.console.util.ConsoleExperimentalApi
 
 /**
  * 插件的类导出管理器
  *
- * 我们允许插件将一些内部实现hidden起来， 避免其他插件调用， 要启动这个特性，
+ *
- * 只需要在你的 resources 文件夹创建名为 `export-rules.txt` 的规则文件，便可以控制插件的类的公开规则
+ * 允许插件将一些内部实现保护起来， 避免其他插件调用， 要启动这个特性，
+ * 只需要创建名为 `export-rules.txt` 的规则文件，便可以控制插件的类的公开规则。
+ *
+ * 如果正在使用 `Gradle` 项目, 该规则文件一般位于 `src/main/resources` 下
  *
  * Example:
  * ```text
  *
- * # #开头的行我们都识别为注释, 你可以在规则文件里面写很多注释
+ * # #开头的行全部识别为注释
  *
- * # export 运行插件访问一个类, 或者一个包
+ * # export, 允许其他插件直接使用某个类
  *
  * # 导出了一个internal包的一个类
- * export org.example.miraiconsole.myplugin.internal.OpenInternal
- *
- * # 导出了整个 api 包, 导出包和导出类的区别就是末尾是否存在 . 号
- * export org.example.miraiconsole.myplugin.api.
- *
- * # deny, 不允许其他插件使用这个包, 要隐藏一个包的时候, 注意不要忘记最后的 . 号
  * #
- * # 别名: hidden, internal
+ * # 别名: export-class
- * deny org.example.miraiconsole.myplugin.internal.
+ * export       org.example.miraiconsole.myplugin.internal.OpenInternal
+ * # 可以使用别名
+ * export-class org.example.miraiconsole.myplugin.internal.OpenInternal
  *
- * # 这条规则不会生效, 因为在这条规则前已经被上面的 deny 给隐藏了
+ * # 导出了整个 api 包
+ * #
+ * # 别名: export-package
+ * exports org.example.miraiconsole.myplugin.api
+ *
+ * # 保护 org.example.miraiconsole.myplugin.api2.Internal, 不允许其他插件直接使用
+ * #
+ * # 别名: protect-class
+ * protect org.example.miraiconsole.myplugin.api2.Internal
+ *
+ * # 保护整个包
+ * #
+ * # 别名: protect-package
+ * protects org.example.miraiconsole.myplugin.internal
+ *
+ * # 此规则不会生效, 因为在此条规则之前,
+ * # org.example.miraiconsole.myplugin.internal 已经被加入到保护域中
  * export org.example.miraiconsole.myplugin.internal.NotOpenInternal
  *
  *
- * # export-all, 导出全部内容, 当然在此规则之前的deny依然会生效
+ * # export-plugin, 允许其他插件使用除了已经被保护的全部类
  * # 使用此规则会同时让此规则后的所有规则全部失效
- * # export-all
+ * # 别名: export-all, export-system
+ * # export-plugin
  *
- * # 拒绝其他插件使用任何类, 除了之前已经explort的
- * # 此规则会导致后面的所有规则全部失效
- * deny-all
  *
- * ```
+ * # 将整个插件放入保护域中
+ * # 除了此规则之前显式 export 的类, 其他插件将不允许直接使用被保护的插件的任何类
+ * # 别名: protect-all, protect-system
+ * protect-plugin
  *
- * 插件也可以通过 Service 来自定义导出控制
- *
- * Example:
- * ```
- * @AutoService(ExportManager::class)
- * object MyExportManager: ExportManager {
- *     override fun isExported(className: String): Boolean {
- *         println("  <== $className")
- *         return true
- *     }
- * }
  * ```
  *
  */
+@ConsoleExperimentalApi
 public interface ExportManager {
     public fun isExported(className: String): Boolean
 }
 
+@ConsoleExperimentalApi
 public object StandardExportManagers {
+    @ConsoleExperimentalApi
     public object AllExported : ExportManager {
         override fun isExported(className: String): Boolean = true
     }
 
+    @ConsoleExperimentalApi
     public object AllDenied : ExportManager {
         override fun isExported(className: String): Boolean = false
     }
 
+    @ConsoleExperimentalApi
     @JvmStatic
     public fun parse(lines: Iterator<String>): ExportManager {
         return ExportManagerImpl.parse(lines)

docs/Plugins.md

@@ -164,38 +164,55 @@ public final class JExample extends JavaPlugin {
 
 ### API 导出管理
 
-我们允许插件将一些内部实现hidden起来， 避免其他插件调用， 要启动这个特性，
+允许插件将一些内部实现保护起来， 避免其他插件调用， 要启动这个特性，
-只需要在你的 resources 文件夹创建名为 `export-rules.txt` 的规则文件，便可以控制插件的类的公开规则
+只需要创建名为 `export-rules.txt` 的规则文件，便可以控制插件的类的公开规则。
+
+如果正在使用 `Gradle` 项目, 该规则文件一般位于 `src/main/resources` 下
 
 Example:
 ```text
 
-# #开头的行我们都识别为注释, 你可以在规则文件里面写很多注释
+# #开头的行全部识别为注释
 
-# export 运行插件访问一个类, 或者一个包
+# export, 允许其他插件直接使用某个类
 
 # 导出了一个internal包的一个类
-export org.example.miraiconsole.myplugin.internal.OpenInternal
-
-# 导出了整个 api 包, 导出包和导出类的区别就是末尾是否存在 . 号
-export org.example.miraiconsole.myplugin.api.
-
-# deny, 不允许其他插件使用这个包, 要隐藏一个包的时候, 注意不要忘记最后的 . 号
 #
-# 别名: hidden, internal
+# 别名: export-class
-deny org.example.miraiconsole.myplugin.internal.
+export       org.example.miraiconsole.myplugin.internal.OpenInternal
+# 可以使用别名
+export-class org.example.miraiconsole.myplugin.internal.OpenInternal
 
-# 这条规则不会生效, 因为在这条规则前已经被上面的 deny 给隐藏了
+# 导出了整个 api 包
+#
+# 别名: export-package
+exports org.example.miraiconsole.myplugin.api
+
+# 保护 org.example.miraiconsole.myplugin.api2.Internal, 不允许其他插件直接使用
+#
+# 别名: protect-class
+protect org.example.miraiconsole.myplugin.api2.Internal
+
+# 保护整个包
+#
+# 别名: protect-package
+protects org.example.miraiconsole.myplugin.internal
+
+# 此规则不会生效, 因为在此条规则之前,
+# org.example.miraiconsole.myplugin.internal 已经被加入到保护域中
 export org.example.miraiconsole.myplugin.internal.NotOpenInternal
 
 
-# export-all, 导出全部内容, 当然在此规则之前的deny依然会生效
+# export-plugin, 允许其他插件使用除了已经被保护的全部类
 # 使用此规则会同时让此规则后的所有规则全部失效
-# export-all
+# 别名: export-all, export-system
+# export-plugin
 
-# 拒绝其他插件使用任何类, 除了之前已经explort的
+
-# 此规则会导致后面的所有规则全部失效
+# 将整个插件放入保护域中
-deny-all
+# 除了此规则之前显式 export 的类, 其他插件将不允许直接使用被保护的插件的任何类
+# 别名: protect-all, protect-system
+protect-plugin
 
 ```