Package groovy.transform

# Annotation Type ToString

@Documented @Retention(RUNTIME) @Target(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
Modifier and Type
Optional Element
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 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.
`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 Details

### excludes

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

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

boolean includeSuper
Whether to include the toString() of super in the generated toString.

Default:
  `false`

### includeSuperProperties

boolean includeSuperProperties
Whether to include super properties in the generated toString.

Since:
  2.4.0

Default:
  `false`

### includeNames

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

Default:
  `false`

### includeFields

boolean includeFields
Include fields as well as properties in the generated toString.

Default:
  `false`

### ignoreNulls

boolean ignoreNulls
Don't display any fields or properties with value `null`.

Default:
  `false`

### includePackage

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

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`