Package studio.mevera.imperat.context.internal

Interface CommandInputStream<S extends Source>

Type Parameters:
S - the type of the command source (e.g., Player, Console, CommandBlock) that initiated the command execution
public interface CommandInputStream<S extends Source>
Represents a stream of command input that provides sequential access to command arguments, parameters, and individual characters. This interface allows for sophisticated navigation and manipulation of command input data with cursor-based positioning.

The CommandInputStream operates on three distinct levels:

  • Character level: Individual character access within the input string
  • Raw input level: Space-separated argument strings
  • Parameter level: Typed command parameters with associated metadata

The stream maintains internal cursors for each level, allowing independent navigation through the input data. This design enables complex parsing scenarios such as:

  • Lookahead parsing without consuming input
  • Backtracking to previous positions
  • Conditional input consumption based on validation
  • Character-by-character parsing for complex argument formats

Usage Example: 


 CommandInputStream<Source> stream = CommandInputStream.of(
     ArgumentInput.of("player", "give", "diamond", "64"),
     detectedUsage
 );

 // Navigate through parameters
 while (stream.isCurrentParameterAvailable()) {
     CommandParameter<Source> param = stream.currentParameterIfPresent();
     String rawValue = stream.currentRawIfPresent();

     // Process parameter...
     stream.skipParameter();
 }

Thread Safety: Implementations of this interface are not guaranteed to be thread-safe. External synchronization is required when accessing the same stream instance from multiple threads concurrently.

