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

Class MemberInfo

  • All Implemented Interfaces:
    ITargetSelector, ITargetSelectorByName, ITargetSelectorConstructor, ITargetSelectorRemappable
    public final class MemberInfo
extends java.lang.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 Detail

      • MemberInfo

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

      • MemberInfo

        public MemberInfo​(java.lang.String name,
                  java.lang.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​(java.lang.String name,
                  java.lang.String owner,
                  java.lang.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​(java.lang.String name,
                  java.lang.String owner,
                  java.lang.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​(java.lang.String name,
                  java.lang.String owner,
                  java.lang.String desc,
                  Quantifier matches,
                  java.lang.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​(java.lang.String name,
                  java.lang.String owner,
                  java.lang.String desc,
                  Quantifier matches,
                  java.lang.String tail,
                  java.lang.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 Detail

      • 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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • toSrg

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

      • toDescriptor

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

      • toCtorDesc

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

      • 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>

      • 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​(java.lang.String owner,
                           java.lang.String name,
                           java.lang.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​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • configure

        public ITargetSelector configure​(ITargetSelector.Configure request,
                                 java.lang.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

      • 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​(java.lang.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