Package org.incendo.cloud.parser

Interface ArgumentParser<C,T>

Type Parameters:

C - command sender type

T - Value type

All Superinterfaces:

SuggestionProviderHolder<C>

All Known Subinterfaces:

AggregateParser<C,O>, ArgumentParser.FutureArgumentParser<C,T>, MappedArgumentParser<C,I,O>

All Known Implementing Classes:

BooleanParser, ByteParser, CharacterParser, CommandFlagParser, DoubleParser, DurationParser, EitherParser, EnumParser, FloatParser, IntegerParser, LiteralParser, LongParser, MappedArgumentParserImpl, NumberParser, ShortParser, StringArrayParser, StringParser, UUIDParser

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
@API(status=STABLE)
public interface ArgumentParser<C,T>
extends SuggestionProviderHolder<C>

Parser that parses strings into values of a specific type

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ArgumentParser.FutureArgumentParser<C,T>	Utility interface extending ArgumentParser to make it easier to implement ArgumentParser.FutureArgumentParser.parseFuture(CommandContext, CommandInput).

Method Summary

Modifier and Type	Method	Description
static <C, U, V> @NonNull ParserDescriptor<C,Either<U,V>>	firstOf(@NonNull ParserDescriptor<C,U> primary, @NonNull ParserDescriptor<C,V> fallback)	Creates a new parser which attempts to use the primary parser and falls back on the fallback parser if that fails.
default <O> @NonNull ArgumentParser.FutureArgumentParser<C,O>	flatMap(MappedArgumentParser.Mapper<C,T,O> mapper)	Create a derived argument parser preserving all properties of this parser, but converting the output type.
default <O> @NonNull ArgumentParser.FutureArgumentParser<C,O>	flatMapSuccess(@NonNull BiFunction<CommandContext<C>,T,CompletableFuture<ArgumentParseResult<O>>> mapper)	Create a parser that passes through failures and flat maps successfully parsed values with mapper.
default <O> @NonNull ArgumentParser.FutureArgumentParser<C,O>	mapSuccess(@NonNull BiFunction<CommandContext<C>,T,CompletableFuture<O>> mapper)	Create a parser that passes through failures and maps successfully parsed values with mapper.
@NonNull ArgumentParseResult<@NonNull T>	parse(@NonNull CommandContext<@NonNull C> commandContext, @NonNull CommandInput commandInput)	Attempts to parse the input into an object of type ArgumentParser.
default @NonNull CompletableFuture<@NonNull ArgumentParseResult<T>>	parseFuture(@NonNull CommandContext<C> commandContext, @NonNull CommandInput commandInput)	Returns a future that completes with the result of parsing the given commandInput.
default @NonNull SuggestionProvider<C>	suggestionProvider()	Returns the suggestion provider.

Method Details

parse

@NonNull ArgumentParseResult<@NonNull T> parse(@NonNull CommandContext<@NonNull C> commandContext,
 @NonNull CommandInput commandInput)

Attempts to parse the input into an object of type ArgumentParser.

This method may be called when a command chain is being parsed for execution (using CommandExecutor.executeCommand(Object, String)) or when a command is being parsed to provide context for suggestions (using SuggestionFactory.suggest(Object, String)). It is possible to use CommandContext.isSuggestions()} to see what the purpose of the parsing is. Particular care should be taken when parsing for suggestions, as the parsing method is then likely to be called once for every character written by the command sender.

This method should never throw any exceptions under normal circumstances. Instead, if the parsing for some reason cannot be done successfully ArgumentParseResult.failure(Throwable) should be returned. This then wraps any exception that should be forwarded to the command sender.

The parser is assumed to be completely stateless and should not store any information about the command sender or the command context. Instead, information should be stored in the CommandContext.

Parameters:

commandContext - Command context

commandInput - Command Input

Returns:

Parsed command result

parseFuture

@API(status=STABLE)
default @NonNull CompletableFuture<@NonNull ArgumentParseResult<T>> parseFuture(@NonNull CommandContext<C> commandContext,
 @NonNull CommandInput commandInput)

Returns a future that completes with the result of parsing the given commandInput.

This method may be called when a command chain is being parsed for execution (using CommandExecutor.executeCommand(Object, String)) or when a command is being parsed to provide context for suggestions (using SuggestionFactory.suggest(Object, String)). It is possible to use CommandContext.isSuggestions()} to see what the purpose of the parsing is. Particular care should be taken when parsing for suggestions, as the parsing method is then likely to be called once for every character written by the command sender.

This method should never throw any exceptions under normal circumstances. Instead, if the parsing for some reason cannot be done successfully ArgumentParseResult.failure(Throwable) or ArgumentParseResult.failureFuture(Throwable) should be returned. This then wraps any exception that should be forwarded to the command sender.

The parser is assumed to be completely stateless and should not store any information about the command sender or the command context. Instead, information should be stored in the CommandContext.

Parameters:

commandContext - Command context

commandInput - Command Input

Returns:

future that completes with the result.

flatMap

@API(status=STABLE)
default <O>
@NonNull ArgumentParser.FutureArgumentParser<C,O> flatMap(MappedArgumentParser.Mapper<C,T,O> mapper)

Create a derived argument parser preserving all properties of this parser, but converting the output type.

Type Parameters:

O - the result type

Parameters:

mapper - the mapper to apply

Returns:

a derived parser.

flatMapSuccess

@API(status=STABLE)
default <O>
@NonNull ArgumentParser.FutureArgumentParser<C,O> flatMapSuccess(@NonNull BiFunction<CommandContext<C>,T,CompletableFuture<ArgumentParseResult<O>>> mapper)

Create a parser that passes through failures and flat maps successfully parsed values with mapper.

Type Parameters:

O - mapped parser value type

Parameters:

mapper - success mapper

Returns:

mapped parser

mapSuccess

@API(status=STABLE)
default <O>
@NonNull ArgumentParser.FutureArgumentParser<C,O> mapSuccess(@NonNull BiFunction<CommandContext<C>,T,CompletableFuture<O>> mapper)

Create a parser that passes through failures and maps successfully parsed values with mapper.

Type Parameters:

O - mapped parser value type

Parameters:

mapper - success mapper

Returns:

mapped parser

suggestionProvider

default @NonNull SuggestionProvider<C> suggestionProvider()

Returns the suggestion provider.

By default, this will return the parser, if the parser is also a SuggestionProvider. Otherwise, SuggestionProvider.noSuggestions() will be returned.

Specified by:

suggestionProvider in interface SuggestionProviderHolder<C>

Returns:

the suggestion provider

firstOf

static <C,
U,
V>
@NonNull ParserDescriptor<C,Either<U,V>> firstOf(@NonNull ParserDescriptor<C,U> primary,
 @NonNull ParserDescriptor<C,V> fallback)

Creates a new parser which attempts to use the primary parser and falls back on the fallback parser if that fails.

Type Parameters:

C - command sender type

U - primary value type

V - fallback value type

Parameters:

primary - primary parser

fallback - fallback parser which gets invoked if the primary parser fails to parse the input

Returns:

the descriptor of the parser