Argumenty przetwarzania

API kontruktora komend jest wyposażony w potężny parser argumentów. Konwertuje input String do podstawowych typów Java (integer, boolean, string) lub obiekty w grze (Player, BlockType, World…). Parser składni obsługuje argumenty i flagi. Także handle TAB ukończenia argumentów.

The parsed arguments are stored in the CommandContext object. If the parser returns a single object, obtain it with CommandContext#getOne(String). Optional and weak arguments may return Optional.empty().

Many of the parsers may return more than one object (e.g. multiple players with a matching username). In that case, you must use the CommandContext#getAll(String) method to get the Collection of possible matches. Otherwise, the context object will throw an exception!

Wskazówka

You can use the GenericArguments#onlyOne(CommandElement) element to limit the amount of returned values to a single one, so you can safely use args.<T>getOne(String).

To create a new CommandElement (argument), use the GenericArguments factory class. Many command elements require a short text key, which is displayed in error and help messages.

Apply the CommandElement to the command builder with the CommandSpec.Builder#arguments(CommandElement…) method. It is possible to pass more than one CommandElement to the method, thus chaining multiple arguments (e.g /msg <player> <msg>). This has the same effect as wrapping the CommandElement objects in a GenericArguments#seq(CommandElement…) element.

Example: Building a Command with Multiple Arguments

import org.spongepowered.api.Sponge;
import org.spongepowered.api.text.Text;
import org.spongepowered.api.entity.living.player.Player;
import org.spongepowered.api.command.CommandException;
import org.spongepowered.api.command.CommandResult;
import org.spongepowered.api.command.CommandSource;
import org.spongepowered.api.command.args.CommandContext;
import org.spongepowered.api.command.args.GenericArguments;
import org.spongepowered.api.command.spec.CommandExecutor;
import org.spongepowered.api.command.spec.CommandSpec;

CommandSpec myCommandSpec = CommandSpec.builder()
        .description(Text.of("Send a message to a player"))
        .permission("myplugin.command.message")

        .arguments(
                GenericArguments.onlyOne(GenericArguments.player(Text.of("player"))),
                GenericArguments.remainingJoinedStrings(Text.of("message")))

        .executor(new CommandExecutor() {
            @Override
            public CommandResult execute(CommandSource src, CommandContext args) throws CommandException {

                Player player = args.<Player>getOne("player").get();
                String message = args.<String>getOne("message").get();

                player.sendMessage(Text.of(message));

                return CommandResult.success();
            }
        })
        .build();

Sponge.getCommandManager().register(plugin, myCommandSpec, "message", "msg", "m");

Overview of the GenericArguments command elements

