Package dev.sympho.modular_commands.api.command.context

Interface CommandContext

All Superinterfaces:
AccessValidator
All Known Subinterfaces:
InstrumentedContext, InteractionCommandContext, LazyContext, MessageCommandContext, SlashCommandContext
All Known Implementing Classes:
MessageContextImpl
public interface CommandContext extends AccessValidator
The execution context of an invoked command.
Since:
1.0
Version:
1.0

  • Method Details

    • getEvent

      @Pure Event getEvent()
      Retrieves the event that triggered the command.
      Returns:
      The trigger event.

    • getClient

      @Pure default GatewayDiscordClient getClient()
      Retrieves the client where the command was received.
      Returns:
      The client.

    • getInvocation

      @Pure Invocation getInvocation()
      Retrieves the invocation that triggered the command.

      Unlike getCommandInvocation(), the returned value may be different from the command's declared Command.invocation() if it was invoked using an alias (when supported).

      If the command has no aliases, or was invoked through a method that does not support aliases, the return of this method is the same as the return of getCommandInvocation().

      Returns:
      The trigger invocation.

    • getCommandInvocation

      @Pure Invocation getCommandInvocation()
      Retrieves the canonical invocation of the triggered command, that is, the value of Command.invocation(). This is equivalent to the triggering invocation after resolving any aliases.

      If the command has no aliases, or was invoked through a method that does not support aliases, the return of this method is the same as the return of getInvocation().

      Returns:
      The normalized trigger invocation.

    • getCaller

      @Pure User getCaller()
      Retrieves the user that called the command.
      Returns:
      The calling user.

    • getCallerMember

      @Pure @Nullable Member getCallerMember()
      Retrieves the user that called the command as a guild member as provided by the triggering event, if present.
      Returns:
      The calling user as a guild member, or null if the command was invoked in a private channel.

    • getChannel

      Mono<MessageChannel> getChannel()
      Retrieves the channel that the command was invoked in.
      Returns:
      The invoking channel.

    • getChannelId

      @Pure Snowflake getChannelId()
      Retrieves the ID of the channel that the command was invoked in.
      Returns:
      The invoking channel's ID.

    • getGuild

      Mono<Guild> getGuild()
      Retrieves the guild that the command was invoked in, if there is one.
      Returns:
      The invoking guild.

    • getGuildId

      @Pure @Nullable Snowflake getGuildId()
      Retrieves the ID of the guild that the command was invoked in, if there is one.
      Returns:
      The invoking guild's ID, or null if the command was invoked in a private channel.

    • isPrivate

      @Pure default boolean isPrivate()
      Determines if the invocation ocurred in a private channel.
      Returns:
      Whether the invocation was made from a private channel.

    • getArgument

      @Pure <T extends @NonNull Object> @Nullable T getArgument(String name, Class<T> argumentType) throws IllegalArgumentException, ClassCastException
      Retrieves one of the arguments to the command.
      Type Parameters:
      T - The type of the argument.
      Parameters:
      name - The name of the corresponding parameter.
      argumentType - The type of the argument.
      Returns:
      The argument value, or null if the received argument is empty (omitted by the caller or an empty parsing result) and does not have a default value.
      Throws:
      IllegalArgumentException - if there is no parameter with the given name.
      ClassCastException - if the given argument type does not match the type of the argument with the given name.
      See Also:
      API Note:
      This method will never return null if the parameter provides a default value. If it is marked as required, it will return null if and only if the parser result was empty (which implies that it will never return null if the parser is guaranteed to never give an empty result).

    • getArgument

      @Pure default <T extends @NonNull Object> @Nullable T getArgument(Parameter<? extends T> parameter, Class<T> argumentType) throws IllegalArgumentException, ClassCastException
      Retrieves one of the arguments to the command.
      Type Parameters:
      T - The type of the argument.
      Parameters:
      parameter - The corresponding parameter.
      argumentType - The type of the argument.
      Returns:
      The argument value, or null if the received argument is empty (omitted by the caller or an empty parsing result) and does not have a default value.
      Throws:
      IllegalArgumentException - if there is no parameter with a matching name.
      ClassCastException - if the given argument type does not match the type of the argument with the given name.
      See Also:
      API Note:
      This is functionally equivalent to getArgument(String, Class), but allows access directly from the parameter instance and provides compile-time type checking.

    • getArgument

      @Pure <T extends @NonNull Object> @Nullable T getArgument(Parameter<? extends T> parameter) throws IllegalArgumentException
      Retrieves one of the arguments to the command.
      Type Parameters:
      T - The type of the argument.
      Parameters:
      parameter - The corresponding parameter.
      Returns:
      The argument value, or null if the received argument is empty (omitted by the caller or an empty parsing result) and does not have a default value.
      Throws:
      IllegalArgumentException - if the given parameter is not present in the invoked command.
      API Note:
      This is functionally equivalent to getArgument(Parameter, Class). However, it has a stronger requirement on the parameter argument in that it must be the same instance (i.e., according to ==) that was used to define the parameter in the original command, instead of just needing to match the name. This is necessary as the lack of the class parameter means there is no other way to ensure type safety. On the other hand, this variant makes it possible to use arguments that have their own type parameters in a type-safe manner.

    • requireArgument

      @Pure default <T extends @NonNull Object> T requireArgument(String name, Class<T> argumentType) throws IllegalArgumentException, ClassCastException, NullPointerException
      Retrieves one of the arguments to the command expecting that it is non-null, i.e. that it either has a default value or is never empty (is required and the parser never has an empty result).
      Type Parameters:
      T - The type of the argument.
      Parameters:
      name - The name of the corresponding parameter.
      argumentType - The type of the argument.
      Returns:
      The argument value.
      Throws:
      IllegalArgumentException - if there is no parameter with the given name.
      ClassCastException - if the given argument type does not match the type of the argument with the given name.
      NullPointerException - if the argument was empty (not received or empty parsing result) and does not have a default value.
      See Also:
      API Note:
      An NPE thrown by this method indicates either a mismatched configuration (code expects the parameter to be required or default but it was not configured as such) or that the parser function unexpectedly returned an empty result.

    • requireArgument

      @Pure default <T extends @NonNull Object> T requireArgument(Parameter<? extends T> parameter, Class<T> argumentType) throws IllegalArgumentException, ClassCastException, NullPointerException
      Retrieves one of the arguments to the command expecting that it is non-null, i.e. that it either has a default value or is never empty (is required and the parser never has an empty result).
      Type Parameters:
      T - The type of the argument.
      Parameters:
      parameter - The name of the corresponding parameter.
      argumentType - The type of the argument.
      Returns:
      The argument value.
      Throws:
      IllegalArgumentException - if there is no parameter with the given name.
      ClassCastException - if the given argument type does not match the type of the argument with the given name.
      NullPointerException - if the argument was empty (not received or empty parsing result) and does not have a default value.
      See Also:
      API Note:
      This is functionally equivalent to requireArgument(String, Class), but allows access directly from the parameter instance and provides compile-time type checking.

    • requireArgument

      @Pure default <T extends @NonNull Object> T requireArgument(Parameter<? extends T> parameter) throws IllegalArgumentException, NullPointerException
      Retrieves one of the arguments to the command expecting that it is non-null, i.e. that it either has a default value or is never empty (is required and the parser never has an empty result).
      Type Parameters:
      T - The type of the argument.
      Parameters:
      parameter - The name of the corresponding parameter.
      Returns:
      The argument value.
      Throws:
      IllegalArgumentException - if the given parameter is not present in the invoked command.
      NullPointerException - if the argument was not received and does not have a default value.
      API Note:
      This is functionally equivalent to requireArgument(Parameter, Class). However, it has a stronger requirement on the parameter argument in that it must be the same instance (i.e., according to ==) that was used to define the parameter in the original command, instead of just needing to match the name. This is necessary as the lack of the class parameter means there is no other way to ensure type safety. On the other hand, this variant makes it possible to use arguments that have their own type parameters in a type-safe manner.

    • setContext

      boolean setContext(String key, @Nullable Object obj, boolean replace)
      Places a context object for subsequent handlers, optionally replacing any existing values under the same key.
      Parameters:
      key - The object key.
      obj - The object to store.
      replace - If true, the object will be placed unconditionally, replacing any existing value in that key. Otherwise, it will only be placed if there are no values with the given key.
      Returns:
      true if the given object was placed in the context. If replace is false and there is already an object at the given key, returns false.
      API Note:
      This method is not thread-safe.

    • setContext

      default void setContext(String key, @Nullable Object obj)
      Unconditionally places a context object for subsequent handlers.
      Parameters:
      key - The object key.
      obj - The object to store.
      See Also:
      API Note:
      This method is equivalent to setContext(key, obj, true).

    • getContext

      @Pure <T> @Nullable T getContext(String key, Class<? extends T> type) throws IllegalArgumentException, ClassCastException
      Retrieves a context object set by setContext(String, Object, boolean).
      Type Parameters:
      T - The type of the object.
      Parameters:
      key - The object key.
      type - The object class.
      Returns:
      The context object.
      Throws:
      IllegalArgumentException - if there is no context object with the given key.
      ClassCastException - if the context object with the given key is not compatible with the given type (not the same or a subtype).

    • requireContext

      @Pure default <T> T requireContext(String key, Class<? extends T> type) throws IllegalArgumentException, ClassCastException, NullPointerException
      Retrieves a non-null context object set by setContext(String, Object, boolean).
      Type Parameters:
      T - The type of the object.
      Parameters:
      key - The object key.
      type - The object class.
      Returns:
      The context object.
      Throws:
      IllegalArgumentException - If there is no context object with the given key.
      ClassCastException - if the context object with the given key is not compatible with the given type (not the same or a subtype).
      NullPointerException - if the context object was null.

    • replies

      @SideEffectFree ReplyManager replies()
      Retrieves the reply manager for this instance.

      Note that calling ReplyManager.longTerm() on the returned manager will cause this method to also return the long-term manager from that point on.

      Returns:
      The reply manager.

    • reply

      default Mono<Reply> reply(String content)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      content - The message content.
      Returns:
      The sent reply.
      See Also:

    • reply

      default Mono<Reply> reply(EmbedCreateSpec... embeds)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      embeds - The message embeds.
      Returns:
      The message.
      See Also:

    • reply

      default Mono<Reply> reply(MessageCreateSpec spec)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      spec - The message specification.
      Returns:
      The message.
      See Also:

    • reply

      default Mono<Reply> reply(InteractionApplicationCommandCallbackSpec spec)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      spec - The message specification.
      Returns:
      The message.
      See Also:

    • reply

      default Mono<Reply> reply(InteractionFollowupCreateSpec spec)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      spec - The message specification.
      Returns:
      The message.
      See Also:

    • reply

      default Mono<Reply> reply(CommandReplySpec spec)
      Sends a reply, as if by calling replies().add().

      Sending more than one causes the replies to be chained (each replying to the previous one).

      Parameters:
      spec - The message specification.
      Returns:
      The message.
      See Also:

    • belongs

      @SideEffectFree default Mono<Boolean> belongs(User user, Group group)
      Determines whether the given user belongs to the given group in the context of this invocation (guild and channel).
      Parameters:
      user - The user to check for.
      group - The group to check for.
      Returns:
      A Mono that emits true if the given user belongs to the given group under this invocation context, or false otherwise.

    • belongs

      @SideEffectFree default Mono<Boolean> belongs(Snowflake user, Group group)
      Determines whether the given user belongs to the given group in the context of this invocation (guild and channel).
      Parameters:
      user - The ID of the user to check for.
      group - The group to check for.
      Returns:
      A Mono that emits true if the given user belongs to the given group under this invocation context, or false otherwise.