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
|
# Extending the Symbol Graph Format
Define custom Symbol or Relationship kinds and store custom information in the graph.
## Overview
SymbolKit makes it easy to parse Symbol Graph Files and inspect or edit the resulting graph's _contents_. However, sometimes you might want to go beyond that by changing the _structure_ of the graph. SymbolKit allows you to define custom Symbol and Relationship kinds and lets you extend nodes and edges with custom properties.
## Defining Custom Symbol or Relationship Kinds
To define a custom ``SymbolGraph/Symbol/KindIdentifier`` or ``SymbolGraph/Relationship/Kind-swift.struct``, first create a static constant using the initializers ``SymbolGraph/Symbol/KindIdentifier/init(rawValue:)`` or ``SymbolGraph/Relationship/Kind-swift.struct/init(rawValue:)``, respectively.
Make sure to **not** include a language prefix such as `"swift."` here for Symbol kinds!
```swift
extension SymbolGraph.Symbol.KindIdentifier {
static let extendedModule = KindIdentifier(rawValue: "module.extension")
}
extension SymbolGraph.Relationship.Kind {
static let extensionTo = Kind(rawValue: "extensionTo")
}
```
Use these constants when manually initializing Symbols/Relationships of the respective kind instead of initializing new instances of ``SymbolGraph/Symbol/KindIdentifier`` / ``SymbolGraph/Relationship/Kind-swift.struct`` all the time.
After defining a custom Symbol kind, make sure to register it using ``SymbolGraph/Symbol/KindIdentifier/register(_:)``. This ensures all static functionality defined on ``SymbolGraph/Symbol/KindIdentifier`` works as expected.
```swift
SymbolGraph.Symbol.KindIdentifier.register(.extendedModule)
// true
print(SymbolGraph.Symbol.KindIdentifier.isKnownIdentifier("swift.module.extension"))
```
## Defining Custom Properties
The key to storing arbitrary information on Symbols or Relationships is the ``Mixin`` protocol.
Start out by defining the information you want to capture:
```swift
/// Commit metadata of the last commit that modified this Symbol.
struct LastCommit: Mixin, Hashable {
static let mixinKey = "lastCommit"
let hash: String
let date: Date
let authorName: String
let authorEmail: String
}
```
You might want to extend Symbol/Relationship for easier access:
```swift
extension SymbolGraph.Symbol {
var lastCommit: LastCommit? {
get {
self[mixin: LastCommit.self]
}
set {
self[mixin: LastCommit.self] = newValue
}
}
}
```
You can now easily edit this information on an existing Symbol Graph.
Before you can encode and decode this information, you need to register your custom Mixin on your encoder/decoder using ``SymbolGraph/Symbol/register(mixins:to:onEncodingError:onDecodingError:)`` (for ``SymbolGraph/Symbol``) or ``SymbolGraph/Relationship/register(mixins:to:onEncodingError:onDecodingError:)`` (for ``SymbolGraph/Relationship``). If you forget this step, you custom mixins will be ignored!
- Note: There exist handy shortcuts on Foundation's `JSONEncoder` and `JSONDecoder` for all the registration functions.
```swift
// prepare encoder and decoder to deal with custom mixin
let decoder = JSONDecoder()
decoder.register(symbolMixins: LastCommit.self)
let encoder = JSONEncoder()
encoder.register(symbolMixins: LastCommit.self)
// decode graph
var graph = try decoder.decode(SymbolGraph.self, from: inputData)
// modify graph ...
// encode graph
let outputData = try encoder.encode(graph)
```
## Topics
### Defining Custom Symbol or Relationship Kinds
- ``SymbolGraph/Symbol/KindIdentifier``
- ``SymbolGraph/Symbol/KindIdentifier/init(rawValue:)``
- ``SymbolGraph/Symbol/KindIdentifier/register(_:)``
- ``SymbolGraph/Symbol/KindIdentifier/register(_:to:)``
- ``SymbolGraph/Relationship/Kind-swift.struct``
- ``SymbolGraph/Relationship/Kind-swift.struct/init(rawValue:)``
### Defining Custom Properties
- ``Mixin``
- ``SymbolGraph/Symbol/register(mixins:to:onEncodingError:onDecodingError:)``
- ``SymbolGraph/Relationship/register(mixins:to:onEncodingError:onDecodingError:)``
<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
|
