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

[Connor Wakamo]

> On Jan 9, 2018, at 4:21 PM, Ben Rimmington <me at benrimmington.com> wrote:
> 
> Something like this was attempted (and reverted) for Swift 3:
> 
> <https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160808/026088.html>
> 
> <https://github.com/apple/swift-evolution/commit/e2610e3fa91b437e06e768aaef6820d755489717>
> 
> <https://github.com/apple/swift-xcode-playground-support/commit/0f42ade5a6302cf953a3ed32a892f23e8e150c62>
> 
> Is it now possible to `import PlaygroundSupport` outside of a playground?

No, it is not. This is a known limitation of the proposal that is acknowledged in the full text of the proposal.

For the corelibs case (and for libraries provided by the OS), it’s expected that the PlaygroundLogger library be updated to support generating rich log data for new types.

For third-party modules there’s not a great solution, though since playgrounds have fairly limited access to third-party modules and because usage of CustomPlaygroundQuickLookable outside of playgrounds is low (as determined by searching GitHub and the source compatibility suite), the proposal asserts that this is a reasonable trade-off for removing something this domain-specific from the standard library.

Since the new protocol doesn’t itself use any custom types, a workaround for this limitation is possible:

	// MyFramework.swift
	public struct MyStruct {
		var playgroundRepresentation: Any? { … }
	}

	// PlaygroundAuxiliarySource.swift
	import MyFramework
	import PlaygroundSupport

	extension MyStruct: CustomPlaygroundRepresentable {}

The proposal intentionally chose to place this in PlaygroundSupport instead of the standard library because it should be possible in a future Swift release to move this protocol from PlaygroundSupport to the standard library (because PlaygroundSupport doesn’t have any ABI concerns at this time), whereas it wouldn’t be possible to go in the reverse direction. (And if we determine that this protocol should live in the standard library during the course of the review process, I’d still want to proceed otherwise as planned — add the new protocol, deprecate-then-remove the old protocol/enum, and provide a shim library for playgrounds only.)

Connor

> 
> -- Ben
> 
>> On 9 Jan 2018, at 23:19, Connor Wakamo wrote:
>> 
>> Good afternoon,
>> 
>> In preparation for ABI stability, I’ve reviewed the API exposed by the standard library for providing customized “quick looks” in playgrounds. This is exposed as the PlaygroundQuickLook enum and the CustomPlaygroundQuickLookable protocol. The PlaygroundQuickLook has a handful of issues:
>> 
>> 	- It hard-codes the list of supported types in the standard library, meaning that PlaygroundLogger/IDEs cannot gain support for new types without standard library changes (including swift-evolution review)
>> 	- The cases of the enum are poorly typed: there are cases like `.view` and `.color` which take NS/UIView or NS/UIColor instances, respectively, but since they’re in the standard library, they have to be typed as taking `Any` instead
>> 	- The names of some of these enum cases do not seem to match Swift naming conventions)
>> 
>> To that end, I am proposing the following:
>> 
>> 	- Deprecate PlaygroundQuickLook and CustomPlaygroundQuickLookable in Swift 4.1 (including in the Swift 3 compatibility mode)
>> 	- Remove PlaygroundQuickLook and CustomPlaygroundQuickLookable in Swift 5 to avoid including them in the stable ABI (this affects the compatibility modes, too)
>> 	- Introduce a new protocol, CustomPlaygroundRepresentable, in the PlaygroundSupport library in Swift 4.1:
>> 
>> 		protocol CustomPlaygroundRepresentable {
>> 			/// Returns an alternate object or value which should stand in for the receiver in playground logging, or nil if the receiver’s default representation is preferred.
>> 			var playgroundRepresentation: Any? { get }
>> 		}
>> 
>> 	- Update the PlaygroundLogger library in Swift 4.1 to support both CustomPlaygroundRepresentable and PlaygroundQuickLook/CustomPlaygroundQuickLookable
>> 	- Provide a compatibility shim library which preserves PlaygroundQuickLook and CustomPlaygroundQuickLookable as deprecated in Swift 3/4 and unavailable in Swift 5, but only in playgrounds (including in the auxiliary source files stored inside a playground)
>> 
>> I’ve put a full proposal below. Please let me know what you think of this proposal; I’d like to get some feedback before taking this through the review process, but I’ll need to get that quickly so I can get it under review soon as this is targeted at Swift 4.1.
>> 
>> Thanks,
>> Connor