Package studio.mevera.imperat.context.internal

Interface Cursor<S extends CommandSource>

Type Parameters:
S - the type of the command source (e.g., Player, Console, CommandBlock) that initiated the command execution
public interface Cursor<S extends CommandSource>
Represents a cursor 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 Cursor 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 cursor 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: 


 Cursor<CommandSource> cursor = Cursor.of(
     ArgumentInput.of("player", "give", "diamond", "64"),
     detectedUsage
 );

 // Navigate through parameters
 while (cursor.isCurrentParameterAvailable()) {
     Argument<CommandSource> param = cursor.currentParameterIfPresent();
     String rawValue = cursor.currentRawIfPresent();

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

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

Since:
1.0.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default String
    collectBeforeFirst(char c)
    Collects and returns all characters before the first occurrence of the specified character.
    String
    collectRawArguments(int count)
    Collect a specific number of raw arguments
    String
    collectRemainingRaw()
    Collects and returns the remaining raw input strings from the current cursor position to the end of the input queue.
    Cursor<S>
    copy()
    Creates a deep copy of this command input cursor.
    default @NotNull Optional<Character>
    currentLetter()
    Retrieves the character at the current cursor position wrapped in an Optional container.
    @Nullable Character
    currentLetterIfPresent()
    Retrieves the character at the current cursor position within the current raw input string without advancing the cursor.
    default @NotNull Optional<Argument<S>>
    currentParameter()
    Retrieves the command parameter at the current cursor position wrapped in an Optional container.
    @Nullable Argument<S>
    currentParameterIfPresent()
    Retrieves the command parameter at the current cursor position without advancing the cursor.
    default int
    currentParameterPosition()
    Retrieves the current position index of the parameter cursor.
    default @NotNull Optional<String>
    currentRaw()
    Retrieves the raw input string at the current cursor position wrapped in an Optional container.
    @Nullable String
    currentRawIfPresent()
    Retrieves the raw input string at the current cursor position without advancing the cursor.
    default int
    currentRawPosition()
    Retrieves the current position index of the raw input cursor.
    default void
    endInput()
     
    void
    exemptParameter(Argument<S> matchingFlagParameter)
    Marks the specified parameter as exempt from normal processing.
    @NotNull List<Argument<S>>
    getParametersList()
    Retrieves the complete list of command parameters associated with this cursor.
    @NotNull ArgumentInput
    getRawQueue()
    Retrieves the underlying queue containing all raw input strings.
    default boolean
    hasFinished()
     
    boolean
    hasNextLetter()
    Checks if there is another character available for reading in the current input string.
    boolean
    hasNextParameter()
    Checks if there is a next command parameter available in the cursor.
    boolean
    hasNextRaw()
    Checks if there is a next raw input string available in the cursor.
    boolean
    hasPreviousParameter()
    Checks if there is a previous command parameter available in the cursor.
    boolean
    hasPreviousRaw()
    Checks if there is a previous raw input string available in the cursor.
    boolean
    isCurrentLetterAvailable()
    Checks if there is a character available at the current cursor position within the current raw input string.
    boolean
    isCurrentParameterAvailable()
    Checks if there is a command parameter available at the current cursor position.
    boolean
    isCurrentRawInputAvailable()
    Checks if there is a raw input string available at the current cursor position.
    @Nullable String
    nextInput()
    Advances the cursor to the next raw input and returns it.
    @Nullable Argument<S>
    nextParameter()
    Advances the cursor to the next parameter and returns it.
    static <S extends CommandSource>
    Cursor<S>
    of(ArgumentInput queue, CommandPathway<S> pathway)
    Creates a new Cursor instance with the specified raw arguments and command pathway information.
    static <S extends CommandSource>
    Cursor<S>
    ofSingleString(@NotNull Argument<S> parameter, @NotNull String str)
    Creates a new Cursor with a single string as input.
    default int
    parametersLength()
    Retrieves the total number of command parameters in the cursor.
    Optional<Character>
    peekLetter()
    Peeks at the next character without advancing the cursor.
    default Optional<Argument<S>>
    peekParameter()
    Peeks at the next command parameter wrapped in an Optional container.
    @Nullable Argument<S>
    peekParameterIfPresent()
    Peeks at the next command parameter without advancing the cursor.
    default Optional<String>
    peekRaw()
    Peeks at the next raw input string wrapped in an Optional container.
    @Nullable String
    peekRawIfPresent()
    Peeks at the next raw input string without advancing the cursor.
    Optional<Character>
    popLetter()
    Removes and returns the current character while advancing the cursor.
    Optional<Argument<S>>
    popParameter()
    Removes and returns the current command parameter while advancing the cursor.
    Optional<String>
    popRaw()
    Removes and returns the current raw input while advancing the cursor.
    @NotNull CursorPosition<S>
    position()
    Retrieves the current cursor position within the input cursor.
    Optional<Argument<S>>
    prevParameter()
    Retrieves the previous command parameter without moving the cursor.
    Optional<String>
    prevRaw()
    Retrieves the previous raw input string without moving the cursor.
    default int
    rawsLength()
    Retrieves the total number of raw input strings in the cursor.
    default String
    readInput()
    Reads and returns the current raw input without advancing the cursor.
    void
    setAt(Cursor<S> cursorCopy)
     
    boolean
    skip()
    Skips the current input element and advances the appropriate cursor.
    boolean
    skipLetter()
    Skips the current character and advances the character cursor.
    default boolean
    skipParameter()
    Skips the current command parameter and advances the parameter cursor.
    default boolean
    skipRaw()
    Skips the current raw input and advances the raw input cursor.
    default boolean
    skipTill(char target)
    Advances the character cursor until the specified target character is encountered.
    static <S extends CommandSource>
    Cursor<S>
    subCursor(@NotNull Cursor<S> cursor, @NotNull String input)
    Creates a subcursor of the specified parent cursor with new input content.

  • Method Details

    • of

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

      This factory method is the primary way to create command input cursors 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
      pathway - the command pathway definition that describes expected parameters
      Returns:
      a new Cursor instance initialized with the provided data
      Throws:
      IllegalArgumentException - if queue or pathway is null

    • ofSingleString

      static <S extends CommandSource> Cursor<S> ofSingleString(@NotNull @NotNull Argument<S> parameter, @NotNull @NotNull String str)
      Creates a new Cursor with a single string as input. This factory method is useful for creating cursors 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 Cursor instance containing the single input
      Throws:
      IllegalArgumentException - if parameter or str is null

    • subCursor

      static <S extends CommandSource> Cursor<S> subCursor(@NotNull @NotNull Cursor<S> cursor, @NotNull @NotNull String input)
      Creates a subcursor of the specified parent cursor with new input content. The subcursor inherits the current parameter context from the parent cursor 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:
      cursor - the parent command input cursor to derive context from
      input - the raw input string for the new subcursor
      Returns:
      a new Cursor instance representing the subcursor
      Throws:
      NoSuchElementException - if the parent cursor has no current parameter available
      IllegalArgumentException - if cursor or input is null

    • position

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

    • copy

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

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

      Returns:
      a new Cursor instance that is an independent copy of this cursor

    • currentParameterIfPresent

      @Nullable @Nullable Argument<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<Argument<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 Argument<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<Argument<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<Argument<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 Argument<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<Argument<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 cursor. 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 cursor. 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 cursor.
      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 cursor.
      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 cursor 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 cursor.
      Returns:
      the total count of command parameters, always non-negative

    • rawsLength

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

    • getParametersList

      @NotNull @NotNull List<Argument<S>> getParametersList()
      Retrieves the complete list of command parameters associated with this cursor. 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 cursor 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()

    • collectRemainingRaw

      String collectRemainingRaw()
      Collects and returns the remaining raw input strings from the current cursor position to the end of the input queue. The raw input cursor is advanced to the end of the queue after this operation.
      Returns:
      a string containing all remaining raw inputs concatenated with spaces, or an empty string if no remaining input exists

    • collectRawArguments

      String collectRawArguments(int count)
      Collect a specific number of raw arguments
      Parameters:
      count - the number of raw input args to collect
      Returns:
      A string separating the collected args by space.

    • exemptParameter

      void exemptParameter(Argument<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 cursor 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

    • hasFinished

      default boolean hasFinished()

    • setAt

      void setAt(Cursor<S> cursorCopy)