Package: groovy.transform

## [Java] Annotation Type ToString

- groovy.transform.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)

  Authors:
    Paul King
    Andre Steingress
  See Also:
    Immutable
    Canonical
  Since:
    1.8.0

- - ### Element Summary

    Optional Element Summary
    Type | Name 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. including the package) or just the simple class name in the generated toString.
    `boolean` | `includeSuper` Whether to include super in generated toString.
    `String[]` | `includes` List of field and/or property names to include within the generated toString.

  - ### Inherited Methods Summary

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

- - ### Element Detail

    - #### public 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). @default false

      Since:
        2.1.0

    - #### public 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 {}

    - #### public boolean ignoreNulls

      Don't display any fields or properties with value `null`. @default false

    - #### public boolean includeFields

      Include fields as well as properties in generated toString. @default false

    - #### public boolean includeNames

      Whether to include names of properties/fields in generated toString. @default false

    - #### public 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. @default true

      Since:
        2.0.6

    - #### public boolean includeSuper

      Whether to include super in generated toString. @default false

    - #### public 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 {}