Repository navigation
Expand file tree
/
Copy pathapi.ts
More file actions
381 lines (340 loc) · 16.8 KB
/
Copy pathapi.ts
File metadata and controls
381 lines (340 loc) · 16.8 KB
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
/* --------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT license.
* ------------------------------------------------------------------------------------------ */
'use strict';
import * as vscode from 'vscode';
/**
* API version information.
*/
export enum Version {
v0 = 0, // 0.x.x
v1 = 1, // 1.x.x
v2 = 2, // 2.x.x
v3 = 3, // 3.x.x
v4 = 4, // 4.x.x
v5 = 5, // 5.x.x
v6 = 6, // 6.x.x
v7 = 7, // 7.x.x
latest = v7
}
export type CStandard = "c89" | "c99" | "c11" | "c17" | "c23";
export type GnuCStandard = "gnu89" | "gnu99" | "gnu11" | "gnu17" | "gnu23";
export type CppStandard = "c++98" | "c++03" | "c++11" | "c++14" | "c++17" | "c++20" | "c++23" | "c++26";
export type GnuCppStandard = "gnu++98" | "gnu++03" | "gnu++11" | "gnu++14" | "gnu++17" | "gnu++20" | "gnu++23" | "gnu++26";
/**
* An interface to allow VS Code extensions to communicate with the C/C++ extension.
* @see [CppToolsExtension](#CppToolsExtension) for a code example.
*/
export interface CppToolsApi extends vscode.Disposable {
/**
* The version of the API being used.
*/
getVersion(): Version;
/**
* Register a [CustomConfigurationProvider](#CustomConfigurationProvider).
* This should be called as soon as the provider extension has been activated and determines that
* it is capable of providing configurations for the workspace. The provider extension does not
* need to be ready to provide configurations when this is called. The C/C++ extension will not
* request configurations until the extension has signaled that it is ready to provide them.
* @see [](#)
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
*/
registerCustomConfigurationProvider(provider: CustomConfigurationProvider): void;
/**
* Notify the C/C++ extension that the [CustomConfigurationProvider](#CustomConfigurationProvider)
* is ready to provide custom configurations.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
*/
notifyReady(provider: CustomConfigurationProvider): void;
/**
* Notify the C/C++ extension that the current configuration has changed. Upon receiving this
* notification, the C/C++ extension will request the new configurations.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
*/
didChangeCustomConfiguration(provider: CustomConfigurationProvider): void;
/**
* Notify the C/C++ extension that the code browsing configuration has changed. Upon receiving this
* notification, the C/C++ extension will request the new configuration.
* @param provider An instance of the [CustomConfigurationProvider](#CustomConfigurationProvider)
* instance representing the provider extension.
*/
didChangeCustomBrowseConfiguration(provider: CustomConfigurationProvider): void;
}
/**
* An interface to allow this extension to communicate with Custom Configuration Provider extensions.
*/
export interface CustomConfigurationProvider extends vscode.Disposable {
/**
* The friendly name of the Custom Configuration Provider extension.
*/
readonly name: string;
/**
* The id of the extension providing custom configurations. (e.g. `ms-vscode.cpptools`)
*/
readonly extensionId: string;
/**
* A request to determine whether this provider can provide IntelliSense configurations for the given document.
* @param uri The URI of the document.
* @param token (optional) The cancellation token.
* @returns 'true' if this provider can provide IntelliSense configurations for the given document.
*/
canProvideConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable<boolean>;
/**
* A request to get Intellisense configurations for the given files.
* @param uris A list of one of more URIs for the files to provide configurations for.
* @param token (optional) The cancellation token.
* @returns A list of [SourceFileConfigurationItem](#SourceFileConfigurationItem) for the documents that this provider
* is able to provide IntelliSense configurations for.
* Note: If this provider cannot provide configurations for any of the files in `uris`, the provider may omit the
* configuration for that file in the return value. An empty array may be returned if the provider cannot provide
* configurations for any of the files requested.
*/
provideConfigurations(uris: vscode.Uri[], token?: vscode.CancellationToken): Thenable<SourceFileConfigurationItem[]>;
/**
* A request to determine whether this provider can provide a code browsing configuration for the workspace folder.
* @param token (optional) The cancellation token.
* @returns 'true' if this provider can provide a code browsing configuration for the workspace folder.
*/
canProvideBrowseConfiguration(token?: vscode.CancellationToken): Thenable<boolean>;
/**
* A request to get the code browsing configuration for the workspace folder.
* @param token (optional) The cancellation token.
* @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to
* construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration to report, or
* the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration)
* then `null` should be returned.
*/
provideBrowseConfiguration(token?: vscode.CancellationToken): Thenable<WorkspaceBrowseConfiguration | null>;
/**
* A request to determine whether this provider can provide a code browsing configuration for each folder in a multi-root workspace.
* @param token (optional) The cancellation token.
* @returns 'true' if this provider can provide a code browsing configuration for each folder in a multi-root workspace.
*/
canProvideBrowseConfigurationsPerFolder(token?: vscode.CancellationToken): Thenable<boolean>;
/**
* A request to get the code browsing configuration for the workspace folder.
* @param uri The URI of the folder to provide a browse configuration for.
* @param token (optional) The cancellation token.
* @returns A [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) with the information required to
* construct the equivalent of `browse.path` from `c_cpp_properties.json`. If there is no configuration for this folder, or
* the provider indicated that it cannot provide a [WorkspaceBrowseConfiguration](#WorkspaceBrowseConfiguration) per folder
* then `null` should be returned.
*/
provideFolderBrowseConfiguration(uri: vscode.Uri, token?: vscode.CancellationToken): Thenable<WorkspaceBrowseConfiguration | null>;
}
/**
* The model representing the custom IntelliSense configurations for a source file.
*/
export interface SourceFileConfiguration {
/**
* This must also include the system include path (compiler defaults) unless
* [compilerPath](#SourceFileConfiguration.compilerPath) is specified.
* Mac framework paths may also be added to this array.
*/
readonly includePath: string[];
/**
* This must also include the compiler default defines (__cplusplus, etc) unless
* [compilerPath](#SourceFileConfiguration.compilerPath) is specified.
*/
readonly defines: string[];
/**
* The platform, compiler, and architecture variant to emulate.
* IntelliSenseMode values without a platform variant will resolve to a value that matches
* the host platform. For example, if the host platform is Windows and the IntelliSenseMode
* is "clang-x64", then "clang-x64" will resolve to "windows-clang-x64".
*/
readonly intelliSenseMode?: "linux-clang-x86" | "linux-clang-x64" | "linux-clang-arm" | "linux-clang-arm64" |
"linux-gcc-x86" | "linux-gcc-x64" | "linux-gcc-arm" | "linux-gcc-arm64" |
"macos-clang-x86" | "macos-clang-x64" | "macos-clang-arm" | "macos-clang-arm64" |
"macos-gcc-x86" | "macos-gcc-x64" | "macos-gcc-arm" | "macos-gcc-arm64" |
"windows-clang-x86" | "windows-clang-x64" | "windows-clang-arm" | "windows-clang-arm64" |
"windows-gcc-x86" | "windows-gcc-x64" | "windows-gcc-arm" | "windows-gcc-arm64" |
"windows-msvc-x86" | "windows-msvc-x64" | "windows-msvc-arm" | "windows-msvc-arm64" |
"msvc-x86" | "msvc-x64" | "msvc-arm" | "msvc-arm64" |
"gcc-x86" | "gcc-x64" | "gcc-arm" | "gcc-arm64" |
"clang-x86" | "clang-x64" | "clang-arm" | "clang-arm64";
/**
* The C or C++ standard to emulate.
*/
readonly standard?: CStandard | GnuCStandard | CppStandard | GnuCppStandard;
/**
* Any files that need to be included before the source file is parsed.
*/
readonly forcedInclude?: string[];
/**
* The full path to the compiler. If specified, the extension will query it for system includes and defines and
* add them to [includePath](#SourceFileConfiguration.includePath) and [defines](#SourceFileConfiguration.defines).
*/
readonly compilerPath?: string;
/**
* Arguments for the compiler. These arguments will not be processed by the shell and should not include any
* shell variables, quoting or escaping.
*/
readonly compilerArgs?: string[];
/**
* Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed
* content such as shell quoting and escaping.
*/
readonly compilerFragments?: string[];
/**
* The version of the Windows SDK that should be used. This field will only be used if
* [compilerPath](#SourceFileConfiguration.compilerPath) is set and the compiler is capable of targeting Windows.
*/
readonly windowsSdkVersion?: string;
}
/**
* The model representing a source file and its corresponding configuration.
*/
export interface SourceFileConfigurationItem {
/**
* The URI of the source file. It should follow the file URI scheme and represent an absolute path to the file.
* @example
```
// When working with a file path,
// convert it to a vscode.Uri first.
let path: string = ...;
let item: SourceFileConfigurationItem = {
uri: vscode.Uri.file(path),
configuration: ...
};
```
*/
readonly uri: string | vscode.Uri;
/**
* The IntelliSense configuration for [uri](#SourceFileConfigurationItem.uri)
*/
readonly configuration: SourceFileConfiguration;
}
/**
* The model representing the source browsing configuration for a workspace folder.
*/
export interface WorkspaceBrowseConfiguration {
/**
* This must also include the system include path (compiler defaults) unless
* [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is specified.
*/
readonly browsePath: string[];
/**
* The full path to the compiler. If specified, the extension will query it for system includes and
* add them to [browsePath](#WorkspaceBrowseConfiguration.browsePath).
*/
readonly compilerPath?: string;
/**
* Arguments for the compiler. These arguments will not be processed by the shell and should not include any
* shell variables, quoting or escaping.
*/
readonly compilerArgs?: string[];
/**
* Command line fragments for the compiler. These are similar to compiler arguments, but support shell parsed
* content such as shell quoting and escaping.
*/
readonly compilerFragments?: string[];
/**
* The C or C++ standard to emulate. This field defaults to "c++17" and will only be used if
* [compilerPath](#WorkspaceBrowseConfiguration.compilerPath) is set.
*/
readonly standard?: CStandard | GnuCStandard | CppStandard | GnuCppStandard;
/**
* The version of the Windows SDK that should be used. This field defaults to the latest Windows SDK
* installed on the PC and will only be used if [compilerPath](#WorkspaceBrowseConfiguration.compilerPath)
* is set and the compiler is capable of targeting Windows.
*/
readonly windowsSdkVersion?: string;
}
/**
* The interface provided by the C/C++ extension during activation.
* It is recommended to use the helper function [getCppToolsApi](#getCppToolsApi) instead
* of querying the extension instance directly.
*/
export interface CppToolsExtension {
/**
* Get an API object.
* @param version The desired version.
*/
getApi(version: Version): CppToolsApi;
}
/**
* Check if an object satisfies the contract of the CppToolsExtension interface.
*/
function isCppToolsExtension(extension: any): extension is CppToolsExtension {
return extension && extension.getApi;
}
/**
* Check if an object satisfies the contract of the first version of the CppToolsApi.
* (The first release of the API only had two functions)
*/
function isLegacyCppToolsApi(api: any): api is CppToolsApi {
return api && api.registerCustomConfigurationProvider && api.didChangeCustomConfiguration
}
/**
* Helper function to get the CppToolsApi from the cpptools extension.
* @param version The desired API version
* @example
```
import {CppToolsApi, Version, CustomConfigurationProvider, getCppToolsApi} from 'vscode-cpptools';
let api: CppToolsApi|undefined = await getCppToolsApi(Version.v1);
if (api) {
// Inform cpptools that a custom config provider
// will be able to service the current workspace.
api.registerCustomConfigurationProvider(provider);
// Do any required setup that the provider needs.
// Notify cpptools that the provider is ready to
// provide IntelliSense configurations.
api.notifyReady(provider);
}
// Dispose of the 'api' in your extension's
// deactivate() method, or whenever you want to
// unregister the provider.
```
*/
export async function getCppToolsApi(version: Version): Promise<CppToolsApi | undefined> {
let cpptools: vscode.Extension<any> | undefined = vscode.extensions.getExtension("ms-vscode.cpptools");
let extension: CppToolsApi | CppToolsExtension | undefined = undefined;
let api: CppToolsApi | undefined = undefined;
if (cpptools) {
if (!cpptools.isActive) {
try {
// activate may throw if VS Code is shutting down.
extension = await cpptools.activate();
} catch {
}
} else {
extension = cpptools.exports;
}
if (isCppToolsExtension(extension)) {
// ms-vscode.cpptools > 0.17.5
try {
api = extension.getApi(version);
} catch (err) {
// Unfortunately, ms-vscode.cpptools [0.17.6, 0.18.1] throws a RangeError if you specify a version greater than v1.
// These versions of the extension will not be able to act on the newer interface and v2 is a superset of v1, so we can safely fall back to v1.
let e: RangeError = <RangeError>err;
if (e && e.message && e.message.startsWith("Invalid version")) {
api = extension.getApi(Version.v1);
}
}
if (version !== Version.v1) {
if (!api.getVersion) {
console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version 1 instead.`);
} else if (version !== api.getVersion()) {
console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in the current version of the cpptools extension. Using version ${api.getVersion()} instead.`);
}
}
} else if (isLegacyCppToolsApi(extension)) {
// ms-vscode.cpptools version 0.17.5
api = extension;
if (version !== Version.v0) {
console.warn(`[vscode-cpptools-api] version ${version} requested, but is not available in version 0.17.5 of the cpptools extension. Using version 0 instead.`);
}
} else {
console.warn('[vscode-cpptools-api] No cpptools API was found.')
}
} else {
console.warn('[vscode-cpptools-api] C/C++ extension is not installed');
}
return api;
}