Package com.ultikits.ultitools.commands.tabcomplete

Class TabCompletionManager

java.lang.Object
com.ultikits.ultitools.commands.tabcomplete.TabCompletionManager
public class TabCompletionManager extends Object
Central manager for tab completion functionality. Provides a unified API for both old and new command systems.
Since:
6.2.0
Version:
1.0.0
Author:
wisdomme

  • Field Details

  • Constructor Details

    • TabCompletionManager

      private TabCompletionManager()
      Private constructor - use getInstance().

  • Method Details

    • getInstance

      public static TabCompletionManager getInstance()
      Gets the singleton instance.
      Returns:
      the tab completion manager instance

    • registerBuiltInCompleters

      private void registerBuiltInCompleters()
      Registers all built-in completers.

    • register

      public void register(String key, TabCompleter completer)
      Registers a custom completer with a key.
      Parameters:
      key - the key to register with (e.g., "@custom")
      completer - the completer to register

    • unregister

      public void unregister(String key)
      Unregisters a completer.
      Parameters:
      key - the key to unregister

    • beginRegistrationScope

      public void beginRegistrationScope(String owner)
      Marks the beginning of a registration scope attributed to owner -- every completer key registered via register(String, TabCompleter) while this scope is active is recorded as owned by owner, so unregisterByOwner(String) can sweep it later without requiring caller code to pass an owner explicitly (05-06 / D-08's "explicit owner parameter on an internal registration path" -- the parameter is ambient rather than a new argument on the published register(String, TabCompleter) signature, which stays frozen).

      ClassLoader-derived ownership was considered and rejected for this codebase. Every internal UltiToolsPlugin module is loaded through ONE shared URLClassLoader covering the whole plugins/ folder (see PluginManager.init(ClassLoader)) -- the identical structural finding already recorded at PluginManager.validateAdditionalEntity's javadoc for D-19 -- so a completer instance's getClass().getClassLoader() cannot distinguish between two different modules here. An explicit scope is the only mechanism reachable from a module's only registration entry point (the public register(String, TabCompleter)) that still correctly separates two modules' completers.

      Not part of the frozen 6.2.5 singleton shape (getInstance(), register(String, TabCompleter), unregister(String)) -- new in 6.3.0, intended for PluginManager's own module load/unload sequence, not for module authors.

      Scopes do not nest: a second beginRegistrationScope call while one is already active simply replaces the current owner. UltiTools' own module loading is sequential -- one module's container is fully assembled (including its pluginContext.refresh(), where @PostConstruct runs) before the next module's load begins -- so nesting has never been required; this is a stated assumption, not an enforced invariant.

      Parameters:
      owner - the identifier (the framework uses the plugin's name) to attribute subsequent registrations to
      Since:
      6.3.0

    • endRegistrationScope

      public void endRegistrationScope()
      Ends the current registration scope started by beginRegistrationScope(String). Registrations made after this call (and before another scope begins) are unowned and never swept by unregisterByOwner(String) -- the same as every registration made before this mechanism existed.
      Since:
      6.3.0

    • unregisterByOwner

      public int unregisterByOwner(String owner)
      Bulk-unregisters every completer key currently attributed to owner by an earlier beginRegistrationScope(String)/endRegistrationScope() window, built entirely from the already-public unregister(String) -- so removal semantics are identical to a caller unregistering each key by hand, just batched by owner (D-08: "No new public method is needed: unregister(String) already exists -- the bulk sweep can be built from it"). A key registered outside any scope (core built-ins, or any caller that never calls beginRegistrationScope(String)) has no recorded owner and is never matched here, regardless of owner's value.
      Parameters:
      owner - the owner identifier to sweep; null matches nothing and is a no-op
      Returns:
      the number of keys unregistered
      Since:
      6.3.0

    • getCompleter

      public TabCompleter getCompleter(String key)
      Gets a registered completer by key.
      Parameters:
      key - the completer key
      Returns:
      the completer or null if not found

    • suggest

      public List<String> suggest(org.bukkit.entity.Player player, org.bukkit.command.Command command, String[] args)
      Generates suggestions using the appropriate completer.
      Parameters:
      player - the player requesting completion
      command - the command
      args - the current arguments
      Returns:
      list of suggestions

    • suggest

      public List<String> suggest(TabCompletionContext context)
      Generates suggestions using the given context.
      Parameters:
      context - the completion context
      Returns:
      list of suggestions

    • suggest

      public List<String> suggest(TabCompletionContext context, String resolvedSuggest)
      Resolves suggestions using an explicitly-resolved @CmdParam.suggest() value, rather than context's TabCompletionContext.parameterName -- which carries @CmdParam.value(), the parameter's DISPLAY NAME, not its suggestion (05-06 / D-07 Pitfall 2, T-05-28). suggest(TabCompletionContext) above is left untouched for existing callers; this overload is the dual-notation entry point a caller that has already resolved the real suggest() value (see resolveSuggestValue(Method, String)) should use instead.

      A resolvedSuggest beginning with @ resolves as a built-in or registered completer key. Any other value -- including null or empty -- falls through to the existing method-invocation completer (and its i18n hint-text fallback), unchanged.

      Parameters:
      context - the completion context
      resolvedSuggest - the already-resolved @CmdParam.suggest() string for the parameter being completed; may be null or empty
      Returns:
      the suggestions; never null
      Since:
      6.3.0

    • resolveSuggestValue

      public static String resolveSuggestValue(Method matchedMethod, String parameterName)
      Resolves matchedMethod's @CmdParam.suggest() value for the parameter whose @CmdParam.value() equals parameterName -- i.e. it keys the lookup off the parameter's DISPLAY NAME to find the right parameter, then returns that parameter's suggestion, never the display name itself (05-06 / D-07). This mirrors MethodInvocationCompleter.getSuggestName's existing lookup shape so the two stay consistent, without depending on that private method directly.
      Parameters:
      matchedMethod - the matched @CmdMapping method, or null
      parameterName - the parameter's display name (@CmdParam.value()) to look up
      Returns:
      the resolved suggest() value, or null if matchedMethod is null or no parameter's value() matches parameterName
      Since:
      6.3.0

    • suggestWith

      public List<String> suggestWith(TabCompletionContext context, String completerKey)
      Suggests completions for a specific parameter type.
      Parameters:
      context - the completion context
      completerKey - the key of the completer to use
      Returns:
      list of suggestions

    • createContext

      public TabCompletionContext createContext(org.bukkit.entity.Player player, org.bukkit.command.Command command, String[] args)
      Creates a context for tab completion with common defaults.
      Parameters:
      player - the player
      command - the command
      args - the arguments
      Returns:
      a tab completion context

    • filterByInput

      public static List<String> filterByInput(List<String> suggestions, String input)
      Helper method to filter suggestions by current input.
      Parameters:
      suggestions - the suggestions to filter
      input - the current input
      Returns:
      filtered suggestions

    • suggestFirstArgs

      public List<String> suggestFirstArgs(Map<String,Method> mappings, TabCompletionContext context)
      Suggests command format first arguments from mappings.
      Parameters:
      mappings - the command mappings (format -> method)
      context - the completion context
      Returns:
      list of first argument suggestions