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

Interface CommandContext

All Superinterfaces:
AccessValidator
All Known Subinterfaces:
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.

      This may be different from the command's declared Command.invocation() if it was invoked using an alias (when supported).

      Returns:
      The trigger invocation.

    • getCaller

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

    • getCallerMember

      @Pure @Nullable Member getCallerMember()
      Retries 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.

    • 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 argument was not given by the caller 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 is marked as required or provides a default value.

    • 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 argument was not given by the caller 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 argument was not given by the caller 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, assuming it is non-null (so either required or with a default value).
      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 not received and does not have a default value.
      See Also:
      API Note:
      An NPE thrown by this method indicates a mismatched configuration (code expects the parameter to be required or default but it was not configured as such).

    • 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, assuming it is non-null (so either required or with a default value).
      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 not received 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, assuming it is non-null (so either required or with a default value).
      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.

    • replyManager

      @SideEffectFree ReplyManager replyManager()
      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.

    • deferReply

      default Mono<Void> deferReply()
      Defers response to the command, as if by calling replyManager().defer().
      Returns:
      A Mono that completes after deferral is processed.
      See Also:

    • reply

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

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

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

    • reply

      default Mono<Message> reply(EmbedCreateSpec... embeds)
      Sends a reply, as if by calling replyManager().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<Message> reply(MessageCreateSpec spec)
      Sends a reply, as if by calling replyManager().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.