Untergeordnete Befehle

Der CommandSpec-Builder unterstützt folgende hierarchische Befehlsstrukturen:

  • /mail (übergeordneter Befehl)

    • /mail send (untergeordneter Befehl)

    • /mail read (untergeordneter Befehl)

Jeder untergeordneter Befehl ist ein separater CommandSpec und kann auf die gleiche Weise, wie ein regulärer Befehl, erstellt werden.

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();

Anstatt untergeordneten Befehle direkt beim Command-Service zu registrieren, wird dies bei ihrem jeweils übergeordnetem Befehl mit der CommandSpec.Builder#child(CommandCallable, String…) Methode getan. Sie werden mit einer Liste von Aliasen registriert. Der zuerst angegebene ist der primäre und wird in der Hilfenachricht zum Befehl angezeigt.

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");

Fallback-Verhalten

If a command has child commands, a CommandExecutor, set through CommandSpec.Builder#executor(CommandExecutor) and their associated CommandSpec.Builder#arguments(CommandElement) are optional. The behavior of error in selection and argument parsing of child commands is dependent on whether this parent executor exists.

Wenn der übergeordnete Executor nicht gesetzt wurde und das gesuchte Unter-Befehl nicht gefunden werden konnte oder dessen Argumente nicht geparsed werden können, dann wird eine ArgumentParseException geworfen.

Wenn ein übergeordnete Executor für den übergeordneten Befehl gesetzt wurde, dann wird es als Ersatz verwendet, wenn das erste Argument nicht einem der Aliase der Unterkommandos entspricht. Wenn ein Unterbefehl ausgewählt wurde, aber die Argumente nicht geparsed werden können, passiert eines der folgenden Dinge, basierend auf was CommandSpec.Builder#childArgumentParseExceptionFallback(boolean) gesetzt wurde:

  • Wenn true (der Standard), wird die ArgumentParseException verworfen und die Argumente des übergeordneten Befehls werden geparsed. Wenn auch diese Fehlschlagen, wird dessen Fehlermeldung angezeigt. Dies ist das gleiche Verhalten wie frühere API Versionen, in denen Argument-Parsing-Fehler von Unterbefehlen auch nicht angezeigt wurden.

  • Wenn false, wird der übergeordnete Executor nicht ausgeführt und die ArgumentParseException des Unterbefehls wird geworfen. Allerdings verhindert dies einige Kombination von Befehlen, zum Beispiel, wenn das erste Argument des übergeordneten Befehls denen des Unterbefehls entspricht.

In all cases, if the arguments parse successfully but the child executor throws an exception, the fallback executor (if any) is not executed and the error message from the child executor is displayed.