com.llamalad7.mixinextras.sugar.Local Maven / Gradle / Ivy

Go to download
package com.llamalad7.mixinextras.sugar;

import com.llamalad7.mixinextras.expression.Definition;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * These docs are for using @Local as a sugar. For its use in expressions, see {@link Definition}.
 * 
 * Allows you to capture local variables wherever you need them. The annotated parameter's type must either match the
 * target variable's type, or be the corresponding
 * {@link com.llamalad7.mixinextras.sugar.ref.LocalRef LocalRef}
 * type. In the latter case you can both read from and write to the target variable.
 * 

 * Targeting the variables can be done in 2 ways:
 * 

 *     Explicit Mode: The variable to target is determined by {@code ordinal}, {@code index} or {@code name}.
 *     Implicit Mode: You don't specify any of the above. If there is exactly one variable of the targeted type
 *     available, that will be targeted. If not, an error is thrown.
 * 
 * See the wiki article for more info.
 */
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.CLASS)
public @interface Local {
    /**
     * Whether to print a table of the available variables so you can determine the right discriminators to use.
     * This will abort the injection.
     */
    boolean print() default false;

    /**
     * The index of the local variable by type. E.g. if there are 3 {@code String} variables, an ordinal of 2 would
     * target the 3rd one.
     */
    int ordinal() default -1;

    /**
     * The LVT index of the local variable. Get this from the bytecode or using {@link Local#print}. This is generally
     * more brittle than {@code ordinal}.
     */
    int index() default -1;

    /**
     * Names of the local variable. This will not work on obfuscated code like Minecraft. For targeting
     * unobfuscated code this is normally the least brittle option.
     */
    String[] name() default {};

    /**
     * Whether only the method's parameters should be included. This makes the capture more efficient.
     */
    boolean argsOnly() default false;

    /**
     * Specifies the type of this local. Only for use in {@link Definition}s.
     */
    Class type() default void.class;
}