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

## Interface ITargetSelector

- All Known Subinterfaces:
    `ITargetSelectorByName`, `ITargetSelectorConstructor`, `ITargetSelectorDynamic`, `ITargetSelectorRemappable`
  All Known Implementing Classes:
    `DynamicSelectorDesc`, `InvalidSelector`, `MemberInfo`, `MemberMatcher`

      public interface ITargetSelector

  Target Selectors are used to identify target members in a class, with the criteria for selection being specified in a single string, effectively defining the query parameters. They are used by injectors and other components which need to identify a target element using a string.

  ### Explicit Target Selectors

  Explicit Target Selectors are handled internally using `MemberInfo` structs, see the javadoc for `MemberInfo` for the supported variants and examples.

  > `// An example explicit target selector
  > Lfully/qualified/OwnerClass;methodName*(III)V`

  ### Pattern Target Selectors (Regex Selectors)

  Pattern Target Selectors are handled internally using `MemberMatcher`, see the javadoc for `MemberMatcher` for the supported variants and examples. Pattern Selectors always end with a forward slash character.

  > `// Matches candidates ending with "Bar" and which take a single int
  > /bar$/ desc=/^\\(I\\)/
  > // The same example but with "name" explicitly specified (optional)
  > name=/bar$/ desc=/^\\(I\\)/
  > // Matches candidates whose name contains "Entity"
  > /Entity/`

  ### Dynamic Target Selectors

  Dynamic Target Selectors can be built-in or user-supplied types with their own specialised syntax or behaviour.

  #### Built-in dynamic selectors:

  - `@Desc Selector`: Selector which uses descriptors defined in `@Desc` annotations

  Dynamic selectors are specified in the following format, and can be recognised by the fact that the selector string starts with "`@`":

  >      // Built-in dynamic selector without argument string
  >      @SelectorId

  >      // Built-in dynamic selector with empty argument string
  >      @SelectorId()

  >      // Built-in dynamic selector with argument
  >      @SelectorId(custom,argument,string,in,any,format)

  >      // User-provided dynamic selector with argument. Note that
  >      // user-provided dynamic selectors are namespaced to avoid conflicts.
  >      @Namespace:SelectorId(some arguments)

  The exact format of the argument string is specified by the dynamic selector itself, consult the documentation for the dynamic selector you are using for details on the required format.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `ITargetSelector.Configure` | Available selector reconfigurations

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ITargetSelector` | `attach​(ISelectorContext context)` | Attach this selector to the specified context.
    `ITargetSelector` | `configure​(ITargetSelector.Configure request, java.lang.String... args)` | Configure and return a modified version of this selector by consuming the supplied arguments.
    `int` | `getMaxMatchCount()` | Maximum number of candidates this selector can match
    `int` | `getMinMatchCount()` | Minimum number of candidates this selector must match
    `<TNode> MatchResult` | `match​(ElementNode<TNode> node)` | Test whether this selector matches the supplied element node
    `ITargetSelector` | `next()` | Get the next target selector in this path (or `null` if this selector is the last selector in the chain.
    `ITargetSelector` | `validate()` | Perform basic sanity-check validation of the selector, checks that the parsed out parameters are basically sane

- - ### Method Detail

    - #### next

          ITargetSelector next()

      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

    - #### configure

          ITargetSelector configure​(ITargetSelector.Configure request,
                                    java.lang.String... args)

      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.

      Parameters:
        `request` - Requested operation
        `args` - Configuration arguments
      Returns:
        Configured selector, may return this selector if the specified condition is already satisfied

    - #### validate

          ITargetSelector validate()
                            throws InvalidSelectorException

      Perform basic sanity-check validation of the selector, checks that the parsed out parameters are basically sane
      Returns:
        fluent (this selector)
      Throws:
        `InvalidSelectorException` - if any sanity check fails

    - #### attach

          ITargetSelector attach​(ISelectorContext context)
                          throws InvalidSelectorException

      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.
      Parameters:
        `context` - Context to attach to
      Returns:
        Attached selector
      Throws:
        `InvalidSelectorException`

    - #### getMinMatchCount

          int getMinMatchCount()

      Minimum number of candidates this selector must match

    - #### getMaxMatchCount

          int getMaxMatchCount()

      Maximum number of candidates this selector can match

    - #### match

          <TNode> MatchResult match​(ElementNode<TNode> node)

      Test whether this selector matches the supplied element node
      Type Parameters:
        `TNode` - node type
      Parameters:
        `node` - node node to test
      Returns:
        true if this selector can match the supplied field