Package dev.sympho.modular_commands.api.command

Interface Command

All Known Subinterfaces:
InteractionCommand, MessageCommand, SlashCommand, TextCommand
All Known Implementing Classes:
InteractionCommandImpl, MessageCommandImpl, SlashCommandImpl, TextCommandImpl
public sealed interface Command permits MessageCommand, SlashCommand
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.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    botOwnerOnly()
    Whether this command can only be invoked by the owner of the bot.
    boolean
    callable()
    Whether this command can be invoked by a user.
    String
    description()
    The description of the command.
    String
    displayName()
    The display name 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.
    InvocationHandler
    invocationHandler()
    The handler to use for processing an invocation of the command.
    boolean
    invokeParent()
    Whether the parent command should be invoked before this command is invoked.
    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 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.
    discord4j.rest.util.PermissionSet
    requiredDiscordPermissions()
    The built-in permissions that a user should have in order to execute the command.
    boolean
    requireParentPermissions()
    Whether a user invoking this command must also have the permissions to invoke its parent command.
    default List<? extends ResultHandler>
    resultHandlers()
    The handlers to use for processing the result, in order.
    Command.Scope
    scope()
    The scope that the command is defined in.
    boolean
    serverOwnerOnly()
    Whether this command can only be invoked by the owner of the server.

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

    • displayName

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

    • requiredDiscordPermissions

      @Pure discord4j.rest.util.PermissionSet requiredDiscordPermissions()
      The built-in permissions that a user should have in order to execute the command.

      If the invoking channel is a private channel and the scope of the command allows being invoked there, this requirement is ignored.

      Returns:
      The built-in permissions required to run the command.

    • requireParentPermissions

      @Pure boolean requireParentPermissions()
      Whether a user invoking this command must also have the permissions to invoke its parent command.
      Returns:
      Whether a user invoking this command must also have the permissions to invoke the parent command.
      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.

    • botOwnerOnly

      @Pure boolean botOwnerOnly()
      Whether this command can only be invoked by the owner of the bot.
      Returns:
      Whether this command can only be invoked by the owner of the bot.

    • serverOwnerOnly

      @Pure boolean serverOwnerOnly()
      Whether this command can only be invoked by the owner of the server.

      If the invoking channel is a private channel and the scope of the command allows being invoked there, this requirement is ignored.

      Returns:
      Whether this command can only be invoked by the owner of the server.

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

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

    • invocationHandler

      @Pure InvocationHandler invocationHandler()
      The handler to use for processing an invocation of the command.
      Returns:
      The handler.
      API Note:
      Why require the use of a handler object instead of using a plain method, you ask? Because the Java compiler is dumb and doesn't automatically deal with widening parameter type overloads, which leads to a lot of boilerplate to get this handler structure working, and I have to make the separate handler classes anyway, so I'd rather not duplicate all of that.
      Making Command extend CommandHandler would also be a solution, except that sealed classes don't work across packages without using modules. So yeah.

    • resultHandlers

      @Pure default List<? extends ResultHandler> resultHandlers()
      The handlers to use for processing the result, in order.

      They are given priority over any handlers defined at the registry or global level.

      Returns:
      The result handlers for this command.
      Implementation Requirements:
      The default is to have no handlers.