Argument Library

| GitHub |

This library contains a network of argument parsers that can be used to create CommandElements. The primary design goal of this system is to have a fluent, functional approach where parsers return a parsed object of the correct type, can be reused and chained together, and support customizable messages for when exceptions are thrown.

The Argument Library was added in PR #2 by Simon_Flash.

Arguments

The Arguments [link] class contains static instances of the provided parsers and also contains factory methods for creating them as well. It is recommended to use the created instances where applicable.

Information about the specific parsers can be found in the javadocs of the appropriate methods, such as the error messages used. Examples for using them can be found below.

// Standard String, Boolean, and User parsers.
Arguments.string().toElement("string");
Arguments.booleanObj().toElement("boolean");
Arguments.user().toElement("user");

// Parses an Integer in the range [1,64] (inclusive) as a quantity.
Arguments.integer()
        .inRange(Range.closed(1, 64)) //sets a predicate ensuring the value is in the range [1,64]
        .toElement("quantity");

// Parses a positive Double.
Arguments.double().inRange(Range.greaterThan(0.0)).toElement("cost");

// Parses the UUID of the provided Player, defaulting to the UUID of the CommandSource.
Arguments.player()
        .orSource() //or the CommandSource, if no player was found and the source is a Player
        .toUuid() //maps the Player to their UUID
        .toElement("uuid");

// Alternatively, the following (equivalent) code can be used.
Arguments.playerOrSource().toUuid().toElement("uuid"); //uses a cached parser for the player or source

// Parses a Crate retrieved from the given map of choice with a custom error message.
Map<String, Crate> crates;
Arguments.choices(crates, ImmutableMap.of("no-choice", "<arg> is not a crate.")).toElement("crate");

// Using flags for this, that, and the other
Arguments.flags()
        .flag("announce", "a") //adds 'true' when parsed under the name 'announce'
        .flag(Arguments.player().toElement("player"), "player", "p")
        .flag(Arguments.intObj().inRange(Range.closed(1, 64)).toElement("quantity"), "quantity", "q")
        .build();

Value Parsers

The Argument Library revolves around the use of the ValueParser [link] interface, which is (roughly) defined as the following:

@FunctionalInterface
public interface ValueParser<T> {

    T parseValue(CommandSource src, CommandArgs args) throws ArgumentParseException;

}

Unlike a CommandElement, a ValueParser is not responsible for adding it’s parsed value to the CommandContext and instead returns it directly through generics. Therefore, a ValueParser<Optional<Player>> returns an Optional<Player> that may be used however the receiving code sees fit.

The majority of parsers provided inherit from StandardParser [link], an abstract class that holds a map of messages and provides a default implementation of the complete method. It is recommended to extend this class if you choose to implement your own ValueParser.

Because the library is designed with a functional approach, many parsers contain utility methods that can be used to create a new parser to fit your needs. For example, the NumberParser [link] has an inRange method that will verify the parsed argument is within the given range. Other similar methods include optional, map, and orSource.

To create a CommandElement from the parser that can be used with Sponge’s Command API, the toElement method may be used. This returns a new CommandElement<T> [link] that serves as a wrapper around the parser, allowing the same parser to be used under different names.

FlagsElement

The FlagsElement [link] class is a CommandElement that has a custom implementation of flags. This element is not the same as Sponge’s CommandFlags element as it does not follow the Unix style of long and short flags. Instead, all flags are prefixed by a single hyphen as in -flag where values may be entered as -flag value or -flag=value. With much agony, tab completion is supported for both variants effectively.