Package dev.sympho.modular_commands.api.command.parameter.parse

Interface ListParser<T extends @NonNull Object>

Type Parameters:
T - The element type.
All Superinterfaces:
ArgumentParser<String,List<T>>, BiFunction<CommandContext,String,Mono<List<T>>>, ChoicesParser<String,List<T>>, InputParser<String,List<T>>, ParserFunction<String,List<T>>, StringParser<List<T>>
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ListParser<T extends @NonNull Object> extends StringParser<List<T>>
A parser that extracts lists of objects by splitting a string argument and parsing each item.

Items appear in the resulting list in the same order that they appear in the raw argument.

Since:
1.0
Version:
1.0

  • Field Details

  • Method Details

    • preprocess

      @SideEffectFree default String preprocess(String arg)
      Applies pre-processing steps to the received argument before splitting, such as cleaning the string.
      Parameters:
      arg - The received argument.
      Returns:
      The pre-processed argument.
      Implementation Note:
      The default is to trim the string, removing leading and trailing whitespace.

    • splitter

      @Pure default StringSplitter.Async splitter()
      Gives the splitter to use for splitting received strings.
      Returns:
      The splitter to use.
      Implementation Requirements:
      The default is DEFAULT_SPLITTER.

    • failFast

      default boolean failFast()
      Determines whether the parser should fail on the first element that encounters an error (true), or finish parsing all elements before reporting an InvalidListException with all encountered errors (false).
      Returns:
      Whether to fail as soon as any error is encountered.
      Implementation Requirements:
      The default is true.

    • minItems

      @Pure default @org.checkerframework.common.value.qual.IntRange(from=0L, to=2147483647L) int minItems()
      The minimum amount of items allowed (inclusive).

      Note that, while this value may technically be 0, the only way for an empty list to be received is through a message-based invocation, where merging does not occur, and the user uses quotations to provide an empty string, as in all other scenarios the argument would simply be missing. Due to that, it is strongly recommended to have an empty list as a default value (and not set the parameter as required) when setting the minimum to 0, in order to maintain consistency.

      Returns:
      The amount.
      Implementation Requirements:
      The default is 1. Must be between 0 and 2147483647.

    • maxItems

      @Pure default @org.checkerframework.common.value.qual.IntRange(from=1L, to=2147483647L) int maxItems()
      The maximum amount of items allowed (inclusive).
      Returns:
      The amount.
      Implementation Requirements:
      The default is 2147483647. Must be between 1 and 2147483647.

    • allowMerge

      default boolean allowMerge()
      Description copied from interface: StringParser
      Whether to allow merge behavior when a parameter using this parser is the last parameter of the command.

      If enabled, whenever an associated parameter is the last parameter of a message-based invocation, all content in the message beyond the second-to-last argument is considered to correspond to this parameter, and is parsed as-is, rather than being tokenized like the preceding arguments.

      This behavior allows the last argument to contain delimiter characters (such as spaces) and generally maintain formatting without the user needing to surround it with quotes (particularly useful when the last parameter is a message or a list).

      One consequence of it, however, is that if the user does include quotes (out of habit, for example), they will not be stripped prior to parsing. It also disables automatic checking for extra arguments, which may cause parsing errors instead.

      If this parameter is not the last parameter, or the invocation is not through a message, this value is ignored.

      Specified by:
      allowMerge in interface StringParser<T extends @NonNull Object>
      Returns:
      Whether to enable merge behavior.
      Implementation Requirements:
      Defaults to true.
      Implementation Note:
      Since lists are split by spaces by default, without trailing arg merging they would need to always be specified with quotes, which is doubly problematic since items within it may also need quotes. Thus, allowing merge behavior is recommended.

    • parseItem

      @SideEffectFree Mono<T> parseItem(CommandContext context, String raw)
      Parses an individual item in the list.
      Parameters:
      context - The invocation context.
      raw - The raw item.
      Returns:
      The parsed item.

    • parseArgument

      default Mono<List<T>> parseArgument(CommandContext context, String raw) throws InvalidArgumentException
      Description copied from interface: ArgumentParser
      Parses the given raw argument from the user into the corresponding value.
      Specified by:
      parseArgument in interface ArgumentParser<String,List<T extends @NonNull Object>>
      Parameters:
      context - The execution context.
      raw - The raw argument received from the user.
      Returns:
      A Mono that issues the parsed argument. If the raw value is invalid, it may fail with a InvalidArgumentException.
      Throws:
      InvalidArgumentException - if the given argument is not a valid value.