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

Interface CommandContext

All Superinterfaces:
dev.sympho.bot_utils.access.AccessContext, dev.sympho.bot_utils.access.AccessValidator, dev.sympho.bot_utils.access.ChannelAccessContext, dev.sympho.bot_utils.access.ChannelAccessValidator, dev.sympho.bot_utils.event.ChannelEventContext, dev.sympho.bot_utils.event.EventContext, dev.sympho.bot_utils.event.RepliableContext
All Known Subinterfaces:
InstrumentedContext, InteractionCommandContext, LazyContext, MessageCommandContext, SlashCommandContext
All Known Implementing Classes:
MessageContextImpl
public interface CommandContext extends dev.sympho.bot_utils.event.RepliableContext
The execution context of an invoked command.
Since:
1.0
Version:
1.0

  • Method Details

    • invocation

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

      Unlike commandInvocation(), 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 commandInvocation().

      Returns:
      The trigger invocation.

    • commandInvocation

      @Pure Invocation commandInvocation()
      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 invocation().

      Returns:
      The normalized trigger invocation.

    • caller

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

    • callerMember

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

    • callerMember

      @Pure default Mono<Member> callerMember(Snowflake guildId)
      Retrieves the user that called the command as a guild member of the given guild.
      Parameters:
      guildId - The ID of the target guild.
      Returns:
      The calling user as a guild member of the given guild.
      Implementation Note:
      The default implementation will re-use the member instance provided by the event if appropriate (that is, if the given guild is the same that the command was invoked from) to avoid making an API request.

    • member

      default Mono<Member> member()
      Specified by:
      member in interface dev.sympho.bot_utils.access.AccessContext
      See Also:

    • member

      default Mono<Member> member(Snowflake guildId)
      Specified by:
      member in interface dev.sympho.bot_utils.access.AccessContext
      See Also:

    • channel

      Mono<MessageChannel> channel()
      Specified by:
      channel in interface dev.sympho.bot_utils.access.ChannelAccessContext

    • 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.