Argument Parsers

Any time a command is ran, the entire input string is delimited by spaces to gather the tokens that make up the command input. These're called raw arguments, and ArgumentParser objects take these raw arguments and turn them into parameters that the command can actually use.

Stock Parsers

Various parsers come with General (with a lot of them being generators). The table below lists available stock parsers that can all be found in the ArgumentParsers class.

Parser	Description
STRING	Takes a token and produces a String. If the token starts with either a single quote or a double quote, the string can contain whitespace and span multiple tokens until the closing quote is reached.
REMAINING_STRING	Takes all remaining tokens and produces a String.
NUMBER	Takes a token and produces a Number (more specifically a double, though it can be taken as a Number for convenient conversion to other numeric types).
INTEGER	Takes a token and produces an Integer.

Generator	Description
anyOf	Accepts tokens that match the provided choices, with the chosen choice being passed to the given parser. Produces a parameter of the given parser's target resolution type.
or	Accepts tokens that satisfy any of the provided parsers. Should no parsers be satisfied, the error messages of all parsers that were passed are compiled and returned in the SyntaxException. Produces a parameter of the first satisfied parser's target resolution type.
remain	Eats all the remaining tokens and passes each to the provided parser. Produces a List containing all parameters that were produced by the given parser.
opt	Accepts tokens that satisfy the given parser. If there are no tokens to consume, the provided default token is given to the parser instead.
alt	Accepts tokens that satisfy the given parser. If there are no tokens to consume, the provided default parameter is produced instead.
lenient	Accepts tokens that satisfy the given parser. If the parser would produce a SyntaxException, the provided default token is given to the parser instead.
fallback	Accepts tokens that satisfy the given parser. If the parser would produce a SyntaxException, the provided default parameter is produced instead.
rename	Creates a functionally identical copy of the provided parser, with the only difference being the changed typename.

Implementing an ArgumentParser

ArgumentParser objects have two important methods, them being getTypename and parse. The typename of a parser is what's used to generate syntax -- if a command named test uses two parsers whose typenames are string and number, the resulting syntax might be test <string> <number>.

The parse method is the main method of an ArgumentParser. It will receive RawArguments to take tokens from and process into parameters. ArgumentParser implementations are not allowed to produce null values; use an Optional if a value is not guaranteed even if syntax is correct. Should syntax errors occur while parsing a token, a parser should throw a ParseException with a failure message to direct to the user. Any other exceptions thrown during the parse method is considered a crash.

ArgumentParser<Double> myDoubleParser = new ArgumentParser<Double>() {

    @Override
    public String getTypename() { return "number"; }

    @Override
    public Double parse(RawArguments args) {
        try {
            return Double.parseDouble(args.next());
        } catch(NumberFormatException e) {
            throw new ParseException("not a number");
        }
    }

}

Two other methods exist to handle optional parameters. Normally, when syntax is generated, the typename of the parsers are surrounded by angle brackets (<>) to signify that they are required. However, if either getDefaultToken or getDefaultParameter return a non-empty Optional, these angle brackets are replaced by square brackets ([]). If the token is available, the default token is appended to the typename after an equals sign. If both are available, the parameter takes priority and the default token will not be appended.

Parameter Completion

The getSuggestions method of an ArgumentParser powers parameter completion. If a parser is able to provide suggestions, completion can be performed using the CommandManager object's completeCommand method.