Ayrıştırma Argümanı

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.

Ayrıştırılan bağımsız değişkenler CommandContext nesnesi. Ayrıştırıcı tek bir nesneyi döndürürse, onu :javadoc: CommandContext#getOne(String) ile alır. İsteğe bağlı ve zayıf argümanlar `` Optional.empty() `` dönebilir.

Ayrıştırıcıların birçoğu birden fazla nesne döndürebilir (örn. Kullanıcı adıyla eşleşen birden çok oyuncu). Bu durumda, CommandContext#getAll(String) yöntemi Collection olası eşleşmelerden almak için kullanılmalıdır. Aksi takdirde, bağlam nesnesi bir istisna atar!

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?

Tüyo

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.

Yeni bir tane oluşturmak için CommandElement (argument) ve GenericArguments fabrika sınıflarını kullanın. Çoğu komut öğesi, hata ve yardım iletileri görüntülenen kısa bir metin anahtarı gerektirir.

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.

Örnek: Çoklu Argümanlarla Komut Oluşturma

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

`` GenericArguments`` komut öğelerine genel bakış

Komut Öğesi

Açıklama

Değer türü & miktar

none

Hiçbir argüman beklemiyor. Bu, bir dosyanın varsayılan davranıştır CommandSpec.

Java Temel Türleri

string

Bir bağımsız değişkenin bir dize olmasını gerektirir.

bir String

remainingJoinedStrings

Geriye kalan tüm bağımsız değişkenleri boşluklarla birbirine bağlar (ileti komutları için kullanışlıdır).

bir String

bool

Argümanın bir boolean olmasını gerektirir.

bir Boolean

integer

Bir bağımsız değişkenin bir tam sayı olmasını gerektirir.

bir Integer

doubleNum

Bir argümanın bir çift olması gerekir.

bir Double

Oyun Nesneleri

player

Bir çevrimiçi oyuncu temsil etmek için bir argüman bekleyin. Birden fazla oyuncu geri dönebilir!

çoklu Player örnekleri

playerOrSource

`` Player`` gibi, ancak eşleşen bir oyuncu bulunamazsa, komutun göndereni geri getirir.

çoklu Player örnekleri

userOrSource

`` PlayerOrSource`` gibi, ancak bir oyuncu yerine bir kullanıcı döndürür.

çoklu User örnekleri

world

Bir dünyayı temsil etmek için bir argümanın olmasını bekleyin (ayrıca boşaltılmış dünyaları da içerir).

çoklu WorldProperties

dimension

Bir argümanın bir boyutu temsil etmesini bekleyin (END, NETHER, OVERWORLD).

çoklu DimensionType örnekleri

location

Bir argümanın Location temsil etmesini bekleyin.

bir Location

vector3d

Bağımsız bir değişkenin Vector3d temsil etmesini bekleyin.

bir Vector3d

catalogedElement

Belirtilen üyenin bir argümanını bekleyin CatalogType.

belirtilen katalog türünde birden çok eşleşen öğe

Matchers

choices

Sınırlı bir değer kümesinden seçim yapmaya izin veren bir bağımsız değişkeni döndürür.

Bir belirtilen değer

literal

Argümanların harf dizisini bekleyin (örn. "i", "luv", "u": /cmd i luv u). Bağımsız değişkenler eşleşmiyorsa bir hata atar.

Bir belirtilen değer

enumValue

Argümanın sağlanan enum altında bir anahtar olmasını gerektirir.

belirtilen enumun birden çok eşleşen öğeleri

Araçlar

Komut öğeleri etrafında sarılabilir. Değer türü sarılmış öğeden devralınır.

seq

Bir dizi komut elemanı oluşturur (örn. /cmd <arg1> <arg2> <arg3>).

miras

repeated

Belirli bir komut öğesinin belirli sayıda sağlanmasını isteyin.

çoklu miras

allOf

Geriye kalan tüm bağımsız değişkenlerin sağlanan komut öğesine uymasını zorunlu kılın.

çoklu miras

optional

Sağlanan komut öğesini isteğe bağlı yapın. Bağımsız değişken geçersiz biçimdeyse ve args yoksa bir hata atar.

miras

optionalWeak

Sağlanan komut öğesini isteğe bağlı yapın. Bağımsız değişken geçersiz biçimdeyse ve args yoksa bir hata atmaz.

miras

firstParsing

Verilen öğelerin ilkiyle eşleşen bir komut öğesi döndürür. (komutu aşırı yüklemek için kullanışlıdır, örn. /settime <day|night|<number>).

miras

onlyOne

Verilen komut öğesi, sağlanan anahtardaki içeriğe yalnızca bir değer eklemek için kısıtlar.

miras

flags

Komut bayrakları için bir oluşturucu döndürür (örn. /cmd [-a] [-b <value>]).

Bakınız Komut Bayrakları

Kısa Bayrak: bir Boolean

Uzun Bayrak: bir String

Değer Bayrağı: Devralınan

requiringPermission

Belirtilen komut argümanını kullanmak için komut göndereninin belirtilen izni almasını gerektirir

miras

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.

miras

Tüyo

Daha fazla bilgi için Javadocs sitesini ziyaret edin GenericArguments.

Uyarı

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

Özel Komut Elementleri

Özel komut öğeleri oluşturmak mümkündür (örn. bir URL ayrıştırıcı veya bir Vector2i elementi) Soyut CommandElement sınıfını uzatarak.

CommandElement#parseValue(CommandSource, CommandArgs) yöntemi bir ham argüman dizesini CommandArgs#next() alıp bir nesneye dönüştürmelidir. Eğer ayrıştırma başarısız olursa bir :javadoc: ArgumentParseException atmalıdır.

CommandElement#complete(CommandSource, CommandArgs, CommandContext) yönteminde bir sonraki ham argümanı okumak için CommandArgs#peek () kullanılmalıdır. TAB tamamlama önerileri listesini döndürür.

Örnek: ``Vector2i``komut elementi tanımı

Bu örnekteki ayrıştırıcı iki girdi bağımsız değişkenini okur ve bir vektöre dönüştürür.

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

Örnek: Vector2i komut elementi kullanımı

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

Tüyo

Daha fazla örnek için kaynak kodundaki <https://github.com/SpongePowered/SpongeAPI/blob/stable-7/src/main/java/org/spongepowered/api/command/args/GenericArguments.java> GenericArguments class’ına bakınız.

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

Tüyo

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