Argumen Parsing

The Command Builder API comes with a powerful argument parser. It converts the string input to java base types (integers, booleans, strings) or game objects (players, worlds, block types, ...). The parser supports optional arguments and flags. It also handles TAB completion of arguments.

Argumen yang diurai disimpan di :javadoc: objek CommandContext. Jika parser mengembalikan satu objek, dapatkan dengan :javadoc: CommandContext # getOne (String). Argumen opsional dan lemah dapat kembali `` Opsional.empty () ``.

Banyak parser dapat mengembalikan lebih dari satu objek (misalnya beberapa pemain dengan nama pengguna yang cocok). Dalam hal ini, Anda harus menggunakan metode :javadoc: CommandContext # getAll (String) untuk mendapatkan `` Collection`` dari kemungkinan kecocokan. ** Jika tidak, objek konteks akan melemparkan pengecualian! **

When creating a command, consider whether the argument could return multiple values, for example, whether a player argument could support multiple players when using a selector. If you support multiple values the users need to type only one command and can use an easier command syntax. Example: /tell @a Who took the cookies?

Tip

You can use the GenericArguments#onlyOne(CommandElement) element to restrict the amount of returned values to a single one, so you can safely use args.<T>getOne(String). However the user will still get a message, if they try to select more than one value.

Untuk membuat yang baru :javadoc: CommandElement (argumen), gunakan :javadoc:` GenericArguments` kelas pabrik. Banyak elemen perintah memerlukan tombol teks singkat, yang ditampilkan dalam pesan error dan help.

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.

Contoh: Membangun Command dengan 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;

