Package studio.mevera.imperat.command

Interface CommandUsage<S extends Source>

All Superinterfaces:
CooldownHolder, DescriptionHolder, Iterable<CommandParameter<S>>, PermissionHolder
public sealed interface CommandUsage<S extends Source> extends Iterable<CommandParameter<S>>, PermissionHolder, DescriptionHolder, CooldownHolder
Represents a usage of a command that can be used in the future during an execution
See Also:

  • Method Details

    • getFlagExtractor

      @NotNull @NotNull FlagExtractor<S> getFlagExtractor()
      Retrieves the flag extractor instance for parsing command flags from input strings.

      The returned FlagExtractor is capable of parsing flag aliases from compact string representations (e.g., "-abc", "alphaby") and resolving them to their corresponding FlagData objects based on the command's usage configuration.

      The extractor uses a greedy longest-match algorithm to handle overlapping aliases efficiently. For example, if both "a" and "alpha" are valid aliases for the same flag, the input "alpha" will match the longer alias rather than just "a".

      Usage Examples: 

      
 // Given flags: alpha["a", "alfa"], beta["b"], gamma["g", "gam"]
 FlagExtractor<MySource> extractor = command.getFlagExtractor();

 Set<FlagData<MySource>> flags1 = extractor.extract("ab");     // alpha, beta
 Set<FlagData<MySource>> flags2 = extractor.extract("alphag"); // alpha, gamma
 Set<FlagData<MySource>> flags3 = extractor.extract("abx");    // throws UnknownFlagException

      Error Handling: The extractor will throw an UnknownFlagException if the input contains any characters that cannot be matched to known flag aliases.

      Thread Safety: The returned extractor instance is thread-safe for concurrent read operations but should not be used across different command contexts.

      Returns:
      a non-null flag extractor configured for this command's flag definitions
      Throws:
      IllegalStateException - if the command usage has not been properly initialized or if no flag definitions are available
      Since:
      1.9.6
      See Also:

    • hasFlag

      boolean hasFlag(String input)
      Checks whether the raw input is a flag registered by this usage
      Parameters:
      input - the raw input
      Returns:
      Whether the input is a flag and is registered in the usage

    • getFlagParameterFromRaw

      @Nullable @Nullable FlagData<S> getFlagParameterFromRaw(String rawInput)
      Fetches the flag from the input
      Parameters:
      rawInput - the input
      Returns:
      the flag from the raw input, null if it cannot be a flag

    • addFlag

      default void addFlag(CommandParameter<S> flagParam)

    • addFlag

      void addFlag(FlagData<S> flagData)
      Adds a free flag to the usage
      Parameters:
      flagData - adds a free flag to the usage

    • getUsedFreeFlags

      Set<FlagData<S>> getUsedFreeFlags()
      The allowed free flags in this usage.
      Returns:
      the allowed free flags that can be used.

    • addParameters

      void addParameters(CommandParameter<S>... params)
      Adds parameters to the usage
      Parameters:
      params - the parameters to add

    • addParameters

      void addParameters(List<CommandParameter<S>> params)
      Adds parameters to the usage
      Parameters:
      params - the parameters to add

    • getParameters

      List<CommandParameter<S>> getParameters()
      Returns:
      the parameters for this usage
      See Also:

    • getParametersWithoutFlags

      List<CommandParameter<S>> getParametersWithoutFlags()
      Returns:
      the parameters without flags
      See Also:

    • getExamples

      List<String> getExamples()
      The pre-defined syntax examples for this usage.
      Returns:
      the pre-defined examples for this CommandUsage

    • addExample

      void addExample(String example)
      Adds an example to the usage
      Parameters:
      example - the example to add using this usage.

    • addExamples

      default void addExamples(List<String> examples)

    • getParameter

      @Nullable @Nullable CommandParameter<S> getParameter(int index)
      Fetches the parameter at the index
      Parameters:
      index - the index of the parameter
      Returns:
      the parameter at specified index/position

    • getExecution

      @NotNull @NotNull CommandExecution<S> getExecution()
      Returns:
      the execution for this usage

    • mergeWithCommand

      default CommandUsage<S> mergeWithCommand(Command<S> subCommand, CommandUsage<S> usage)
      Creates a new command usage instance to use it to Merge this usage with the usage regarding parameters and takes the targetToLoad's execution as well

      it also includes the subcommand's parameter itself into the command's usage !

      Parameters:
      subCommand - the subcommand owning that usage
      usage - the usage to merge with
      Returns:
      the merged command usage!

    • hasParamType

      boolean hasParamType(Class<?> clazz)
      Parameters:
      clazz - the valueType of the parameter to check upon
      Returns:
      Whether the usage has a specific valueType of parameter

    • getMinLength

      int getMinLength()
      Returns:
      Gets the minimal possible number of parameters that are acceptable to initiate this usage of a command.

    • getMaxLength

      int getMaxLength()
      Returns:
      Gets the maximum possible number of parameters that are acceptable to initiate this usage of a command.

    • hasParameters

      boolean hasParameters(Predicate<CommandParameter<S>> parameterPredicate)
      Searches for a parameter with specific valueType
      Parameters:
      parameterPredicate - the parameter condition
      Returns:
      whether this usage has atLeast on CommandParameter with specific condition or not

    • getParameter

      @Nullable @Nullable CommandParameter<S> getParameter(Predicate<CommandParameter<S>> parameterPredicate)
      Parameters:
      parameterPredicate - the condition
      Returns:
      the parameter to get using a condition

    • getCooldownHandler

      @NotNull @NotNull CooldownHandler<S> getCooldownHandler()
      Returns:
      the cool down handler CooldownHandler

    • setCooldownHandler

      void setCooldownHandler(CooldownHandler<S> cooldownHandler)
      Sets the cooldown handler CooldownHandler
      Parameters:
      cooldownHandler - the cool down handler to set

    • isDefault

      default boolean isDefault()

    • getCoordinator

      CommandCoordinator<S> getCoordinator()
      Returns:
      the coordinator for execution of the command

    • setCoordinator

      void setCoordinator(CommandCoordinator<S> commandCoordinator)
      Sets the command coordinator
      Parameters:
      commandCoordinator - the coordinator to set

    • execute

      void execute(Imperat<S> imperat, S source, ExecutionContext<S> context) throws ImperatException
      Executes the usage's actions using the supplied CommandCoordinator
      Parameters:
      imperat - the api
      source - the command source/sender
      context - the context of the command
      Throws:
      ImperatException

    • isHelp

      boolean isHelp()
      Returns:
      Whether this usage is a help-subcommand usage

    • hasParameters

      boolean hasParameters(List<CommandParameter<S>> parameters)
      Parameters:
      parameters - the parameters
      Returns:
      whether this usage has this sequence of parameters

    • size

      default int size()

    • formatted

      default String formatted()

    • format

      static <S extends Source> String format(@Nullable @Nullable String label, CommandUsage<S> usage)

    • format

      static <S extends Source> String format(@Nullable @Nullable Command<S> command, CommandUsage<S> usage)

    • builder

      static <S extends Source> CommandUsage.Builder<S> builder()