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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021 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
*/
import Foundation
import SymbolKit
extension String {
/// Returns a copy of the string with an appended hash of the given identifier.
func appendingHashedIdentifier(_ identifier: String) -> String {
return appending("-\(identifier.stableHashString)")
}
}
/// A reference to a symbol, possibly defined in a symbol graph.
public struct SymbolReference {
/// Returns `true` if the symbol is a known graph leaf symbol.
static func isLeaf(_ symbol: SymbolGraph.Symbol) -> Bool {
return !symbol.kind.identifier.swiftSymbolCouldHaveChildren
}
/// Creates a new reference to a symbol.
///
/// The two symbols `MyFramework/Manager`, a class, and `MyFramework/manager`, a static variable,
/// have the same topic reference paths. For such symbols, set `shouldAddKind` to `true`
/// to add the symbol kind to the reference path and generate the unique paths
/// `/myframework/manager-swift.class` and `/myframework/manager-swift.variable`.
///
/// Another case might be two symbols of the same kind with colliding paths, for example,
/// the variable `MyFramework/vaRiable` and `MyFramework/VARiable`. Set `shouldAddHash` to `true`
/// to append a hash of the symbol name at the end of the path to make the two paths distinct.
/// - Parameters:
/// - identifier: The precise identifier of a symbol.
/// - interfaceLanguages: The source languages of the symbol.
/// - symbol: The default symbol graph node representing this symbol, if available.
/// - shouldAddHash: If `true`, the new reference has a hash appended to its path.
/// - shouldAddKind: If `true`, the new reference has the referenced-symbol kind appended to its path.
public init(
_ identifier: String,
interfaceLanguages: Set<SourceLanguage>,
defaultSymbol symbol: SymbolGraph.Symbol? = nil,
shouldAddHash: Bool = false,
shouldAddKind: Bool = false
) {
self.interfaceLanguages = Set(interfaceLanguages)
guard let symbol else {
path = shouldAddHash ?
identifier.appendingHashedIdentifier(identifier) :
identifier
return
}
// A module reference does not have path as it's a root symbol in the topic graph.
if symbol.kind.identifier == SymbolGraph.Symbol.KindIdentifier.module {
path = ""
return
}
var name = symbol.pathComponents.joinedSymbolPathComponents
if shouldAddKind {
let interfaceLanguage = symbol.identifier.interfaceLanguage
let languageIdentifier = SourceLanguage(
knownLanguageIdentifier: interfaceLanguage
)?.linkDisambiguationID ?? interfaceLanguage
name = name.appending("-\(languageIdentifier).\(symbol.kind.identifier.identifier)")
}
if shouldAddHash {
name = name.appendingHashedIdentifier(identifier)
}
path = name
}
/// Creates a new reference to a symbol.
///
/// - Parameters:
/// - identifier: The precise identifier of a symbol.
/// - unifiedSymbol: The unified symbol graph node representing this symbol, if available.
/// - shouldAddHash: If `true`, the new reference has a hash appended to its path.
/// - shouldAddKind: If `true`, the new reference has the referenced-symbol kind appended to its path.
public init(
_ identifier: String,
unifiedSymbol: UnifiedSymbolGraph.Symbol? = nil,
shouldAddHash: Bool = false,
shouldAddKind: Bool = false
) {
self.init(
identifier,
interfaceLanguages: unifiedSymbol?.sourceLanguages ?? [],
defaultSymbol: unifiedSymbol?.defaultSymbol,
shouldAddHash: shouldAddHash,
shouldAddKind: shouldAddKind
)
}
/// Creates a new reference to a symbol.
///
/// - Parameters:
/// - identifier: The precise identifier of a symbol.
/// - interfaceLanguage: The source language of the symbol.
/// - symbol: The symbol graph node representing this symbol, if available.
/// - shouldAddHash: If `true`, the new reference has a hash appended to its path.
/// - shouldAddKind: If `true`, the new reference has the referenced-symbol kind appended to its path.
public init(
_ identifier: String,
interfaceLanguage: SourceLanguage,
symbol: SymbolGraph.Symbol? = nil,
shouldAddHash: Bool = false,
shouldAddKind: Bool = false
) {
self.init(
identifier,
interfaceLanguages: [interfaceLanguage],
defaultSymbol: symbol,
shouldAddHash: shouldAddHash,
shouldAddKind: shouldAddKind
)
}
/// Creates a new symbol reference with the given components and source languages.
///
/// - Parameters:
/// - pathComponents: The relative path components from the module or framework to the symbol.
/// - interfaceLanguages: The source languages of the symbol.
public init(
pathComponents: [String],
interfaceLanguages: some Collection<SourceLanguage>
) {
self.path = pathComponents.joinedSymbolPathComponents
self.interfaceLanguages = Set(interfaceLanguages)
}
/// Creates a new symbol reference with the given components and source language.
///
/// - Parameters:
/// - pathComponents: The relative path components from the module or framework to the symbol.
/// - interfaceLanguage: The source language of the symbol.
public init(pathComponents: [String], interfaceLanguage: SourceLanguage) {
self.path = pathComponents.joinedSymbolPathComponents
self.interfaceLanguages = [interfaceLanguage]
}
/// The relative path from the module or framework to the symbol itself.
public let path: String
/// The interface language for the reference.
public let interfaceLanguages: Set<SourceLanguage>
}
private extension [String] {
var joinedSymbolPathComponents: String {
return joined(separator: "/").components(
separatedBy: CharacterSet.urlPathAllowed.inverted
).joined(separator: "_")
}
}
extension UnifiedSymbolGraph.Symbol {
var sourceLanguages: Set<SourceLanguage> {
// FIXME: Replace with new SymbolKit API once available.
// Adding a dedicated SymbolKit API for this purpose is tracked
// with github.com/apple/swift-docc-symbolkit/issues/32 and rdar://85982095.
return Set(
pathComponents.keys.map { selector in
SourceLanguage(knownLanguageIdentifier: selector.interfaceLanguage)
?? SourceLanguage(id: selector.interfaceLanguage)
}
)
}
}
|
