Debian Codegraph @

LspCpp/include/LibLsp/lsp/textDocument/SemanticTokens.h

raw
1 #pragma once
2
3 #include "LibLsp/lsp/lsTextDocumentIdentifier.h"
4 #include "LibLsp/lsp/lsVersionedTextDocumentIdentifier.h"
5 #include "LibLsp/JsonRpc/RequestInMessage.h"
6 enum class HighlightingKind_clangD
7 {
8 Variable = 0,
9 LocalVariable,
10 Parameter,
11 Function,
12 Method,
13 StaticMethod,
14 Field,
15 StaticField,
16 Class,
17 Interface,
18 Enum,
19 EnumConstant,
20 Typedef,
21 Type,
22 Unknown,
23 Namespace,
24 TemplateParameter,
25 Concept,
26 Primitive,
27 Macro,
28
29 // This one is different from the other kinds as it's a line style
30 // rather than a token style.
31 InactiveCode,
32
33 LastKind = InactiveCode
34 };
35 std::string toSemanticTokenType(HighlightingKind_clangD kind);
36
37 enum class HighlightingModifier_clangD
38 {
39 Declaration,
40 Deprecated,
41 Deduced,
42 Readonly,
43 Static,
44 Abstract,
45 DependentName,
46 DefaultLibrary,
47
48 FunctionScope,
49 ClassScope,
50 FileScope,
51 GlobalScope,
52
53 LastModifier = GlobalScope
54 };
55 std::string toSemanticTokenModifier(HighlightingModifier_clangD modifier);
56
57 enum SemanticTokenType
58 {
59 ls_namespace = 0, // 'namespace',
60 /**
61 * Represents a generic type. Acts as a fallback for types which
62 * can't be mapped to a specific type like class or enum.
63 */
64 ls_type, // 'type',
65 ls_class, // 'class',
66 ls_enum, // 'enum',
67 ls_interface, // 'interface',
68 ls_struct, // 'struct',
69 ls_typeParameter, // 'typeParameter',
70 ls_parameter, // 'parameter',
71 ls_variable, // 'variable',
72 ls_property, // 'property',
73 ls_enumMember, // 'enumMember',
74 ls_event, // 'event',
75 ls_function, // 'function',
76 ls_method, // 'method',
77 ls_macro, // 'macro',
78 ls_keyword, // 'keyword',
79 ls_modifier, // 'modifier',
80 ls_comment, // 'comment',
81 ls_string, // 'string',
82 ls_number, // 'number',
83 ls_regexp, // 'regexp',
84 ls_operator, // 'operator'
85 lastKind = ls_operator
86 };
87 std::string to_string(SemanticTokenType);
88 unsigned toSemanticTokenType(std::vector<SemanticTokenType>& modifiers);
89
90 enum TokenType_JDT
91 {
92 PACKAGE_JDT = 0,
93 CLASS_JDT,
94 INTERFACE_JDT,
95 ENUM_JDT,
96 ENUM_MEMBER_JDT,
97 TYPE_JDT,
98 TYPE_PARAMETER_JDT,
99 ANNOTATION_JDT,
100 ANNOTATION_MEMBER_JDT,
101 METHOD_JDT,
102 PROPERTY_JDT,
103 VARIABLE_JDT,
104 PARAMETER_JDT
105 };
106 std::string to_string(TokenType_JDT);
107
108 enum SemanticTokenModifier
109 {
110 ls_declaration = 0, // 'declaration',
111 ls_definition, // 'definition',
112 ls_readonly, // 'readonly',
113 ls_static, // 'static',
114 ls_deprecated, // 'deprecated',
115 ls_abstract, // 'abstract',
116 ls_async, // 'async',
117 ls_modification, // 'modification',
118 ls_documentation, // 'documentation',
119 ls_defaultLibrary, // 'defaultLibrary'
120 LastModifier = ls_defaultLibrary
121 };
122 std::string to_string(SemanticTokenModifier);
123 unsigned toSemanticTokenModifiers(std::vector<SemanticTokenModifier>&);
124 /// Specifies a single semantic token in the document.
125 /// This struct is not part of LSP, which just encodes lists of tokens as
126 /// arrays of numbers directly.
127 struct SemanticToken
128 {
129 /// token line number, relative to the previous token
130 unsigned deltaLine = 0;
131 /// token start character, relative to the previous token
132 /// (relative to 0 or the previous token's start if they are on the same line)
133 unsigned deltaStart = 0;
134 /// the length of the token. A token cannot be multiline
135 unsigned length = 0;
136 /// will be looked up in `SemanticTokensLegend.tokenTypes`
137 unsigned tokenType = 0;
138 /// each set bit will be looked up in `SemanticTokensLegend.tokenModifiers`
139 unsigned tokenModifiers = 0;
140 };
141 bool operator==(SemanticToken const&, SemanticToken const&);
142 struct SemanticTokens
143 {
144
145 /**
146 * Tokens in a file are represented as an array of integers. The position of each token is expressed relative to
147 * the token before it, because most tokens remain stable relative to each other when edits are made in a file.
148 *
149 * ---
150 * In short, each token takes 5 integers to represent, so a specific token `i` in the file consists of the following array indices:
151 * - at index `5*i` - `deltaLine`: token line number, relative to the previous token
152 * - at index `5*i+1` - `deltaStart`: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line)
153 * - at index `5*i+2` - `length`: the length of the token. A token cannot be multiline.
154 * - at index `5*i+3` - `tokenType`: will be looked up in `SemanticTokensLegend.tokenTypes`. We currently ask that `tokenType` < 65536.
155 * - at index `5*i+4` - `tokenModifiers`: each set bit will be looked up in `SemanticTokensLegend.tokenModifiers`
156 *
157 * ---
158 * ### How to encode tokens
159 *
160 * Here is an example for encoding a file with 3 tokens in a uint32 array:
161 * ```
162 * { line: 2, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] },
163 * { line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] },
164 * { line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] }
165 * ```
166 *
167 * 1. First of all, a legend must be devised. This legend must be provided up-front and capture all possible token types.
168 * For this example, we will choose the following legend which must be passed in when registering the provider:
169 * ```
170 * tokenTypes: ['property', 'type', 'class'],
171 * tokenModifiers: ['private', 'static']
172 * ```
173 *
174 * 2. The first transformation step is to encode `tokenType` and `tokenModifiers` as integers using the legend. Token types are looked
175 * up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Multiple token modifiers can be set by using bit flags,
176 * so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because
177 * bits 0 and 1 are set. Using this legend, the tokens now are:
178 * ```
179 * { line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
180 * { line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 },
181 * { line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
182 * ```
183 *
184 * 3. The next step is to represent each token relative to the previous token in the file. In this case, the second token
185 * is on the same line as the first token, so the `startChar` of the second token is made relative to the `startChar`
186 * of the first token, so it will be `10 - 5`. The third token is on a different line than the second token, so the
187 * `startChar` of the third token will not be altered:
188 * ```
189 * { deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
190 * { deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 },
191 * { deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
192 * ```
193 *
194 * 4. Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation:
195 * ```
196 * // 1st token, 2nd token, 3rd token
197 * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
198 * ```
199 */
200 std::vector<int32_t> data;
201 static std::vector<int32_t> encodeTokens(std::vector<SemanticToken>& tokens);
202
203 /**
204 * An optional result id. If provided and clients support delta updating
205 * the client will include the result id in the next semantic token request.
206 * A server can then instead of computing all semantic tokens again simply
207 * send a delta.
208 */
209 optional<std::string> resultId;
210 MAKE_SWAP_METHOD(SemanticTokens, data, resultId)
211 };
212 MAKE_REFLECT_STRUCT(SemanticTokens, data, resultId)
213
214 /// Body of textDocument/semanticTokens/full request.
215 struct SemanticTokensParams
216 {
217 /// The text document.
218 lsTextDocumentIdentifier textDocument;
219 MAKE_REFLECT_STRUCT(SemanticTokensParams, textDocument)
220 };
221 MAKE_REFLECT_STRUCT(SemanticTokensParams, textDocument)
222
223 /// Body of textDocument/semanticTokens/full/delta request.
224 /// Requests the changes in semantic tokens since a previous response.
225 struct SemanticTokensDeltaParams
226 {
227 /// The text document.
228 lsTextDocumentIdentifier textDocument;
229 /**
230 * The result id of a previous response. The result Id can either point to
231 * a full response or a delta response depending on what was received last.
232 */
233 std::string previousResultId;
234
235 MAKE_REFLECT_STRUCT(SemanticTokensDeltaParams, textDocument, previousResultId)
236 };
237 MAKE_REFLECT_STRUCT(SemanticTokensDeltaParams, textDocument, previousResultId)
238
239 /// Describes a a replacement of a contiguous range of semanticTokens.
240 struct SemanticTokensEdit
241 {
242 // LSP specifies `start` and `deleteCount` which are relative to the array
243 // encoding of the previous tokens.
244 // We use token counts instead, and translate when serializing this struct.
245 unsigned startToken = 0;
246 unsigned deleteTokens = 0;
247 std::vector<int32_t> tokens; // encoded as a flat integer array
248
249 MAKE_REFLECT_STRUCT(SemanticTokensEdit, startToken, deleteTokens, tokens)
250 };
251 MAKE_REFLECT_STRUCT(SemanticTokensEdit, startToken, deleteTokens, tokens)
252
253 /// This models LSP SemanticTokensDelta | SemanticTokens, which is the result of
254 /// textDocument/semanticTokens/full/delta.
255 struct SemanticTokensOrDelta
256 {
257 optional<std::string> resultId;
258 /// Set if we computed edits relative to a previous set of tokens.
259 optional<std::vector<SemanticTokensEdit>> edits;
260 /// Set if we computed a fresh set of tokens.
261 /// Set if we computed edits relative to a previous set of tokens.
262 optional<std::vector<int32_t>> tokens; // encoded as integer array
263 MAKE_REFLECT_STRUCT(SemanticTokensOrDelta, resultId, edits, tokens)
264 };
265 MAKE_REFLECT_STRUCT(SemanticTokensOrDelta, resultId, edits, tokens)
266
267 struct SemanticTokensLegend
268 {
269 std::vector<std::string> tokenTypes;
270 std::vector<std::string> tokenModifiers;
271 MAKE_REFLECT_STRUCT(SemanticTokensLegend, tokenTypes, tokenModifiers)
272 };
273 MAKE_REFLECT_STRUCT(SemanticTokensLegend, tokenTypes, tokenModifiers)
274
275 DEFINE_REQUEST_RESPONSE_TYPE(
276 td_semanticTokens_full, SemanticTokensParams, optional<SemanticTokens>, "textDocument/semanticTokens/full"
277 )
278 DEFINE_REQUEST_RESPONSE_TYPE(
279 td_semanticTokens_full_delta, SemanticTokensDeltaParams, optional<SemanticTokensOrDelta>,
280 "textDocument/semanticTokens/full/delta"
281 )