1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021-2024 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 Swift project authors
*/
public import Foundation
/// A type that vends bundles and responds to requests for data.
@available(*, deprecated, message: "Pass the context its inputs at initialization instead. This deprecated API will be removed after 6.2 is released")
public protocol DocumentationWorkspaceDataProvider {
/// A string that uniquely identifies this data provider.
///
/// Unless your implementation needs a stable identifier to associate with an external system, it's reasonable to
/// use `UUID().uuidString` for the provider's identifier.
var identifier: String { get }
/// Returns the data backing one of the files that this data provider provides.
///
/// Your implementation can expect to only receive URLs that it provides. It's acceptable to assert if you receive
/// a URL that wasn't provided by your data provider, because this indicates a bug in the ``DocumentationWorkspace``.
///
/// - Parameter url: The URL of a file to return the backing data for.
func contentsOfURL(_ url: URL) throws -> Data
/// Returns the documentation bundles that your data provider provides.
///
/// - Parameter options: Configuration that controls how the provider discovers documentation bundles.
///
/// If your data provider also conforms to ``FileSystemProvider``, there is a default implementation of this method
/// that traverses the ``FileSystemProvider/fileSystem`` to find all documentation bundles in it.
func bundles(options: BundleDiscoveryOptions) throws -> [DocumentationBundle]
}
@available(*, deprecated, message: "Pass the context its inputs at initialization instead. This deprecated API will be removed after 6.2 is released")
public extension DocumentationWorkspaceDataProvider {
/// Returns the documentation bundles that your data provider provides; discovered with the default options.
///
/// If your data provider also conforms to ``FileSystemProvider``, there is a default implementation of this method
/// that traverses the ``FileSystemProvider/fileSystem`` to find all documentation bundles in it.
func bundles() throws -> [DocumentationBundle] {
return try bundles(options: BundleDiscoveryOptions())
}
}
/// Options to configure the discovery of documentation bundles
public struct BundleDiscoveryOptions {
// When adding new configuration, remember to include a default value in the initializer so that an options
// value can be created without passing any arguments, resulting in the "default" configuration.
//
// The provider uses the default configuration in the `DocumentationWorkspaceDataProvider.bundles()` function.
/// Fallback values for information that's missing in the bundle's Info.plist file.
public let infoPlistFallbacks: [String: Any]
/// Additional symbol graph files that the provider should include in the discovered bundles.
public let additionalSymbolGraphFiles: [URL]
/// Creates a new options value with the given configurations.
///
/// - Parameters:
/// - infoPlistFallbacks: Fallback values for information that's missing in the bundle's Info.plist file.
/// - additionalSymbolGraphFiles: Additional symbol graph files that the provider should include in the discovered bundles.
public init(
infoPlistFallbacks: [String: Any] = [:],
additionalSymbolGraphFiles: [URL] = []
) {
self.infoPlistFallbacks = infoPlistFallbacks
self.additionalSymbolGraphFiles = additionalSymbolGraphFiles
}
/// Creates new bundle discovery options with the provided documentation bundle info
/// as Info.plist fallback values.
///
/// - Parameters:
/// - fallbackInfo: Fallback documentation bundle information to use if any discovered bundles are missing an Info.plist.
/// - additionalSymbolGraphFiles: Additional symbol graph files to augment any discovered bundles.
public init(
fallbackInfo: DocumentationBundle.Info,
additionalSymbolGraphFiles: [URL] = []
) throws {
// Use JSONEncoder to dynamically create the Info.plist fallback
// dictionary the `BundleDiscoveryOption`s expect from given DocumentationBundle.Info
// model.
let data = try JSONEncoder().encode(fallbackInfo)
let serializedFallbackInfo = try JSONSerialization.jsonObject(with: data)
guard let fallbackInfoDictionary = serializedFallbackInfo as? [String: Any] else {
throw DocumentationBundle.Info.Error.wrongType(
expected: [String: Any].Type.self,
actual: type(of: serializedFallbackInfo)
)
}
self.init(
infoPlistFallbacks: fallbackInfoDictionary,
additionalSymbolGraphFiles: additionalSymbolGraphFiles
)
}
}
|
