Package org.spongepowered.asm.mixin.injection.selectors.dynamic

Class DynamicSelectorDesc

java.lang.Object
org.spongepowered.asm.mixin.injection.selectors.dynamic.DynamicSelectorDesc
All Implemented Interfaces:
ITargetSelector, ITargetSelectorByName, ITargetSelectorDynamic
public class DynamicSelectorDesc extends Object implements ITargetSelectorDynamic, ITargetSelectorByName
A Target Selector which matches candidates using descriptors contained in @Desc annotations. The descriptor annotations may be local, or may be applied to the method or even the owning mixin using user-specified ids, or implicit coordinates based on the relative location of the consumer. eg. an @At annotation and the @Desc annotation itself, which might be on a parent element for convenience.

See @Desc for the specific syntax of descriptor annotations.

Local Descriptors

Some annotations can use @Desc selectors directly, namely @At (specified in @At.desc) and all Injector annotations (specified in target - for example @Inject.target). In these cases it is not necessary to specify an id for the descriptor since the usage is inferred from context.

Resolved Descriptors

Descriptors can also be placed as annotations on the mixin method or the mixin class, thus allowing descriptors to be re-used by multiple consumers. For example where several injectors target the same method, the descriptor can be placed on the mixin itself and consumed by id. In this situation it is necessary to specify an id for the descriptor and specify the chosen id as a selector string:

@Mixin(TargetClass.class)
@Desc(id = "foo", value = "getFoo", args = { int.class })
abstract class MyMixin {

    @Inject(target = "@Desc(foo)", at = @At("RETURN"))
    void myHandlerMethod(int arg, CallbackInfo ci) {
      ...
    }

}

Note that the id string can be anything you wish, but is matched case-insensitively and must be non-empty, so feel free to be as descriptive as you wish.

Implicit coordinates

As an alternative to specifying an explicit descriptor id for descriptors, it is also possible to use implicit coordinates generated using the location of the consumer. To do so, use the selector "@Desc" with no arguments and give the descriptor an id which corresponds to the coordinate of the consumer:

In this example, the coordinate of the @At annotation, "at" is used as the descriptor id.

    @Desc(id = "at", value = "theMethodName", args = { String.class }, ret = boolean.class)
    @Inject(method = "targetMethod()V", at = @At(value = "INVOKE" target = "@Desc"))
    void myHandlerMethod(int arg, CallbackInfo ci) {
      ...
    }

As the resolver widens its search it adds new components to the start of the implicit coordinate which match the element, separated by dots. For example @At annotations inside a @Slice will first resolve as (local coordinate) from, followed by slice.from, and finally handlerMethodName.slice.from. This allows implicit coordinates to be used up to the mixin level as in the first example.

@Mixin(TargetClass.class)
@Desc(id = "myHandlerMethod.at", value = "theMethodName", args = { String.class }, ret = boolean.class)
@Desc(id = "myHandlerMethod.method", value = "getFoo", args = { int.class })
abstract class MyMixin {

    @Inject(method = "@Desc", at = @At(value = "INVOKE" target = "@Desc"))
    void myHandlerMethod(int arg, CallbackInfo ci) {
      ...
    }

To view the coordinates used to resolve the descriptor for a particular element, use the special id "?" in the selector:

    @Inject(method = "@Desc", at = @At(value = "INVOKE" target = "@Desc(?)"))
    void myHandler(int arg, CallbackInfo ci) {

This will cause the resolver to pretty-print the considered coordinates and elements into the console:

/*****************************************************/
/* Coordinate    Search Element       Detail         */
/*****************************************************/
/* at            @At                  @At.desc       */
/* at            myHandler            method         */
/* myhandler.at  mixins.json:MyMixin  mixin          */
/* myhandler.at  @Redirect            @Redirect.desc */
/* myhandler.at  myhandler            method         */
/*****************************************************/

Don't worry that some combinations of coordinate and element are not possible (for example there is no member desc on @At). The resolver doesn't know that and scans each visited element for members it supports.

  • Constructor Details

  • Method Details

    • parse

      public static DynamicSelectorDesc parse(String input, ISelectorContext context)
      Parse a descriptor selector from the supplied input. The input is treated as a descriptor id to be resolved, or if empty uses implicit coordinates from the selection context
      Parameters:
      input - ID string, can be empty
      context - Selector context
      Returns:
      parsed selector

    • parse

      public static DynamicSelectorDesc parse(IAnnotationHandle desc, ISelectorContext context)
      Convert the supplied annotation into a selector instance
      Parameters:
      desc - Annotation to parse
      context - Selector context
      Returns:
      selector

    • resolve

      public static DynamicSelectorDesc resolve(ISelectorContext context)
      Resolve a descriptor selector from the supplied context only, implicit coordinates are used.
      Parameters:
      context - Selector context
      Returns:
      parsed selector

    • of

      public static DynamicSelectorDesc of(IAnnotationHandle desc, ISelectorContext context)
      Convert the supplied annotation into a selector instance
      Parameters:
      desc - Annotation to parse
      context - Selector context
      Returns:
      selector

    • of

      public static DynamicSelectorDesc of(IResolvedDescriptor desc)
      Convert the supplied annotation into a selector instance
      Parameters:
      desc - Resolved descriptor
      Returns:
      selector

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getId

      public String getId()

    • getOwner

      public String getOwner()
      Description copied from interface: ITargetSelectorByName
      Get the member owner, can be null
      Specified by:
      getOwner in interface ITargetSelectorByName

    • getName

      public String getName()
      Description copied from interface: ITargetSelectorByName
      Get the member name, can be null
      Specified by:
      getName in interface ITargetSelectorByName

    • getArgs

      public org.objectweb.asm.Type[] getArgs()

    • getReturnType

      public org.objectweb.asm.Type getReturnType()

    • getDesc

      public String getDesc()
      Description copied from interface: ITargetSelectorByName
      Get the member descriptor, can be null
      Specified by:
      getDesc in interface ITargetSelectorByName

    • toDescriptor

      public String toDescriptor()
      Description copied from interface: ITargetSelectorByName
      Get a representation of this selector as a complete descriptor
      Specified by:
      toDescriptor in interface ITargetSelectorByName

    • validate

      public ITargetSelector validate() throws InvalidSelectorException
      Description copied from interface: ITargetSelector
      Perform basic sanity-check validation of the selector, checks that the parsed out parameters are basically sane
      Specified by:
      validate in interface ITargetSelector
      Returns:
      fluent (this selector)
      Throws:
      InvalidSelectorException - if any sanity check fails

    • next

      public ITargetSelector next()
      Description copied from interface: ITargetSelector
      Get the next target selector in this path (or null if this selector is the last selector in the chain. Called at recurse points in the subject in order to match against the child subject.

      Can return null

      Specified by:
      next in interface ITargetSelector

    • next

      protected ITargetSelector next(int index)

    • configure

      public ITargetSelector configure(ITargetSelector.Configure request, String... args)
      Description copied from interface: ITargetSelector
      Configure and return a modified version of this selector by consuming the supplied arguments. Results from this method should be idempotent in terms of the configuration of the returned object, but do not have to necessarily return the same object if the callee already matches the supplied configuration, or if the requested mutation is not supported by the selector, though this is generally the case.

      In other words, calling configure(Configure.ORPHAN) when this object is already an orphan or does not support orphaning, may simply return this object, or might return an identically-configured copy.

      Must not return null, defaults to returning unmodified selector.

      Specified by:
      configure in interface ITargetSelector
      Parameters:
      request - Requested operation
      args - Configuration arguments
      Returns:
      Configured selector, may return this selector if the specified condition is already satisfied

    • attach

      public ITargetSelector attach(ISelectorContext context) throws InvalidSelectorException
      Description copied from interface: ITargetSelector
      Attach this selector to the specified context. Should return this selector unmodified if all is well, or a new selector to be used for further processing of the supplied context. If the supplied context is invalid, an InvalidSelectorException is thrown.
      Specified by:
      attach in interface ITargetSelector
      Parameters:
      context - Context to attach to
      Returns:
      Attached selector
      Throws:
      InvalidSelectorException

    • getMinMatchCount

      public int getMinMatchCount()
      Description copied from interface: ITargetSelector
      Minimum number of candidates this selector must match
      Specified by:
      getMinMatchCount in interface ITargetSelector

    • getMaxMatchCount

      public int getMaxMatchCount()
      Description copied from interface: ITargetSelector
      Maximum number of candidates this selector can match
      Specified by:
      getMaxMatchCount in interface ITargetSelector

    • matches

      public MatchResult matches(String owner, String name, String desc)
      Description copied from interface: ITargetSelectorByName
      Test whether this selector matches the supplied values. Null values are ignored.
      Specified by:
      matches in interface ITargetSelectorByName
      Parameters:
      owner - Owner to compare with, null to skip
      name - Name to compare with, null to skip
      desc - Signature to compare with, null to skip
      Returns:
      true if all non-null values in this reference match non-null arguments supplied to this method

    • match

      public <TNode> MatchResult match(ElementNode<TNode> node)
      Description copied from interface: ITargetSelector
      Test whether this selector matches the supplied element node
      Specified by:
      match in interface ITargetSelector
      Type Parameters:
      TNode - node type
      Parameters:
      node - node node to test
      Returns:
      true if this selector can match the supplied field