PluginContainer plugin = ...;

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((CommandSource src, CommandContext args) -> {

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

Ikhtisar elemen perintah `` GenericArguments``

Elemen perintah	Deskripsi	Jenis & Jumlah Nilai
`` none``	Tidak mengharapkan argumen. Ini adalah perilaku default dari `` CommandSpec``.
** Jenis Dasar Java **
`` string``	Membutuhkan argumen untuk menjadi sebuah string.	satu `` String``
`` tersisaJoinedStrings``	Menyatukan semua argumen yang tersisa yang dipisahkan oleh spasi (berguna untuk perintah pesan).	satu `` String``
`` bool``	Membutuhkan sebuah argumen untuk menjadi seorang boolean.	satu `` Boolean``
`` integer``	Mengharuskan sebuah argumen untuk menjadi integer.	satu `` Integer``
`` doubleNum``	Mengharuskan argumen menjadi ganda.	satu `` Double``
** Objek Game **
`` pemain``	Harapkan argumen untuk mewakili pemain online. ** Bisa mengembalikan beberapa pemain! **	beberapa contoh `` Pemain``
beberapa contoh `` Pemain``	Seperti `` player``, namun mengembalikan pengirim perintah jika tidak ada pemain yang cocok ditemukan.	beberapa contoh `` Pemain``
`` userOrSource``	Seperti `` playerOrSource``, namun mengembalikan pengguna dan bukan pemain.	beberapa `` User`` contoh
`` dunia``	Harapkan argumen untuk mewakili dunia (juga mencakup dunia yang tidak dibebani).	beberapa `` WorldProperties``
`` dimensi``	Harapkan argumen untuk mewakili dimensi (`` END``, `` NETHER``, `` OVERWORLD``).	beberapa instance `` DimensionType``
`` lokasi``	Harapkan argumen untuk mewakili `` Lokasi``.	satu `` lokasi``
`` vector3d``	Harapkan argumen untuk mewakili `` Vector3d``.	satu `` Vector3d``
katalogedElement`	Harapkan argumen yang merupakan anggota dari ditentukan :javadoc:`JenisKatalog`.	beberapa pencocokan elemen ditentukan jenis katalog
Pencocokan
pilihan	Kembalikan argumen yang memungkinkan pemilihan dari serangkaian nilai yang terbatas.	salah satu nilai yang ditentukan
harfiah	Ekspektasi urutan argumen (contoh, "i", "luv", "u": /cmd i luv u). Memberikan sebuah galat jika argumen tidak cocok.	salah satu nilai yang ditentukan
enumNilai	Memerlukan argumen yang menjadi kunci di bawah enum yang telah disediakan.	beberapa elemen pencocokan dari enum yang telah ditetapkan
Utilitas Dapat dibungkus di sekitar elemen-elemen perintah. Jenis nilainya diwariskan dari elemen yang terbungkus.
seq	Membangun urutan elemen perintah (e.g. /cmd <arg1> <arg2> <arg3>).	diwariskan
ulang	Memerlukan elemen perintah yang diberikan untuk beberapa kali.	beberapa diwarisi
`` allOf``	Mengharuskan semua yang tersisa args untuk mencocokkan disediakan perintah elemen.	beberapa diwarisi
`` opsional``	Buat elemen perintah yang disediakan opsional. Melontarkan kesalahan jika argumen itu format tidak valid dan tidak ada args lagi.	diwariskan
`` optionalWeak``	Membuat perintah yang disediakan elemen opsional. Tidak melemparkan kesalahan jika argumen adalah format tidak valid dan tidak ada lagi args.	diwariskan
`` firstParsing``	Mengembalikan elemen perintah yang cocok dengan elemen yang disediakan pertama yang menguraikan (berguna untuk perintah yang memuat berlebihan, contoh. /settime <day|night|<number>).	diwariskan
`` onlyOne``	Batasi elemen perintah yang diberikan untuk hanya memasukkan satu nilai ke dalam konteks pada tombol yang disediakan.	diwariskan
`` bendera``	Kembali membangun perintah untuk bendera (misalnya /cmd [-a] [-b <nilai>]). Lihat : doc: flags	Bendera Pendek: satu `` Boolean`` Bendera Panjang: satu `` String`` Nilai Bendera: diwariskan
require Permission	Membutuhkan perintah pengirim yang telah ditentukan izin untuk menggunakan perintah yang diberikan argumen	diwariskan
requiringPermissionWeak	Requires the command sender to have the specified permission in order to use the given command argument. Does not throw an error if the user does not have the permission.	diwariskan

Tip

Lihat GenericArguments untuk informasi lebih lanjut.

Peringatan

Don't expect that a CommandElements will only ever return a single value, a lot of them support multiple return values; some might even support regular expressions or use a command selector. This is intentional as it makes commands easier to use. Example: /tell @a BanditPlayer has the cookies!. If you want to make sure to only get a single value use GenericArguments#onlyOne(CommandElement).

Elemen-Elemen Perintah Pilihan

Ini memungkinkan untuk membuat elemen perintah pilihan (contoh. sebuah pengurai URL atau elemen Vector2i) dengan memperluas kelas abstrak``CommandElement``.

CommandElement#parseValue(CommandSource, CommandArgs) metode harus mengambil mentah-mentah argumen string dengan CommandArgs#next() dan mengubahnya menjadi sebuah objek. Metode harus membuang ArgumentParseException jika parsing gagal.

CommandElement#lengkap(CommandSource, CommandArgs, CommandContext) metode harus digunakan CommandArgs#peek() untuk baca halaman berikutnya baku argumen. Mengembalikan daftar saran untuk TAB penyelesaian.

Contoh: Vector2i ketentuan elemen perintah

Parser dalam contoh ini membaca dua argumen masukan dan mengubahnya menjadi vektor.

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 {

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

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

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

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

        return new Vector2i(x, y);
    }

    private int parseInt(String input, CommandArgs args) throws ArgumentParseException {
        try {
            return Integer.parseInt(input);
        } catch(NumberFormatException e) {
            throw args.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>");
    }
}

Contoh: Vektor2i penggunaan elemen perintah

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

Tip

Lihatlah Kode sumber dari ArgumenGenerik kelas untuk lebih banyak contoh.

Using Selectors in Custom Command Elements

Sponge provides support for parsing selectors, meaning that you can make use of them in your custom elements. There are two steps in using selectors, parsing (getting a Selector from the string) and resolving (getting a set of Entity objects selected by the selector).

To parse a selector string, use the Selector#parse(String) method, passing the entire selector, including the @ symbol. This will turn the string into a Selector object that can be queried or resolved. Note that if the string is not a valid selector, an IllegalArgumentException will be thrown.

To resolve this selector, use Selector#resolve(CommandSource). This will return a set of Entity objects selected by the selector.

The following parseValue method from the CommandElement class attempts to parse a selector and return a set of entities based on the location of the CommandSource. If the passed string does not start with @, an exception will be thrown indicating that the passed argument is not a selector.

@Override
protected Object parseValue(CommandSource source, CommandArgs args) throws ArgumentParseException {
    String nextArg = args.next();
    if (nextArg.startsWith("@")) {
        Set<Entity> selectedEntities;
        try {
            selectedEntities = Selector.parse(nextArg).resolve(source);
        } catch (IllegalArgumentException e) {
            throw args.createError(Text.of("Could not parse selector."));
        }

        if (selectedEntities.isEmpty()) {
            throw args.createError(Text.of("No entities selected."));
        }

        return selectedEntities;
    }

    throw args.createError(Text.of("Not a selector."));
}

Tip

Look at the SelectorCommandElement source code for an example of how selector parsing is performed in the standard Sponge CommandElements.