[GROOVY-8431] toDebugString method as a core concept

• Type: Proposal
• Status: Open
• Priority: Major
• Resolution: Unresolved
• Affects Version/s: 3.x, 2.5.x
• Component/s: GEP, groovy-jdk
• Labels: features
• Assignee: Unassigned
• Reporter: mgroovy
• Created: 03/Jan/18 17:28
• Updated: 15/Jan/18 23:25

Description

• Groovy should introduce a toDebugString method as a core concept, to separate debug to-string-conversion semantics from heavily oversubscribed standard Java Object#toString.
• The power of this feature as a core concept lies in support to create
  1. Easy to use, human readable debug output of any object
  2. Creating debug output of objects owned by other objects (i.e. hierarchical debug output)
• Adding this feature should be relatively simple, the challenge is to decide what features/parameters toDebugString should have, because this will be hard to change once the feature has been introduced.
• The default implementation could
  1. Call the Java default Object#toString method
  2. Automatically create a reflection based output (performance will probably be bad for this, so it might be better to enable this behavior through an annotation)
  3. Returns something along the line of getClass().simpleName + '@' + System.identityHashcode(this) (though Object#toString is probably more useful)
  4. Fall back to the class' toString method (although in most cases it's most likely not what the user wants/expects)
• An extension would be for an overloaded toDebugString to take an indentationLevel and indentationString parameter:

  String toDebugString(int indentationLevel, String indentationString = '\t')

  • Implementations would be expected to indent the resulting String accordingly, which is very helpful for
    1. Complex objects which require a multi-line output to make sense of them in a debug log
    2. Outputting inner objects (e.g. a collection) owned by an object
  • Groovy default implementation could be, to indent the result of calling toDebugString(), by scanning for newline sequences in the returned string
• Questions:
  1. Is there a better name than the (relatively long) "toDebugString" ?
     • toDebugString was suggested, since it is easy to discover, and its purpose should immediately clear
  2. Should the return type of toDebugString be GString instead of String ?
     • This would allow for Groovy to process the objects embedded in the GString differently
     • Having an additional GString toDebugGString() method might be an alternative
  3. Should there be additional parameters such as a terseness/verboseness parameter, which indicates how compact or verbose the generated debug string should be (implementations would be free to ignore this, of course) ?