Package dev.sympho.modular_commands.api.command

Interface Command<H extends 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.
All Known Implementing Classes:
CommandImpl
public interface Command<H extends 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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Command.Scope
    The scopes that a command may be defined in.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final @Regex String
    DESCRIPTION_REGEX
    Pattern for valid command descriptions in the Discord API.
    static final @Regex String
    DISPLAY_NAME_REGEX
    Pattern for valid user/message command names in the Discord API.
    static final @Regex String
    NAME_REGEX
    Pattern for valid slash command names in the Discord API.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    default Set<Invocation>
    aliasInvocations()
    The alias invocations that may also invoke the command.
    boolean
    callable()
    Whether this command can be invoked by a user.
    @MatchesRegex("(?Us)^.{1,100}+$") String
    description()
    The description of the command.
    @MatchesRegex("(?U)^[ -_\\p{L}\\p{N}\\p{sc=Deva}\\p{sc=Thai}]{1,32}+$") String
    displayName()
    The display name of the command.
    ReplyManager.EphemeralType
    ephemeralReply()
    The type of ephemeral response to use, if any.
    H
    handlers()
    The handlers to use for processing an invocation of the command.
    boolean
    inheritSettings()
    Whether the command settings should be inherited from the parent command (ignoring the values provided by this command).
    default Invocation
    invocation()
    The invocation that executes this command.
    boolean
    invokeParent()
    Whether the parent command should be invoked before this command is invoked.
    @MatchesRegex("(?U)^[-_\\p{L}\\p{N}\\p{sc=Deva}\\p{sc=Thai}]{1,32}+$") String
    name()
    The name of the command.
    boolean
    nsfw()
    Whether this command can only be invoked in a NSFW channel.
    List<Parameter<?>>
    parameters()
    The command inline parameters, in the order that they should be provided by the user.
    Invocation
    parent()
    The parent of the command.
    boolean
    privateReply()
    Whether this command's response is sent in a way that only the invoking user can see.
    Group
    requiredGroup()
    The group that a user must have access for in order to invoke this command.
    boolean
    requireParentGroups()
    Whether a user invoking this command must also have access to the groups necessary to invoke its parent command(s).
    Command.Scope
    scope()
    The scope that the command is defined in.
    default boolean
    skipGroupCheckOnInteraction()
    Whether group access checking should be skipped when this command is invoked through an interaction.

  • Field Details

  • Method Details

    • scope

      @Pure Command.Scope scope()
      The scope that the command is defined in.
      Returns:
      The command scope.

    • callable

      @Pure 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.

    • parent

      @Pure 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.

    • 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

      @Pure 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 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

      @Pure 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 inline 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 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.

    • skipGroupCheckOnInteraction

      @Pure 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 returns true, as application commands should generally avoid clashing with user-set permissions unless necessary.

    • requireParentGroups

      @Pure 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.

    • nsfw

      @Pure 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.

    • privateReply

      @Pure boolean privateReply()
      Whether this command's response is sent in a way that only the invoking user can see.
      Returns:
      Whether this command's response is sent in a way that only the invoking user can see.
      API Note:
      This setting only affects the default configuration of the reply manager provided by the execution context. The specific mechanism used for it depends on how the command was invoked (message, slash command, etc) and the value of ephemeralReply().

    • ephemeralReply

      @Pure ReplyManager.EphemeralType ephemeralReply()
      The type of ephemeral response to use, if any.
      Returns:
      The ephemeral response type.
      API Note:
      This setting only affects the default configuration of the reply manager provided by the execution context. The specific mechanism used for it depends on how the command was invoked (message, slash command, etc).

    • inheritSettings

      @Pure 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.

    • invokeParent

      @Pure 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.

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