groovy.transform

## Annotation Type ToString

-     @Documented
      @Retention(value=RUNTIME)
      @Target(value=TYPE)
      public @interface ToString

  Class annotation used to assist in the creation of `toString()` methods in classes. The `@ToString` annotation instructs the compiler to execute an AST transformation which adds the necessary toString() method.

  It allows you to write classes in this shortened form:

       @ToString
       class Customer {
           String first, last
           int age
           Date since = new Date()
           Collection favItems
           private answer = 42
       }
       println new Customer(first:'Tom', last:'Jones', age:21, favItems:['Books', 'Games'])

  Which will have this output:

       Customer(Tom, Jones, 21, Wed Jul 14 23:57:14 EST 2010, [Books, Games])

  There are numerous options to customize the format of the generated output. E.g. if you change the first annotation to:

       @ToString(includeNames=true)

  Then the output will be:

       Customer(first:Tom, last:Jones, age:21, since:Wed Jul 14 23:57:50 EST 2010, favItems:[Books, Games])

  Or if you change the first annotation to:

       @ToString(includeNames=true,includeFields=true,excludes="since,favItems")

  Then the output will be:

       Customer(first:Tom, last:Jones, age:21, answer:42)

  If you have this example:

       import groovy.transform.ToString
       @ToString class NamedThing {
           String name
       }
       @ToString(includeNames=true,includeSuper=true)
       class AgedThing extends NamedThing {
           int age
       }
       println new AgedThing(name:'Lassie', age:5)

  Then the output will be:

       AgedThing(age:5, super:NamedThing(Lassie))

  `@ToString` can also be used in conjunction with `@Canonical` and `@Immutable`.

  If you want to omit fields or properties referring to `null`, you can use the `ignoreNulls` flag:

       import groovy.transform.ToString
       @ToString(ignoreNulls = true) class NamedThing {
           String name
       }
       println new NamedThing(name: null)

  Which results in:

       NamedThing()

  By default the fully-qualified class name is used as part of the generated toString. If you want to exclude the package, you can set the includePackage flag to false, e.g.:

       package my.company
       import groovy.transform.ToString
       @ToString(includePackage = false) class NamedThing {
           String name
       }
       println new NamedThing(name: "Lassie")

  Which results in:

       NamedThing(name: Lassie)

  If the includePackage flag is `true` (the default), then the output will be:

       my.company.NamedThing(name: Lassie)

  Since:
    1.8.0
  Author:
    Paul King, Andre Steingress
  See Also:
    `Immutable`, `Canonical`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `boolean` | `cache` Whether to cache toString() calculations.
    `String[]` | `excludes` List of field and/or property names to exclude from generated toString.
    `boolean` | `ignoreNulls` Don't display any fields or properties with value `null`.
    `boolean` | `includeFields` Include fields as well as properties in generated toString.
    `boolean` | `includeNames` Whether to include names of properties/fields in generated toString.
    `boolean` | `includePackage` Whether to include the fully-qualified class name (i.e.
    `String[]` | `includes` List of field and/or property names to include within the generated toString.
    `boolean` | `includeSuper` Whether to include super in generated toString.

- - ### Element Detail

    - #### excludes

          public abstract String[] excludes

      List of field and/or property names to exclude from generated toString. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.
      Default:
        {}

    - #### includes

          public abstract String[] includes

      List of field and/or property names to include within the generated toString. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values.
      Default:
        {}

    - #### includeSuper

          public abstract boolean includeSuper

      Whether to include super in generated toString.
      Default:
        false

    - #### includeNames

          public abstract boolean includeNames

      Whether to include names of properties/fields in generated toString.
      Default:
        false

    - #### includeFields

          public abstract boolean includeFields

      Include fields as well as properties in generated toString.
      Default:
        false

    - #### ignoreNulls

          public abstract boolean ignoreNulls

      Don't display any fields or properties with value `null`.
      Default:
        false

    - #### includePackage

          public abstract boolean includePackage

      Whether to include the fully-qualified class name (i.e. including the package) or just the simple class name in the generated toString.
      Since:
        2.0.6
      Default:
        true

    - #### cache

          public abstract boolean cache

      Whether to cache toString() calculations. You should only set this to true if you know the object is immutable (or technically mutable but never changed).
      Since:
        2.1.0
      Default:
        false