Package dev.sympho.modular_commands.execute

Class PipelineBuilder<E extends Event,CTX extends CommandContext & LazyContext,H extends Handlers,I extends SmartIterator<String>>

java.lang.Object
dev.sympho.modular_commands.execute.PipelineBuilder<E,CTX,H,I>
Type Parameters:
E - The type of event that triggers commands.
CTX - The type of command context.
H - The type of handlers.
I - The iterator type used to traverse the received arguments.
public abstract class PipelineBuilder<E extends Event,CTX extends CommandContext & LazyContext,H extends Handlers,I extends SmartIterator<String>> extends Object
Type responsible for building a command processing pipeline.
Since:
1.0
Version:
1.0
API Note:
Note that, for the purposes of this class, there is a distinction between args and arguments:
  • args is the raw sequence of strings provided by the triggering event that identifies the command to execute. It may or may not also contain, after the command identifiers, strings that should be parsed into command arguments.
  • arguments are the values that satisfy the defined parameters of a command. They may be obtain from args that appear after the command identification, or directly from the event in some way (or both).

  • Field Details

    • accessManager

      protected final AccessManager accessManager
      The access manager to use for access checks.

  • Constructor Details

    • PipelineBuilder

      protected PipelineBuilder(AccessManager accessManager)
      Creates a new instance.
      Parameters:
      accessManager - The access manager to use for access checks.

  • Method Details

    • buildPipeline

      public Mono<Void> buildPipeline(GatewayDiscordClient client, Registry registry)
      Builds a new pipeline with the given client and registry.
      Parameters:
      client - The client to receive events from.
      registry - The registry to use to look up commands.
      Returns:
      The built processing pipeline.

    • eventType

      @Pure protected abstract Class<E> eventType()
      Retrieves the event type to listen for.
      Returns:
      The event type.

    • commandType

      @Pure protected abstract Class<H> commandType()
      Retrives the command type to use.
      Returns:
      The command type.

    • fullMatch

      @Pure protected abstract boolean fullMatch()
      Determines whether a parsed arg list (as given by parse(Event)) must always be fully matched to a command. If true, the presence of leftover args (as would be received by makeContext(Event, Command, Invocation, SmartIterator)) triggers an error for that event (stopping the processing of that particular event, but without stopping the pipeline).
      Returns:
      true if the parsed args must be fully matched to a command. false if additional args are allowed.
      API Note:
      This check is not related to any user-facing functionality, but purely as an internal sanity check. If an event provides arguments in a way other than the parsed args, with said args being used only to identify the command to execute, it would not make sense for extra args to be received.

      For example, in a slash command, the comand name is provided separately from the arguments, and any subcommands are already labeled as such, so there is no need to evaluate any further args when looking up the command. At the same time, since slash commands (including subcommands) have to be registered with Discord ahead of time to be callable by users, the only way that a slash command event would provide a subcommand that is not found is if the command was registered to Discord without having a corresponding internal handler, without would indicate an inconsistency in the command system (the declared commands do not match the implemented commands), which should be reported to the administrator as a (non-fatal) pipeline error.

    • eventFilter

      @Pure protected boolean eventFilter(E event)
      Determines if an event should be processed for commands. This filter is applied at the start of handling, before any parsing is performed.
      Parameters:
      event - The event to check.
      Returns:
      true if the event should be processed. false if the event should be discarded.
      Implementation Requirements:
      The default is to process all received events.

    • getValidator

      @Pure protected abstract InvocationValidator<E> getValidator()
      Retrieves the validator to use for validating command invocations.

      For performance reasons, the validator should be implemented statelessly, with a single instance being created by the implenting builder which is then returned every time. This avoids the cost of constructing a new instance every time.

      Note that there is no reason why a validator implementation would need to keep state, as it is intended to be a simple filter.

      Returns:
      The validator to use.

    • parse

      @SideEffectFree protected abstract I parse(E event)
      Parses the raw args from the event. This includes the names that identify the command and subcommands, as well as any additional args, if allowed.
      Parameters:
      event - The event to parse args from.
      Returns:
      The parsed args. May have no elements if the event should not be handled as a command.

    • makeContext

      @SideEffectFree protected abstract CTX makeContext(E event, Command<? extends H> command, Invocation invocation, I args)
      Creates a command context from a parsed invocation.
      Parameters:
      event - The event being processed.
      command - The identified command.
      invocation - The invocation that mapped to the command. This may be different from the command's declared Command.invocation() if it was invoked using an alias (when supported).
      args - The args that remained after removing the command identifiers. If fullMatch() is true, this will always be empty.
      Returns:
      The context that represents the given invocation.

    • getGuildId

      @SideEffectFree protected abstract Optional<Snowflake> getGuildId(E event)
      Retrieves the ID of the guild where the command was invoked, if any, from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The ID of the guild where the event was invoked.

    • getGuild

      @SideEffectFree protected abstract Mono<Guild> getGuild(E event)
      Retrieves the guild where the command was invoked, if any, from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The guild where the event was invoked.

    • getChannel

      @SideEffectFree protected abstract Mono<MessageChannel> getChannel(E event)
      Retrieves the channel where the command was invoked from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The channel where the event was invoked.

    • getCaller

      @SideEffectFree protected abstract User getCaller(E event)
      Retrieves the user that invoked the command from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The user that invoked the command.

    • accessValidator

      @SideEffectFree protected AccessValidator accessValidator(E event)
      Creates an access validator for the context of the given event.
      Parameters:
      event - The triggering event.
      Returns:
      The access validator.

    • getInvocationHandler

      @Pure protected abstract InvocationHandler<? super CTX> getInvocationHandler(H handlers)
      Retrieves the invocation handler specified by the given hander set.
      Parameters:
      handlers - The handler set.
      Returns:
      The invocation handler.

    • getResultHandlers

      @Pure protected abstract List<? extends ResultHandler<? super CTX>> getResultHandlers(H handlers)
      Retrieves the result handlers specified by the given hander set.
      Parameters:
      handlers - The handler set.
      Returns:
      The result handlers.