com.llamalad7.mixinextras.injector.wrapoperation.WrapOperation Maven / Gradle / Ivy

Go to download

package com.llamalad7.mixinextras.injector.wrapoperation;

import org.spongepowered.asm.mixin.injection.At;
import org.spongepowered.asm.mixin.injection.Constant;
import org.spongepowered.asm.mixin.injection.Slice;

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

/**
 * Allows you to wrap a
 * {@link org.spongepowered.asm.mixin.injection.points.BeforeInvoke method call},
 * {@link org.spongepowered.asm.mixin.injection.points.BeforeFieldAccess field get/set},
 * {@link org.spongepowered.asm.mixin.injection.Constant instanceof check}, or
 * {@link org.spongepowered.asm.mixin.injection.points.BeforeNew object instantiation}.
 * 
 * Your handler method receives the targeted instruction's arguments and an {@link Operation} representing the operation
 * being wrapped (optionally followed by the enclosing method's parameters).
 * You should return the same type as the wrapped operation does:
 * 
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 *   
 *     
 *     
 *   
 * Targeted operation Handler signature
Non-static method call private (static) ReturnType handler(ReceiverType instance, <params of the original
 *     call>, Operation<ReturnType> original)
super. method call private (static) ReturnType handler(ThisClass instance, <params of the original
 *     call>, Operation<ReturnType> original)
Static method call private (static) ReturnType handler(<params of the original call>,
 *     Operation<ReturnType> original)
Non-static field get private (static) FieldType handler(ReceiverType instance,
 *     Operation<FieldType> original)
Static field get private (static) FieldType handler(Operation<FieldType> original)
Non-static field write private (static) void handler(ReceiverType instance, FieldType newValue,
 *     Operation<Void> original)
Static field write private (static) void handler(FieldType newValue, Operation<Void> original)
instanceof check private (static) boolean handler(Object obj, Operation<Boolean> original)
Object instantiation private (static) ObjectType handler(<params of the original ctor>,
 *     Operation<ObjectType> original)
 * When {@code call}ing the {@code original}, you must pass everything before the {@code original} in your handler's
 * parameters. You can optionally pass different values to change what the {@code original} uses.
 * 
 * This chains when used by multiple people, unlike
 * {@link org.spongepowered.asm.mixin.injection.Redirect @Redirect} and
 * {@link org.spongepowered.asm.mixin.injection.ModifyConstant @ModifyConstant}.
 * 

 * If you never call the {@code original} then you risk other people's code being silently ignored.
 * 
 * See the wiki article for more info.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface WrapOperation {
    String[] method();

    /**
     * Selector for targeting method calls, field gets/sets and object instantiations.
     */
    At[] at() default {};

    /**
     * Selector for targeting `instanceof`s.
     */
    Constant[] constant() default {};

    Slice[] slice() default {};

    boolean remap() default true;

    int require() default -1;

    int expect() default 1;

    int allow() default -1;
}

Targeted operation	Handler signature
Non-static method call	`private (static) ReturnType handler(ReceiverType instance, <params of the original * call>, Operation<ReturnType> original)`
`super.` method call	`private (static) ReturnType handler(ThisClass instance, <params of the original * call>, Operation<ReturnType> original)`
Static method call	`private (static) ReturnType handler(<params of the original call>, * Operation<ReturnType> original)`
Non-static field get	`private (static) FieldType handler(ReceiverType instance, * Operation<FieldType> original)`
Static field get	`private (static) FieldType handler(Operation<FieldType> original)`
Non-static field write	`private (static) void handler(ReceiverType instance, FieldType newValue, * Operation<Void> original)`
Static field write	`private (static) void handler(FieldType newValue, Operation<Void> original)`
`instanceof` check	`private (static) boolean handler(Object obj, Operation<Boolean> original)`
Object instantiation	`private (static) ObjectType handler(<params of the original ctor>, * Operation<ObjectType> original)`