Package dev.sympho.modular_commands.api.command

Interface Command<H extends @NonNull Handlers>

Type Parameters:
H - The handler type of this command. The subtype(s) of Handlers used determine what methods of invocation are supported by this command. However, this type parameter is used only to facilitate type checking, with actual support being determined by the concrete type of the return value of handlers(). See the description of that method for details.
@Immutable public interface Command<H extends @NonNull Handlers>
A command that can be invoked by a user.

Irrespective of whether the command it is used with is compatible with interactions or not, all values must be compatible with the Discord API specification for command parameters.

Since:
1.0
Version:
1.0

  • Field Details

  • Method Details

    • id

      @Pure String id()
      The ID that uniquely identifies this command in the system.
      Returns:
      The command ID.

    • scope

      @Pure @Default default Command.Scope scope()
      The scope that the command is defined in.
      Returns:
      The command scope.
      Implementation Requirements:
      The default value is DEFAULT_SCOPE.

    • callable

      @Pure @Default default boolean callable()
      Whether this command can be invoked by a user.

      A non-callable command is usually used as a parent for other commands that should not be itself invoked.

      Do note that slash commands cannot be invoked if they have children commands, and so in that case this parameter has no effect. This is a limitation from Discord itself.

      Returns:
      true if the command may be directly called by users. false otherwise.
      Implementation Requirements:
      The default value is true.

    • parent

      @Pure @Default default Invocation parent()
      The parent of the command.

      If the invocation returned by this is empty, this command has no parent, and is therefore a main command. Otherwise, it is a subcommand.

      Note that a parent can only be specified by its name, not any aliases it may have (when supported). This implies that any command that may match the Invocation returned by this method through an alias is not considered a parent of this command.

      Returns:
      The parent of the command.
      Implementation Requirements:
      The default is the empty invocation (e.g. no parent).

    • name

      @Pure @MatchesRegex("(?U)^[-_\\p{L}\\p{N}\\p{sc=Deva}\\p{sc=Thai}]{1,32}+$") String name()
      The name of the command.

      This is the name used to match the command internally and for accessing text-based commands (slash and text commands). It is provided to the Discord API for slash commands, but not for user and message commands (for that, see displayName()).

      Returns:
      The name of the command.

    • invocation

      @SideEffectFree @NonAttribute default Invocation invocation()
      The invocation that executes this command.
      Returns:
      The command invocation.
      Implementation Requirements:
      The invocation is determined by appending the name to the parent.

    • aliases

      @Pure @Default default Set<@MatchesRegex("(?U)^[-_\\p{L}\\p{N}\\p{sc=Deva}\\p{sc=Thai}]{1,32}+$") String> aliases()
      The aliases that may also invoke the command, when invoking through a message.

      These aliases are only relevant to handling invocations. They may not be used to specify the command as a parent.

      Aliases must satisfy the same restrictions as the name.

      Returns:
      The command aliases.
      API Note:
      This setting is only meaningful for message-based invocations. By extension, if the command does not support message invocations, this setting has no effect.
      Implementation Requirements:
      The default is an empty set.

    • aliasInvocations

      @SideEffectFree @NonAttribute default Set<Invocation> aliasInvocations()
      The alias invocations that may also invoke the command.
      Returns:
      The command aliases as invocations.
      See Also:
      API Note:
      This value is only meaningful for message-based invocations. By extension, if the command does not support message invocations, this setting has no effect.
      Implementation Requirements:
      The invocation is determined by appending each alias to the parent. Do not override this.

    • displayName

      @Pure @MatchesRegex("(?U)^[ -_\\p{L}\\p{N}\\p{sc=Deva}\\p{sc=Thai}]{1,32}+$") String displayName()
      The display name of the command.

      This is displayed to the user in documentation-related functionality. For user and message commands, this is also the value provided to the Discord API as the command name instead of name().

      Returns:
      The display name of the command.

    • description

      @Pure @MatchesRegex("(?Us)^.{1,100}+$") String description()
      The description of the command.
      Returns:
      The description of the command.

    • parameters

      @Pure List<Parameter<?>> parameters()
      The command parameters, in the order that they should be provided by the user.

      All parameters that are marked as required must come before all parameters that aren't (optional parameters).

      Returns:
      The command parameters.
      API Note:
      The restriction in parameter order is due to the fact that it would not make any sense to have an optional parameter before a required one. Since all parameters must be provided in sequence, that would effectively make the optional parameter required.

    • requiredGroup

      @Pure @Default default Group requiredGroup()
      The group that a user must have access for in order to invoke this command.

      Note that having access to a group is not necessarily the same as belonging to that group (although it is the basic threshold); the specific definition depends on the AccessValidator implementation used to verify access.

      For application commands, be aware that this is completely disjoint from Discord's own permission system, and so utilizing this feature may lead to user confusion due to discrepancies between the apparent configured permissions and the internal group checks. It is nonetheless left as an option for situations where the application should have control over who is allowed to run the command (instead of guild administrators), for example global debug commands that should be reserved for the developers, and for complex permissions beyond what Discord can support (for example, subcommand-specific access restrictions). Make sure that group checking is not skipped when doing this.

      To completely skip group checking on invocations made through application commands (possibly saving a few function calls in such cases), use skipGroupCheckOnInteraction(). It may also be useful in the case of commands that support both text and interactions, where group checking may be wanted only for the text case (where there is no built-in permission system through Discord).

      Returns:
      The required group.
      Implementation Requirements:
      The default value is DEFAULT_GROUP.

    • skipGroupCheckOnInteraction

      @Pure @Default default boolean skipGroupCheckOnInteraction()
      Whether group access checking should be skipped when this command is invoked through an interaction.
      Returns:
      Whether group access checking should be skipped when this command is invoked through an interaction.
      See Also:
      API Note:
      This value is only meaningful for interaction-based invocations. By extension, if the command does not support interaction invocations, this setting has no effect.
      Implementation Requirements:
      The default value is true, as application commands should generally avoid clashing with user-set permissions unless necessary.

    • requireParentGroups

      @Pure @Default default boolean requireParentGroups()
      Whether a user invoking this command must also have access to the groups necessary to invoke its parent command(s).
      Returns:
      Whether a user invoking this command must also have access to the groups required by its parents.
      See Also:
      API Note:
      This value is only meaningful for subcommands.
      Implementation Requirements:
      The default value is true.

    • nsfw

      @Pure @Default default boolean nsfw()
      Whether this command can only be invoked in a NSFW channel.

      A private channel (if the scope of the command allows invocation in one) always satisfies this condition.

      Conversely, a guild channel that cannot be marked as NSFW (such as an announcement channel) never satisfies this condition.

      Returns:
      Whether this command can only be invoked in a NSFW channel.
      Implementation Requirements:
      The default value is false.

    • repliesDefaultPrivate

      @Pure @Default default boolean repliesDefaultPrivate()
      Whether the replies sent by this command should be private by default (i.e. unless specified otherwise on the individual reply).
      Returns:
      Whether this command's responses should be private by default.
      See Also:
      API Note:
      The specific mechanism used for private replies may vary depending on how the command was invoked (message, slash command, etc).
      Implementation Requirements:
      The default value is false.

    • deferReply

      @Pure @Default default boolean deferReply()
      Whether the initial reply to the command should be deferred, indicating to the user that a reply is pending.

      Note that whether the deferral is publicly visible or not is defined by the default visibility of replies. Note also that, if deferral is used, the visibility of the first reply will be set to the default to match the deferral, with the value of CommandReplySpec.privately() being ignored if set. Further replies are not affected.

      If using a deferral, it is expected that a reply will be sent at some point. It is an error to set this to true and not send any replies.

      Returns:
      Whether this command's initial response is deferred.
      API Note:
      The specific mechanism used for deferral may vary depending on how the command was invoked (message, slash command, etc).
      Implementation Requirements:
      The default value is false.

    • inheritSettings

      @Pure @Default default boolean inheritSettings()
      Whether the command settings should be inherited from the parent command (ignoring the values provided by this command).

      The settings are the values provided by the following methods:

      Returns:
      Whether settings should be inherited from the parent command.
      API Note:
      This value is only meaningful for subcommands.
      Implementation Requirements:
      The default value is false.

    • invokeParent

      @Pure @Default default boolean invokeParent()
      Whether the parent command should be invoked before this command is invoked.

      If the parent command may also define that its parent must be executed, and so on. Execution will start at the closest ancestor that sets this to false or does not have a parent (including itself).

      The parent(s) will be invoked with the same context object, which means that a parent may pass objects to a child through the context. It also means that the parameters to this command must be compatible with all executed ancestors, which means that

      • Any parameter that is defined in both this command and an executed parent (that is, has the same name) must be of the same type.
      • Any parameter that is required in an executed parent must be defined in this command, and it must either be also required or have a default value.
      • The order of shared parameters does not need to be the same or similar in any way.

      If the parameters of this command are not compatible with those of any executed parent as defined above, an error will be triggered at execution time.

      There are no compatibility requirements for ancestors that would not be executed as part of an execution of this command.

      Naturally, this flag has no effect on a command with no parent.

      Returns:
      Whether this command's parent should be executed as part of an invocation.
      Implementation Requirements:
      The default value is false.

    • handlers

      @Pure H handlers()
      The handlers to use for processing an invocation of the command.

      Note that the subtype(s) of Handlers implemented by the returned instance determine what methods of invocation are supported by this command. For example, if it implements only MessageHandlers, it will only support message commands; if it implements both MessageHandlers and SlashHandlers, it will support both message commands and slash commands; and so on.

      Be careful that, while this interface does have a generic type parameter to constrain the allowed return type for this method, it is used only to facilitate type checking (especially internally). The invocation support is determined by the actual type of the instance returned by this method. That is, if this method returns an object that implements both MessageHandlers and SlashHandlers, this command will support both message and slash commands, even if this instance is created as of type Command<MessageHandlers>. There is no way around this due to the nature of type erasure.

      Returns:
      The handler.

    • validate

      @Pure @Check default void validate() throws IllegalArgumentException, NullPointerException
      Validates that the command properties of this instance are valid.
      Throws:
      IllegalArgumentException - if any of properties are invalid.
      NullPointerException - if a null value was found where not allowed.
      See Also:

    • builder

      @SideEffectFree static <H extends @NonNull Handlers> Command.Builder<H> builder()
      Creates a new builder.
      Type Parameters:
      H - The handler type.
      Returns:
      The builder.

    • builder

      @SideEffectFree static <H extends @NonNull Handlers> Command.Builder<H> builder(Command<H> base)
      Creates a new builder initialized with the properties of the given command.
      Type Parameters:
      H - The argument type.
      Parameters:
      base - The base instance to copy.
      Returns:
      The builder.

    • message

      @SideEffectFree static Command.Builder<MessageHandlers> message()
      Creates a builder for a message-only command.
      Returns:
      The builder.
      API Note:
      Use to force the type argument when it cannot be inferred.

    • slash

      @SideEffectFree static Command.Builder<SlashHandlers> slash()
      Creates a builder for a slash-only command.
      Returns:
      The builder.
      API Note:
      Use to force the type argument when it cannot be inferred.

    • text

      @SideEffectFree static Command.Builder<TextHandlers> text()
      Creates a builder for a text (message and slash) command.
      Returns:
      The builder.
      API Note:
      Use to force the type argument when it cannot be inferred.

    • interaction

      @SideEffectFree static Command.Builder<InteractionHandlers> interaction()
      Creates a builder for an interaction command.
      Returns:
      The builder.
      API Note:
      Use to force the type argument when it cannot be inferred.