Stringification and the design of debug string facilities

[soc]

Brought up in https://github.com/dinfuehr/dora/pull/254#issuecomment-907566068 by @dinfuehr, my plan as promised in https://github.com/dinfuehr/dora/pull/254#issuecomment-907648809.

Plan

Stringable#toString() focuses on general-purpose output:

• A textual representation that provides useful information about a type for general consumption.
• It avoids exposing innards or implementation details (capacity for collections, the structure of binary trees, the occupancy ratio of hash maps etc.).
• The output remains relatively stable across version and implementation changes.
• It requires implementing the Stringable traits, and putting that constraint on parameters/values when calling the method.
• It can be implemented manually by users or derived by the compiler via an annotation
• It has no access to runtime-internal facilities and has to follow the general rules of the language regarding visibility and accessibility.

runtime.debugString(value) provides debugging-oriented output:

• A textual representation that provides insights into implementation details and helps investigating bugs in the type that is being printed.
• It potentially exposes private fields, which would generally elided from general-purpose output.
• The output is not stable and makes no guarantees.
• It is an @internal static method implemented by the runtime.
• It uses runtime-internal facilities, which may ignore language rules to inspect innards of instances and retrieve information not accessible from user code, e. g. pointer addresses.
• Supported by these facilities, it makes reasonable efforts to avoid non-termination due to circular references, disambiguation of equal but not identical references etc.
• Usage does not require any kind of trait.
• Output of debugString is "" except in release builds.

[soc]

Motivation

The proposed design is based on lessons learned and problems experienced with various languages, including Java, Haskell, Rust and Scala:

• A single stringification method struggles to fulfill the multiple, often contradictory roles library users/library authors/debug people have.
  • Example: In Java this has lead to an approach where toString is supposed to only ever be used for debugging, and no common interface/method exists for user-facing display/printing of values.
• Providing reliable and useful debug output is hard when no extra-language facilities are provided.
  • Example: Scala spent considerable effort to patch up its REPL's string output due to it's (forced) reliance on types' toString implementation. Due to the lack of runtime-facilities, it had to laboriously implement an almost-reliable REPL printing mechanism in user-code as a workaround.
• Constraining debug stringification/printing of values to an interface/trait often leads to undesirable type gymnastics and hard choices on whether to complicate signatures or make things harder to debug.
  • Example: Haskell has a similar long-standing debate around logging and its relationship with the IO type. This is largely due to being able to write arbitrary user code to log in Haskell. The proposed design avoids this issue by not allowing arbitrary user-code to run to create a debug string, but deferring to a single runtime-internal implementation that can be built/verified to provide the desired safety guarantees.

[soc]

Status

• Everything in the first section (about Stringable) exists, except the derivation of a toString implementation by the compiler via an annotation. This is not a blocker and may happen independently of the next point.
• Everything in the second section (about debugString) does no exist and I propose implementing it.