Package: groovy.transform.stc

## [Java] Class MapEntryOrKeyValue

- groovy.transform.stc.MapEntryOrKeyValue

-     public class MapEntryOrKeyValue
      extends ClosureSignatureHint

  A special hint which handles a common use case in the Groovy methods that work on maps. In case of an iteration on a list of map entries, you often want the user to be able to work either on a Entry map entry or on a key,value pair.

  The result is a closure which can have the following forms:

  - `{ key, value `->` ... }` where key is the key of a map entry, and value the corresponding value
  - `{ entry `->` ... }` where entry is a Entry map entry
  - `{ ... }` where it is an implicit Entry map entry

  This hint handles all those cases by picking the generics from the first argument of the method (by default).

  The options array is used to modify the behavior of this hint. Each string in the option array consists of a key=value pair.

  - argNum=index of the parameter representing the map (by default, 0)
  - index=true or false, by default false. If true, then an additional "int" parameter is added, for "withIndex" variants
  `void doSomething(String str, Map<K,>V map, @ClosureParams(value=MapEntryOrKeyValue.class,options="argNum=1") Closure c) { ... }`

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public List<ClassNode>` | `getClosureSignatures(MethodNode node, SourceUnit sourceUnit, CompilationUnit compilationUnit, String[] options, ASTNode usage)` Subclasses should implement this method, which returns the list of accepted closure signatures. The compiler will call this method each time, in a source file, a method call using a closure literal is encountered and that the target method has the corresponding Closure parameter annotated with ClosureParams. So imagine the following code needs to be compiled: `@groovy.transform.TypeChecked void doSomething() { println ['a','b'].collect { it.toUpperCase() } }` The collect method accepts a closure, but normally, the type checker doesn't have enough type information in the sole DefaultGroovyMethods.collect method signature to infer the type of it. With the annotation, it will now try to find an annotation on the closure parameter. If it finds it, then an instance of the hint class is created and the type checker calls it with the following arguments: the method node corresponding to the target method (here, the DefaultGroovyMethods.collect method the (optional) list of options found in the annotation Now, the hint instance can return the list of expected parameters. Here, it would have to say that the collect method accepts a closure for which the only argument is of the type of the first generic type of the first argument. With that type information, the type checker can now infer that the type of it is String, because the first argument (here the receiver of the collect method) is a List<String> Subclasses are therefore expected to return the signatures according to the available context, which is only the target method and the potential options. Parameters: `node` - the method node for which a Closure parameter was annotated with ClosureParams `sourceUnit` - the source unit of the file being compiled `compilationUnit` - the compilation unit of the file being compiled `options` - the options, corresponding to the ClosureParams.options found on the annotation `usage` - the AST node, in the compiled file, which triggered a call to this method. Normally only used for logging/error handling Returns: a non-null list of signature, where a signature corresponds to an array of class nodes, each of them matching a parameter.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class ClosureSignatureHint` | `findClassNode, getClosureSignatures, pickGenericType, pickGenericType`

- - ### Method Detail

    - #### public List<ClassNode> getClosureSignatures(MethodNode node, SourceUnit sourceUnit, CompilationUnit compilationUnit, String[] options, ASTNode usage)

      Subclasses should implement this method, which returns the list of accepted closure signatures.

      The compiler will call this method each time, in a source file, a method call using a closure literal is encountered and that the target method has the corresponding Closure parameter annotated with ClosureParams. So imagine the following code needs to be compiled:

      `@groovy.transform.TypeChecked void doSomething() { println ['a','b'].collect { it.toUpperCase() } }`

      The collect method accepts a closure, but normally, the type checker doesn't have enough type information in the sole DefaultGroovyMethods.collect method signature to infer the type of it. With the annotation, it will now try to find an annotation on the closure parameter. If it finds it, then an instance of the hint class is created and the type checker calls it with the following arguments:

      - the method node corresponding to the target method (here, the DefaultGroovyMethods.collect method
      - the (optional) list of options found in the annotation

      Now, the hint instance can return the list of expected parameters. Here, it would have to say that the collect method accepts a closure for which the only argument is of the type of the first generic type of the first argument.

      With that type information, the type checker can now infer that the type of it is String, because the first argument (here the receiver of the collect method) is a List<String>

      Subclasses are therefore expected to return the signatures according to the available context, which is only the target method and the potential options.

      Parameters:
        `node` - the method node for which a Closure parameter was annotated with ClosureParams
        `sourceUnit` - the source unit of the file being compiled
        `compilationUnit` - the compilation unit of the file being compiled
        `options` - the options, corresponding to the ClosureParams.options found on the annotation
        `usage` - the AST node, in the compiled file, which triggered a call to this method. Normally only used for logging/error handling
      Returns:
        a non-null list of signature, where a signature corresponds to an array of class nodes, each of them matching a parameter.