[PlaygroundLogger] Implemented support for capping the depth of log entries.

This pulls over behavior matching the legacy PlaygroundLogger, which capped log entries at a maximum depth of 2.
This includes commits for a small handful of cases. More to be added later.

Author: cwakamo

PlaygroundLogger/PlaygroundLogger/LogEntry+Reflection.swift

@@ -21,12 +21,16 @@ fileprivate let emptyNameString = ""
 
 extension LogEntry {
     init(describing instance: Any, name: String? = nil, policy: LogPolicy) {
-        self = .init(describing: instance, name: name ?? emptyNameString, typeName: nil, summary: nil, policy: policy)
+        self = .init(describing: instance, name: name ?? emptyNameString, typeName: nil, summary: nil, policy: policy, currentDepth: 0)
     }
 
-    private init(describing instance: Any, name: String, typeName passedInTypeName: String?, summary passedInSummary: String?, policy: LogPolicy) {
-        // TODO: need to handle optionals better (e.g. implicitly unwrap optionality, I think)
-        
+    fileprivate init(describing instance: Any, name: String, typeName passedInTypeName: String?, summary passedInSummary: String?, policy: LogPolicy, currentDepth: Int) {
+        guard currentDepth <= policy.maximumDepth else {
+            // We're trying to log an instance that is "too deep"; as a result, we need to just return a gap.
+            self = .gap
+            return
+        }
+
         // Returns either the passed-in type name/summary or the type name/summary of `instance`.
         var typeName: String { return passedInTypeName ?? normalizedName(of: type(of: instance)) }
         var summary: String { return passedInSummary ?? String(describing: instance) }
@@ -47,7 +51,7 @@ extension LogEntry {
 
         // If a type implements the `debugQuickLookObject()` Objective-C method, then get their debug quick look object and use that for logging (by passing it back through this initializer).
         else if let debugQuickLookObjectMethod = (instance as AnyObject).debugQuickLookObject, let debugQuickLookObject = debugQuickLookObjectMethod() {
-            self = .init(describing: debugQuickLookObject, name: name, typeName: typeName, summary: nil, policy: policy)
+            self = .init(describing: debugQuickLookObject, name: name, typeName: typeName, summary: nil, policy: policy, currentDepth: currentDepth)
         }
 
         // Otherwise, first check if this is an interesting CF type before logging structure.
@@ -68,11 +72,11 @@ extension LogEntry {
 
                 if mirror.displayStyle == .optional && mirror.children.count == 1 {
                     // If the mirror displays as an Optional and has exactly one child, then we want to unwrap the optionality and generate a log entry for the child.
-                    self = .init(describing: mirror.children.first!.value, name: name, typeName: typeName, summary: nil, policy: policy)
+                    self = .init(describing: mirror.children.first!.value, name: name, typeName: typeName, summary: nil, policy: policy, currentDepth: currentDepth)
                 }
                 else {
                     // Otherwise, we want to generate a log entry with the structure from the mirror.
-                    self = .init(structureFrom: mirror, name: name, typeName: typeName, summary: summary, policy: policy)
+                    self = .init(structureFrom: mirror, name: name, typeName: typeName, summary: summary, policy: policy, currentDepth: currentDepth)
                 }
             }
         }
@@ -85,12 +89,12 @@ extension LogEntry {
 
     fileprivate static let superclassLogEntryName = "super"
 
-    fileprivate init(structureFrom mirror: Mirror, name: String, typeName: String, summary: String, policy: LogPolicy) {
+    fileprivate init(structureFrom mirror: Mirror, name: String, typeName: String, summary: String, policy: LogPolicy, currentDepth: Int) {
         self = .structured(name: name,
                            typeName: typeName,
                            summary: summary,
                            totalChildrenCount: mirror.totalChildCount,
-                           children: mirror.childEntries(using: policy),
+                           children: mirror.childEntries(using: policy, currentDepth: currentDepth),
                            disposition: .init(displayStyle: mirror.displayStyle)
         )
     }
@@ -134,7 +138,7 @@ extension Mirror {
         }
     }
 
-    fileprivate func childEntries(using policy: LogPolicy) -> [LogEntry] {
+    fileprivate func childEntries(using policy: LogPolicy, currentDepth: Int) -> [LogEntry] {
         let childPolicy: LogPolicy.ChildPolicy = {
             switch self.displayStyle ?? .struct {
             case .class, .struct, .tuple, .enum:
@@ -144,14 +148,26 @@ extension Mirror {
             }
         }()
 
+        let childDepth: Int = {
+            switch self.displayStyle ?? .struct {
+            case .optional, .dictionary:
+                // We don't consume a level of depth for optionals or dictionaries.
+                // We don't want optional to count as a level of depth as we would quickly end up with gaps.
+                // We don't want dictionary to count as a level of depth as dictionary is modeled as a collection of (key, value) pairs, and we don't want to lose a level due to the pairs themselves consuming a level, so for ease of bookkeeping the dictionary level is counted as not consuming a level.
+                return currentDepth
+            case .class, .struct, .tuple, .enum, .collection, .set:
+                return currentDepth + 1
+            }
+        }()
+
         func logEntry(forChild child: Mirror.Child) -> LogEntry {
-            return LogEntry(describing: child.value, name: child.label, policy: policy)
+            return LogEntry(describing: child.value, name: child.label ?? emptyNameString, typeName: nil, summary: nil, policy: policy, currentDepth: childDepth)
         }
 
         func logEntriesForAllChildren() -> [LogEntry] {
             let childEntries = children.map(logEntry(forChild:))
             if let superclassMirror = superclassMirror {
-                return [superclassMirror.logEntry(named: LogEntry.superclassLogEntryName, usingPolicy: policy)] + childEntries
+                return [superclassMirror.logEntry(named: LogEntry.superclassLogEntryName, usingPolicy: policy, depth: childDepth)] + childEntries
             }
             else {
                 return childEntries
@@ -162,7 +178,7 @@ extension Mirror {
             let numberOfChildren: Int
             let superclassEntries: [LogEntry]
             if let superclassMirror = superclassMirror {
-                superclassEntries = [superclassMirror.logEntry(named: LogEntry.superclassLogEntryName, usingPolicy: policy)]
+                superclassEntries = [superclassMirror.logEntry(named: LogEntry.superclassLogEntryName, usingPolicy: policy, depth: childDepth)]
                 numberOfChildren = count - 1
             }
             else {
@@ -183,6 +199,12 @@ extension Mirror {
             return children[start..<max].map(logEntry(forChild:))
         }
 
+        // Ensure that our children are loggable (i.e. their depth is not prohibited by our current policy).
+        // If our children **are** too deep, then simply return a single gap as our children.
+        guard childDepth <= policy.maximumDepth else {
+            return [.gap]
+        }
+
         switch childPolicy {
         case .all:
             return logEntriesForAllChildren()
@@ -203,8 +225,8 @@ extension Mirror {
         }
     }
 
-    fileprivate func logEntry(named name: String, usingPolicy policy: LogPolicy) -> LogEntry {
+    fileprivate func logEntry(named name: String, usingPolicy policy: LogPolicy, depth: Int) -> LogEntry {
         let subjectTypeName = normalizedName(of: self.subjectType)
-        return LogEntry(structureFrom: self, name: name, typeName: subjectTypeName, summary: subjectTypeName, policy: policy)
+        return LogEntry(structureFrom: self, name: name, typeName: subjectTypeName, summary: subjectTypeName, policy: policy, currentDepth: depth)
     }
 }

PlaygroundLogger/PlaygroundLogger/LogPolicy.swift

@@ -13,6 +13,9 @@
 struct LogPolicy {
     static let `default`: LogPolicy = LogPolicy()
 
+    /// The policy for the maximum depth level for log entries.
+    var maximumDepth: Int
+
     enum ChildPolicy {
         /// Indicates that all children should be logged.
         case all
@@ -32,10 +35,13 @@ struct LogPolicy {
 
     /// Initializes a new `LogPolicy`.
     ///
+    /// - parameter maximumDepth: The maximum depth level for logging children of children. Defaults to 2.
     /// - parameter aggregateChildPolicy: The policy to use for logging children of aggregates. Defaults to logging no more than the first 10,000 children.
     /// - parameter containerChildPolicy: The policy to use for logging children of collections. Defaults to logging no more than the first 80 children plus the last 20 children.
-    init(aggregateChildPolicy: ChildPolicy = .head(count: 10_000),
+    init(maximumDepth: Int = 2,
+         aggregateChildPolicy: ChildPolicy = .head(count: 10_000),
          containerChildPolicy: ChildPolicy = .headTail(headCount: 80, tailCount: 20)) {
+        self.maximumDepth = maximumDepth
         self.aggregateChildPolicy = aggregateChildPolicy
         self.containerChildPolicy = containerChildPolicy
     }

PlaygroundLogger/PlaygroundLoggerTests/LogPolicyTests.swift

@@ -23,7 +23,243 @@ fileprivate struct TestStruct {
     init() {}
 }
 
+fileprivate class TestClass {
+    let a: Int = 1
+    init() {}
+}
+
+fileprivate class TestSubclass: TestClass {
+    let b: Int = 2
+    override init() { super.init() }
+}
+
+fileprivate class TestSubsubclass: TestSubclass {
+    let c: Int = 3
+    override init() { super.init() }
+}
+
 class LogPolicyTests: XCTestCase {
+    func testMaximumDepthLimitZero() {
+        let testPolicy = LogPolicy(maximumDepth: 0)
+
+        let logEntry = LogEntry(describing: TestStruct(), name: "testStruct", policy: testPolicy)
+
+        guard case let .structured(name, _, _, totalChildrenCount, children, disposition) = logEntry else {
+            XCTFail("Expected a structured log entry for a struct")
+            return
+        }
+
+        XCTAssertEqual(name, "testStruct")
+        XCTAssertEqual(disposition, .struct)
+        XCTAssertEqual(totalChildrenCount, 5)
+
+        guard children.count == 1 else {
+            XCTFail("Expected the struct to have exactly one child")
+            return
+        }
+
+        guard case .gap = children[0] else {
+            XCTFail("Expected the struct's only child to be a gap")
+            return
+        }
+    }
+
+    func testMaximumDepthLimitOne() {
+        let testPolicy = LogPolicy(maximumDepth: 1)
+
+        let logEntry = LogEntry(describing: TestStruct(), name: "testStruct", policy: testPolicy)
+
+        guard case let .structured(name, _, _, totalChildrenCount, children, disposition) = logEntry else {
+            XCTFail("Expected a structured log entry for a struct")
+            return
+        }
+
+        XCTAssertEqual(name, "testStruct")
+        XCTAssertEqual(disposition, .struct)
+        XCTAssertEqual(totalChildrenCount, 5)
+        XCTAssertEqual(children.count, 5)
+
+        for (index, child) in children.enumerated() {
+            guard case let .opaque(_, typeName, _, _, representation) = child else {
+                XCTFail("Expected an opaque log entry for an item in the array")
+                continue
+            }
+
+            XCTAssertEqual(typeName, "Int")
+
+            guard let integer = representation as? Int64 else {
+                XCTFail("Expected an Int64 as the representation for an Int")
+                return
+            }
+
+            XCTAssertEqual(integer, Int64(index + 1))
+        }
+    }
+
+    func testMaximumDepthLimitTwoWithSuperclasses() {
+        let testPolicy = LogPolicy(maximumDepth: 2)
+
+        check_TestClass: do {
+            let logEntry = LogEntry(describing: TestClass(), name: "testClass", policy: testPolicy)
+
+            guard case let .structured(name, _, _, totalChildrenCount, children, disposition) = logEntry else {
+                XCTFail("Expected a structured log entry for a class")
+                return
+            }
+
+            XCTAssertEqual(name, "testClass")
+            XCTAssertEqual(disposition, .class)
+            XCTAssertEqual(totalChildrenCount, 1)
+
+            guard children.count == 1 else {
+                XCTFail("Expected TestClass to have exactly one child, but it had \(children.count)")
+                break check_TestClass
+            }
+
+            check_child: do {
+                guard case let .opaque(childName, childTypeName, _, _, childRepresentation) = children[0] else {
+                    XCTFail("Expected an opaque log entry for the first child")
+                    break check_TestClass
+                }
+
+                XCTAssertEqual(childName, "a")
+                XCTAssertEqual(childTypeName, "Int")
+                XCTAssertEqual(childRepresentation as? Int64, 1 as Int64)
+            }
+        }
+
+        check_TestSubclass: do {
+            let logEntry = LogEntry(describing: TestSubclass(), name: "testSubclass", policy: testPolicy)
+
+            guard case let .structured(name, _, _, totalChildrenCount, children, disposition) = logEntry else {
+                XCTFail("Expected a structured log entry for a class")
+                return
+            }
+
+            XCTAssertEqual(name, "testSubclass")
+            XCTAssertEqual(disposition, .class)
+            XCTAssertEqual(totalChildrenCount, 2)
+
+            guard children.count == 2 else {
+                XCTFail("Expected TestSubclass to have exactly two children, but it had \(children.count)")
+                break check_TestSubclass
+            }
+
+            check_superclassChild: do {
+                guard case let .structured(superclassName, _, _, superclassChildrenCount, superclassChildren, superclassDisposition) = children[0] else {
+                    XCTFail("Expected a structured log entry for the first child (superclass)")
+                    break check_TestSubclass
+                }
+
+                XCTAssertEqual(superclassName, "super")
+                XCTAssertEqual(superclassChildrenCount, 1)
+                XCTAssertEqual(superclassDisposition, .class)
+
+                guard superclassChildren.count == 1 else {
+                    XCTFail("Expected exactly one child of the superclass")
+                    break check_superclassChild
+                }
+
+                guard case let .opaque(childName, childTypeName, _, _, childRepresentation) = superclassChildren[0] else {
+                    XCTFail("Expected an opaque log entry for the first child")
+                    break check_superclassChild
+                }
+
+                XCTAssertEqual(childName, "a")
+                XCTAssertEqual(childTypeName, "Int")
+                XCTAssertEqual(childRepresentation as? Int64, 1 as Int64)
+            }
+
+            check_child: do {
+                guard case let .opaque(childName, childTypeName, _, _, childRepresentation) = children[1] else {
+                    XCTFail("Expected an opaque log entry for the second child")
+                    break check_TestSubclass
+                }
+
+                XCTAssertEqual(childName, "b")
+                XCTAssertEqual(childTypeName, "Int")
+                XCTAssertEqual(childRepresentation as? Int64, 2 as Int64)
+            }
+        }
+
+        check_TestSubsubclass: do {
+            let logEntry = LogEntry(describing: TestSubsubclass(), name: "testSubsubclass", policy: testPolicy)
+
+            guard case let .structured(name, _, _, totalChildrenCount, children, disposition) = logEntry else {
+                XCTFail("Expected a structured log entry for a class")
+                return
+            }
+
+            XCTAssertEqual(name, "testSubsubclass")
+            XCTAssertEqual(disposition, .class)
+            XCTAssertEqual(totalChildrenCount, 2)
+
+            guard children.count == 2 else {
+                XCTFail("Expected TestSubsubclass to have exactly two children, but it had \(children.count)")
+                break check_TestSubsubclass
+            }
+
+            check_superclass: do {
+                guard case let .structured(superclassName, _, _, superclassChildrenCount, superclassChildren, superclassDisposition) = children[0] else {
+                    XCTFail("Expected a structured log entry for the first child (superclass)")
+                    break check_superclass
+                }
+
+                XCTAssertEqual(superclassName, "super")
+                XCTAssertEqual(superclassChildrenCount, 2)
+                XCTAssertEqual(superclassDisposition, .class)
+
+                guard superclassChildren.count == 2 else {
+                    XCTFail("Expected exactly two children for the superclass")
+                    break check_superclass
+                }
+
+                check_doubleSuperclass: do {
+                    guard case let .structured(doubleSuperclassName, _, _, doubleSuperclassChildrenCount, doubleSuperclassChildren, doubleSuperclassDisposition) = superclassChildren[0] else {
+                        XCTFail("Expected a structured log entry for the superclass's first child (double-superclass)")
+                        break check_doubleSuperclass
+                    }
+
+                    XCTAssertEqual(doubleSuperclassName, "super")
+                    XCTAssertEqual(doubleSuperclassChildrenCount, 1)
+                    XCTAssertEqual(doubleSuperclassDisposition, .class)
+
+                    guard doubleSuperclassChildren.count == 1 else {
+                        XCTFail("Expected exactly one child for the double-superclass")
+                        break check_doubleSuperclass
+                    }
+
+                    guard case .gap = doubleSuperclassChildren[0] else {
+                        XCTFail("Expected the double-superclass's child to be a gap")
+                        break check_doubleSuperclass
+                    }
+                }
+
+                check_superclassChild: do {
+                    guard case let .opaque(superclassChildName, superclassChildTypeName, _, _, superclassChildRepresentation) = superclassChildren[1] else {
+                        XCTFail("Expected an opaque log entry for the superclass's second child")
+                        break check_superclassChild
+                    }
+
+                    XCTAssertEqual(superclassChildName, "b")
+                    XCTAssertEqual(superclassChildTypeName, "Int")
+                    XCTAssertEqual(superclassChildRepresentation as? Int64, 2 as Int64)
+                }
+            }
+
+            check_child: do {
+                guard case let .opaque(childName, childTypeName, _, _, childRepresentation) = children[1] else {
+                    XCTFail("Expected an opaque log entry for the second child")
+                    break check_child
+                }
+
+                XCTAssertEqual(childName, "c")
+                XCTAssertEqual(childTypeName, "Int")
+                XCTAssertEqual(childRepresentation as? Int64, 3 as Int64)
+            }
+        }
+    }
+
     func testContainerChildPolicyAll() {
         let testPolicy = LogPolicy(containerChildPolicy: .all)