Package com.j3d.engine.interact.cmd

Class CommandParser

java.lang.Object
com.j3d.engine.interact.cmd.CommandParser
public class CommandParser extends Object
A parser for the command palette that handles tokenisation, argument parsing, command execution, and command history.

It supports various argument types including strings, vectors, colours, UUIDs, numbers, and booleans. It also integrates with CommandsManager for command lookup and execution, and RunHistory for command history management.

Author:
Lehlogonolo Poole
See Also:

  • Field Details

    • arguments

      private final ArrayList<Object> arguments
      Collected argument objects for the current command invocation. Elements may be instances of String, UUID, Vector3, Color, GObject, Thing, or other types produced by argument parsing.

    • taggedArguments

      private final ArrayList<TaggedArgValue<?>> taggedArguments
      Collected tagged argument values for the current command invocation.

    • ignoreDocumentEvent

      private boolean ignoreDocumentEvent
      When true, document events coming from the input field are ignored. This is used to prevent re-entrant parsing when the parser programmatically updates the field.

    • commandPalette

      public final CommandPalette commandPalette
      The UI command palette that supplies input and receives feedback from this parser.

    • label

      private final SafeJLabel label
      Helper label wrapper used to show parsing/execution messages to the user.

    • commandPaletteBinds

      public final KeyBindings commandPaletteBinds
      Key bindings for the command palette's input field.

    • runHistory

      public final RunHistory runHistory
      Manages the history of executed commands.

    • typingHints

      private final TypingHints typingHints
      Provides typing hints and tab completion suggestions.

    • tokens

      private final ArrayList<CmdToken> tokens
      A list of CmdToken objects representing the parsed input line.

  • Constructor Details

    • CommandParser

      public CommandParser(CommandPalette p)
      Create a new CommandParser bound to the given CommandPalette.

      It registers key bindings for command execution, tab completion, and history navigation. It also sets up a DocumentListener to reparse the input line as the user types.

      Parameters:
      p - the CommandPalette instance this parser should use for input and output

  • Method Details

    • enable

      public void enable()
      Enable the command input field and apply the 'active' background styling.

      This makes the input field editable and darkens its background to indicate focus/availability.

    • disable

      public void disable()
      Disable the command input field and restore the default background styling.

      This prevents user input and brightens the field background to indicate it is inactive.

    • setInputField

      public void setInputField(String input)
      Sets the text of the command palette's input field and triggers a re-parsing of the line. This method temporarily ignores document events to prevent re-entrant parsing.
      Parameters:
      input - The string to set as the input field's text.

    • reParseLine

      private void reParseLine()
      Reparses the current line in the command palette's input field. This method clears existing tokens and arguments, then re-tokenises and reparses the input.

    • injectArgument

      public void injectArgument(Object obj)
      Injects an object as an argument into the command palette's input field. This method converts the object into its command palette string representation and appends it to the input.
      Parameters:
      obj - The object to inject as an argument. Supported types include Vector3, GObject, Thing, Color, String, Integer, Double, and Boolean.

    • inject

      private void inject(String t)
      Appends the given string to the command palette's input field, followed by a space. This method is used internally to update the input field when arguments are programmatically injected.
      Parameters:
      t - The string to inject into the input field.

    • colourToCommandPaletteString

      public static String colourToCommandPaletteString(Color col)
      Convert a Color into the textual representation used by the command palette (format: #R:G:B:A#).
      Parameters:
      col - the colour to convert
      Returns:
      a string in the palette colour format, including surrounding '#'

    • argAddUUID

      private void argAddUUID(CmdToken tok, UUID uuid, boolean injected)
      Attempts to finder a GObject or Thing with the given UUID and adds it to the arguments list.

      This will be used by the command parser to convert UUID strings into actual objects when parsing command arguments.

      Parameters:
      uuid - The UUID of the GObject or Thing to finder.

    • addArg

      private void addArg(CmdToken cmdToken, Object arg, CmdToken.Type t, boolean injected)
      Adds an argument to the internal list of arguments and updates the command palette's input field if the argument was "injected" (i.e., programmatically added rather than typed by the user).
      Parameters:
      cmdToken - The CmdToken representing the argument.
      arg - The parsed argument object.
      t - The CmdToken.Type of the argument.
      injected - A boolean indicating whether the argument was injected programmatically. If true, the argument's string representation will be appended to the input field.

    • parse

      private void parse(CmdToken token)
      Parses a single command token, attempting to convert its string representation into a specific object type (String, Vector3, Colour, UUID-referenced object, number, boolean, or tagged argument). The parsed object is then added to the arguments or taggedArguments list.
      Parameters:
      token - The CmdToken to parse.

    • parseAsNumberOrBool

      private void parseAsNumberOrBool(CmdToken token, String accumulator, Consumer<String> otherwise)
      Attempt to parse the given token as an integer or double and add the resulting number to arguments. If parsing as a number fails, the provided otherwise consumer is invoked with the original token.
      Parameters:
      token - the token to parse
      accumulator - the token to parse
      otherwise - a fallback consumer called when the token is not numeric

    • isEmpty

      public boolean isEmpty()
      Checks if the command parser currently has no tokens.
      Returns:
      true if the tokens list is empty, false otherwise.

    • run

      private void run()
      Execute the parsed command using the collected arguments.

      The first argument is expected to be the command name (a String). The parser will resolve the command via CommandsManager.getCommand(String), check for any currently running stateful command, and if applicable mark the resolved command as the current stateful command before invoking its run method.

    • run

      public boolean run(Command cmd, ArrayList<Object> arguments, ArrayList<TaggedArgValue<?>> taggedArguments)
      Calls a specific command. This is the default run method for anything which is labelled as invoked by the engine
      Parameters:
      cmd - The command to run
      arguments - The arguments to pass to the command
      taggedArguments - The tagged arguments to pass to the command
      Returns:
      true if the command was run successfully, false otherwise

    • run

      public boolean run(Command cmd, ArrayList<Object> arguments, ArrayList<TaggedArgValue<?>> taggedArguments, Command caller)
      Calls a specific command wit an extra note labelling that it was called by some other command's invocation. This is different from a command calling it's own subcommand as that uses Invoker.byParentCommand(Command) whereas this uses Invoker.byCommandCall(Command)
      Parameters:
      cmd - The command to run
      arguments - The arguments to pass to the command
      taggedArguments - The tagged arguments to pass to the command
      caller - The command that is invoking this command.
      Returns:
      true if the command was run successfully, false otherwise

    • runMacro

      public boolean runMacro(Command cmd, ArrayList<Object> arguments, ArrayList<TaggedArgValue<?>> taggedArguments)

    • runCommand

      private boolean runCommand(Command cmd, String cmdName, ArrayList<Object> arguments, ArrayList<TaggedArgValue<?>> taggedArguments, Invoker invoker)

    • parseColor

      private Color parseColor(String input)
      Parse a colour specification string into a Color.

      Supported formats:

      • R:G:B:A (four integers separated by colons)
      • R:G:B (three integers separated by colons)
      • Hex string parseable by Color.decode(String)
      Parameters:
      input - the colour string (without surrounding hashes)
      Returns:
      a Color instance if parsing succeeds, or null on failure

    • safeJLabel

      public SafeJLabel safeJLabel()
      Returns the SafeJLabel instance used by this parser to display messages.
      Returns:
      the SafeJLabel instance

    • getTypingHintSession

      public TypingHints getTypingHintSession()
      Returns the TypingHints instance associated with this parser.
      Returns:
      the TypingHints instance

    • caretAtEnd

      public boolean caretAtEnd()
      Checks if the caret in the command palette's input field is at the end of the text.
      Returns:
      true if the caret is at the end, false otherwise

    • getCommandPaletteKeyBinds

      public KeyBindings getCommandPaletteKeyBinds()
      Returns the KeyBindings instance used for the command palette.
      Returns:
      the KeyBindings instance

    • getTokens

      public ArrayList<CmdToken> getTokens()

    • getTaggedArguments

      public ArrayList<TaggedArgValue<?>> getTaggedArguments()

    • registerKeys

      private void registerKeys()
      Registers the following keybinds: