Class MagicCommand

java.lang.Object
dev.ua.theroer.magicutils.commands.MagicCommand
Direct Known Subclasses:
DynamicCommand, HelpCommandBase, MagicUtilsBundleCommand
public abstract class MagicCommand extends Object
Abstract base class for all custom commands. Provides utilities for command info, subcommands, and argument parsing.

  • Constructor Details

    • MagicCommand

      public MagicCommand()
      Default constructor for MagicCommand.

  • Method Details

    • getCommandInfo

      public static Optional<CommandInfo> getCommandInfo(Class<?> clazz)
      Gets the CommandInfo annotation from a class.
      Parameters:
      clazz - the command class
      Returns:
      an Optional containing CommandInfo if present

    • builder

      public static <S> MagicCommand.Builder<S> builder(String name)
      Creates a builder-backed command definition.
      Type Parameters:
      S - sender type
      Parameters:
      name - command name
      Returns:
      builder instance

    • fromSpec

      public static MagicCommand fromSpec(CommandSpec<?> spec)
      Wraps a compatibility command spec into a runtime MagicCommand.
      Parameters:
      spec - command spec
      Returns:
      built command

    • resolveInfo

      public final CommandInfo resolveInfo()
      Resolves the effective command metadata after runtime overrides.
      Returns:
      effective command info or null if this command has no metadata

    • isFrozen

      public final boolean isFrozen()
      Returns whether this command is frozen for runtime use.
      Returns:
      true when mutations are no longer allowed

    • withName

      public MagicCommand withName(String name)
      Override command name at runtime.
      Parameters:
      name - new name
      Returns:
      this

    • withInfo

      public MagicCommand withInfo(CommandInfo info)
      Override full command info at runtime (builder API).
      Parameters:
      info - command metadata
      Returns:
      this

    • addAlias

      public MagicCommand addAlias(String alias)
      Add an alias at runtime.
      Parameters:
      alias - alias to add
      Returns:
      this

    • removeAlias

      public MagicCommand removeAlias(String alias)
      Remove an alias (by exact match, case-insensitive) at runtime.
      Parameters:
      alias - alias to remove
      Returns:
      this

    • mount

      public MagicCommand mount(MagicCommand command)
      Mounts another command tree under this command using the child's own root label.

      The mounted command is snapshotted into dynamic subcommands. Metadata and route structure are copied at mount time, while execution still targets the mounted command instance.

      Parameters:
      command - command tree to mount
      Returns:
      this command

    • mount

      public MagicCommand mount(String route, MagicCommand command)
      Mounts another command tree under this command using a parent-local route label.

      This overrides the mounted route segment without renaming the source command definition itself. When a custom route is used, root aliases from the mounted command are not exposed automatically.

      Parameters:
      route - route label inside this command tree
      command - command tree to mount
      Returns:
      this command

    • mountSubCommands

      public MagicCommand mountSubCommands(MagicCommand command)
      Adds another command's sub-commands directly into this command tree, at the same level — without nesting them under the source command's name the way mount(MagicCommand) does.

      Where mount(cmd) produces /root <cmd-name> <sub>, this produces /root <sub>. Use it to let a plugin contribute top-level sub-commands to a shared root command it does not own: define them as @SubCommand methods on a carrier class, then flat-mount that carrier into a copy of the root and re-register. The source command's own direct execute (its bare-name action) is intentionally not carried over — only its sub-commands are.

      Parameters:
      command - the command whose sub-commands to graft in at this level
      Returns:
      this command

    • mergeSubCommands

      public MagicCommand mergeSubCommands(MagicCommand command, Consumer<String> warn)
      Merges command's sub-commands into this one so several plugins can contribute to a shared tree (e.g. each adding under /nox) without clobbering each other. Unlike mountSubCommands(MagicCommand), which blindly appends, this deduplicates by (path + name): when a node already exists, ownership of its execute is decided by MergePolicy — MergePolicy.CONTRIBUTE keeps the existing handler (put-if-absent), MergePolicy.OVERRIDE replaces it (logging warn if the existing one was itself an explicit override), and MergePolicy.EXTEND never claims the node. Leaf nodes that don't collide are simply added.
      Parameters:
      command - the carrier whose sub-commands to merge in
      warn - sink for a one-line conflict warning (may be null)
      Returns:
      this command

    • addSubCommand

      public MagicCommand addSubCommand(SubCommandSpec<?> subCommand)
      Add a dynamic subcommand (builder API).
      Parameters:
      subCommand - subcommand spec
      Returns:
      this

    • addSubCommand

      public MagicCommand addSubCommand(SubCommandSpec<?> subCommand, boolean replaceExisting)
      Add a dynamic subcommand with explicit replace flag.
      Parameters:
      subCommand - subcommand spec
      replaceExisting - whether to override matching subcommands
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, List<CommandArgument> arguments, boolean replaceExisting)
      Define a dynamic execute handler (builder API).
      Parameters:
      executor - command executor
      arguments - argument definitions
      replaceExisting - whether to replace annotated execute method
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, List<CommandArgument> arguments, CommandThreading threading, boolean replaceExisting)
      Define a dynamic execute handler (builder API).
      Parameters:
      executor - command executor
      arguments - argument definitions
      threading - threading policy
      replaceExisting - whether to replace annotated execute method
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, List<CommandArgument> arguments)
      Define a dynamic execute handler (builder API).
      Parameters:
      executor - command executor
      arguments - argument definitions
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, List<CommandArgument> arguments, CommandThreading threading)
      Define a dynamic execute handler (builder API) with explicit threading policy.
      Parameters:
      executor - command executor
      arguments - argument definitions
      threading - threading policy
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, CommandArgument... arguments)
      Define a dynamic execute handler (builder API).
      Parameters:
      executor - command executor
      arguments - argument definitions
      Returns:
      this

    • setExecute

      public MagicCommand setExecute(CommandExecutor<?> executor, CommandThreading threading, CommandArgument... arguments)
      Define a dynamic execute handler (builder API) with explicit threading policy.
      Parameters:
      executor - command executor
      threading - threading policy
      arguments - argument definitions
      Returns:
      this

    • overrideInfo

      public CommandInfo overrideInfo(CommandInfo original)
      Apply runtime overrides to a CommandInfo annotation.
      Parameters:
      original - original info
      Returns:
      overridden info

    • copy

      public MagicCommand copy()
      Creates an unfrozen duplicate of this command's declarative state so it can be modified and re-registered after the original was frozen by registration.

      Registration freezes a command, after which mount(MagicCommand) and the other mutators throw. This is the supported way to add sub-commands to an already-registered command tree: copy it, mount into the copy, and register the copy under the same name (registration replaces the previous owner by name). Because a copy preserves the mounted sub-commands of the source, multiple contributors can each copy-mount-register in turn and their additions accumulate.

      The copy is a DynamicCommand carrying the source's effective info, name/alias overrides, dynamic sub-commands (which is where mount(MagicCommand) records mounted trees) and dynamic execute. Sub-commands declared as @SubCommand methods on a concrete subclass are part of that subclass, not of this declarative state; a subclass that carries such methods and needs them preserved across a copy should override this method to return an instance of its own type. Commands built from a spec/builder or assembled purely by mount(MagicCommand) — such as an aggregate root command — copy losslessly with the default implementation.

      Returns:
      an unfrozen copy that can be mutated and re-registered

    • getSubCommands

      public static List<MagicCommand.SubCommandInfo> getSubCommands(Class<?> clazz)
      Gets all subcommands from a command class.
      Parameters:
      clazz - the command class
      Returns:
      a list of SubCommandInfo

    • findExecuteMethod

      public static Method findExecuteMethod(Class<?> clazz)
      Gets the direct execute method from a command class.
      Parameters:
      clazz - command class
      Returns:
      execute method or null

    • getArguments

      public static List<CommandArgument> getArguments(Method method)
      Gets all arguments for a subcommand method.
      Parameters:
      method - the subcommand method
      Returns:
      a list of CommandArgument

    • getUsage

      public static String getUsage(Class<?> clazz)
      Gets the usage string for a command class.
      Parameters:
      clazz - the command class
      Returns:
      the usage string, or null if not available