Package groovy.transform
Annotation Type ToString
-
@Documented @Retention(RUNTIME) @Target(TYPE) public @interface ToString
Class annotation used to assist in the creation oftoString()methods in classes. The@ToStringannotation instructs the compiler to execute an AST transformation which adds the necessary toString() method.It allows you to write classes in this shortened form:
Which will have this output:@ToStringclass 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'])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:
Then the output will be:@ToString(includeNames=true)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:
Then the output will be:@ToString(includeNames=true,includeFields=true,excludes="since,favItems")Customer(first:Tom, last:Jones, age:21, answer:42)
If you have this example:import groovy.transform.ToString
@ToStringclass 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))'@ToStringcan also be used in conjunction with@Canonicaland@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
Which results in:@ToString(includePackage = false)class NamedThing { String name } println new NamedThing(name: "Lassie")NamedThing(name: Lassie)
If the includePackage flag istrue(the default), then the output will be:my.company.NamedThing(name: Lassie)
More examples:
//-------------------------------------------------------------------------- // Most simple implementation of toString. import groovy.transform.ToString
@ToStringclass 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'
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description booleancacheWhether to cache toString() calculations.String[]excludesList of field and/or property names to exclude from generated toString.booleanignoreNullsDon't display any fields or properties with value null.booleanincludeFieldsInclude fields as well as properties in the generated toString.booleanincludeNamesWhether to include names of properties/fields in the generated toString.booleanincludePackageWhether to include the fully-qualified class name (i.e.String[]includesList of field and/or property names to include within the generated toString.booleanincludeSuperWhether to include the toString() of super in the generated toString.booleanincludeSuperPropertiesWhether to include super properties in the generated toString.
-
-
-
Element Detail
-
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:
- {}
-
-