Element Poleceń	Opis	Typ i ilość wartości
none	Expects no arguments. This is the default behavior of a CommandSpec.
Java Base Types
string	Wymaga, żeby argument był ciągiem.	jeden String
remainingJoinedStrings	Concatenates all remaining arguments separated by spaces (useful for message commands).	jeden String
bool	Wymaga, żeby argument był boolean’em.	jeden Boolean
integer	Wymaga, żeby argument był liczbą całkowitą.	jeden Integer
doubleNum	Wymaga, żeby argument był podwójny.	jeden Double
Obiekty Gry
player	Expect an argument to represent an online player. May return multiple players!	wiele wystąpień gracza
playerOrSource	Like player, but returns the sender of the command if no matching player was found.	wiele wystąpień gracza
userOrSource	Like playerOrSource, but returns a user instead of a player.	multiple User instances
world	Expect an argument to represent a world (also includes unloaded worlds).	multiple WorldProperties
dimension	Expect an argument to represent a dimension (END, NETHER, OVERWORLD).	wiele wystąpień DimensionType
location	Oczekuj, że argument będzie reprezentował lokalizację.	jedna Location
vector3d	Oczekuj, że argument będzie reprezentował Vector3d.	jeden Vector3d
catalogedElement	Expect an argument that is a member of the specified CatalogType.	multiple matching elements of the specified catalog type
Matchers
choices	Return an argument that allows selecting from a limited set of values.	jedna określona wartość
literal	Expect a literal sequence of arguments (e.g. "i", "luv", "u": /cmd i luv u). Throws an error if the arguments do not match.	jedna określona wartość
enumValue	Require the argument to be a key under the provided enum.	wiele pasujących elementów z określonego enum
Narzędzia Can be wrapped around command elements. The value type is inherited from the wrapped element.
seq	Buduje sekwencję elementów poleceń (np. /cmd <arg1> <arg2> <arg3>).	dziedziczone
powtarzane	Wymaga elementu danego polecenia aby był dostarczany określoną liczbę razy.	wiele razy dziedziczone
allOf	Require all remaining args to match the provided command element.	wiele razy dziedziczone
opcjonalne	Make the provided command element optional. Throws an error if the argument is of invalid format and there are no more args.	dziedziczone
optionalWeak	Make the provided command element optional. Does not throw an error if the argument is of invalid format and there are no more args.	dziedziczone
firstParsing	Returns a command element that matches the first of the provided elements that parses (useful for command overloading, e.g. /settime <day|night|<number>).	dziedziczone
onlyOne	Restricts the given command element to only insert one value into the context at the provided key.	dziedziczone
flagi	Zwraca konstruktora dla flag polecenia (np. `` / cmd [-a] [-b <value>]”). Zobacz :doc: flags	Short Flag: one Boolean Long Flag: one String Flaga wartości: odzedziczono
requiringPermission	Wymaga od osoby wysyłającej komendy posiadania określonych uprawnień w celu użycia podanego argumentu komendy	dziedziczone

Wskazówka

See the Javadocs for GenericArguments for more information.

Niestandardowe elementy poleceń

It is possible to create custom command elements (e.g. a URL parser or a Vector2i element) by extending the abstract CommandElement class.

The CommandElement#parseValue(CommandSource, CommandArgs) method should fetch a raw argument string with CommandArgs#next() and convert it to an object. The method should throw an ArgumentParseException if the parsing fails.

The CommandElement#complete(CommandSource, CommandArgs, CommandContext) method should use CommandArgs#peek() to read the next raw argument. It returns a list of suggestions for TAB completion.

Przykład: ``Vector2i``definicja elementu polecenia

The parser in this example reads two input arguments and converts them to a vector.

import com.flowpowered.math.vector.Vector2i;
import org.spongepowered.api.command.args.ArgumentParseException;
import org.spongepowered.api.command.args.CommandArgs;
import org.spongepowered.api.text.Text;
import org.spongepowered.api.command.args.CommandElement;

import java.util.Collections;
import java.util.List;

public class Vector2iCommandElement extends CommandElement {
    CommandArgs errorargs;

    protected Vector2iCommandElement(Text key) {
        super(key);
    }

    @Override
    protected Object parseValue(CommandSource source, CommandArgs args) throws ArgumentParseException {

        // <x> <y>
        errorargs=args;

        String xInput = args.next();
        int x = parseInt(xInput);

        String yInput = args.next();
        int y = parseInt(yInput);

        return new Vector2i(x, y);
    }

    private int parseInt(String input) throws ArgumentParseException {
        try {
            return Integer.parseInt(input);
        } catch(NumberFormatException e) {
            throw errorargs.createError(Text.of("'" + input + "' is not a valid number!"));
        }
    }

    @Override
    public List<String> complete(CommandSource src, CommandArgs args, CommandContext context) {
        return Collections.emptyList();
    }

    @Override
    public Text getUsage(CommandSource src) {
        return Text.of("<x> <y>");
    }
}

Przykład: użycie elementu polecenia Vector2i

// /plottp <x> <y>
CommandSpec myCommandSpec = CommandSpec.builder()
        .description(Text.of("Teleport to a plot"))
        .permission("myplugin.command.plot.tp")

        .arguments(new Vector2iCommandElement(Text.of("coordinates")))

        .executor(new MyCommandExecutor())
        .build();

Wskazówka

Look at the source code of the GenericArguments class for more examples.