Module dev.despical.commandframework
Package dev.despical.commandframework

Class CompleterHelper

java.lang.Object
dev.despical.commandframework.CompleterHelper
public final class CompleterHelper extends Object
A utility class designed to simplify the process of handling tab completion for commands.

This helper provides methods to easily filter lists of strings (like player names or command sub-arguments) based on the user's current input.

Author:
Despical

Created at 2.12.2025

  • Constructor Details

    • CompleterHelper

      @Internal public CompleterHelper(CommandArguments arguments)

  • Method Details

    • playerNames

      @NotNull @Contract(pure=true) public @NotNull List<String> playerNames()
      Retrieves a list of names for all players currently online on the server.

      This is commonly used for tab completion where a target player name is required.

      Returns:
      An unmodifiable list containing the names of online players. Returns an empty list if no players are online. Never returns null.

    • empty

      @NotNull @Contract(pure=true) public @NotNull List<String> empty()
      Returns an empty, immutable list of strings.

      This method is commonly used to terminate tab completion suggestions, indicating that no matches or further arguments are available for the current context.

      Returns:
      An empty, immutable list. Never returns null.

    • equalsAny

      @Contract(pure=true) public boolean equalsAny(String input, String... matches)
      Checks if the given input string matches any of the provided candidate strings.

      This method performs a case-sensitive comparison. If the input is null, it returns false immediately.

      Parameters:
      input - The string to check.
      matches - The potential matching strings.
      Returns:
      true if the input equals any of the matches; false otherwise.

    • equalsAny

      @Contract(pure=true) public boolean equalsAny(int index, String... matches)
      Checks if the argument at the specified index matches any of the provided candidate strings.

      This method retrieves the argument from the internal arguments list at the given index and delegates the comparison to equalsAny(String, String...).

      Parameters:
      index - The index of the argument to check.
      matches - The potential matching strings.
      Returns:
      true if the argument at the specified index matches any of the candidates.

    • copyMatches

      @NotNull @Contract(pure=true) public <T extends Collection<? super String>> T copyMatches(int index, @NotNull @NotNull Iterable<String> originals)
      Filters a collection of strings based on the argument at the specified index.

      This is a convenience overload that creates a new ArrayList to store results.

      Type Parameters:
      T - The type of the collection (inferred).
      Parameters:
      index - The index of the command argument to use as the filter token.
      originals - The source collection of strings to filter (e.g., all possible sub-commands).
      Returns:
      A new ArrayList containing only the strings from originals that start with the argument at the given index.
      See Also:

    • copyMatches

      @NotNull @Contract(pure=true) public <T extends Collection<? super String>> T copyMatches(int index, @NotNull @NotNull Iterable<String> originals, @NotNull T collection)
      Filters a collection of strings based on the argument at the specified index and adds matches to the provided collection.

      If the argument at the specified index is null or empty, the original collection is returned as is (or added to).

      Type Parameters:
      T - The type of the collection to return.
      Parameters:
      index - The index of the command argument to use as the filter token.
      originals - The source iterable of strings to filter.
      collection - The target collection where matches will be added.
      Returns:
      The collection provided, now containing the filtered matches.
      Throws:
      IllegalArgumentException - if any parameter is null.

    • copyMatches

      @NotNull @Contract(pure=true) public <T extends Collection<? super String>> T copyMatches(@NotNull @NotNull String token, @NotNull @NotNull Iterable<String> originals)
      Filters a collection of strings based on a specific token string.

      This is a convenience overload that creates a new ArrayList to store results.

      Type Parameters:
      T - The type of the collection (inferred).
      Parameters:
      token - The string token to search for (starts-with match).
      originals - The source collection of strings to filter.
      Returns:
      A new ArrayList containing only the strings that match the token.

    • copyMatches

      @NotNull @Contract(pure=true) public <T extends Collection<? super String>> T copyMatches(@NotNull @NotNull String token, @NotNull @NotNull Iterable<String> originals, @NotNull T collection)
      Filters a collection of strings based on a specific token string and adds matches to the provided collection.

      This delegates directly to Bukkit's StringUtil.copyPartialMatches(String, Iterable, Collection).

      Type Parameters:
      T - The type of the collection to return.
      Parameters:
      token - The string token to search for (starts-with match).
      originals - The source iterable of strings to filter.
      collection - The target collection where matches will be added.
      Returns:
      The collection provided, populated with matches.
      Throws:
      IllegalArgumentException - if originals contains a null element.