Package org.spongepowered.asm.mixin.injection.struct

Class MemberInfo

java.lang.Object
org.spongepowered.asm.mixin.injection.struct.MemberInfo
All Implemented Interfaces:
ITargetSelector, ITargetSelectorByName, ITargetSelectorConstructor, ITargetSelectorRemappable
public final class MemberInfo extends Object implements ITargetSelectorRemappable, ITargetSelectorConstructor

Struct which defines an Explcit Target selector, See ITargetSelector for other supported selector types. This struct is also used as a general-purpose information bundle about a member (method or field) parsed from a String token in another annotation, this is used where target members need to be specified as Strings in order to parse the String representation to something useful.

In general a MemberInfo consists of 4 parts, owner, name, quantifier and descriptor, all of which are optional:

  Owner Name Quantifier   Descriptor Resulting selector string
Method Lfully/qualified/OwnerClass; methodName {1,3}   (III)V Lfully/qualified/OwnerClass;methodName{1,3}(III)V
Field Lfully/qualified/OwnerClass; fieldName * : Ljava/lang/String; Lfully/qualified/OwnerClass;fieldName*:Ljava/lang/String;

Any part of the selector can be omitted, though they must appear in the correct order. Some examples:

// selects a method or field called func_1234_a, if there are multiple
// members with the same signature, matches the first occurrence
 func_1234_a

// selects a method or field called func_1234_a, if there are multiple
// members with matching name, matches all occurrences
func_1234_a*

// selects a method or field called func_1234_a, if there are multiple
// members with matching name, matches all occurrences, matching less than 1
// occurrence is an error condition
func_1234_a+

// selects a method or field called func_1234_a, if there are multiple
// members with matching name, matches up to 3 occurrences
func_1234_a{,3}

// selects a method or field called func_1234_a, if there are multiple
// members with matching name, matches exactly 3 occurrences, matching fewer
// than 3 occurrences is an error condition
func_1234_a{3}

// selects a method or field called func_1234_a, if there are multiple
// members with matching name, matches at least 3 occurrences, matching fewer
// than 3 occurrences is an error condition
func_1234_a{3,}

// selects all members of any type and descriptor
*

// selects the first member of any type and descriptor
{1}

// selects all methods which take 3 ints and return a bool
*(III)Z

// selects the first 2 methods which take a bool and return void
{2}(Z)V

// selects a method called func_1234_a which takes 3 ints and returns a bool
func_1234_a(III)Z

// selects a field called field_5678_z which is a String
field_5678_z:Ljava/lang/String;

// selects a ctor which takes a single String argument
<init>(Ljava/lang/String;)V

// selects a method called func_1234_a in class foo.bar.Baz
Lfoo/bar/Baz;func_1234_a

// selects a field called field_5678_z in class com.example.Dave
Lcom/example/Dave;field_5678_z

// selects a field called field_5678_z in class com.example.Dave
// which is of type String
Lcom/example/Dave;field_5678_z:Ljava/lang/String;

// selects a method called func_1234_a in class foo.bar.Baz which
// takes three doubles and returns void
Lfoo/bar/Baz;func_1234_a(DDD)V

// alternate syntax for the same
foo.bar.Baz.func_1234_a(DDD)V

