[swift-evolution] Custom summary for Mirrors?

[Austin Zheng]

Hi all,

I'd like to gauge reaction for a proposal I was considering: adding to the
standard library's Mirror type a 'summary' property, and the option to
initialize a Mirror with a custom summary. If no custom summary is
provided, the summary would default to the string produced by calling
String(reflecting: subject) on the subject at the time of mirror creation.

Some context: right now, there are two APIs for mirrors in the standard
library: CustomReflectable, which is publicly exposed and relies on the
conforming type creating a Mirror object, and _Reflectable, which relies on
the conforming type having a companion type conforming to _MirrorType. A
short-term goal is to migrate the standard library's types off the
_Reflectable API and have them use the CustomReflectable API, and changing
dump() accordingly.

The extant implementation of dump() uses a property on _MirrorType called
"summary". (This is where e.g. "4 elements" comes from when you dump() an
array.) "summary" is absent from Mirror or any types related to
CustomReflectable. I asked Joe Groff about this and the rationale was that
it was deemed too similar to debugDescription (or String(reflecting: foo))
to be worth carrying over.

I would like to suggest that there might be a purpose for "summary":

- Types with children, especially container types like arrays, often print
out a description of their children as part of their debugDescription or
description, redundant when using an API like dump() which provides a
structural representation of the children of the subject. In such cases a
lighter-weight description (like "3 elements") might be more appropriate to
represent to the user.

- Certain types like CGRect don't conform to CustomStringConvertible,
CustomDebugStringConvertible, Streamable, etc. Having a custom summary for
these types customized by the corresponding Mirror would allow for a
'pretty' representation during reflection in lieu of the ugly one generated
by the runtime without making more substantial changes to the API which
might break third-party code (such as conforming CGRect to any of the
aforementioned protocols).

I know that Mirror (and reflection as a whole) are being considered for
major design changes, so this would be a minor transient change to make the
API easier to work with in the meantime.

Please let me know whether or not you think this proposed change is
meaningful and worthwhile, or if you have any questions.

Best,
Austin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20151229/06569cdd/attachment.html>