NamedVariant (groovy 2.5.0 API)
Date: 2018-05-27

Package: groovy.transform

## [Java] Annotation Type NamedVariant

- groovy.transform.NamedVariant

- Allows construction of a named-arg equivalent method or constructor. The method or constructor will have at least a first argument of type `Map` and may have more arguments. As such, it can be called using Groovy's named-arg syntax. The original method/constructor is retained and is called by the generated method/constructor. One benefit of this approach is the potential for improved type checking. The annotated "tuple" method/constructor can be type rich and will be checked as such during normal compilation. The generated method/constructor using the map argument will be named-argument friendly but the map also hides type information. The generated method however contains no business logic so the chance of errors is minimal. Any arguments identified as named arguments will be supplied as part of the map. Any additional arguments are supplied in the normal tuple style. Named arguments are identified in one of three ways:

  1. Use one or more `@NamedParam` annotations to explicitly identify such arguments
  2. Use one or more `@NamedDelegate` annotations to explicitly identify such arguments as delegate arguments
  3. If no arguments with `@NamedParam` or `@NamedDelegate` annotations are found the first argument is assumed to be an implicit named delegate
  You can also mix and match the `@NamedParam` and `@NamedDelegate` annotations. Named arguments will be supplied via the map with their property name (configurable via annotation attributes within `@NamedParam`) being the key and value being the argument value. For named delegates, any properties of the delegate can become map keys. Duplicate keys across delegates or named parameters are not allowed. Delegate arguments must be compatible with Groovy's `as` cast operation from a `Map`. Here is an example using the implicit delegate approach.

       import groovy.transform.*

       @ToString(includeNames=true, includeFields=true)
       class Color {
           Integer r, g, b
       }

       @NamedVariant
       String foo(Color shade) {
           shade
       }

       def result = foo(g: 12, b: 42, r: 12)
       assert result.toString() == 'Color(r:12, g:12, b:42)'

  You could also explicitly annotate the `shade` argument with the `@NamedDelegate` annotation if you wanted. The generated method will be something like this:

       String foo(Map args) {
           return foo(args as Color)
       }

  The generated method/constructor retains the visibility and return type of the original method/constructor but the VisibilityOptions annotation can be added to customize the visibility. You could have the annotated method/constructor private for instance but have the generated one be public.
  See Also:
    VisibilityOptions
    NamedParam
    NamedDelegate
  Since:
    2.5.0

- - ### Element Summary

    Optional Element Summary
    Type | Name and Description
    --- | ---
    `String` | `visibilityId` If specified, must match the optional "id" attribute in an applicable `VisibilityOptions` annotation.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Element Detail

    - #### public String visibilityId

      If specified, must match the optional "id" attribute in an applicable `VisibilityOptions` annotation. @default Undefined.STRING