feat: Register SingleConfig<T> when injecting single configs, auto reload configs when tick changes

docs: Add more KDoc for DI helpers, update command dsl docs

Author: 0ffz

docs/command-dsl.md

@@ -2,54 +2,43 @@
 
 [//]: # ([:simple-gradle: ![](https://img.shields.io/maven-metadata/v?label=idofront-commands&metadataUrl=https://repo.mineinabyss.com/releases/com/mineinabyss/idofront-commands/maven-metadata.xml){ style="vertical-align:middle" }](https://repo.mineinabyss.com/#/releases/com/mineinabyss/idofront-commands))
 
-Idofront provides a clean way of creating custom command structures through a DSL. This feature is currently very
-experimental.
+Idofront provides a commands DSL that wraps Minecraft's Brigadier system.
+We show an example implementation in the `examples` module on GitHub.
 
 ## Register your command executor
 
-Implement `IdofrontCommandExecutor` It is recommended to create a singleton object for managing your commands.
+In your plugin's `onEnable`, call the `commands` block.
+Brigadier only lets you register commands on server startup, so your structure can't be changed after this:
 
 ```kotlin
-object MyCommandExecutor: IdofrontCommandExecutor() {
-    override val commands: CommandHolder = commands(MyPlugin) { //MyPlugin is a reference to your main plugin instance
-        //Command DSL ishere
+plugin.commands {
+    // Registers a top level /example command
+    "example" {
+        ...
     }
 }
-
-...
-
-override fun onEnable(){
-    MyCommandExecutor //instantiate the singleton
-}
 ```
 
-That's it! The command registration is done for you. You do however currently need to add your commands into
-`plugin.yml` like you normally would, but hopefully this won't be necessary in the future.
-
 ## Creating commands
 
 Within your `commands` block, you may create new commands as follows:
 
 ```kotlin
-command("basicCommand"){
-}
-
-command("anotherCommand", "alias", "anotherAlias", desc= "Short description") {
-}
-
-//or alternatively, which will be the preferred format in this guide
-
+// Command with description and permission set
 "basicCommand" {
+    description = "Short description"
+    permission = "my.plugin.perm"
 }
 
-("anotherCommand" / "alias" / "anotherAlias")(desc= "Short description") {
+// Command with aliases
+("anotherCommand" / "alias" / "anotherAlias") {
+    ...
 }
 ""
 ```
 
 This will allow players to use `/basicCommand`, and `/anotherCommand` (or `/alias`, `/anotherAlias`)
-A malformated command will display relevant help information, such as subcommands or missing arguments.
-`/basicCommand ?` will display the full help message with description, aliases, etc...
+Note that subcommands default to using permission `parentpermission.<commandName>`.
 
 ## Subcommands
 
@@ -58,7 +47,8 @@ different things. We want to be able to do:
 `/myplugin version` - To get the plugin version
 `/myplugin giveApple <amount (default 1)> <player (default to self)>` - To give an apple to a certain player
 
-We can simply nest subcommands within other commands (indefinitely) to create a structure:
+We can nest subcommands within other commands (indefinitely) to create a structure.
+Under the hood this chains together Brigadier's `literal`.
 
 ```kotlin
 "myplugin" {
@@ -67,83 +57,45 @@ We can simply nest subcommands within other commands (indefinitely) to create a
 }
 ```
 
-## Actions
-
-To actually run things with a command, we must specify actions. Actions, like the `playerAction` may have conditions
-that need to be met before they are run. If any condition ever fails, the command will stop right there, and an error
-will be sent to the sender. Multiple actions may exist in a command, but upon failure, no other actions will be
-executed.
+## Executes blocks
 
-If an action succeeds, it will execute the code inside, plus give some extra contextual information, such as the sender.
-
-Let's use the default `action` for our version, which gives us access to a sender, and `playerAction` which ensures the
-sender is a player, and gives us a player to work with:
+We specify what a command does with an `executes` block. Idofront provides some helpers on this to ensure
+a sender is a player and to pass command arguments.
 
 ```kotlin
 "myplugin" {
     "version" {
-        action {
-            sender.info("Plugin version: ${MyPlugin.version}")
+        executes {
+            sender.sendMessage("Plugin version: ${MyPlugin.version}")
         }
     }
     "giveApple" {
-        playerAction {
+        executes.asPlayer {
             player.inventory.addItem(ItemStack(Material.APPLE, 1))
         }
     }
 }
 ```
 
+Note that we can also `fail("Message")` inside executes blocks to stop the command at any point and send the sender a message.
+
 ## Arguments
 
 Now we need to let players pass an amount for the item.
-
-Arguments are done through delegates, there are some methods for primitives, but you may also create custom arguments:
+Arguments take normal Brigadier argument types, with our own DSL around them for providing suggestions or
+restricting options. We provide a singleton `Args` you can use to see a list of argument options, as well as `ArgsMinecraft`
+which is an alias for Paper's custom argumetns for things like Player, Location, etc...
 
 ```kotlin
 "giveApple" {
-    val amount by intArg { default = 1 }
-    playerAction {
-        player.inventory.addItem(ItemStack(Material.APPLE, amount))
+    executes.asPlayer().args(
+        "amount" to Args.integer(min = 1).default { 1 },
+        "player" to Args.otherPlayer() // A built-in helper in Idofront for an optional target player 
+    ) { amount, other ->
+        other.inventory.addItem(ItemStack(Material.APPLE, amount))
     }
 }
 ```
 
-And that's it! If you have multiple arguments, they will be required in that order. You may also customize some other
-things, like the error message within `intArg { }`. You may even use mutable properties.
-
-Default just means the argument may be omitted. It doesn't do much if a default argument is followed by a mandated one.
-
-## Limiting argument visibility
-
-The general rule is, if you have access to an argument, it will be required in that command. This means, while you may
-share the same arguments between several subcommands, any commands below will also require that argument to be passed (
-the only limitation is that there cannot be any root level arguments yet).
-
-To fix this, a `commandGroup` block exists, which does nothing but limit argument visibility:
-
-```kotlin
-commandGroup {
-    val amount by intArg()
-    //both commands below will require the "amount" to be passed
-    "one" { ... }
-    "two" { ... }
-}
-//no arguments will be required here, because we can't access any in our code!
-"noArgs" { ... }
-```
-
-## Conclusion
-
-There are some more features sprinkled into the plugin, but many might disappear. I'm more confident the DSL will remain
-more or less similar going into the future, but be warned that some refactors may happen, and some things may change.
-
-## Future plans
-
-The current system also doesn't build any structure at startup, so it's unaware of things like arguments of subcommands,
-or subcommands of subcommands. Everything is evaluated on-the-go, except root level commands, since those need to be
-registered upon startup (this is why we can't currently have root level arguments). The biggest thing stopping a
-structure from being generated upon startup is arguments. While it is possible to get a reference to the object the
-delegate is being called from (and thus have separate instances of each argument in a map), this does not work for
-lambdas, which return null as the reference. Perhaps it is possible to sidestep this with `inline` functions, thought I
-have not tried it yet.
+Please be sure to look at the [ExampleCommands](https://github.com/MineInAbyss/Idofront/blob/master/examples/src/main/kotlin/com/mineinabyss/idofront/examples/commands/ExampleCommands.kt)
+implementation for more tips around using Minecraft arguments, providing suggestions, and more!

idofront-commands/src/main/kotlin/com/mineinabyss/idofront/commands/brigadier/Args.kt

@@ -35,8 +35,10 @@ object Args {
         .map { Bukkit.getOfflinePlayer(it) }
 
     /**
-     * An argument for as singple player that defaults to the sender.
+     * An argument for a single player that defaults to the sender.
      * Useful for commands that can optionally run as other players.
+     *
+     * Requires `<permission>.others` to run as other players.
      */
     fun otherPlayer() = ArgsMinecraft
         .player()

idofront-features/src/main/kotlin/com/mineinabyss/idofront/features/CommandHelpers.kt

@@ -0,0 +1,99 @@
+package com.mineinabyss.idofront.features
+
+import com.mineinabyss.dependencies.DI
+import com.mineinabyss.dependencies.DIScope
+import com.mineinabyss.dependencies.get
+import com.mineinabyss.dependencies.module
+import com.mineinabyss.idofront.commands.brigadier.*
+import com.mineinabyss.idofront.messaging.error
+import com.mineinabyss.idofront.messaging.success
+import org.bukkit.plugin.Plugin
+
+/**
+ * Lets other features register subcommands under this plugin's [MainCommand].
+ *
+ * @see mainCommand
+ */
+val MainCommandFeature = module("Main Command") {
+    onServerStartup {
+        plugin.commands {
+            val main = get<MainCommand>()
+            val manager = get<DIScope>()
+            main.names.invoke {
+                description = main.description
+                permission = main.permission
+                main.subcommands.forEach { subcommand ->
+//                val feature = manager.getModule(subcommand.module) ?: error("Feature name not found: ${subcommand.module}")
+                    val context = DICommandContext(manager, subcommand.module)
+                    subcommand.create(context, this)
+                }
+
+                if (main.reloadCommandName != null) {
+                    main.reloadCommandName {
+                        permission = main.reloadCommandPermission
+
+                        executes {
+                            if (main.reloadableFeatures == null)
+                                manager.reloadAll()
+                            else manager.reload(*main.reloadableFeatures.toTypedArray())
+                        }
+
+                        executes.args(
+                            "feature" to Args.string().oneOf {
+                                if (main.reloadableFeatures == null)
+                                    manager.loaded.map { it.name }.toList()
+                                else main.reloadableFeatures.map { it.name }
+                            }
+                        ) { featureName ->
+                            val feat = manager.loaded.find { it.name == featureName } ?: fail("Feature $featureName not found")
+                            if (runCatching { manager.reload(feat) }.onFailure { it.printStackTrace() }.isSuccess) {
+                                sender.success("Reloaded feature $featureName")
+                            } else {
+                                sender.error("Failed to reload feature $featureName")
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Registers a subcommand under this plugin's [MainCommand].
+ *
+ * Plugins using this must first inject a [MainCommand] into their DI container, then load [MainCommandFeature] *after* all other features are loaded:
+ *
+ * ```kotlin
+ * val di = DI {
+ *   single { MainCommand(names = listOf("mycommand"), ...) }
+ * }
+ *
+ * val FeatureA = module("Feature A") { ... }.mainCommand {
+ *   "subcommand" { ... }
+ * }
+ *
+ * di.scope.loadAllCatching(FeatureA, FeatureB, ...)
+ * di.scope.load(MainCommandFeature)
+ */
+fun DI.Module.mainCommand(block: context(DICommandContext) IdoRootCommand.() -> Unit): DI.Module {
+    return override {
+        onServerStartup {
+            get<MainCommand>().subcommand(this@mainCommand, block)
+        }
+    }
+}
+
+/**
+ * Registers new commands under the [plugin] in this context, unlike [mainCommand], these are top-level commands.
+ *
+ * The entire block is only evaluated once on startup, use [DICommandContext]'s `get` to get dependencies in commands.
+ */
+fun DI.Module.commands(block: context(DICommandContext) RootIdoCommands.() -> Unit) = override {
+    onServerStartup {
+        val context = DICommandContext(get(), get())
+        get<Plugin>().commands {
+            block(context, this)
+        }
+    }
+}

idofront-features/src/main/kotlin/com/mineinabyss/idofront/features/InjectHelpers.kt

@@ -0,0 +1,66 @@
+package com.mineinabyss.idofront.features
+
+import co.touchlab.kermit.Logger
+import co.touchlab.kermit.Severity
+import com.mineinabyss.dependencies.*
+import com.mineinabyss.idofront.config.ConfigBuilder
+import com.mineinabyss.idofront.config.SingleConfig
+import com.mineinabyss.idofront.config.config
+import com.mineinabyss.idofront.messaging.ComponentLogger
+import org.bukkit.Bukkit
+import org.bukkit.plugin.Plugin
+import kotlin.io.path.div
+
+/**
+ * Injects a single serializable config of type [T], located at [path] relative to the plugin's data folder.
+ *
+ * The config will be automatically re-read on a new server tick using a factory binding.
+ * Also registers a `SingleConfig<T>` binding which can be used to read/write the config manually.
+ *
+ * For more complicated config use-cases (ex. reading a directory), use [ConfigBuilder] and manually inject via a context class.
+ *
+ * ### Example usage:
+ *
+ * ```kotlin
+ * // Inject, overriding format to Yaml
+ * singleConfig<MyConfig>("config.yml") { format = Yaml() }
+ *
+ * // Gets updated config if requesting on a new server tick
+ * val config = get<MyConfig>()
+ *
+ * // Write newConfig to disk
+ * get<SingleConfig<MyConfig>>().write(newConfig)
+ * ```
+ */
+inline fun <reified T : Any> MutableDI.singleConfig(
+    path: String,
+    crossinline configure: ConfigBuilder<T>.() -> Unit = {},
+) {
+    val configHolder by single<SingleConfig<T>> {
+        val plugin = get<Plugin>()
+        config<T> { configure() }.single(plugin.dataPath / path)
+    }
+    var cache = configHolder.read() to Bukkit.getCurrentTick()
+    factory<T> {
+        val currentTick = Bukkit.getCurrentTick()
+        val (data, lastRead) = cache
+        if (currentTick == lastRead) return@factory data
+        else {
+            val read = configHolder.read()
+            cache = read to currentTick
+            return@factory read
+        }
+    }
+}
+
+/**
+ * Injects a [Logger] and [ComponentLogger] for the given [plugin].
+ *
+ * In the future might be updated to allow re-reading severity from a config after reloads, for now [minSeverity] is evaluated once.
+ *
+ * @param minSeverity Provider for the minimum severity to log, can read DI values.
+ */
+fun MutableDI.singlePluginLogger(
+    plugin: Plugin,
+    minSeverity: DI.() -> Severity = { Severity.Info },
+) = single { ComponentLogger.forPlugin(plugin, minSeverity()) }.and<Logger>()