tsdoc/tsdoc/src/beta/DeclarationReference.grammarkdown at main · microsoft/tsdoc · GitHub

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
//
// Lexical Grammar
//

SourceCharacter::
  > Any unicode code point

WhiteSpace::
  <TAB>
  <VT>
  <FF>
  <SP>
  <NBSP>
  <ZWNBSP>
  <USP>

LineTerminator::
  <LF>
  <CR>
  <LS>
  <PS>

// MeaningKeyword represents each of the possible meanings of a TypeScript symbol,
// in addition to some custom types.
MeaningKeyword: one of
  `class`                                       // SymbolFlags.Class
  `interface`                                   // SymbolFlags.Interface
  `type`                                        // SymbolFlags.TypeAlias
  `enum`                                        // SymbolFlags.Enum
  `namespace`                                   // SymbolFlags.Module
  `function`                                    // SymbolFlags.Function
  `var`                                         // SymbolFlags.Variable
  `constructor`                                 // SymbolFlags.Constructor
  `member`                                      // SymbolFlags.ClassMember | SymbolFlags.EnumMember
  `event`                                       //
  `call`                                        // SymbolFlags.Signature (for __call)
  `new`                                         // SymbolFlags.Signature (for __new)
  `index`                                       // SymbolFlags.Signature (for __index)
  `complex`                                     // Any complex type

Punctuator:: one of
  `{` `}` `(` `)` `[` `]` `!` `.` `#` `~` `:` `,`

FutureReservedPunctuator:: one of
  `{` `}` `@`

NavigationPunctuator: one of
  `.`                                           // Navigate via 'exports' of symbol
  `#`                                           // Navigate via 'members' of symbol
  `~`                                           // Navigate via 'locals' of symbol

DecimalDigits::
  DecimalDigit
  DecimalDigits DecimalDigit

DecimalDigit:: one of
  `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`

HexDigits::
  HexDigit HexDigits?

HexDigit:: one of
  `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` `a` `b` `c` `d` `e` `f` `A` `B` `C` `D` `E` `F`

String::
  `"` StringCharacters? `"`

StringCharacters::
  StringCharacter StringCharacters?

StringCharacter::
  SourceCharacter but not one of `"` or `\` or LineTerminator
  `\` EscapeSequence

EscapeSequence::
  CharacterEscapeSequence
  `0` [lookahead != DecimalDigit]
  HexEscapeSequence
  UnicodeEscapeSequence

CharacterEscapeSequence::
  SingleEscapeCharacter
  NonEscapeCharacter

SingleEscapeCharacter:: one of
  `'` `"` `\` `b` `f` `n` `r` `t` `v`

NonEscapeCharacter::
  SourceCharacter but not one of EscapeCharacter or LineTerminator

EscapeCharacter::
  SingleEscapeCharacter
  DecimalDigit
  `x`
  `u`

HexEscapeSequence::
  `x` HexDigit HexDigit

UnicodeEscapeSequence::
  `u` Hex4Digits
  `u` `{` CodePoint `}`

Hex4Digits::
  HexDigit HexDigit HexDigit HexDigit

CodePoint::
  > |HexDigits| but only if MV of |HexDigits| ≤ 0x10FFFF

// Represents the path for a module
ModuleSource::
  String
  ModuleSourceCharacters

ModuleSourceCharacters::
  ModuleSourceCharacter ModuleSourceCharacters?

ModuleSourceCharacter::
  SourceCharacter but not one of `"` or `!` or LineTerminator

Component::
  String
  ComponentCharacters
  `[` DeclarationReference `]`

ComponentCharacters::
  ComponentCharacter ComponentCharacters?

ComponentCharacter::
  SourceCharacter but not one of `"` or Punctuator or FutureReservedPunctuator or WhiteSpace or LineTerminator

//
// Syntactic Grammar
//

// NOTE: The following grammar is incorrect as |SymbolReference| and |ModuleSource| have an
//       ambiguous parse. The correct solution is to use a cover grammar to parse
//       |SymbolReference| until we hit a `!` and then reinterpret the grammar.
DeclarationReference:
  [empty]
  SymbolReference                               // Shorthand reference to symbol
  ModuleSource `!`                              // Reference to a module
  ModuleSource `!` SymbolReference              // Reference to an export of a module
  ModuleSource `!` `~` SymbolReference          // Reference to a local of a module
  `!` SymbolReference                           // Reference to global symbol

SymbolReference:
  ComponentPath Meaning?
  Meaning

ComponentPath:
  Component
  ComponentPath `.` Component                      // Navigate via 'exports' of |ComponentPath|
  ComponentPath `#` Component                      // Navigate via 'members' of |ComponentPath|
  ComponentPath `~` Component                      // Navigate via 'locals' of |ComponentPath|

Meaning:
  `:` MeaningKeyword                            // Indicates the meaning of a symbol (i.e. ':class')
  `:` MeaningKeyword `(` DecimalDigits `)`      // Indicates an overloaded meaning (i.e. ':function(1)')
  `:` `(` DecimalDigits `)`                     // Shorthand for an overloaded meaning (i.e. `:(1)`)
  `:` DecimalDigits                             // Shorthand for an overloaded meaning (i.e. ':1')