personthecat.catlib.command.annotations.Node Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of catlib-quilt Show documentation
Utilities for serialization, commands, noise generation, IO, and some new data types.
The newest version!
package personthecat.catlib.command.annotations;

import com.mojang.brigadier.arguments.ArgumentType;
import personthecat.catlib.command.arguments.ListArgumentBuilder;
import personthecat.catlib.command.arguments.ArgumentSupplier;
import personthecat.catlib.command.CommandContextWrapper;

/**
 * Represents a single argument node in a command builder tree.
 * 
 *   Constructing this annotation requires a single parameter: name.
 *   If no other values are provided, this node will be treated as a literal
 *   argument.
 * 
 *     branch = @Node(name = "argument")
 * 

 *   For required arguments, the annotation provides several options for
 *   generating builders. You must chose one, or else the value of
 *   type will be chosen, as it comes first.
 * 
 *     branch = @Node(name = "block", type = BlockStateArgument.class)
 * 

 *   See the documentation on the individual parameters for more info on using
 *   them.
 * 

 *   In addition, the {@link Node} annotation provides support for generating
 *   list arguments (written as /cmd arg1 arg2 arg3 ...). This
 *   can be achieved by providing an intoList value, as follows:
 * 
 *     branch = @Node(
 *         name = "files",
 *         descriptor = ArgumentSuppliers.XjsFile.class,
 *         intoList = @ListInfo(size = 3)
 *     )
 * 

 *   Note that, in order to use a list argument type, the node must either be
 *   the last argument in the branch, or be followed by a literal argument
 *   and then another regular argument.
 * 
 *     branch = {
 *       @Node(
 *           name = "numbers",
 *           descriptor = ArgumentSuppliers.AnyInt.class,
 *           intoList = @ListInfo
 *       ),
 *       @Node(name = "in"),
 *       @Node(name = "format", type = MyArgumentType.class)
 *     }
 * 
 */
public @interface Node {

    /**
     * The key used to retrieve this argument in-code
     */
    String name() default "";

    /**
     * Optional alias for name used for declaring literal argument types.
     *      *     branch = @Node("exact")
     * 
     */
    String value() default "";

    /**
     * Whether the given argument is optional. When this value is true, the
     * command will be able to execute before reaching this node.
     *
     * @see CommandContextWrapper#getOptional
     */
    boolean optional() default false;

    // Chose one

    /**
     * A single argument type which will parse the value for this node. This type
     * must have a no-argument constructor to be valid. Otherwise, you must create
     * a new {@link ArgumentSupplier} class.
     *      *     branch = @Node(name = "a", type = ItemArgument.class)
     * 
     */
    Class>[] type() default {};

    /**
     * A single argument supplier which provides information about argument type
     * and suggestions needed for this node. Note that this type must provide a
     * no-argument constructor to be valid.
     *      *     branch = @Node(name = "b", descriptor = ArgumentSuppliers.XjsFile.class)
     * 
     */
    Class>[] descriptor() default {};

    /**
     * A single element type which will generate a registry argument. Note that,
     * on the Forge platform, this argument will pull from the Forge registries.
     *      *     branch = @Node(name = "feature", registry = Feature.class)
     * 

     *     This can be used as:
     * 
     *     /<mod> <cmd> minecraft:ore_feature
     * 
     */
    Class[] registry() default {};

    /**
     * A single integer range for the current node.
     *      *     branch = @Node(name = "x", intRange = @IntRange(max = 5))
     * 
     */
    IntRange[] intRange() default {};

    /**
     * A single decimal range for the current node.
     *      *     branch = @Node(name = "y", doubleRange = @DoubleRange(min = -1.0, max = 1.0))
     * 
     */
    DoubleRange[] doubleRange() default {};

    /**
     * Converts this argument node into a boolean argument type.
     *      *     branch = @Node(name = "toggle", isBoolean = true)
     * 
     */
    boolean isBoolean() default false;

    /**
     * A single string value type for the current node.
     *      *     branch = @Node(name = "text", stringValue = @StringValue(type = Type.GREEDY))
     * 
     */
    StringValue[] stringValue() default {};

    /**
     * A single enum value type for the current node.
     *      *     branch = @Node(name = "stage", enumValue = GenerationStep.Decoration.class)
     * 
     */
    Class>[] enumValue() default {};

    /**
     * Converts the given node into a list argument which can be repeated up to a
     * maximum number of 32 times. This node must either be the last argument in
     * the branch or be followed by a literal argument and then any other
     * required argument type.
     *      *     branches = {
     *         @Node(name = "numbers", intVal = @IntRange(max = 100), intoList = @ListInfo),
     *         @Node(name = "in"),
     *         @Node(name = "format", descriptor = MyArgumentSupplier.class)
     *     }
     * 
     */
    ListInfo intoList() default @ListInfo(useList = false);

    @interface IntRange {
        int min() default 0;
        int max() default Integer.MAX_VALUE;
    }

    @interface DoubleRange {
        double min() default 0.0;
        double max() default Double.MAX_VALUE;
    }

    @interface StringValue {
        Type value() default Type.WORD;
        enum Type { STRING, GREEDY, WORD }
    }

    @interface ListInfo {
        boolean useList() default true;
        int size() default ListArgumentBuilder.MAX_LIST_DEPTH;
    }
}