Package studio.mevera.imperat.context

Interface ExecutionContext<S extends Source>

Type Parameters:
S - the type of the command source/sender
All Superinterfaces:
Context<S>
@AvailableSince("1.0.0") public interface ExecutionContext<S extends Source> extends Context<S>
Represents the execution context for a command, responsible for resolving and managing command arguments, flags, and their values during command execution.

This interface serves as the bridge between raw command input and executable command logic by:

  • Resolving string inputs into typed values
  • Managing command flags and their values
  • Caching resolved arguments for execution
  • Tracking the command execution path

Each Command maintains its own context, allowing subcommands to have independent argument resolution while preserving the full execution chain.

Since:
1.0.0
See Also:

  • Method Details

    • getPathwaySearch

      @NotNull @NotNull CommandPathSearch<S> getPathwaySearch()
      Fetches the command path search instance used to resolve the command execution path. This provides access to the full command hierarchy leading to the executed command.
      Returns:
      the command path search instance

    • getFlag

      Optional<ExtractedInputFlag> getFlag(String flagName)
      Retrieves a flag by its name if it was provided in the command input.
      Parameters:
      flagName - the name of the flag (without prefix)
      Returns:
      an Optional containing the flag if present, empty otherwise

    • getFlagValue

      @Nullable <T> T getFlagValue(String flagName)
      Gets the resolved value of a command flag.
      Type Parameters:
      T - the type of the flag value
      Parameters:
      flagName - the name of the flag (without prefix)
      Returns:
      the resolved flag value, or null if:
      • The flag is a switch (no value)
      • The flag wasn't provided
      • The value couldn't be resolved

    • getArgument

      @Nullable <T> T getArgument(String name)
      Gets a resolved command argument by its parameter name.
      Type Parameters:
      T - the type of the argument value
      Parameters:
      name - the parameter name defined in the CommandUsage
      Returns:
      the resolved argument value, or null if not provided or couldn't be resolved
      See Also:

    • getArgumentOr

      @NotNull default <T> T getArgumentOr(String name, T value)
      Gets a resolved argument or returns a default value if not present.
      Type Parameters:
      T - the type of the argument value
      Parameters:
      name - the parameter name
      value - the default value to return if argument isn't present
      Returns:
      the resolved argument value or the default value

    • getRawArgument

      default String getRawArgument(int index)
      Gets the raw string input for an argument by its position.
      Parameters:
      index - the zero-based position of the argument in the command input
      Returns:
      the raw argument string, or null if index is out of bounds

    • getResolvedSource

      @NotNull <R> R getResolvedSource(Type type) throws ImperatException
      Resolves the command source into a different type using the configured source resolver.
      Type Parameters:
      R - the target type to resolve to
      Parameters:
      type - the target type class
      Returns:
      the resolved source, never null
      Throws:
      ImperatException - if resolution fails
      See Also:

    • getContextResolvedArgument

      @Nullable <T> T getContextResolvedArgument(Class<T> type) throws ImperatException
      Gets an argument resolved by the context resolver system.
      Type Parameters:
      T - the type of the argument
      Parameters:
      type - the class of the argument type
      Returns:
      the resolved argument value, or null if not resolvable
      Throws:
      ImperatException - if resolution fails
      See Also:

    • getResolvedFlags

      Collection<? extends ExtractedInputFlag> getResolvedFlags()
      Gets all flags that were resolved from the command input.
      Returns:
      a collection of resolved flags

    • resolveArgument

      <T> void resolveArgument(Command<S> command, @Nullable @Nullable String raw, int index, CommandParameter<S> parameter, @Nullable T value) throws ImperatException
      Resolves and registers a command argument.
      Type Parameters:
      T - the type of the argument value
      Parameters:
      command - the owning command
      raw - the raw input string
      index - the argument position
      parameter - the parameter definition
      value - the resolved value
      Throws:
      ImperatException - if resolution fails

    • resolveArgument

      default <T> void resolveArgument(CommandInputStream<S> stream, @Nullable T value) throws ImperatException
      Resolves and registers a command argument.
      Type Parameters:
      T - the type of the argument value
      Parameters:
      stream - the stream having the current input's data.
      value - the resolved value.
      Throws:
      ImperatException - if resolution fails.

    • resolveFlag

      default void resolveFlag(FlagData<S> flagDetected, String flagRaw, @Nullable @Nullable String flagInputRaw, @Nullable @Nullable Object flagInputValue)
      Resolves a command flag from its raw components.
      Parameters:
      flagDetected - the flag parameter definition
      flagRaw - the raw flag string (including prefix)
      flagInputRaw - the raw flag value (may be null for switches)
      flagInputValue - the resolved flag value

    • resolveFlag

      void resolveFlag(ExtractedInputFlag flag)
      Registers a resolved flag in the context.
      Parameters:
      flag - the resolved flag to register

    • getLastUsedCommand

      Command<S> getLastUsedCommand()
      Gets the most specific command that was resolved in this context.
      Returns:
      the terminal command that will be executed

    • getDetectedUsage

      CommandUsage<S> getDetectedUsage()
      Gets the command usage pattern that matched the input.
      Returns:
      the detected command usage

    • resolve

      void resolve() throws ImperatException
      Resolves all arguments and flags from the raw context input.
      Throws:
      ImperatException - if resolution fails

    • getResolvedArgument

      @Nullable @Nullable Argument<S> getResolvedArgument(Command<S> command, String name)
      Gets a resolved argument by its owning command and parameter name.
      Parameters:
      command - the owning command
      name - the parameter name
      Returns:
      the resolved argument, or null if not present

    • getResolvedArguments

      List<Argument<S>> getResolvedArguments(Command<S> command)
      Gets all resolved arguments for a specific command.
      Parameters:
      command - the owning command
      Returns:
      a list of resolved arguments in declaration order

    • getCommandsUsed

      @NotNull @NotNull Iterable<? extends Command<S>> getCommandsUsed()
      Gets all commands in the resolution path.
      Returns:
      an iterable of all commands from root to terminal command

    • getResolvedArguments

      Collection<? extends Argument<S>> getResolvedArguments()
      Gets all resolved arguments in input order.
      Returns:
      a collection of arguments in the order they appeared in the input

    • hasResolvedFlag

      default boolean hasResolvedFlag(CommandParameter<S> currentParameter)
      Checks if a flag parameter was resolved in this context.
      Parameters:
      currentParameter - the flag parameter to check
      Returns:
      true if the flag was provided and resolved

    • hasResolvedFlag

      boolean hasResolvedFlag(FlagData<S> flagData)
      Checks if a flag was resolved in this context.
      Parameters:
      flagData - the flag definition to check
      Returns:
      true if the flag was provided and resolved

    • debug

      void debug()
      Debugs the current resolved arguments cached/mapped.
      This requires ImperatDebugger to be enabled.
      Example: ImperatDebugger.setEnabled(true)