Main spec

An example of a new command using this system can be found here.

Commands

Commands consist of an (ideally) public class with the @Command annotation. The @Command annotation specifies the command's name. We'll call this the "command class".

Command class "global" arguments

Inside the command class, class field members can be specified with argument annotations, for example:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    // ...

}

These arguments are arguments that are present for all commands in the class. Arguments are accessed in declaration order, so the following will only allow /mycommand <name> <value>, and not /mycommand <value> <name>:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @AIntegerArgument
    int value;

    // ...

}

Due to the nature of command class arguments, the declaration location does not matter when it comes to subcommands. The following two code blocks will yield the same command /mycommand <name> <value> subcommand:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @AIntegerArgument
    int value;

    @Subcommand("subcommand")
    class Subcommand {

        // Executor

    }
}

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @Subcommand("subcommand")
    class Subcommand {

        // Executor

    }

    @AIntegerArgument
    int value;
}

Subcommand executors

In the dev/annotations example, subcommand executors were implemented using @Subcommand on the method itself. I think it would be better to use a different annotation to avoid misleading syntax. For example, the following allows /mycommand <name> subcommand:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @Subcommand("subcommand")
    class Subcommand {

        @Executes
        public void myMethod(Player player) {
            // ...
        }

    }
}

Per-method arguments are still valid, allowing /mycommand <name> subcommand <value>:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @Subcommand("subcommand")
    class Subcommand {

        @Executes
        public void myMethod(Player player, @AIntegerArgument int value) {
            // ...
        }

    }
}

Subcommand non-class subcommands

It may be desirable to add subcommands without creating a giant tree. This can be done by applying (a repeatable) @Subcommand annotation to the executable method. This example shows /mycommand <name> subcommand subsubcommand <value>:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @Subcommand("subcommand")
    class Subcommand {

        @Subcommand("subsubcommand")
        @Executes
        public void myMethod(Player player, @AIntegerArgument int value) {
            // ...
        }

    }
}

This could also be implemented on the class-level:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @Subcommand("subcommand")
    @Subcommand("subsubcommand")
    class Subcommand {

        @Executes
        public void myMethod(Player player, @AIntegerArgument int value) {
            // ...
        }

    }
}

Arguments with different names to their parameters

Currently not planned unless demand requires this feature.

Suggestions

Since suggestions are implemented as functional interfaces, we can simply bind functional interface implementations to corresponding arguments via class references.

Arguments with suggestions requires @Suggests, and classes that implement suggestions requires @Suggestion. These "pairs" will be checked at compile time. Since we can observe all matching pairs (each @Suggests should have a corresponding @Suggestion), we can also provide compiler warnings for unused suggestions.

The compiler should error if @Suggestion does not implement the correct type.

This command represents /mycommand <name>, and the suggestions for <name> will be Player1, Player2 and Player3:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    @Suggests(ListOfNames.class)
    String name;

    @Executes
    public void myExecutor(Player player) {
        // ...
    }

    @Suggestion
    class ListOfNames implements Supplier<ArgumentSuggestions> {

        @Override
        public ArgumentSuggestions get() {
            return ArgumentSuggestions.strings("Player1", "Player2", "Player3");
        }

    }
}

Subcommands from another class

See #318 (comment).

Subcommands need not be declared in the command class. They can be declared in their own class. To link these together, the CommandAPI can use a @ExternalSubcommand annotation (actual name TBD) which takes in the class reference of the subcommand. The external subcommand must have its corresponding @Subcommand declaration on the class level. The external subcommand class must inherit the parent command in order to inherit global class variables. For example, Subcommand can access name because it extends MyCommand:

@Command("mycommand")
public class MyCommand {

    @AStringArgument
    String name;

    @ExternalSubcommand(Subcommand.class)
    Subcommand subcommand;
}

@Subcommand("subcommand")
public class Subcommand extends MyCommand {

    @Executes
    public void myMethod(Player player, @AIntegerArgument int value) {
        // ...
    }

}

Aliases

Aliases should no longer be provided using the @Alias annotation - it gets too messy. Consider adding it as a parameter to the @Command annotation.

Uh oh!