Skip to content

Commit d615ce4

Browse files
najacquenajacque
authored
Merge pull request #14777 from cwakamo/introducing-CustomPlaygroundDisplayConvertible-4.1
[4.1] [SE-0198] Introduced CustomPlaygroundDisplayConvertible and deprecated PlaygroundQuickLook/CustomPlaygroundQuickLookable
2 parents 5b03c9f + bd40005 commit d615ce4

21 files changed

+118
-0
lines changed

‎stdlib/public/SDK/AppKit/AppKit.swift

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import Foundation
1414
@_exported import AppKit
1515

1616
extension NSCursor : _DefaultCustomPlaygroundQuickLookable {
17+
@available(*, deprecated, message: "NSCursor._defaultCustomPlaygroundQuickLook will be removed in a future Swift version")
1718
public var _defaultCustomPlaygroundQuickLook: PlaygroundQuickLook {
1819
return .image(image)
1920
}
@@ -24,6 +25,7 @@ internal struct _NSViewQuickLookState {
2425
}
2526

2627
extension NSView : _DefaultCustomPlaygroundQuickLookable {
28+
@available(*, deprecated, message: "NSView._defaultCustomPlaygroundQuickLook will be removed in a future Swift version")
2729
public var _defaultCustomPlaygroundQuickLook: PlaygroundQuickLook {
2830
// if you set NSView.needsDisplay, you can get yourself in a recursive scenario where the same view
2931
// could need to draw itself in order to get a QLObject for itself, which in turn if your code was

‎stdlib/public/SDK/CoreGraphics/CoreGraphics.swift

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,6 +232,7 @@ extension CGPoint : CustomReflectable, CustomPlaygroundQuickLookable {
232232
return Mirror(self, children: ["x": x, "y": y], displayStyle: .`struct`)
233233
}
234234

235+
@available(*, deprecated, message: "CGPoint.customPlaygroundQuickLook will be removed in a future Swift version")
235236
public var customPlaygroundQuickLook: PlaygroundQuickLook {
236237
return .point(Double(x), Double(y))
237238
}
@@ -299,6 +300,7 @@ extension CGSize : CustomReflectable, CustomPlaygroundQuickLookable {
299300
displayStyle: .`struct`)
300301
}
301302

303+
@available(*, deprecated, message: "CGSize.customPlaygroundQuickLook will be removed in a future Swift version")
302304
public var customPlaygroundQuickLook: PlaygroundQuickLook {
303305
return .size(Double(width), Double(height))
304306
}
@@ -436,6 +438,7 @@ extension CGRect : CustomReflectable, CustomPlaygroundQuickLookable {
436438
displayStyle: .`struct`)
437439
}
438440

441+
@available(*, deprecated, message: "CGRect.customPlaygroundQuickLook will be removed in a future Swift version")
439442
public var customPlaygroundQuickLook: PlaygroundQuickLook {
440443
return .rectangle(
441444
Double(origin.x), Double(origin.y),

‎stdlib/public/SDK/Foundation/Date.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,7 @@ extension Date : CustomPlaygroundQuickLookable {
280280
return df.string(from: self)
281281
}
282282

283+
@available(*, deprecated, message: "Date.customPlaygroundQuickLook will be removed in a future Swift version")
283284
public var customPlaygroundQuickLook: PlaygroundQuickLook {
284285
return .text(summary)
285286
}

‎stdlib/public/SDK/Foundation/NSDate.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ extension NSDate : CustomPlaygroundQuickLookable {
2121
return df.string(from: self as Date)
2222
}
2323

24+
@available(*, deprecated, message: "NSDate.customPlaygroundQuickLook will be removed in a future Swift version")
2425
public var customPlaygroundQuickLook: PlaygroundQuickLook {
2526
return .text(summary)
2627
}

‎stdlib/public/SDK/Foundation/NSRange.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,7 @@ extension NSRange : CustomReflectable {
198198
}
199199

200200
extension NSRange : CustomPlaygroundQuickLookable {
201+
@available(*, deprecated, message: "NSRange.customPlaygroundQuickLook will be removed in a future Swift version")
201202
public var customPlaygroundQuickLook: PlaygroundQuickLook {
202203
return .range(Int64(location), Int64(length))
203204
}

‎stdlib/public/SDK/Foundation/NSString.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ extension NSString {
113113
}
114114

115115
extension NSString : CustomPlaygroundQuickLookable {
116+
@available(*, deprecated, message: "NSString.customPlaygroundQuickLook will be removed in a future Swift version")
116117
public var customPlaygroundQuickLook: PlaygroundQuickLook {
117118
return .text(self as String)
118119
}

‎stdlib/public/SDK/Foundation/NSURL.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
@_exported import Foundation // Clang module
1414

1515
extension NSURL : CustomPlaygroundQuickLookable {
16+
@available(*, deprecated, message: "NSURL.customPlaygroundQuickLook will be removed in a future Swift version")
1617
public var customPlaygroundQuickLook: PlaygroundQuickLook {
1718
guard let str = absoluteString else { return .text("Unknown URL") }
1819
return .url(str)

‎stdlib/public/SDK/Foundation/URL.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1202,6 +1202,7 @@ extension NSURL : _HasCustomAnyHashableRepresentation {
12021202
}
12031203

12041204
extension URL : CustomPlaygroundQuickLookable {
1205+
@available(*, deprecated, message: "URL.customPlaygroundQuickLook will be removed in a future Swift version")
12051206
public var customPlaygroundQuickLook: PlaygroundQuickLook {
12061207
return .url(absoluteString)
12071208
}

‎stdlib/public/SDK/SpriteKit/SpriteKitQuickLooks.swift.gyb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
% for Self in ['SKShapeNode', 'SKSpriteNode', 'SKTextureAtlas', 'SKTexture']:
1616

1717
extension ${Self} : CustomPlaygroundQuickLookable {
18+
@available(*, deprecated, message: "${Self}.customPlaygroundQuickLook will be removed in a future Swift version")
1819
public var customPlaygroundQuickLook: PlaygroundQuickLook {
1920
let data = (self as AnyObject)._copyImageData?() as Data?
2021

‎stdlib/public/SDK/UIKit/UIKit.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,7 @@ internal struct _UIViewQuickLookState {
231231
}
232232

233233
extension UIView : _DefaultCustomPlaygroundQuickLookable {
234+
@available(*, deprecated, message: "UIView._defaultCustomPlaygroundQuickLook will be removed in a future Swift version")
234235
public var _defaultCustomPlaygroundQuickLook: PlaygroundQuickLook {
235236
if _UIViewQuickLookState.views.contains(self) {
236237
return .view(UIImage())

‎stdlib/public/core/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@ set(SWIFTLIB_SOURCES
167167
CollectionOfOne.swift
168168
ExistentialCollection.swift.gyb
169169
Mirror.swift
170+
PlaygroundDisplay.swift
170171
CommandLine.swift
171172
SliceBuffer.swift
172173
Tuple.swift.gyb

‎stdlib/public/core/GroupInfo.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,9 @@
148148
"CompilerProtocols.swift",
149149
"ShadowProtocols.swift"
150150
],
151+
"Playground": [
152+
"PlaygroundDisplay.swift"
153+
],
151154
"Misc": [
152155
"AnyHashable.swift",
153156
"Interval.swift",

‎stdlib/public/core/Mirror.swift

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -659,7 +659,19 @@ internal extension Mirror {
659659
//===--- QuickLooks -------------------------------------------------------===//
660660

661661
/// The sum of types that can be used as a Quick Look representation.
662+
///
663+
/// - note: `PlaygroundQuickLook` is deprecated, and will be removed from the
664+
/// standard library in a future Swift release. Customizing display for in a
665+
/// playground is now done using the `CustomPlaygroundDisplayConvertible`
666+
/// protocol, which does not use the `PlaygroundQuickLook` enum. Please remove
667+
/// your uses of `PlaygroundQuickLook`, or conditionalize your use such that it
668+
/// is only present when compiling with Swift 4.0 or Swift 3.2 or earlier:
669+
///
670+
/// #if !(swift(>=4.1) || swift(>=3.3) && !swift(>=4.0))
671+
/// /* OK to use PlaygroundQuickLook */
672+
/// #endif
662673
@_fixed_layout // FIXME(sil-serialize-all)
674+
@available(*, deprecated, message: "PlaygroundQuickLook will be removed in a future Swift version. For customizing how types are presented in playgrounds, use CustomPlaygroundDisplayConvertible instead.")
663675
public enum PlaygroundQuickLook {
664676
/// Plain text.
665677
case text(String)
@@ -746,6 +758,7 @@ extension PlaygroundQuickLook {
746758
/// - Parameter subject: The instance to represent with the resulting Quick
747759
/// Look.
748760
@_inlineable // FIXME(sil-serialize-all)
761+
@available(*, deprecated, message: "PlaygroundQuickLook will be removed in a future Swift version.")
749762
public init(reflecting subject: Any) {
750763
if let customized = subject as? CustomPlaygroundQuickLookable {
751764
self = customized.customPlaygroundQuickLook
@@ -771,6 +784,23 @@ extension PlaygroundQuickLook {
771784
/// with the representation supplied for your type by default, you can make it
772785
/// conform to the `CustomPlaygroundQuickLookable` protocol and provide a
773786
/// custom `PlaygroundQuickLook` instance.
787+
///
788+
/// - note: `CustomPlaygroundQuickLookable` is deprecated, and will be removed
789+
/// from the standard library in a future Swift release. Please migrate to the
790+
/// `CustomPlaygroundDisplayConvertible` protocol instead, or conditionalize
791+
/// your conformance such that it is only present when compiling with Swift 4.0
792+
/// or Swift 3.2 or earlier:
793+
///
794+
/// #if swift(>=4.1) || swift(>=3.3) && !swift(>=4.0)
795+
/// // With Swift 4.1 and later (including Swift 3.3 and later), implement
796+
/// // CustomPlaygroundDisplayConvertible.
797+
/// extension MyType: CustomPlaygroundDisplayConvertible { /*...*/ }
798+
/// #else
799+
/// // Otherwise, on Swift 4.0 and Swift 3.2 and earlier,
800+
/// // implement CustomPlaygroundQuickLookable.
801+
/// extension MyType: CustomPlaygroundQuickLookable { /*...*/ }
802+
/// #endif
803+
@available(*, deprecated, message: "CustomPlaygroundQuickLookable will be removed in a future Swift version. For customizing how types are presented in playgrounds, use CustomPlaygroundDisplayConvertible instead.")
774804
public protocol CustomPlaygroundQuickLookable {
775805
/// A custom playground Quick Look for this instance.
776806
///
@@ -782,6 +812,7 @@ public protocol CustomPlaygroundQuickLookable {
782812

783813
// A workaround for <rdar://problem/26182650>
784814
// FIXME(ABI)#50 (Dynamic Dispatch for Class Extensions) though not if it moves out of stdlib.
815+
@available(*, deprecated, message: "_DefaultCustomPlaygroundQuickLookable will be removed in a future Swift version. For customizing how types are presented in playgrounds, use CustomPlaygroundDisplayConvertible instead.")
785816
public protocol _DefaultCustomPlaygroundQuickLookable {
786817
var _defaultCustomPlaygroundQuickLook: PlaygroundQuickLook { get }
787818
}

‎stdlib/public/core/Mirrors.swift.gyb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ extension ${Type[0]} : CustomReflectable {
4848
extension ${Type[0]} : CustomPlaygroundQuickLookable {
4949
/// A custom playground Quick Look for the `${Type[0]}` instance.
5050
@_inlineable // FIXME(sil-serialize-all)
51+
@available(*, deprecated, message: "${Type[0]}.customPlaygroundQuickLook will be removed in a future Swift version")
5152
public var customPlaygroundQuickLook: PlaygroundQuickLook {
5253
return ${Type[1]}(${Type[2]})
5354
}

‎stdlib/public/core/PlaygroundDisplay.swift

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
//===--- PlaygroundDisplay.swift ------------------------------------------===//
2+
//
3+
// This source file is part of the Swift.org open source project
4+
//
5+
// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
6+
// Licensed under Apache License v2.0 with Runtime Library Exception
7+
//
8+
// See https://swift.org/LICENSE.txt for license information
9+
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
10+
//
11+
//===----------------------------------------------------------------------===//
12+
13+
/// A type that supplies a custom description for playground logging.
14+
///
15+
/// All types have a default description for playgrounds. This protocol
16+
/// allows types to provide custom descriptions which are then logged in
17+
/// place of the original instance.
18+
///
19+
/// Playground logging can generate, at a minimum, a structured description
20+
/// of any type. Playground logging is also capable of generating a richer,
21+
/// more specialized description of core types -- for instance, the contents
22+
/// of a `String` are logged, as are the components of an `NSColor` or
23+
/// `UIColor`.
24+
///
25+
/// The current playground logging implementation logs specialized
26+
/// descriptions of at least the following types:
27+
///
28+
/// - `String` and `NSString`
29+
/// - `Int` and `UInt` (including the sized variants)
30+
/// - `Float` and `Double`
31+
/// - `Bool`
32+
/// - `Date` and `NSDate`
33+
/// - `NSAttributedString`
34+
/// - `NSNumber`
35+
/// - `NSRange`
36+
/// - `URL` and `NSURL`
37+
/// - `CGPoint`, `CGSize`, and `CGRect`
38+
/// - `NSColor`, `UIColor`, `CGColor`, and `CIColor`
39+
/// - `NSImage`, `UIImage`, `CGImage`, and `CIImage`
40+
/// - `NSBezierPath` and `UIBezierPath`
41+
/// - `NSView` and `UIView`
42+
///
43+
/// Playground logging may also be able to support specialized descriptions
44+
/// of other types.
45+
///
46+
/// Implementors of `CustomPlaygroundDisplayConvertible` may return a value of
47+
/// one of the above types to also receive a specialized log description.
48+
/// Implementors may also return any other type, and playground logging will
49+
/// generated structured logging for the returned value.
50+
///
51+
/// - note: `CustomPlaygroundDisplayConvertible` conformances chain -- that is,
52+
/// if `playgroundDescription` returns an instance which itself conforms to
53+
/// `CustomPlaygroundDisplayConvertible`, then playground logging will ask for
54+
/// that instance's `playgroundDescription` and so on. It is permissible for
55+
/// playground logging implementations to place a reasonable limit on this
56+
/// kind of chaining to prevent infinite loops.
57+
public protocol CustomPlaygroundDisplayConvertible {
58+
/// Returns the custom playground description for this instance.
59+
///
60+
/// If this type has value semantics, the instance returned should be
61+
/// unaffected by subsequent mutations if possible.
62+
var playgroundDescription: Any { get }
63+
}

‎stdlib/public/core/StringUTF16.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,6 +440,7 @@ extension String.UTF16View : CustomReflectable {
440440

441441
extension String.UTF16View : CustomPlaygroundQuickLookable {
442442
@_inlineable // FIXME(sil-serialize-all)
443+
@available(*, deprecated, message: "UTF16View.customPlaygroundQuickLook will be removed in a future Swift version")
443444
public var customPlaygroundQuickLook: PlaygroundQuickLook {
444445
return .text(description)
445446
}

‎stdlib/public/core/StringUTF8.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -659,6 +659,7 @@ extension String.UTF8View : CustomReflectable {
659659

660660
extension String.UTF8View : CustomPlaygroundQuickLookable {
661661
@_inlineable // FIXME(sil-serialize-all)
662+
@available(*, deprecated, message: "UTF8View.customPlaygroundQuickLook will be removed in a future Swift version")
662663
public var customPlaygroundQuickLook: PlaygroundQuickLook {
663664
return .text(description)
664665
}

‎stdlib/public/core/StringUnicodeScalarView.swift

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -509,6 +509,7 @@ extension String.UnicodeScalarView : CustomReflectable {
509509

510510
extension String.UnicodeScalarView : CustomPlaygroundQuickLookable {
511511
@_inlineable // FIXME(sil-serialize-all)
512+
@available(*, deprecated, message: "UnicodeScalarView.customPlaygroundQuickLook will be removed in a future Swift version")
512513
public var customPlaygroundQuickLook: PlaygroundQuickLook {
513514
return .text(description)
514515
}

‎stdlib/public/core/Substring.swift.gyb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,7 @@ extension Substring : CustomReflectable {
365365

366366
extension Substring : CustomPlaygroundQuickLookable {
367367
@_inlineable // FIXME(sil-serialize-all)
368+
@available(*, deprecated, message: "Substring.customPlaygroundQuickLook will be removed in a future Swift version")
368369
public var customPlaygroundQuickLook: PlaygroundQuickLook {
369370
return String(self).customPlaygroundQuickLook
370371
}

‎stdlib/public/core/UnsafePointer.swift.gyb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1000,6 +1000,7 @@ extension ${Self} : CustomPlaygroundQuickLookable {
10001000
}
10011001

10021002
@_inlineable // FIXME(sil-serialize-all)
1003+
@available(*, deprecated, message: "${Self}.customPlaygroundQuickLook will be removed in a future Swift version")
10031004
public var customPlaygroundQuickLook: PlaygroundQuickLook {
10041005
return .text(summary)
10051006
}

‎stdlib/public/core/UnsafeRawPointer.swift.gyb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -996,6 +996,7 @@ extension Unsafe${Mutable}RawPointer : CustomReflectable {
996996
extension Unsafe${Mutable}RawPointer : CustomPlaygroundQuickLookable {
997997
@_inlineable // FIXME(sil-serialize-all)
998998
@_versioned // FIXME(sil-serialize-all)
999+
@available(*, deprecated, message: "Unsafe${Mutable}RawPointer.customPlaygroundQuickLook will be removed in a future Swift version")
9991000
internal var summary: String {
10001001
let selfType = "${Self}"
10011002
let ptrValue = UInt64(

0 commit comments

Comments
 (0)