Introduce the notion of a terminal parameter.

It is roughly what GenericArguments#optional did in API 7, but happens one element earlier - a terminal element is parsed then control passes to an executor, rather than seeing there is nothing to parse.

Author: dualspiral

src/main/java/org/spongepowered/api/command/parameter/Parameter.java

@@ -25,6 +25,7 @@
 package org.spongepowered.api.command.parameter;
 
 import com.google.common.reflect.TypeToken;
+import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.spongepowered.api.CatalogType;
 import org.spongepowered.api.Sponge;
@@ -738,41 +739,22 @@ static <T> Parameter.Value.Builder<T> literal(Class<T> returnType, T returnedVal
     }
 
     /**
-     * Parses the next element(s) in the {@link CommandContext}
+     * Gets whether this parameter can be considered terminal.
      *
-     * @param reader The {@link ArgumentReader.Mutable} containing the strings
-     *               that need to be parsed
-     * @param context The {@link CommandContext.Builder} that contains the
-     *                current state of the execution
-     * @throws ArgumentParseException thrown if the parameter could not be
-     *      parsed
-     */
-    void parse(ArgumentReader.Mutable reader, CommandContext.Builder context) throws ArgumentParseException;
-
-    /**
-     * Returns potential completions of the current tokenized argument.
-     *
-     * @param reader The {@link ArgumentReader} containing the strings that need
-     *               to be parsed
-     * @param context The {@link CommandContext} that contains the
-     *                current state of the execution.
-     * @return The potential completions.
-     * @throws ArgumentParseException thrown if the parameter could not be
-     *      parsed
-     */
-    List<String> complete(ArgumentReader.Immutable reader, CommandContext context) throws ArgumentParseException;
-
-    /**
-     * Gets the usage of this parameter.
+     * <p>A terminal parameter will pass control to the command's associated
+     * {@link CommandExecutor} if the parameter consumes the end of an input
+     * string.</p>
      *
-     * @param cause The {@link CommandCause} that requested the usage
-     * @return The usage
+     * @return true if terminal, else false.
      */
-    Text getUsage(CommandCause cause);
+    boolean isTerminal();
 
     /**
      * Gets whether this parameter is optional.
      *
+     * <p>An optional parameter will not throw an exception if it cannot parse
+     * an input, instead passing control to another parameter.</p>
+     *
      * @return true if optional, else false.
      */
     boolean isOptional();
@@ -814,7 +796,7 @@ interface Builder extends ResettableBuilder<Key<?>, Builder> {
              * @param <T> The type of the value represented by the key
              * @return The built {@link Key}
              */
-            <T> Key<T> build(String key, TypeToken<T> typeToken);
+            <T> Key<T> build(@NonNull String key, @NonNull TypeToken<T> typeToken);
         }
 
     }
@@ -868,6 +850,39 @@ interface Value<T> extends Parameter {
          */
         Predicate<CommandCause> getRequirement();
 
+        /**
+         * Parses the next element(s) in the {@link CommandContext}
+         *
+         * @param reader The {@link ArgumentReader.Mutable} containing the strings
+         *               that need to be parsed
+         * @param context The {@link CommandContext.Builder} that contains the
+         *                current state of the execution
+         * @throws ArgumentParseException thrown if the parameter could not be
+         *      parsed
+         */
+        void parse(ArgumentReader.@NonNull Mutable reader, CommandContext.@NonNull Builder context) throws ArgumentParseException;
+
+        /**
+         * Returns potential completions of the current tokenized argument.
+         *
+         * @param reader The {@link ArgumentReader} containing the strings that need
+         *               to be parsed
+         * @param context The {@link CommandContext} that contains the
+         *                current state of the execution.
+         * @return The potential completions.
+         * @throws ArgumentParseException thrown if the parameter could not be
+         *      parsed
+         */
+        List<String> complete(ArgumentReader.@NonNull Immutable reader, @NonNull CommandContext context) throws ArgumentParseException;
+
+        /**
+         * Gets the usage of this parameter.
+         *
+         * @param cause The {@link CommandCause} that requested the usage
+         * @return The usage
+         */
+        Text getUsage(CommandCause cause);
+
         /**
          * Builds a {@link Parameter} from constituent components.
          */
@@ -1159,15 +1174,15 @@ interface SequenceBuilder extends ResettableBuilder<Parameter, SequenceBuilder>
          *
          * @return This builder, for chaining
          */
-        SequenceBuilder optional();
+        SequenceBuilder terminal();
 
         /**
          * Sets that this parameter is weak optional and will be ignored if it
          * cannot parse the next element(s).
          *
          * @return This builder, for chaining
          */
-        SequenceBuilder optionalWeak();
+        SequenceBuilder optional();
 
         /**
          * Defines the next parameter in the parameter sequence.
@@ -1228,15 +1243,15 @@ interface FirstOfBuilder extends ResettableBuilder<Parameter, FirstOfBuilder> {
          *
          * @return This builder, for chaining
          */
-        FirstOfBuilder optional();
+        FirstOfBuilder terminal();
 
         /**
          * Sets that this parameter is weak optional and will be ignored if it
          * cannot parse the next element(s).
          *
          * @return This builder, for chaining
          */
-        FirstOfBuilder optionalWeak();
+        FirstOfBuilder optional();
 
         /**
          * Adds a parameter that can be used to parse an argument. Parameters