mirror of
https://github.com/LegacyModdingMC/UniMix.git
synced 2026-11-21 23:12:11 +00:00
Some more minor javadoc improvements, update README
This commit is contained in:
1 parent
e9f7d752f2
commit
4e4c72ee22
3 files changed
+143
-30
No files matched your search
@@ -78,15 +78,63 @@ import com.google.common.collect.ImmutableList.Builder;
|
||||
* using intersection (and) or union (or) relationships to allow multiple
|
||||
* strategies to be easily combined.</p>
|
||||
*
|
||||
* <p>You are free to create your own injection point subclasses, but take note
|
||||
* that it <b>is allowed</b> for a single InjectionPoint instance to be used for
|
||||
* multiple injections and thus implementing classes MUST NOT cache the insn
|
||||
* list, event, or nodes instance passed to the {@link #find find} method, as
|
||||
* each call to {@link #find find} must be considered a separate functional
|
||||
* contract and the InjectionPoint's lifespan is not linked to the discovery
|
||||
* lifespan, therefore it is important that the InjectionPoint implementation is
|
||||
* fully <b>stateless</b> and that calls to {@link #find find} are idempotent.
|
||||
* </p>
|
||||
* <h4>Built-in Injection Points</h4>
|
||||
*
|
||||
* <p>The following built-in Injection Points are available:</p>
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@link MethodHead HEAD} - Selects the first insn</li>
|
||||
* <li>{@link BeforeReturn RETURN} - Selects RETURN insns</li>
|
||||
* <li>{@link BeforeFinalReturn TAIL} - Selects the last RETURN insn</li>
|
||||
* <li>{@link BeforeInvoke INVOKE} - Selects method invocations</li>
|
||||
* <li>{@link AfterInvoke INVOKE_ASSIGN} - Selects STORE insns after method
|
||||
* invocations which return a value</li>
|
||||
* <li>{@link BeforeFieldAccess FIELD} - Selects field access insns</li>
|
||||
* <li>{@link BeforeNew NEW} - Selects object constructions</li>
|
||||
* <li>{@link BeforeStringInvoke INVOKE_STRING} - Selects method invocations
|
||||
* where a specific string is passed to the invocation.</li>
|
||||
* <li>{@link JumpInsnPoint JUMP} - Selects branching (jump) instructions</li>
|
||||
* <li>{@link BeforeConstant CONSTANT} - Selects constant values</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>Additionally, the two special injection points are available which are
|
||||
* only supported for use with {@link ModifyVariable @ModifyVariable}:</p>
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@link BeforeLoadLocal LOAD} - Selects xLOAD insns matching the <tt>
|
||||
* ModifyVariable</tt> discriminators.</li>
|
||||
* <li>{@link AfterStoreLocal STORE} - Selects xSTORE insns matching the <tt>
|
||||
* ModifyVariable</tt> discriminators.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>See the javadoc for each type for more details on the scheme used by each
|
||||
* injection point.</p>
|
||||
*
|
||||
* <h4>Custom Injection Points</h4>
|
||||
*
|
||||
* <p>You are free to create your own injection point subclasses. Once defined,
|
||||
* they can be used by your mixins in one of two ways:</p>
|
||||
*
|
||||
* <ol>
|
||||
* <li>Specify the fully-qualified name of the injection point class in the
|
||||
* {@link At#value @At.value}.</li>
|
||||
* <li>Decorate your injection point class with {@link AtCode @AtCode}
|
||||
* annotation which specifies a namespace and shortcode for the injection
|
||||
* point, and register the class in your mixin config. You can then specify
|
||||
* the namespaced code (eg. <tt>MYMOD:CUSTOMPOINT</tt>) in {@link At#value
|
||||
* @At.value}.</li>
|
||||
* </ol>
|
||||
*
|
||||
* <p>When writing custom injection points, note that the general contract of
|
||||
* injection points is that they be entirely - or at least behaviourally -
|
||||
* stateless. It <b>is allowed</b> for a single InjectionPoint instance to be
|
||||
* used by the mixin processor for multiple injections and thus implementing
|
||||
* classes <em>MUST NOT</em> cache the insn list, event, or nodes instance
|
||||
* passed to the {@link #find find} method, as each call to {@link #find find}
|
||||
* must be considered a separate contract and the InjectionPoint's lifespan is
|
||||
* not linked to the discovery lifespan. It is therefore important that the
|
||||
* InjectionPoint implementation is fully stateless and that calls to
|
||||
* {@link #find find} are idempotent.</p>
|
||||
*/
|
||||
public abstract class InjectionPoint {
|
||||
|
||||
|
||||
@@ -30,6 +30,8 @@ import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
import org.spongepowered.asm.mixin.MixinEnvironment.Option;
|
||||
import org.spongepowered.asm.mixin.injection.modify.AfterStoreLocal;
|
||||
import org.spongepowered.asm.mixin.injection.modify.BeforeLoadLocal;
|
||||
import org.spongepowered.asm.mixin.injection.selectors.ITargetSelector;
|
||||
import org.spongepowered.asm.mixin.injection.throwables.InjectionError;
|
||||
import org.spongepowered.asm.mixin.injection.throwables.InvalidInjectionException;
|
||||
@@ -57,7 +59,9 @@ import org.spongepowered.asm.util.ConstraintParser.Constraint;
|
||||
*
|
||||
* <p>The injector has two operating modes, <em>explicit</em> and <em>implicit
|
||||
* </em>, and can operate either on the entire LVT or on the {@link #argsOnly
|
||||
* ethod arguments only}.</p>
|
||||
* method arguments only}.</p>
|
||||
*
|
||||
* <h4>Explicit mode</h4>
|
||||
*
|
||||
* <p>In <em>explicit</em> mode, the variable to capture can be specified by
|
||||
* specifying values for the discriminator arguments {@link #ordinal},
|
||||
@@ -65,12 +69,32 @@ import org.spongepowered.asm.util.ConstraintParser.Constraint;
|
||||
* order to attempt to locate the variable to capture. If no local variable
|
||||
* matches any discriminators, the capture fails.</p>
|
||||
*
|
||||
* <h4>Implicit mode</h4>
|
||||
*
|
||||
* <p>If no values for the capture discrimiators are specified, the injector
|
||||
* operates in <em>implicit</em> mode. If exactly one variable of the capture
|
||||
* type exists in the target LVT, then capture will succeed. However, if more
|
||||
* than one variable of the required type is encountered in the LVT then an
|
||||
* {@link InvalidInjectionException} is thrown.</p>
|
||||
*
|
||||
* <h4>Context-sensitive injection points</h4>
|
||||
*
|
||||
* <p>Normally the {@link InjectionPoint injection points} specified by {@link
|
||||
* #at} are independent of the injector being used. With <tt>ModifyVariable</tt>
|
||||
* there are two special injection points which consume the discriminator from
|
||||
* the annotation:</p>
|
||||
*
|
||||
* <ul>
|
||||
* <li>{@link BeforeLoadLocal LOAD} - matches <tt>xLOAD</tt> insns <em>for
|
||||
* the variable matched by the discriminator</em> in the target method.</li>
|
||||
* <li>{@link AfterStoreLocal STORE} - matches <tt>xSTORE</tt> insns <em>for
|
||||
* the variable matched by the discriminator</em> in the target method.</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>See the javadoc for each injection point for details.</p>
|
||||
*
|
||||
* <h4>Notes</h4>
|
||||
*
|
||||
* <p>Like other injectors, the callback signature can optionally include the
|
||||
* target method arguments by simply appending them to the handler method
|
||||
* signature.</p>
|
||||
@@ -108,7 +132,8 @@ public @interface ModifyVariable {
|
||||
* An {@link At} annotation which describes the {@link InjectionPoint} in
|
||||
* the target method.
|
||||
*
|
||||
* @return {@link At} which identifies the target method invocation
|
||||
* @return {@link At} which identifies the location to inject inside the
|
||||
* target method.
|
||||
*/
|
||||
public At at();
|
||||
|
||||
|
||||
Reference in new issue
Block a user