Argumen Parsing

API Command Builder hadir dengan parser argumen yang hebat. Ini mengubah input string menjadi tipe dasar java (bilangan bulat, boolean, string) atau objek permainan (pemain, dunia, jenis blok, ...). Parser mendukung argumen opsional dan flag. Ini juga menangani penyelesaian argumen TAB.

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! **

Tip

Anda dapat menggunakan elemen :javadoc: GenericArguments # onlyOne (CommandElement) untuk membatasi jumlah nilai yang dikembalikan ke satu karakter tunggal, jadi Anda dapat menggunakan `` args dengan aman. <T> getOne (String) ``.

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.

Terapkan `` CommandElement`` ke pembangun perintah dengan metode :javadoc: CommandSpec.Builder # arguments (CommandElement ...). Anda bisa melewati lebih dari satu `` CommandElement`` ke metode ini, jadi chaining beberapa argumen (misalnya `` / msg <player> <msg> ``). Ini memiliki efek yang sama seperti membungkus objek `` CommandElement` di elemen :javadoc: GenericArguments # seq (CommandElement ...).

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;

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

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

Tip

Lihat GenericArguments untuk informasi lebih lanjut.

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

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

Lihat pada kode sumber dari kelas GenericArgument untuk lebih banyak contoh.