Парсинг аргументов

API builder’а команд имеет мощный парсер аргументов. Он преобразует введённые данные в базовые типы Java (целочисленные, булевые, строки), либо же игровые объекты (игроки, миры, типы блоков, и т. д.). Парсер поддерживает необязательные аргументы и флаги. А также может совершать автозавершение аргументов при нажатии клавиши TAB.

Прошедшие парсинг аргументы сохраняются в объекты типа CommandContext. Если парсер возвращает один объект, то можно получить его при помощи args.<T>getOne(String key) (вместо T введите тип значения). Необязательные и слабые аргументы могут возвращать Optional.empty().

Многие парсеры могут возвращать более одного объекта (например, несколько игроков с соответствующим именем). В этом случае, Вам необходимо использовать метод args.<T>getAll(String key) для получения коллекции Collection возможных вариантов. Если этого не сделать, будет сгенерировано исключение!

Совет

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).

Для создания новых CommandElement (аргументы команды), используете фабричный класс GenericArguments. Многие элементы команды требуют короткий текстовый ключ, который отображается в ошибках и в сообщениях помощи.

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.

Пример: Создание команды с несколькими аргументами

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

Элемент команды

Описание

Количество и тип значения

none

Не требует аргументов. Это обычное поведение CommandSpec.

Базовые типы Java

string

Требует аргумент типа String.

один String

remainingJoinedStrings

Соединяет все оставшиеся аргументы разделенные пробелами (может быть использовано для команд-сообщений).

один String

bool

Требует аргумент типа boolean.

один Boolean

integer

Требует аргумент типа integer.

один Integer

doubleNum

Требует аргумент типа double.

один Double

Игровые объекты

player

Ожидает аргумент в виде онлайн-игрока. Может возвращать несколько игроков!

несколько экземпляров Player

playerOrSource

Как player, но возвращает отправителя команды, если соответствующий игрок не был найден.

несколько экземпляров Player

userOrSource

Как playerOrSource, но возвращает пользователя, а не игрока.

несколько экземпляров User

world

Ожидает аргумент в виде мира (также включает выгруженные миры).

несколько WorldProperties

dimension

Ожидает аргумент в виде измерения (END, NETHER, OVERWORLD).

несколько экземпляров DimensionType

location

Ожидает аргумент в виде Location.

один Location

vector3d

Ожидает аргумент в виде Vector3d.

один Vector3d

catalogedElement

Expect an argument that is a member of the specified CatalogType.

multiple matching elements of the specified catalog type

Шаблоны

choices

Return an argument that allows selecting from a limited set of values.

one specified value

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.

one specified value

enumValue

Require the argument to be a key under the provided enum.

multiple matching elements of the specified enum

Утилиты

Can be wrapped around command elements. The value type is inherited from the wrapped element.

seq

Builds a sequence of command elements (e.g. /cmd <arg1> <arg2> <arg3>).

унаследованное

repeated

Require a given command element to be provided a certain number of times.

несколько унаследованных

allOf

Require all remaining args to match the provided command element.

несколько унаследованных

optional

Make the provided command element optional. Throws an error if the argument is of invalid format and there are no more args.

унаследованное

optionalWeak

Сделайте предоставленный командный элемент необязательным. Не выдает ошибку, если аргумент имеет недопустимый формат и больше нет аргументов.

унаследованное

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>).

унаследованное

onlyOne

Restricts the given command element to only insert one value into the context at the provided key.

унаследованное

flags

Returns a builder for command flags (e.g. /cmd [-a] [-b <value>]).

См. Флаги команд

Short Flag: one Boolean

Long Flag: one String

Value Flag: inherited

requiringPermission

Requires the command sender to have the specified permission in order to use the given command argument

унаследованное

Совет

Больше информации доступно в Javadoc: GenericArguments.

Пользовательские CommandElement’ы

Можно создать пользовательские командные элементы (например, URL-парсер или элемент Vector2i), расширив абстрактный класс CommandElement.

Метод CommandElement#parseValue(CommandSource, CommandArgs) должен получить необработанный аргумент в виде строки с помощью CommandArgs#next() и конвертировать его в объект. Если парсинг окажется неудачным, метод должен сгенерировать исключение ArgumentParseException.

Метод The CommandElement#complete(CommandSource, CommandArgs, CommandContext) должен использовать CommandArgs#peek() для прочтения следующего исходного аргумента. Этот метод возвращает список аргументов для автозавершения при нажатии клавиши TAB.

Пример: определение командного элемента Vector2i

В этом примере парсер читает два входных аргумента и преобразует их в вектор.

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

Пример: использование командного элемента 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();

Совет

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