Kommandoflagg
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.
Now that we have specified that our command may be run with the flag, we can now get the value of the flag. For a
simple boolean flag like the one we have specified above, we can simply just check if it exists. In the example below,
we are checking if the CommandContext for the command has a value for s
.
import org.spongepowered.api.text.Text;
if (args.hasAny("s")) {
src.sendMessage(Text.of("The command flag s was specified!"));
}
Permission Flags
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
.
Value Flags
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."));
}
Long Flags
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
.
Unknown Flag Behavior
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
.