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. including the package) or just the simple class name in the generated toString.
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