Annotation Command Framework (ACF)

A RegisteredCommand represents a specific method in your command class that has been mapped to a command or subcommand. When a command is invoked, the following lifecycle occurs:

1. Permission Check: The framework verifies if the CommandIssuer has the required permissions defined by @CommandPermission on the method or the parent class.
2. Pre-Command: The preCommand() method is called (can be overridden in subclasses).
3. Condition Validation: The framework validates any @Conditions defined on the method.
4. Argument Resolution: The framework attempts to resolve the provided command arguments into the method's parameter types using ContextResolvers.
5. Method Invocation: The actual command method is invoked with the resolved arguments.
6. Post-Command: The postCommand() method is called (can be overridden in subclasses).

If the method returns a CompletionStage<?>, the framework handles the asynchronous result and manages exceptions via handleException.

Command completions in ACF follow a specific resolution hierarchy:

1. Explicit ID: The command parameter specifies a completion ID (e.g., @my_id).
2. Default Type Completion: If no ID is specified, ACF looks up the parameter's type in the defaultCompletions map.
3. Enum Support: If the parameter is an Enum, ACF automatically generates completions based on the enum's constant names using a built-in DEFAULT_ENUM_ID (@__defaultenum__).
4. Pipe and Config Syntax: Completions can be combined or configured using special syntax:
   • id1|id2: Provides completions from either id1 OR id2.
   • id:config: Passes a config string to the completion handler (e.g., @range:0-10).
   • repeat@id: Tells the system to repeat the completion logic for multi-word arguments.

When a completion handler is invoked, it receives a CommandCompletionContext which provides access to the current input, arguments, and configuration.

When defining command methods in ACF, you can use several annotations on method parameters to control how they are parsed, validated, and displayed in help text.

Parameter Annotations

• @Name: Sets the internal name of the parameter (used for localization keys).
• @Default: Provides a default value if the parameter is not provided in the command input.
• @Description: Provides a human-readable description for the parameter.
• @Conditions: Defines requirements/conditions that must be met for this parameter to be valid.
• @Optional: Marks the parameter as optional. A parameter is also considered optional if it has a @Default value or if it is the last parameter and is of type String[].
• @Single: When used with a String type, prevents the parameter from consuming all remaining input (rest consumption).
• @Syntax: Overrides the automatically generated syntax display (e.g., <name> or [name]).
• @Values: Restricts the parameter to a specific set of allowed values.
• @Flags: Defines command-line style flags for the parameter using a comma-separated list of key=value or key pairs.
• @ConsumesRest: Explicitly marks the parameter as one that consumes all remaining input.
• @CommandPermission: Specifies the permission(s) required to use this specific parameter.

Syntax Generation Logic

If no @Syntax is provided, ACF generates syntax based on the parameter's state:

• Required Input: <DisplayName>
• Optional Input: [DisplayName]

ACF allows you to define custom validation logic for commands and their parameters using two types of conditions:

1. Command Conditions (Condition<I>): Used for general command-level validation (e.g., checking if a command is available in a specific scope). These are validated against a ConditionContext.

2. Parameter Conditions (ParameterCondition<P, CEC, I>): Used to validate specific command arguments. These have access to the CommandExecutionContext and the actual value being passed, allowing for type-specific validation (e.g., checking if a string is a valid username).

To use them, you must register them with the CommandManager using addCondition.

// Example of a Parameter Condition implementation
public class MyParameterCondition implements ParameterCondition<String, MyExecutionContext, MyIssuer> {
    @Override
    public void validateCondition(ConditionContext<MyIssuer> context, MyExecutionContext execContext, String value) throws InvalidCommandArgument {
        if (!value.startsWith("prefix_")) {
            throw new InvalidCommandArgument("Value must start with prefix_");
        }
    }
}

The CommandManager is the central entry point for the Annotation Command Framework (ACF). It is an abstract class that you must extend to implement your specific command handling logic. It manages command registration, dependency injection, locales, and exception handling.

To use it, you must implement the abstract methods such as registerCommand, getCommandContexts, getCommandCompletions, and getCommandIssuer.

public class MyCommandManager extends CommandManager<MyType, MyIssuer, MyFormat, MyMessageFormatter, MyExecutionContext, MyConditionContext> {
    @Override
    public void registerCommand(BaseCommand command) {
        // Implementation for registering commands
    }

    @Override
    public CommandContexts<?> getCommandContexts() {
        return null; // Implementation
    }

    @Override
    public CommandCompletions<?> getCommandCompletions() {
        return null; // Implementation
    }

    @Override
    public MyIssuer getCommandIssuer(Object issuer) {
        return (MyIssuer) issuer;
    }

    @Override
    public boolean isCommandIssuer(Class<?> type) {
        return MyIssuer.class.isAssignableFrom(type);
    }

    @Override
    public RootCommand createRootCommand(String cmd) {
        return null; // Implementation
    }

    @Override
    public Locales getLocales() {
        return null; // Implementation
    }

    @Override
    public CommandExecutionContext<?> createCommandContext(RegisteredCommand command, CommandParameter parameter, CommandIssuer sender, List<String> args, int i, Map<String, Object> passedArgs) {
        return null; // Implementation
    }

    @Override
    public CommandCompletionContext createCompletionContext(RegisteredCommand command, CommandIssuer sender, String input, String config, String[] args) {
        return null; // Implementation
    }

    @Override
    public void log(LogLevel level, String message, Throwable throwable) {
        // Implementation
    }

    @Override
    public Collection<RootCommand> getRegisteredRootCommands() {
        return null; // Implementation
    }
}