Command Flags

Les Command Flags sont utiles pour spécifier des paramètres supplémentaires à être utilisés pour le traitement d’une commande qui n’appartient pas aux arguments de la commande.

Pour créer un Flag, nous avons d’abord besoin d’un constructeur pour les Flags. Nous pouvons simplement utiliser la méthode GenericArguments#flags() fournie par GenericArguments pour obtenir le constructeur dont nous avons besoin. À partir de là, nous pouvons spécifier quel type de Flag nous voulons créer. Notez que les Flags sont spécifiés en tant qu’arguments.

import org.spongepowered.api.command.args.GenericArguments;
import org.spongepowered.api.command.spec.CommandSpec;

CommandSpec myCommand = CommandSpec.builder()
    .executor(new MyCommand())
    .arguments(GenericArguments.flags().flag("s").buildWith(GenericArguments.none()))
    .build();

Ceci va créer un Command Flag, afin que quand le joueur effectue /our-command -s, le Flag pour s soit true. Notez que la construction avec GenericArguments#none() empêchera la commande d’avoir des arguments. Si vous souhaitez que la commande aie des arguments et des Flags, vous devez spécifier vos arguments à l’intérieur de la méthode CommandFlags.Builder#buildWith(CommandElement).

Maintenant que nous avons spécifié que notre commande peut être exécutée avec le Flag, nous pouvons maintenant récupérer la valeur du Flag. Pour un simple Flag booléen comme celui que nous avons spécifié plus haut, nous pouvons simplement vérifier si il existe. Dans l’exemple ci-dessous, nous vérifions si le CommandContext pour la commande a une valeur pour s.

import org.spongepowered.api.text.Text;

if (args.hasAny("s")) {
    src.sendMessage(Text.of("The command flag s was specified!"));
}

Permission Flags

Nos Flags jusqu’à présent étaient bien, mais que se passe-t-il si nous voulions qu’un joueur aie besoin d’une permission pour utiliser un Flag ? Nous pouvons à la place utiliser la méthode CommandFlags.Builder#permissionFlag(String, String…) sur notre constructeur de Flag. Cela requiert que le joueur aie une permission spécifique pour exécuter la commande avec le Flag. Un exemple est illustré ci-dessous :

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().permissionFlag("myplugin.command.flag",
            "s").buildWith(GenericArguments.none()))
        .build();

Si un joueur n’a pas la permission myplugin.command.flag, alors il ne sera pas autorisé à exécuter notre commande avec le Command Flag s.

Value Flags

Les booléens peuvent être bien, masi que se passe-t-il si nous voulions des Flags pour les choses telles que des chaînes de caractères ou des entiers ? C’est là où les Value Flags entrent en jeu. Nous devons simplement utiliser la méthode CommandFlags.Builder#valueFlag(CommandElement, String…) sur notre constructeur de Flag. En utilisant la méthode valueFlag(), nous pouvons spécifier le type de Flag que nous voulons créer, comme un entier ou une chaîne de caractères. Nous pouvons créer un Value Flag de type entier comme ceci :

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().valueFlag(GenericArguments
                .integer(Text.of("value")), "s").buildWith(GenericArguments.none()))
        .build();

Vous pouvez remplacer GenericArguments#integer(Text) avec n’importe quel autre type de Flag que vous souhaiteriez spécifier, comme GenericArguments#string(Text).

Maintenant, pour récupérer la valeur du Flag depuis notre commande, nous pouvons simplement le traiter comme n’importe quel autre argument de la commande. Nous avons simplement besoin de vérifier si il existe avant de le récupérer :

import java.util.Optional;

Optional<Integer> optional = args.<Integer>getOne("value");
if (optional.isPresent()) {
    int value = optional.get().intValue();
} else {
    src.sendMessage(Text.of("The value flag was not specified."));
}

Long Flags

Comme alternative aux Short Flags comme ceux que nous avons utilisé plus haut, nous pouvons aussi utiliser les Long Flags. En utilisant un Long Flag, vous pouvez spécifier une valeur avec le Flag en utilisant le signe égal dans la commande. Pour créer un Long Flag, précédez simplement de votre Flag normal avec un tiret -, comme ceci :

CommandSpec myCommand = CommandSpec.builder()
        .executor(new MyCommand())
        .arguments(GenericArguments.flags().flag("-myflag")
            .buildWith(GenericArguments.none()))
        .build();

Nous pouvez récupérer la valeur qui a été spécifiée avec notre Flag de la même façon qu’avec les Value Flags :

Optional<String> optional = args.<String>getOne("myflag");
if (optional.isPresent()) {
    String value = optional.get();
}

Donc, si un utilisateur exécute /our-command --myflag=Flag_Value, le Flag_Value sera stocké dans la chaîne de caractères value.

Comportement de Flag Inconnu

Maintenant, et si nous ne spécifions pas de Flag spécifique pour aller avec notre commande, mais voulons toujours accepter les Flags inconnus ? Nous pouvons définir le comportement de Flag inconnu (Unknown Flag Behavior) de notre commande pour y parvenir :

import org.spongepowered.api.command.args.CommandFlags;

CommandSpec myCommand = CommandSpec.builder()
            .executor(new MyCommand())
            .arguments(GenericArguments.flags()
                    .setUnknownShortFlagBehavior(
                        CommandFlags.UnknownFlagBehavior.ACCEPT_VALUE)
                    .buildWith(GenericArguments.none()))
            .build();

En utilisant ceci, nous pouvons spécifier que n’importe quel Short Flag avec une valeur spécifiée sera accepté. Sans cela, essayer d’utiliser un flag inconnu va lever une exception. Certains des comportements de Flag inconnu sont ERROR, ACCEPT_NONVALUE, ACCEPT_VALUE et IGNORE. Notez que le comportement par défaut pour les Flags inconnus est ERROR.