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
     }
     String agedThingAsString = new AgedThing(name:'Lassie', age:5).toString()
     assert agedThingAsString == '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
     }
     assert new NamedThing(name: null).toString() == '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)

More examples:

     //--------------------------------------------------------------------------
     // Most simple implementation of toString.
     import groovy.transform.ToString

     @ToString
     class Person {
         String name
         List likes
         private boolean active = false
     }

     def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

     assert person.toString() == 'Person(mrhaki, [Groovy, Java])'

     //--------------------------------------------------------------------------
     // includeNames to output the names of the properties.
     import groovy.transform.ToString

     @ToString(includeNames=true)
     class Person {
         String name
         List likes
         private boolean active = false
     }

     def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

     assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java])'

     //--------------------------------------------------------------------------
     // includeFields to not only output properties, but also field values.
     import groovy.transform.ToString

     @ToString(includeNames=true, includeFields=true)
     class Person {
         String name
         List likes
         private boolean active = false
     }

     def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

     assert person.toString() == 'Person(name:mrhaki, likes:[Groovy, Java], active:false)'

     //--------------------------------------------------------------------------
     // Use includeSuper to include properties from super class in output.
     import groovy.transform.ToString

     @ToString(includeNames=true)
     class Person {
         String name
         List likes
         private boolean active = false
     }

     @ToString(includeSuper=true, includeNames=true)
     class Student extends Person {
         List courses
     }

     def student = new Student(name: 'mrhaki', likes: ['Groovy', 'Java'], courses: ['IT', 'Business'])

     assert student.toString() == 'Student(courses:[IT, Business], super:Person(name:mrhaki, likes:[Groovy, Java]))'

     //--------------------------------------------------------------------------
     // excludes active field and likes property from output
     import groovy.transform.ToString

     @ToString(includeNames=true, includeFields=true, excludes='active,likes')
     class Person {
         String name
         List likes
         private boolean active = false
     }

     def person = new Person(name: 'mrhaki', likes: ['Groovy', 'Java'])

     assert person.toString() == 'Person(name:mrhaki)'

     //--------------------------------------------------------------------------
     // Don't include the package name in the output
     package com.mrhaki.blog.groovy

     import groovy.transform.*

     @ToString(includePackage=false)
     class Course {
         String title
         Integer maxAttendees
     }

     final Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

     assert course.toString() == 'Course(Groovy 101, 200)'

     //--------------------------------------------------------------------------
     // Don't use properties with null value.
     package com.mrhaki.blog.groovy

     import groovy.transform.*

     @ToString(ignoreNulls=true)
     class Course {
         String title
         Integer maxAttendees
     }

     final Course course = new Course(title: 'Groovy 101')

     assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101)'

     //--------------------------------------------------------------------------
     // Cache toString() result.
     package com.mrhaki.blog.groovy

     import groovy.transform.*

     @ToString(cache=true)
     class Course {
         String title
         Integer maxAttendees
     }

     Course course = new Course(title: 'Groovy 101', maxAttendees: 200)

     assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'

     // Value change will not be reflected in toString().
     course.title = 'Grails with REST'

     assert course.toString() == 'com.mrhaki.blog.groovy.Course(Groovy 101, 200)'
     assert course.title == 'Grails with REST'

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

### Optional Element Summary

Optional Elements
`boolean` `cache` Whether to cache toString() calculations.
`java.lang.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 the generated toString.
`boolean` `includeNames` Whether to include names of properties/fields in the generated toString.
`boolean` `includePackage` Whether to include the fully-qualified class name (i.e.
`java.lang.String[]` `includes` List of field and/or property names to include within the generated toString.
`boolean` `includeSuper` Whether to include the toString() of super in the generated toString.
`boolean` `includeSuperProperties` Whether to include super properties in the generated toString.

### Element Detail

#### excludes

    public abstract java.lang.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 java.lang.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 the toString() of super in the generated toString.

Default:
  false

#### includeSuperProperties

    public abstract boolean includeSuperProperties

Whether to include super properties in the generated toString.

Since:
  2.4.0

Default:
  false

#### includeNames

    public abstract boolean includeNames

Whether to include names of properties/fields in the generated toString.

Default:
  false

#### includeFields

    public abstract boolean includeFields

Include fields as well as properties in the 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