ToString (groovy 2.4.10 API)
Date: 2017-03-14

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
       }
       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'

  See Also:
    Immutable
    Canonical
  Authors:
    Paul King
    Andre Steingress
  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 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. including the package) or just the simple class name in 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.
    `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 the generated toString. @default false

    - #### public boolean includeNames

      Whether to include names of properties/fields in the 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 the toString() of super in the generated toString. @default false

    - #### public boolean includeSuperProperties

      Whether to include super properties in the generated toString. @default false

      Since:
        2.4.0

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