Since:
1.0.0
See Also:

  • Method Details

    • position

      @NotNull @NotNull StreamPosition<S> position()
      Retrieves the current cursor position within the input stream. The position object contains cursors for all navigation levels (character, raw input, and parameter).
      Returns:
      the current stream position, never null

    • copy

      CommandInputStream<S> copy()
      Creates a deep copy of this command input stream. The copy maintains independent cursor positions and can be navigated separately from the original stream.

      This method is useful for implementing backtracking parsers or for creating savepoints during complex parsing operations.

      Returns:
      a new CommandInputStream instance that is an independent copy of this stream

    • currentParameterIfPresent

      @Nullable @Nullable CommandParameter<S> currentParameterIfPresent()
      Retrieves the command parameter at the current cursor position without advancing the cursor.
      Returns:
      the current command parameter, or null if the cursor is beyond the end of the parameter list or no parameter exists

    • currentParameter

      @NotNull default @NotNull Optional<CommandParameter<S>> currentParameter()
      Retrieves the command parameter at the current cursor position wrapped in an Optional container.
      Returns:
      an Optional containing the current command parameter, or Optional.empty() if none exists

    • currentRawIfPresent

      @Nullable @Nullable String currentRawIfPresent()
      Retrieves the raw input string at the current cursor position without advancing the cursor.
      Returns:
      the current raw input string, or null if the cursor is beyond the end of the input queue or no input exists

    • currentRaw

      @NotNull default @NotNull Optional<String> currentRaw()
      Retrieves the raw input string at the current cursor position wrapped in an Optional container.
      Returns:
      an Optional containing the current raw input, or Optional.empty() if none exists

    • currentLetterIfPresent

      @Nullable @Nullable Character currentLetterIfPresent()
      Retrieves the character at the current cursor position within the current raw input string without advancing the cursor.
      Returns:
      the current character, or null if the cursor is beyond the end of the current input string or no character exists

    • currentLetter

      @NotNull default @NotNull Optional<Character> currentLetter()
      Retrieves the character at the current cursor position wrapped in an Optional container.
      Returns:
      an Optional containing the current character, or Optional.empty() if none exists

    • peekParameterIfPresent

      @Nullable @Nullable CommandParameter<S> peekParameterIfPresent()
      Peeks at the next command parameter without advancing the cursor. This method allows lookahead parsing to determine the next parameter type without consuming it.
      Returns:
      the next command parameter, or null if no next parameter exists

    • peekParameter

      default Optional<CommandParameter<S>> peekParameter()
      Peeks at the next command parameter wrapped in an Optional container.
      Returns:
      an Optional containing the next command parameter, or Optional.empty() if none exists

    • peekRawIfPresent

      @Nullable @Nullable String peekRawIfPresent()
      Peeks at the next raw input string without advancing the cursor. This method allows lookahead parsing to examine the next input without consuming it.
      Returns:
      the next raw input string, or null if no next input exists

    • peekRaw

      default Optional<String> peekRaw()
      Peeks at the next raw input string wrapped in an Optional container.
      Returns:
      an Optional containing the next raw input, or Optional.empty() if none exists

    • peekLetter

      Optional<Character> peekLetter()
      Peeks at the next character without advancing the cursor. This method allows character-level lookahead parsing.
      Returns:
      an Optional containing the next character, or Optional.empty() if none exists

    • prevParameter

      Optional<CommandParameter<S>> prevParameter()
      Retrieves the previous command parameter without moving the cursor. This method allows backward navigation through the parameter list.
      Returns:
      an Optional containing the previous command parameter, or Optional.empty() if no previous parameter exists

    • prevRaw

      Optional<String> prevRaw()
      Retrieves the previous raw input string without moving the cursor. This method allows backward navigation through the input queue.
      Returns:
      an Optional containing the previous raw input, or Optional.empty() if no previous input exists

    • nextParameter

      @Nullable @Nullable CommandParameter<S> nextParameter()
      Advances the cursor to the next parameter and returns it. This method consumes the parameter and moves the cursor forward.
      Returns:
      the next command parameter, or null if no more parameters exist

    • nextInput

      @Nullable @Nullable String nextInput()
      Advances the cursor to the next raw input and returns it. This method consumes the input and moves the cursor forward.
      Returns:
      the next raw input string, or null if no more input exists

    • popParameter

      Optional<CommandParameter<S>> popParameter()
      Removes and returns the current command parameter while advancing the cursor. This method is equivalent to calling currentParameter() followed by skipParameter().
      Returns:
      an Optional containing the popped command parameter, or Optional.empty() if none exists

    • popRaw

      Optional<String> popRaw()
      Removes and returns the current raw input while advancing the cursor. This method is equivalent to calling currentRaw() followed by skipRaw().
      Returns:
      an Optional containing the popped raw input, or Optional.empty() if none exists

    • popLetter

      Optional<Character> popLetter()
      Removes and returns the current character while advancing the cursor. This method is useful for character-by-character parsing of complex argument formats.
      Returns:
      an Optional containing the popped character, or Optional.empty() if none exists

    • isCurrentParameterAvailable

      boolean isCurrentParameterAvailable()
      Checks if there is a command parameter available at the current cursor position.
      Returns:
      true if current parameter is available, false otherwise

    • isCurrentRawInputAvailable

      boolean isCurrentRawInputAvailable()
      Checks if there is a raw input string available at the current cursor position.
      Returns:
      true if current raw input is available, false otherwise

    • isCurrentLetterAvailable

      boolean isCurrentLetterAvailable()
      Checks if there is a character available at the current cursor position within the current raw input string.
      Returns:
      true if current character is available, false otherwise

    • hasNextParameter

      boolean hasNextParameter()
      Checks if there is a next command parameter available in the stream. This method allows checking for the availability of the next parameter without consuming or peeking at it.
      Returns:
      true if a next command parameter exists, false otherwise

    • hasNextRaw

      boolean hasNextRaw()
      Checks if there is a next raw input string available in the stream. This method allows checking for the availability of the next input without consuming or peeking at it.
      Returns:
      true if a next raw input exists, false otherwise

    • hasNextLetter

      boolean hasNextLetter()
      Checks if there is another character available for reading in the current input string.
      Returns:
      true if a next character exists, false otherwise

    • hasPreviousParameter

      boolean hasPreviousParameter()
      Checks if there is a previous command parameter available in the stream.
      Returns:
      true if a previous command parameter exists, false otherwise

    • hasPreviousRaw

      boolean hasPreviousRaw()
      Checks if there is a previous raw input string available in the stream.
      Returns:
      true if a previous raw input exists, false otherwise

    • skip

      boolean skip()
      Skips the current input element and advances the appropriate cursor. The specific behavior depends on the current stream position and available input types.
      Returns:
      true if the skip operation was successful, false if no input was available to skip

    • skipParameter

      default boolean skipParameter()
      Skips the current command parameter and advances the parameter cursor. This method moves to the next typed parameter in the parameter list.
      Returns:
      true if the skip operation was successful, false if no parameter was available to skip

    • skipRaw

      default boolean skipRaw()
      Skips the current raw input and advances the raw input cursor. This method moves to the next space-separated argument in the input queue.
      Returns:
      true if the skip operation was successful, false if no raw input was available to skip

    • skipLetter

      boolean skipLetter()
      Skips the current character and advances the character cursor. This method is used for character-level navigation within input strings.
      Returns:
      true if the skip operation was successful, false if no character was available to skip

    • currentParameterPosition

      default int currentParameterPosition()
      Retrieves the current position index of the parameter cursor.
      Returns:
      the zero-based index of the current parameter position

    • currentRawPosition

      default int currentRawPosition()
      Retrieves the current position index of the raw input cursor.
      Returns:
      the zero-based index of the current raw input position

    • parametersLength

      default int parametersLength()
      Retrieves the total number of command parameters in the stream.
      Returns:
      the total count of command parameters, always non-negative

    • rawsLength

      default int rawsLength()
      Retrieves the total number of raw input strings in the stream.
      Returns:
      the total count of raw inputs, always non-negative

    • getParametersList

      @NotNull @NotNull List<CommandParameter<S>> getParametersList()
      Retrieves the complete list of command parameters associated with this stream. This provides access to all parameter metadata for validation or processing.
      Returns:
      an immutable List of command parameters, never null

    • getRawQueue

      @NotNull @NotNull ArgumentInput getRawQueue()
      Retrieves the underlying queue containing all raw input strings. This provides access to the complete input data for batch operations or stream analysis.
      Returns:
      the ArgumentInput containing all raw inputs, never null

    • skipTill

      default boolean skipTill(char target)
      Advances the character cursor until the specified target character is encountered. The target character is also consumed (skipped) by this operation.

      This method is useful for parsing delimited strings or finding specific separators within command arguments.

      Parameters:
      target - the character to search for and skip to
      Returns:
      true if the target character was found and reached, false if the end of input was reached without finding the target

    • collectBeforeFirst

      default String collectBeforeFirst(char c)
      Collects and returns all characters before the first occurrence of the specified character. The character cursor is advanced to the position just before the target character. The target character itself is not consumed or included in the result.

      This method is useful for extracting string tokens that are delimited by specific characters.

      Parameters:
      c - the delimiter character to stop collection at
      Returns:
      a string containing all characters collected before the delimiter, or an empty string if the delimiter is immediately encountered or no characters are available

    • readInput

      default String readInput()
      Reads and returns the current raw input without advancing the cursor. This method provides a fail-fast alternative to currentRawIfPresent() when the presence of input is guaranteed.
      Returns:
      the current raw input string, never null
      Throws:
      NoSuchElementException - if no raw input is available at the current position

    • endInput

      default void endInput()

    • exemptParameter

      void exemptParameter(CommandParameter<S> matchingFlagParameter)
      Marks the specified parameter as exempt from normal processing. Exempt parameters are typically flag parameters that have been handled separately from the main argument processing flow.

      This method allows the stream to track which parameters have been processed outside the normal sequential flow, enabling proper validation and error reporting.

      Parameters:
      matchingFlagParameter - the parameter to mark as exempt
      Throws:
      IllegalArgumentException - if matchingFlagParameter is null

    • of

      static <S extends Source> CommandInputStream<S> of(ArgumentInput queue, CommandUsage<S> usage)
      Creates a new CommandInputStream instance with the specified raw arguments and command usage information. The usage information determines how the raw arguments are mapped to typed command parameters.

      This factory method is the primary way to create command input streams from parsed command input and detected command structure.

      Type Parameters:
      S - the type of command source
      Parameters:
      queue - the queue containing all raw argument strings
      usage - the command usage definition that describes expected parameters
      Returns:
      a new CommandInputStream instance initialized with the provided data
      Throws:
      IllegalArgumentException - if queue or usage is null

    • ofSingleString

      static <S extends Source> CommandInputStream<S> ofSingleString(@NotNull @NotNull CommandParameter<S> parameter, @NotNull @NotNull String str)
      Creates a new CommandInputStream with a single string as input. This factory method is useful for creating streams for single-argument parsing or testing scenarios.
      Type Parameters:
      S - the type of command source
      Parameters:
      parameter - the command parameter associated with the input string
      str - the raw input string to be processed
      Returns:
      a new CommandInputStream instance containing the single input
      Throws:
      IllegalArgumentException - if parameter or str is null

    • subStream

      static <S extends Source> CommandInputStream<S> subStream(@NotNull @NotNull CommandInputStream<S> stream, @NotNull @NotNull String input)
      Creates a substream of the specified parent stream with new input content. The substream inherits the current parameter context from the parent stream but operates on the new input string.

      This method is useful for recursive parsing scenarios where a parameter value needs to be parsed as a nested command structure.

      Type Parameters:
      S - the type of command source
      Parameters:
      stream - the parent command input stream to derive context from
      input - the raw input string for the new substream
      Returns:
      a new CommandInputStream instance representing the substream
      Throws:
      NoSuchElementException - if the parent stream has no current parameter available
      IllegalArgumentException - if stream or input is null