stdlib/public/core/PlaygroundDisplay.swift

//===--- PlaygroundDisplay.swift ------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//

/// A type that supplies a custom description for playground logging.
///
/// Playground logging can generate, at a minimum, a structured description
/// of any type. If you want to provide a custom description of your type to be
/// logged in place of the default description, conform to the
/// `CustomPlaygroundDisplayConvertible` protocol.
///
/// Playground logging generates a richer, more specialized description of core
/// types. For example, the contents of a `String` are logged, as are the
/// components of an `NSColor` or `UIColor`. The current playground logging
/// implementation logs specialized descriptions of at least the following
/// types:
///
/// - `String` and `NSString`
/// - `Int`, `UInt`, and the other standard library integer types
/// - `Float` and `Double`
/// - `Bool`
/// - `Date` and `NSDate`
/// - `NSAttributedString`
/// - `NSNumber`
/// - `NSRange`
/// - `URL` and `NSURL`
/// - `CGPoint`, `CGSize`, and `CGRect`
/// - `NSColor`, `UIColor`, `CGColor`, and `CIColor`
/// - `NSImage`, `UIImage`, `CGImage`, and `CIImage`
/// - `NSBezierPath` and `UIBezierPath`
/// - `NSView` and `UIView`
///
/// Playground logging may also be able to support specialized descriptions
/// of other types.
///
/// Conforming to the CustomPlaygroundDisplayConvertible Protocol
/// -------------------------------------------------------------
///
/// To add `CustomPlaygroundDisplayConvertible` conformance to your custom type,
/// implement the `playgroundDescription` property. If your implementation
/// returns an instance of one of the types above, that type's specialized
/// description is used. If you return any other type, a structured description
/// is generated.
///
/// If your type has value semantics, the `playgroundDescription` should be
/// unaffected by subsequent mutations, if possible.
///
/// If your type's `playgroundDescription` returns an instance which itself
/// conforms to `CustomPlaygroundDisplayConvertible`, then that type's
/// `playgroundDescription` will be used, and so on. To prevent infinite loops,
/// playground logging implementations can place a reasonable limit on this
/// kind of chaining.
public protocol CustomPlaygroundDisplayConvertible {
  /// A custom playground description for this instance.
  var playgroundDescription: Any { get }
}