-
Notifications
You must be signed in to change notification settings - Fork 226
/
File.swift
510 lines (447 loc) · 21.5 KB
/
File.swift
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
import Dispatch
import Foundation
#if SWIFT_PACKAGE
import SourceKit
#endif
import SWXMLHash
// swiftlint:disable file_length
// This file could easily be split up
/// Represents a source file.
public final class File { // swiftlint:disable:this type_body_length
/// File path. Nil if initialized directly with `File(contents:)`.
public let path: String?
/// File contents.
public var contents: String {
get {
_contentsQueue.sync {
if _contents == nil {
do {
_contents = try String(contentsOfFile: path!, encoding: .utf8)
} catch {
fputs("Could not read contents of `\(path!)`\n", stderr)
_contents = ""
}
}
}
return _contents!
}
set {
_contentsQueue.sync {
_contents = newValue
_stringViewQueue.sync {
_stringView = nil
}
}
}
}
public func clearCaches() {
_contentsQueue.sync {
_contents = nil
_stringViewQueue.sync {
_stringView = nil
}
}
}
public var stringView: StringView {
_stringViewQueue.sync {
if _stringView == nil {
_stringView = StringView(contents)
}
}
return _stringView!
}
public var lines: [Line] {
return stringView.lines
}
private var _contents: String?
private var _stringView: StringView?
private let _contentsQueue = DispatchQueue(label: "com.sourcekitten.sourcekitten.file.contents")
private let _stringViewQueue = DispatchQueue(label: "com.sourcekitten.sourcekitten.file.stringView")
/**
Failable initializer by path. Fails if file contents could not be read as a UTF8 string.
- parameter path: File path.
*/
public init?(path: String) {
self.path = path.bridge().absolutePathRepresentation()
do {
_contents = try String(contentsOfFile: path, encoding: .utf8)
} catch {
fputs("Could not read contents of `\(path)`\n", stderr)
return nil
}
}
public init(pathDeferringReading path: String) {
self.path = path.bridge().absolutePathRepresentation()
}
/**
Initializer by file contents. File path is nil.
- parameter contents: File contents.
*/
public init(contents: String) {
path = nil
_contents = contents
}
/// Formats the file.
///
/// - Parameters:
/// - trimmingTrailingWhitespace: Boolean
/// - useTabs: Boolean
/// - indentWidth: Int
/// - Returns: formatted String
/// - Throws: Request.Error
public func format(trimmingTrailingWhitespace: Bool,
useTabs: Bool,
indentWidth: Int) throws -> String {
guard let path = path else {
return contents
}
_ = try Request.editorOpen(file: self).send()
var newContents = [String]()
var offset: ByteCount = 0
for line in lines {
let formatResponse = try Request.format(file: path,
line: Int64(line.index),
useTabs: useTabs,
indentWidth: Int64(indentWidth)).send()
let newText = formatResponse["key.sourcetext"] as! String
newContents.append(newText)
guard newText != line.content else { continue }
_ = try Request.replaceText(file: path,
range: ByteRange(location: line.byteRange.location + offset,
length: line.byteRange.length - 1),
sourceText: newText).send()
let oldLength = line.byteRange.length
let newLength = ByteCount(newText.lengthOfBytes(using: .utf8))
offset += 1 + newLength - oldLength
}
if trimmingTrailingWhitespace {
newContents = newContents.map {
$0.bridge().trimmingTrailingCharacters(in: .whitespaces)
}
}
return newContents.joined(separator: "\n") + "\n"
}
/**
Parse source declaration string from SourceKit dictionary.
- parameter dictionary: SourceKit dictionary to extract declaration from.
- returns: Source declaration if successfully parsed.
*/
public func parseDeclaration(_ dictionary: [String: SourceKitRepresentable]) -> String? {
guard shouldParseDeclaration(dictionary),
let start = SwiftDocKey.getOffset(dictionary) else {
return nil
}
let substring: String?
if let end = SwiftDocKey.getBodyOffset(dictionary) {
let range = ByteRange(location: start, length: end - start)
substring = stringView.substringStartingLinesWithByteRange(range)
} else if let length = SwiftDocKey.getLength(dictionary),
SwiftVersion.current >= .fiveDotOne {
let range = ByteRange(location: start, length: length)
substring = stringView.substringStartingLinesWithByteRange(range)
} else {
substring = stringView.substringLinesWithByteRange(ByteRange(location: start, length: 0))
}
return substring?.removingCommonLeadingWhitespaceFromLines()
.trimmingWhitespaceAndOpeningCurlyBrace()
}
/**
Parse line numbers containing the declaration's implementation from SourceKit dictionary.
- parameter dictionary: SourceKit dictionary to extract declaration from.
- returns: Line numbers containing the declaration's implementation.
*/
public func parseScopeRange(_ dictionary: [String: SourceKitRepresentable]) -> (start: Int, end: Int)? {
if !shouldParseDeclaration(dictionary) {
return nil
}
return SwiftDocKey.getOffset(dictionary).flatMap { start in
let end = SwiftDocKey.getBodyOffset(dictionary).flatMap { bodyOffset in
return SwiftDocKey.getBodyLength(dictionary).map { bodyLength in
return bodyOffset + bodyLength
}
} ?? start
return stringView.lineRangeWithByteRange(ByteRange(location: start, length: end - start))
}
}
/**
Extract mark-style comment string from doc dictionary. e.g. '// MARK: - The Name'
- parameter dictionary: Doc dictionary to parse.
- returns: Mark name if successfully parsed.
*/
private func parseMarkName(_ dictionary: [String: SourceKitRepresentable]) -> String? {
precondition(SwiftDocKey.getKind(dictionary)! == SyntaxKind.commentMark.rawValue)
let offset = SwiftDocKey.getOffset(dictionary)!.value
let length = SwiftDocKey.getLength(dictionary)!.value
let fileContentsData = contents.data(using: .utf8)
let subdata = fileContentsData?.subdata(in: offset..<(offset + length))
return subdata.flatMap { String(data: $0, encoding: .utf8) }
}
/**
Returns a copy of the input dictionary with comment mark names, cursor.info information and
parsed declarations for the top-level of the input dictionary and its substructures.
- parameter dictionary: Dictionary to process.
- parameter cursorInfoRequest: Cursor.Info request to get declaration information.
*/
public func process(dictionary: [String: SourceKitRepresentable], cursorInfoRequest: SourceKitObject? = nil,
syntaxMap: SyntaxMap? = nil) -> [String: SourceKitRepresentable] {
var dictionary = dictionary
if let cursorInfoRequest = cursorInfoRequest {
dictionary = merge(
dictionary,
dictWithCommentMarkNamesCursorInfo(dictionary, cursorInfoRequest: cursorInfoRequest)
)
}
// Parse declaration and add to dictionary
if let parsedDeclaration = parseDeclaration(dictionary) {
dictionary[SwiftDocKey.parsedDeclaration.rawValue] = parsedDeclaration
}
// Parse scope range and add to dictionary
if let parsedScopeRange = parseScopeRange(dictionary) {
dictionary[SwiftDocKey.parsedScopeStart.rawValue] = Int64(parsedScopeRange.start)
dictionary[SwiftDocKey.parsedScopeEnd.rawValue] = Int64(parsedScopeRange.end)
}
// Parse `key.doc.full_as_xml` and add to dictionary
if let parsedXMLDocs = (SwiftDocKey.getFullXMLDocs(dictionary).flatMap(parseFullXMLDocs)) {
dictionary = merge(dictionary, parsedXMLDocs)
}
// Update substructure
if let substructure = newSubstructure(dictionary, cursorInfoRequest: cursorInfoRequest, syntaxMap: syntaxMap) {
dictionary[SwiftDocKey.substructure.rawValue] = substructure
}
return dictionary
}
/**
Returns a copy of the input dictionary with additional cursorinfo information at the given
`documentationTokenOffsets` that haven't yet been documented.
- parameter dictionary: Dictionary to insert new docs into.
- parameter documentedTokenOffsets: Offsets that are likely documented.
- parameter cursorInfoRequest: Cursor.Info request to get declaration information.
*/
internal func furtherProcess(dictionary: [String: SourceKitRepresentable], documentedTokenOffsets: [ByteCount],
cursorInfoRequest: SourceKitObject,
syntaxMap: SyntaxMap) -> [String: SourceKitRepresentable] {
var dictionary = dictionary
let offsetMap = makeOffsetMap(documentedTokenOffsets: documentedTokenOffsets, dictionary: dictionary)
for offset in offsetMap.keys.reversed() { // Do this in reverse to insert the doc at the correct offset
if let rawResponse = Request.send(cursorInfoRequest: cursorInfoRequest, atOffset: offset),
let kind = SwiftDocKey.getKind(rawResponse),
SwiftDeclarationKind(rawValue: kind) != nil,
case let response = process(dictionary: rawResponse, cursorInfoRequest: nil, syntaxMap: syntaxMap),
let parentOffset = offsetMap[offset],
let inserted = insert(doc: response, parent: dictionary, offset: parentOffset) {
dictionary = inserted
}
}
return dictionary
}
/**
Update input dictionary's substructure by running `processDictionary(_:cursorInfoRequest:syntaxMap:)` on
its elements, only keeping comment marks and declarations.
- parameter dictionary: Input dictionary to process its substructure.
- parameter cursorInfoRequest: Cursor.Info request to get declaration information.
- returns: A copy of the input dictionary's substructure processed by running
`processDictionary(_:cursorInfoRequest:syntaxMap:)` on its elements, only keeping comment marks
and declarations.
*/
private func newSubstructure(_ dictionary: [String: SourceKitRepresentable], cursorInfoRequest: SourceKitObject?,
syntaxMap: SyntaxMap?) -> [SourceKitRepresentable]? {
return SwiftDocKey.getSubstructure(dictionary)?
.filter(isDeclarationOrCommentMark)
.map {
process(dictionary: $0, cursorInfoRequest: cursorInfoRequest, syntaxMap: syntaxMap)
}
}
/**
Returns an updated copy of the input dictionary with comment mark names and cursor.info information.
- parameter dictionary: Dictionary to update.
- parameter cursorInfoRequest: Cursor.Info request to get declaration information.
*/
private func dictWithCommentMarkNamesCursorInfo(_ dictionary: [String: SourceKitRepresentable],
cursorInfoRequest: SourceKitObject) -> [String: SourceKitRepresentable]? {
guard let kind = SwiftDocKey.getKind(dictionary) else {
return nil
}
// Only update dictionaries with a 'kind' key
if kind == SyntaxKind.commentMark.rawValue, let markName = parseMarkName(dictionary) {
// Update comment marks
return [SwiftDocKey.name.rawValue: markName]
} else if let decl = SwiftDeclarationKind(rawValue: kind), decl != .varParameter, decl != .enumcase {
// Update if kind is a declaration (but not a parameter or the enumcase wrapper)
let innerTypeNameOffset = SwiftDocKey.getName(dictionary)?.byteOffsetOfInnerTypeName() ?? 0
let offset = SwiftDocKey.getNameOffset(dictionary)! + innerTypeNameOffset
var updateDict = Request.send(cursorInfoRequest: cursorInfoRequest, atOffset: offset) ?? [:]
File.untrustedCursorInfoKeys.forEach {
updateDict.removeValue(forKey: $0.rawValue)
}
return updateDict
}
return nil
}
/// Keys to ignore from cursorinfo when already have dictionary from editor.open
private static let untrustedCursorInfoKeys: [SwiftDocKey] = [
.kind, // values from editor.open are more accurate than cursorinfo
.offset, // usually same as nameoffset, but for extension, value locates **type's declaration** in type's file
.length, // usually same as namelength, but for extension, value locates **type's declaration** in type's file
.name // for extensions of nested types has just the inner name, prefer fully-qualified name
]
/**
Returns whether or not a doc should be inserted into a parent at the provided offset.
- parameter parent: Parent dictionary to evaluate.
- parameter offset: Offset to search for in parent dictionary.
- returns: True if a doc should be inserted in the parent at the provided offset.
*/
private func shouldInsert(parent: [String: SourceKitRepresentable], offset: ByteCount) -> Bool {
return SwiftDocKey.getSubstructure(parent) != nil &&
((offset == 0) || SwiftDocKey.getNameOffset(parent) == offset)
}
/**
Inserts a document dictionary at the specified offset.
Parent will be traversed until the offset is found.
Returns nil if offset could not be found.
- parameter doc: Document dictionary to insert.
- parameter parent: Parent to traverse to find insertion point.
- parameter offset: Offset to insert document dictionary.
- returns: Parent with doc inserted if successful.
*/
private func insert(doc: [String: SourceKitRepresentable], parent: [String: SourceKitRepresentable],
offset: ByteCount) -> [String: SourceKitRepresentable]? {
var parent = parent
if shouldInsert(parent: parent, offset: offset) {
var substructure = SwiftDocKey.getSubstructure(parent)!
let docOffset = SwiftDocKey.getBestOffset(doc)!
let insertIndex = substructure.firstIndex(where: { structure in
SwiftDocKey.getBestOffset(structure)! > docOffset
}) ?? substructure.endIndex
substructure.insert(doc, at: insertIndex)
parent[SwiftDocKey.substructure.rawValue] = substructure
return parent
}
for key in parent.keys {
guard var subArray = parent[key] as? [SourceKitRepresentable] else {
continue
}
for index in 0..<subArray.count {
let subDict = insert(doc: doc,
parent: subArray[index] as! [String: SourceKitRepresentable],
offset: offset)
if let subDict = subDict {
subArray[index] = subDict
parent[key] = subArray
return parent
}
}
}
return nil
}
/**
Returns true if the input dictionary contains a parseable declaration.
- parameter dictionary: Dictionary to parse.
*/
private func shouldParseDeclaration(_ dictionary: [String: SourceKitRepresentable]) -> Bool {
let hasTypeName = SwiftDocKey.getTypeName(dictionary) != nil
let hasAnnotatedDeclaration = SwiftDocKey.getAnnotatedDeclaration(dictionary) != nil
let hasOffset = SwiftDocKey.getOffset(dictionary) != nil
return hasTypeName && hasAnnotatedDeclaration && hasOffset
}
/**
Add doc comment attributes to an otherwise complete set of declarations for a file.
- parameter dictionary: dictionary of file declarations
- parameter syntaxMap: syntaxmap for the file
- returns: dictionary of declarations with comments
*/
internal func addDocComments(dictionary: [String: SourceKitRepresentable], syntaxMap: SyntaxMap) -> [String: SourceKitRepresentable] {
return addDocComments(dictionary: dictionary, finder: syntaxMap.createDocCommentFinder())
}
/**
Add doc comment attributes to a declaration and its children
- parameter dictionary: declaration to update
- parameter finder: current state of doc comment location
- returns: updated version of declaration dictionary
*/
internal func addDocComments(dictionary: [String: SourceKitRepresentable], finder: SyntaxMap.DocCommentFinder) -> [String: SourceKitRepresentable] {
var dictionary = dictionary
// special-case skip 'enumcase': has same offset as child 'enumelement'
if let kind = SwiftDocKey.getKind(dictionary).flatMap(SwiftDeclarationKind.init),
kind != .enumcase,
let offset = SwiftDocKey.getBestOffset(dictionary),
let commentRange = finder.getRangeForDeclaration(atOffset: offset),
case let start = commentRange.lowerBound,
case let end = commentRange.upperBound,
let nsRange = stringView.byteRangeToNSRange(ByteRange(location: start, length: end - start)),
let commentBody = contents.commentBody(range: nsRange) {
dictionary[SwiftDocKey.documentationComment.rawValue] = commentBody
}
if let substructure = SwiftDocKey.getSubstructure(dictionary) {
dictionary[SwiftDocKey.substructure.rawValue] = substructure.map {
addDocComments(dictionary: $0, finder: finder)
}
}
return dictionary
}
}
/**
Returns true if the dictionary represents a source declaration or a mark-style comment.
- parameter dictionary: Dictionary to parse.
*/
private func isDeclarationOrCommentMark(_ dictionary: [String: SourceKitRepresentable]) -> Bool {
if let kind = SwiftDocKey.getKind(dictionary) {
return kind != SwiftDeclarationKind.varParameter.rawValue &&
(kind == SyntaxKind.commentMark.rawValue || SwiftDeclarationKind(rawValue: kind) != nil)
}
return false
}
/**
Parse XML from `key.doc.full_as_xml` from `cursor.info` request.
- parameter xmlDocs: Contents of `key.doc.full_as_xml` from SourceKit.
- returns: XML parsed as an `[String: SourceKitRepresentable]`.
*/
public func parseFullXMLDocs(_ xmlDocs: String) -> [String: SourceKitRepresentable]? {
let cleanXMLDocs = xmlDocs.replacingOccurrences(of: "<rawHTML>", with: "")
.replacingOccurrences(of: "</rawHTML>", with: "")
.replacingOccurrences(of: "<codeVoice>", with: "`")
.replacingOccurrences(of: "</codeVoice>", with: "`")
return XMLHash.parse(cleanXMLDocs).children.first.map { rootXML in
var docs = [String: SourceKitRepresentable]()
docs[SwiftDocKey.docType.rawValue] = rootXML.element?.name
docs[SwiftDocKey.docFile.rawValue] = rootXML.element?.allAttributes["file"]?.text
docs[SwiftDocKey.docLine.rawValue] = (rootXML.element?.allAttributes["line"]?.text).flatMap {
Int64($0)
}
docs[SwiftDocKey.docColumn.rawValue] = (rootXML.element?.allAttributes["column"]?.text).flatMap {
Int64($0)
}
docs[SwiftDocKey.docName.rawValue] = rootXML["Name"].element?.text
docs[SwiftDocKey.usr.rawValue] = rootXML["USR"].element?.text
docs[SwiftDocKey.docDeclaration.rawValue] = rootXML["Declaration"].element?.text
// XML before swift 3.2 does not have CommentParts container
let commentPartsXML = (try? rootXML.byKey("CommentParts")) ?? rootXML
let parameters = commentPartsXML["Parameters"].children
if !parameters.isEmpty {
func docParameters(from indexer: XMLIndexer) -> [String: SourceKitRepresentable] {
return [
"name": (indexer["Name"].element?.text ?? ""),
"discussion": (indexer["Discussion"].childrenAsArray() ?? [])
]
}
docs[SwiftDocKey.docParameters.rawValue] = parameters.map(docParameters(from:)) as [SourceKitRepresentable]
}
docs[SwiftDocKey.docDiscussion.rawValue] = commentPartsXML["Discussion"].childrenAsArray()
docs[SwiftDocKey.docResultDiscussion.rawValue] = commentPartsXML["ResultDiscussion"].childrenAsArray()
return docs
}
}
private extension XMLIndexer {
/**
Returns an `[SourceKitRepresentable]` of `[String: SourceKitRepresentable]` items from `indexer` children, if any.
*/
func childrenAsArray() -> [SourceKitRepresentable]? {
if children.isEmpty {
return nil
}
let elements = children.compactMap { $0.element }
func dictionary(from element: SWXMLHash.XMLElement) -> [String: SourceKitRepresentable] {
return [element.name: element.text]
}
return elements.map(dictionary(from:)) as [SourceKitRepresentable]
}
}