[swift-evolution] [Proposal] Revamp the playground quicklook APIs

[Connor Wakamo]

> On Jan 9, 2018, at 10:02 PM, Chris Lattner <clattner at nondot.org> wrote:
> 
> On Jan 9, 2018, at 3:19 PM, Connor Wakamo via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>> Good afternoon,
> 
> Hi Connor,
> 
> Huge +1 for this proposal, I’m thrilled you’re cleaning this up.  Couple of detail questions:
> 
>>  <https://github.com/cwakamo/swift-evolution/tree/playground-quicklook-api-revamp#proposed-solution>
>> Detailed design
>> 
>> To provide a more flexible API, we propose deprecating and ultimately removing the PlaygroundQuickLook enum and CustomPlaygroundQuickLookable protocol in favor of a simpler design. Instead, we propose introducing a protocol which just provides the ability to return an Any (or nil) that serves as a stand-in for the instance being logged:
>> 
> 
> What is the use-case for a type conforming to this protocol but returning nil?  If there is a use case for that, why not have such an implementation return “self” instead?

Riley and Saagar answered this down-thread, but to confirm — returning nil would allow some instances of a type to use the “default” playground logging presentation while others use an alternate presentation instead.

This isn’t handled by `return self` because, unless I’m mistaken, there’s no way to detect that from the caller’s side (e.g. with two `Any` values, I can’t do `self === self.playgroundRepresentation`). This would be necessary because the intention is that `CustomPlaygroundRepresentable` conformances can chain — if I return an object/value which itself conforms to `CustomPlaygroundRepresentable`, then the playground logger should follow that so that I’m presented the same way as whatever I return would have been. (That’s probably not absolutely true, as the PlaygroundLogger library will likely have some sort of failsafe to prevent infinite chaining here. But I wouldn’t want to rely on such a failsafe mechanism in the design of this API.)

> In short, can we change playgroundRepresentation to return Any instead of Any?.  Among other things, doing so could ease the case of playground formatting Optional itself, which should presumably get a conditional conformance to this.  :-)

I don’t think we can change this to return `Any` instead of `Any?`. I think there are potentially cases where a developer might want to selectively opt-in to this behavior.

I also don’t think that `Optional` would get a conditional conformance to this. I’m not proposing that any standard library or corelibs types gain conformances to this protocol. Instead, it’s up to a playground logger (such as PlaygroundLogger in swift-xcode-playground-support <https://github.com/apple/swift-xcode-playground-support>) to recognize these types and handle them accordingly. The playground logger would look through the `Optional` so that this would effectively be true, but ideally the log data generated by a logger would indicate that it was wrapped by `Optional.some`.

One possibility would be to change the API so that it returns an enum. Imagine:

	enum PlaygroundLoggingBehavior {
		/// Asks the playground logger to generate the standard logging for `self`.
		case standard

		/// Asks the playground logger to generate logging for the given `Any` instead of `self`.
		case custom(Any)
	}

	protocol CustomPlaygroundLoggable {
		/// Returns the `PlaygroundLoggingBehavior` to use for `self`.
		var playgroundLoggingBehavior: PlaygroundLoggingBehavior { get }
	}

(To Saagar’s point in another email — you could even add a `case none` to PlaygroundLoggingBehavior to inhibit logging of a particular instance.)

`CustomPlaygroundLoggable` would be a little clunkier to implement than `CustomPlaygroundRepresentable` is, as in the common case folks would have to write `return .custom(…)`. It’s possible that the clarity and additional flexibility this grants outweighs that cost; I’m not sure, and would love feedback on that.

>> /// Implementors of `CustomPlaygroundRepresentable` may return a value of one of
>> /// the above types to also receive a specialized log representation.
>> /// Implementors may also return any other type, and playground logging will
>> /// generated structured logging for the returned value.
>> public protocol CustomPlaygroundRepresentable {
> On the naming bikeshed, the closest analog to this feature is CustomStringConvertible, which is used when a type wants to customize the default conversion to string.  As such, have you considered CustomPlaygroundConvertible for consistency with it?
> 
> The only prior art for the word “Representable” in the standard library is RawRepresentable, which is quite a different concept.
> 
>>   /// Returns the custom playground representation for this instance, or nil if
>>   /// the default representation should be used.
>>   ///
>>   /// If this type has value semantics, the instance returned should be
>>   /// unaffected by subsequent mutations if possible.
>>   var playgroundRepresentation: Any? { get }
> Again to align with CustomStringConvertible which has a ‘description’ member, it might make sense to name this member “playgroundDescription”.

I’m definitely open to different names for this. (`CustomPlaygroundRepresentable` was inspired by the API I’m removing, `CustomPlaygroundQuickLookable`, as they both take their sole property and make them -able.)

I do like the `playgroundDescription` name for the property, but am a little hesitant to use the name `CustomPlaygroundConvertible` because conforming types can’t be converted to playgrounds. I can’t come up with an appropriate word in `CustomPlaygroundThingConvertible` to use in place of `Thing`, though. (If we end up pivoting to the enum I described above then something like `CustomPlaygroundLoggable` would be more appropriate.)

Connor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20180110/57c67c0d/attachment.html>