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
|
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2023 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 the list of Swift project authors
//
//===----------------------------------------------------------------------===//
import SwiftSyntax
/// Generates grammar doc comments for syntax nodes.
struct GrammarGenerator {
/// Returns grammar for a ``TokenChoice``.
///
/// - parameters:
/// - tokenChoice: ``TokenChoice`` to describe
private func grammar(for tokenChoice: TokenChoice) -> String {
switch tokenChoice {
case .keyword(let keyword):
return "`\(keyword.spec.name)`"
case .token(let token):
let tokenSpec = token.spec
if let tokenText = tokenSpec.text {
return "`\(tokenText)`"
} else {
return "`<\(tokenSpec.varOrCaseName)>`"
}
}
}
private func grammar(for child: Child) -> String {
let optionality = child.isOptional ? "?" : ""
switch child.kind {
case .node(let kind):
return "\(kind.doccLink)\(optionality)"
case .nodeChoices(let choices):
let choicesDescriptions = choices.map { grammar(for: $0) }
return "(\(choicesDescriptions.joined(separator: " | ")))\(optionality)"
case .collection(kind: let kind, _, _, _):
return "\(kind.doccLink)\(optionality)"
case .token(let choices, _, _):
if choices.count == 1 {
return "\(grammar(for: choices.first!))\(optionality)"
} else {
let choicesDescriptions = choices.map { grammar(for: $0) }
return "(\(choicesDescriptions.joined(separator: " | ")))\(optionality)"
}
}
}
/// Generates a markdown list containing the children’s names and their
/// grammar.
///
/// - Parameter children: The children to show in the list
static func childrenList(for children: [Child]) -> String {
let generator = GrammarGenerator()
return
children
.filter { !$0.isUnexpectedNodes }
.map { " - `\($0.varOrCaseName)`: \(generator.grammar(for: $0))" }
.joined(separator: "\n")
}
/// Generates a markdown string describing possible choices for the given child
/// token.
static func childTokenChoices(for choices: [TokenChoice]) -> String {
let grammar = GrammarGenerator()
if choices.count == 1 {
return """
### Tokens
For syntax trees generated by the parser, this is guaranteed to be \(grammar.grammar(for: choices.first!)).
"""
} else {
return """
### Tokens
For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
\(choices.map { " - \(grammar.grammar(for: $0))" }.joined(separator: "\n"))
"""
}
}
}
|
