|
| 1 | +// |
| 2 | +// This source file is part of the Swift.org open source project |
| 3 | +// |
| 4 | +// Copyright (c) 2024 Apple Inc. and the Swift project authors |
| 5 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 6 | +// |
| 7 | +// See https://swift.org/LICENSE.txt for license information |
| 8 | +// See https://swift.org/CONTRIBUTORS.txt for Swift project authors |
| 9 | +// |
| 10 | + |
| 11 | +#if canImport(Foundation) |
| 12 | +@_spi(Experimental) public import Testing |
| 13 | +private import Foundation |
| 14 | + |
| 15 | +/// A common implementation of ``withUnsafeBufferPointer(for:_:)`` that is |
| 16 | +/// used when a type conforms to `Encodable`, whether or not it also conforms |
| 17 | +/// to `NSSecureCoding`. |
| 18 | +/// |
| 19 | +/// - Parameters: |
| 20 | +/// - attachment: The attachment that is requesting a buffer (that is, the |
| 21 | +/// attachment containing this instance.) |
| 22 | +/// - body: A function to call. A temporary buffer containing a data |
| 23 | +/// representation of this instance is passed to it. |
| 24 | +/// |
| 25 | +/// - Returns: Whatever is returned by `body`. |
| 26 | +/// |
| 27 | +/// - Throws: Whatever is thrown by `body`, or any error that prevented the |
| 28 | +/// creation of the buffer. |
| 29 | +func withUnsafeBufferPointer<E, R>(encoding attachableValue: borrowing E, for attachment: borrowing Test.Attachment<E>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R where E: Test.Attachable & Encodable { |
| 30 | + let format = try EncodingFormat(for: attachment) |
| 31 | + |
| 32 | + let data: Data |
| 33 | + switch format { |
| 34 | + case let .propertyListFormat(propertyListFormat): |
| 35 | + let plistEncoder = PropertyListEncoder() |
| 36 | + plistEncoder.outputFormat = propertyListFormat |
| 37 | + data = try plistEncoder.encode(attachableValue) |
| 38 | + case .default: |
| 39 | + // The default format is JSON. |
| 40 | + fallthrough |
| 41 | + case .json: |
| 42 | + // We cannot use our own JSON encoding wrapper here because that would |
| 43 | + // require it be exported with (at least) package visibility which would |
| 44 | + // create a visible external dependency on Foundation in the main testing |
| 45 | + // library target. |
| 46 | + data = try JSONEncoder().encode(attachableValue) |
| 47 | + } |
| 48 | + |
| 49 | + return try data.withUnsafeBytes(body) |
| 50 | +} |
| 51 | + |
| 52 | +// Implement the protocol requirements generically for any encodable value by |
| 53 | +// encoding to JSON. This lets developers provide trivial conformance to the |
| 54 | +// protocol for types that already support Codable. |
| 55 | +@_spi(Experimental) |
| 56 | +extension Test.Attachable where Self: Encodable { |
| 57 | + /// Encode this value into a buffer using either [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) |
| 58 | + /// or [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder), |
| 59 | + /// then call a function and pass that buffer to it. |
| 60 | + /// |
| 61 | + /// - Parameters: |
| 62 | + /// - attachment: The attachment that is requesting a buffer (that is, the |
| 63 | + /// attachment containing this instance.) |
| 64 | + /// - body: A function to call. A temporary buffer containing a data |
| 65 | + /// representation of this instance is passed to it. |
| 66 | + /// |
| 67 | + /// - Returns: Whatever is returned by `body`. |
| 68 | + /// |
| 69 | + /// - Throws: Whatever is thrown by `body`, or any error that prevented the |
| 70 | + /// creation of the buffer. |
| 71 | + /// |
| 72 | + /// The testing library uses this function when writing an attachment to a |
| 73 | + /// test report or to a file on disk. The encoding used depends on the path |
| 74 | + /// extension specified by the value of `attachment`'s ``Testing/Test/Attachment/preferredName`` |
| 75 | + /// property: |
| 76 | + /// |
| 77 | + /// | Extension | Encoding Used | Encoder Used | |
| 78 | + /// |-|-|-| |
| 79 | + /// | `".xml"` | XML property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) | |
| 80 | + /// | `".plist"` | Binary property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) | |
| 81 | + /// | None, `".json"` | JSON | [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder) | |
| 82 | + /// |
| 83 | + /// OpenStep-style property lists are not supported. If a value conforms to |
| 84 | + /// _both_ [`Encodable`](https://developer.apple.com/documentation/swift/encodable) |
| 85 | + /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding), |
| 86 | + /// the default implementation of this function uses the value's conformance |
| 87 | + /// to `Encodable`. |
| 88 | + /// |
| 89 | + /// - Note: On Apple platforms, if the attachment's preferred name includes |
| 90 | + /// some other path extension, that path extension must represent a type |
| 91 | + /// that conforms to [`UTType.propertyList`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/propertylist) |
| 92 | + /// or to [`UTType.json`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/json). |
| 93 | + public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R { |
| 94 | + try _Testing_Foundation.withUnsafeBufferPointer(encoding: self, for: attachment, body) |
| 95 | + } |
| 96 | +} |
| 97 | +#endif |
0 commit comments