Package: groovy.transform

## [Java] Annotation Type Monadic

- groovy.transform.Monadic

-     @Documented
      @Incubating
      @Target(ElementType.TYPE)
      @Retention(RetentionPolicy.RUNTIME)
      public @interface Monadic

  Marks a type as participating in monadic comprehensions (the `DO` macro). Optional members declare the bind/map method names when they diverge from the structural convention (`flatMap`/`map`). When both are omitted, the annotation merely opts the type in and the structural defaults apply.

  Modelled on Reducer: a pure marker, read by tooling, with no AST transformation. The runtime dispatcher and the type checker match this annotation by simple name (`Monadic`), exactly as `groovy.typecheckers.CombinerChecker` matches `@Reducer`/`@Associative`.

  Lawful carriers and value equality. A comprehension composes monadic values, which are only meaningful up to value equality: two carriers wrapping equal contents denote the same result. A data-style carrier should therefore provide structural `equals`/`hashCode` (Groovy's `==` dispatches to `equals`); without them, results compare by identity and the laws — right identity and functor identity in particular — are reference-unequal and silently fail to hold. This does not apply to effectful or lazy carriers (`Stream`, `CompletableFuture`, `Awaitable`), whose laws hold only up to observational equivalence and for which value equality is neither available nor expected.

  As with Associative and Reducer, this annotation asserts that the carrier is lawful (the left/right identity and associativity laws); it does not prove it. The assertion is intended to be backed by tests.

  Since:
    6.0.0

- - ### Element Summary

    Optional Element Summary
    Type | Name and Description
    --- | ---
    `String` | `bind` The flatMap-shaped bind method name.
    `String` | `map` The map method name.
    `String` | `unit` The name of the carrier's unit (a.k.a.

  - ### Inherited Methods Summary

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

- - ### Element Detail

    - #### public String bind

      The flatMap-shaped bind method name. Empty means the structural default `flatMap`.

      Default:
        ""

    - #### public String map

      The map method name. Empty means the structural default `map`.

      Default:
        ""

    - #### public String unit

      The name of the carrier's unit (a.k.a. `of`/`pure`/`return`) factory: a static, single-argument method that lifts a bare value into the carrier. Empty means undeclared.

      The `DO` macro does not use this member — its body yields the carrier explicitly, so no implicit lifting is performed. Unlike bind() and map(), the unit cannot be recovered structurally: it is a producer (`value -> carrier`), commonly a static factory (for example `Optional.of`), and for a multi-case carrier several factories share that shape (an `Either`'s `left`/`right`). Naming it lets law-deriving or law-checking tooling synthesize the unit-dependent laws (left identity, right identity); the unit-free laws (associativity, the functor laws) do not need it. This is the `@Monadic` analogue of Reducer.zero.

      Default:
        ""