Sous-Commandes

Le constructeur CommandSpec supporte les commandes à structures hiérarchiques tel que:

• /mail (commande principale)

  • /mail send (sous-commande)

  • /mail read (sous-commande)

Chaque sous-commande est un CommandSpec différent et peut être créé de la même façon que les autres commandes.

import org.spongepowered.api.text.Text;
import org.spongepowered.api.command.spec.CommandSpec;

// /mail read
CommandSpec readCmd = CommandSpec.builder()
    .permission("myplugin.mail.read")
    .description(Text.of("Read your inbox"))
    .executor(...)
    .build();

// /mail send
CommandSpec sendCmd = CommandSpec.builder()
    .permission("myplugin.mail.send")
    .description(Text.of("Send a mail"))
    .arguments(...)
    .executor(...)
    .build();

Au lieu de les enregistrer dans le service de commande, les sous-commandes sont enregistrées dans la commande principale par le biais de la méthode CommandSpec.Builder#child(CommandCallable, String…). Elles sont enregistrées avec la liste de leurs alias. Le premier alias fourni est le principal et apparaîtra dans la message d’aide d’utilisation.

import org.spongepowered.api.Sponge;

PluginContainer plugin = ...;

CommandSpec mailCommandSpec = CommandSpec.builder()
    .permission("myplugin.mail.base")
    .description(Text.of("Send and receive mails"))
    .child(readCmd, "read", "r", "inbox")
    .child(sendCmd, "send", "s", "write")
    .build();

Sponge.getCommandManager().register(plugin, mailCommandSpec, "mail", "email");

Comportement de Secours

Si une commande a une sous-commande, un CommandExecutor, défini via CommandSpec.Builder#executor(CommandExecutor) et ses CommandSpec.Builder#arguments(CommandElement) associés sont optionnels. Le comportement des erreurs dans la sélection et la lecture des arguments des sous-commandes dépend de si l’exécuteur parent existe.

Si un exécuteur parent n’a pas été défini, alors la sous-commande demandée ne pourra pas être trouvée ou l’argument ne pourra pas être lu, alors une ArgumentParseException sera lancée.

Si un exécuteur parent a été défini pour la commande parent, il est utilisé comme secours si le premier argument ne correspond à aucune sous-commande. Si une sous-commande est sélectionnée mais les arguments ne peuvent pas être lus, un des suivants arrivera par rapport à ce sur quoi CommandSpec.Builder#childArgumentParseExceptionFallback(boolean) est défini :

• Si true (par défaut), la ArgumentParseException est annulée et les arguments de la commande parent sont lus. S’il ratent, l’exception de la commande parent sera affichée. C’est le même comportement que dans les versions précédentes de l’API, où les exceptions de lecture d’argument de la sou-commande ne seront pas affichées.

• Si false, l’exécuteur parent n’est pas exécuté et une ArgumentParseException est lancée, retournant l’exception de l’argument de la sous-commande qui n’a pas pu être lu, mais peut empêcher certaines combinaisons de commandes parent et d’arguments d’être exécutés (si le premier argument du secours est le même que la sous-commande).

Dans tous les cas, si l’argument est correctement lu mais que l’exécuteur enfant lance une exception, l’exécuteur de secours (s’il existe) n’est pas exécuté et le message d’erreur de l’exécuteur enfant est affiché.