Flagi Poleceń

Command flags are useful for specifying extra parameters to be used for the processing of a command that doesn’t belong as a command argument.

To create a flag, we first need a builder for flags. We can simply use the GenericArguments#flags() method provided by GenericArguments to obtain the builder we need. From there, we can specify what type of flag we would like to create. Note that flags are specified as an argument.

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

This will create a command flag, so that when the player performs /our-command -s, the flag for s will be true. Note that building with GenericArguments#none() will prevent the command from having any arguments. If you wish for the command to have arguments and flags, you will need to specify your arguments within the CommandFlags.Builder#buildWith(CommandElement) method.

Teraz, gdy określiliśmy, że nasza komenda może być uruchamiane z flagą, możemy teraz uzyskać wartość flagi. W przypadku prostej zero-jedynkowej flagi, takiej jak ta, którą podaliśmy powyżej, wystarczy, że sprawdzimy czy istnieje. W poniższym przykładzie sprawdzamy, czy CommandContext dla komendy posiada wartość dla` s`.

import org.spongepowered.api.text.Text;

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

Flagi Uprawnień

Our flags so far are great, but what if we wanted to have it so that a player needs a permission to use a flag? We can instead use the CommandFlags.Builder#permissionFlag(String, String…) method on our flag builder. This will require the player to have a specific permission to run the command with the flag. An example of this is below:

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

If a player does not have the permission myplugin.command.flag, then they will not be allowed to execute our command with the command flag s.

Flagi wartości

Booleans can be great, but what if we wanted flags for things such as strings or integers? This is where value flags come into play. We simply need to use the CommandFlags.Builder#valueFlag(CommandElement, String…) method on our flag builder. Using the valueFlag() method, we can specify the type of flag we want to create, such as an integer or string. Creating an integer value flag can be done like so:

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

You may replace GenericArguments#integer(Text) with any other flag type you would like to specify, such as GenericArguments#string(Text).

Now to retrieve the flag value from our command, we can simply treat it like any other command argument. We simply need to check if it exists before retrieving it:

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

Długie flagi

As an alternative to short flags like the ones we have been using above, we can also use long flags. Using a long flag, you can specify a value along with the flag using equals (=) in the command. To create a long flag, simply prefix your normal flag with a dash -, like so:

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

We can retrieve the value that was specified with our flag similarly to value flags:

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

So if a user runs /our-command --myflag=Flag_Value, the Flag_Value will be stored in the string value.

Nieznane zachowanie flagi

Now what if we didn’t specify a specific flag to go along with our command, but still wanted to accept unknown flags? We can set the unknown flag behavior of our command to achieve this:

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

Using this, we can specify that any short flag with a specified value will be accepted. Without this, attempting to use an unknown flag will throw an exception. Some of the possible unknown flag behaviors are ERROR, ACCEPT_NONVALUE, ACCEPT_VALUE, and IGNORE. Note that the default behavior for unknown flags is ERROR.