Notes

  • All whitespace in the selector string is stripped before the selector is parsed.
  • Quantifiers for selectors can be used as a form of early validation (prior to injector require directives) that an injection point has matched a required number of targets or to limit the number of matches it can return.
  • The syntax for quantifiers is based on the syntax for quantifiers in regular expressions, though more limited. In particular:
    • No quantifer is equivalent to the regex ? quantifier, in that undecorated selectors can match {0,1}, this is for backward compatibility reasons. Likewise ? is not supported since it's implied. To require exactly one match use {1}.
    • The quantifiers * and + work the same as their regex counterparts.

  • Constructor Details

    • MemberInfo

      public MemberInfo(String name, Quantifier matches)
      ctor
      Parameters:
      name - Member name, must not be null
      matches - Quantifier specifying the number of matches required

    • MemberInfo

      public MemberInfo(String name, String owner, Quantifier matches)
      ctor
      Parameters:
      name - Member name, must not be null
      owner - Member owner, can be null otherwise must be in internal form without L;
      matches - Quantifier specifying the number of matches required

    • MemberInfo

      public MemberInfo(String name, String owner, String desc)
      ctor
      Parameters:
      name - Member name, must not be null
      owner - Member owner, can be null otherwise must be in internal form without L;
      desc - Member descriptor, can be null

    • MemberInfo

      public MemberInfo(String name, String owner, String desc, Quantifier matches)
      ctor
      Parameters:
      name - Member name, must not be null
      owner - Member owner, can be null otherwise must be in internal form without L;
      desc - Member descriptor, can be null
      matches - Quantifier specifying the number of matches required

    • MemberInfo

      public MemberInfo(String name, String owner, String desc, Quantifier matches, String tail)
      ctor
      Parameters:
      name - Member name, must not be null
      owner - Member owner, can be null otherwise must be in internal form without L;
      desc - Member descriptor, can be null
      matches - Quantifier specifying the number of matches required

    • MemberInfo

      public MemberInfo(String name, String owner, String desc, Quantifier matches, String tail, String input)
      ctor
      Parameters:
      name - Member name, must not be null
      owner - Member owner, can be null otherwise must be in internal form without L;
      desc - Member descriptor, can be null
      matches - Quantifier specifying the number of matches required

    • MemberInfo

      public MemberInfo(org.objectweb.asm.tree.AbstractInsnNode insn)
      Initialise a MemberInfo using the supplied insn which must be an instance of MethodInsnNode or FieldInsnNode.
      Parameters:
      insn - instruction node to copy values from

    • MemberInfo

      public MemberInfo(IMapping<?> mapping)
      Initialise a MemberInfo using the supplied mapping object
      Parameters:
      mapping - Mapping object to copy values from

  • Method Details

    • 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

    • 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

    • getDesc

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

    • 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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toSrg

      @Deprecated public String toSrg()
      Deprecated.
      use m.asMethodMapping().serialise() instead
      Return this MemberInfo as an SRG mapping
      Returns:
      SRG representation of this MemberInfo

    • toDescriptor

      public String toDescriptor()
      Returns this MemberInfo as a java-style descriptor
      Specified by:
      toDescriptor in interface ITargetSelectorByName

    • toCtorType

      public String toCtorType()
      Returns the constructor type represented by this MemberInfo
      Specified by:
      toCtorType in interface ITargetSelectorConstructor

    • toCtorDesc

      public String toCtorDesc()
      Returns the constructor descriptor represented by this MemberInfo, returns null if no descriptor is present.
      Specified by:
      toCtorDesc in interface ITargetSelectorConstructor

    • asMapping

      public IMapping<?> asMapping()
      Returns this MemberInfo as a MappingField or MappingMethod
      Specified by:
      asMapping in interface ITargetSelectorRemappable

    • asMethodMapping

      public MappingMethod asMethodMapping()
      Returns this MemberInfo as a mapping method
      Specified by:
      asMethodMapping in interface ITargetSelectorRemappable

    • asFieldMapping

      public MappingField asFieldMapping()
      Returns this MemberInfo as a mapping field
      Specified by:
      asFieldMapping in interface ITargetSelectorRemappable

    • isFullyQualified

      public boolean isFullyQualified()
      Description copied from interface: ITargetSelectorRemappable
      Get whether this reference is fully qualified
      Specified by:
      isFullyQualified in interface ITargetSelectorRemappable
      Returns:
      true if all components of this reference are non-null

    • isField

      public boolean isField()
      Get whether this MemberInfo is definitely a field, the output of this method is undefined if isFullyQualified() returns false.
      Specified by:
      isField in interface ITargetSelectorRemappable
      Returns:
      true if this is definitely a field

    • isConstructor

      public boolean isConstructor()
      Get whether this member represents a constructor
      Specified by:
      isConstructor in interface ITargetSelectorRemappable
      Returns:
      true if member name is <init>

    • isClassInitialiser

      public boolean isClassInitialiser()
      Get whether this member represents a class initialiser
      Specified by:
      isClassInitialiser in interface ITargetSelectorRemappable
      Returns:
      true if member name is <clinit>

    • isInitialiser

      public boolean isInitialiser()
      Get whether this member represents a constructor or class initialiser
      Specified by:
      isInitialiser in interface ITargetSelectorRemappable
      Returns:
      true if member name is <init> or <clinit>

    • validate

      public MemberInfo validate() throws InvalidSelectorException
      Perform ultra-simple validation of the descriptor, checks that the parts of the descriptor are basically sane.
      Specified by:
      validate in interface ITargetSelector
      Returns:
      fluent
      Throws:
      InvalidSelectorException - if any validation check fails

    • 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

    • 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

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • 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

    • move

      public ITargetSelectorRemappable move(String newOwner)
      Create a new version of this member with a different owner
      Specified by:
      move in interface ITargetSelectorRemappable
      Parameters:
      newOwner - New owner for this member

    • transform

      public ITargetSelectorRemappable transform(String newDesc)
      Create a new version of this member with a different descriptor
      Specified by:
      transform in interface ITargetSelectorRemappable
      Parameters:
      newDesc - New descriptor for this member

    • remapUsing

      public ITargetSelectorRemappable remapUsing(MappingMethod srgMethod, boolean setOwner)
      Create a remapped version of this member using the supplied method data
      Specified by:
      remapUsing in interface ITargetSelectorRemappable
      Parameters:
      srgMethod - SRG method data to use
      setOwner - True to set the owner as well as the name
      Returns:
      New MethodInfo with remapped values

    • parse

      public static MemberInfo parse(String input, ISelectorContext context)
      Parse a MemberInfo from a string
      Parameters:
      input - String to parse MemberInfo from
      context - Selector context for this parse request
      Returns:
      parsed MemberInfo

    • fromMapping

      public static MemberInfo fromMapping(IMapping<?> mapping)
      Return the supplied mapping parsed as a MemberInfo
      Parameters:
      mapping - mapping to parse
      Returns:
      new MemberInfo