Skip to content

Commit f35b6ce

Browse files
roblourensroblourens
committed
File/Text search provider docs
1 parent 0707dd4 commit f35b6ce

1 file changed

Lines changed: 42 additions & 16 deletions

File tree

‎src/vs/vscode.proposed.d.ts‎

Lines changed: 42 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -153,23 +153,36 @@ declare module 'vscode' {
153153
preview: TextSearchResultPreview;
154154
}
155155

156+
/**
157+
* A FileIndexProvider provides a list of files in the given folder. VS Code will filter that list for searching with quickopen or from other extensions.
158+
*
159+
* A FileIndexProvider is the simpler of two ways to implement file search in VS Code. Use a FileIndexProvider if you are able to provide a listing of all files
160+
* in a folder, and want VS Code to filter them according to the user's search query.
161+
*
162+
* The FileIndexProvider will be invoked once when quickopen is opened, and VS Code will filter the returned list. It will also be invoked when
163+
* `workspace.findFiles` is called.
164+
*
165+
* If a [`FileSearchProvider`](#FileSearchProvider) is registered for the scheme, that provider will be used instead.
166+
*/
156167
export interface FileIndexProvider {
157-
provideFileIndex(options: FileSearchOptions, token: CancellationToken): Thenable<Uri[]>;
158-
}
159-
160-
export interface TextSearchProvider {
161168
/**
162-
* Provide results that match the given text pattern.
163-
* @param query The parameters for this query.
169+
* Provide the set of files in the folder.
164170
* @param options A set of options to consider while searching.
165-
* @param progress A progress callback that must be invoked for all results.
166171
* @param token A cancellation token.
167172
*/
168-
provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress<TextSearchResult>, token: CancellationToken): Thenable<void>;
173+
provideFileIndex(options: FileSearchOptions, token: CancellationToken): Thenable<Uri[]>;
169174
}
170175

171176
/**
172-
* A FileSearchProvider provides search results for files or text in files. It can be invoked by quickopen and other extensions.
177+
* A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions.
178+
*
179+
* A FileSearchProvider is the more powerful of two ways to implement file search in VS Code. Use a FileSearchProvider if you wish to search within a folder for
180+
* all files that match the user's query.
181+
*
182+
* The FileSearchProvider will be invoked on every keypress in quickopen. When `workspace.findFiles` is called, it will be invoked with an empty query string,
183+
* and in that case, every file in the folder should be returned.
184+
*
185+
* @see [FileIndexProvider](#FileIndexProvider)
173186
*/
174187
export interface FileSearchProvider {
175188
/**
@@ -182,6 +195,20 @@ declare module 'vscode' {
182195
provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, progress: Progress<Uri>, token: CancellationToken): Thenable<void>;
183196
}
184197

198+
/**
199+
* A TextSearchProvider provides search results for text results inside files in the workspace.
200+
*/
201+
export interface TextSearchProvider {
202+
/**
203+
* Provide results that match the given text pattern.
204+
* @param query The parameters for this query.
205+
* @param options A set of options to consider while searching.
206+
* @param progress A progress callback that must be invoked for all results.
207+
* @param token A cancellation token.
208+
*/
209+
provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress<TextSearchResult>, token: CancellationToken): Thenable<void>;
210+
}
211+
185212
/**
186213
* Options that can be set on a findTextInFiles search.
187214
*/
@@ -231,38 +258,37 @@ declare module 'vscode' {
231258
export function registerSearchProvider(): Disposable;
232259

233260
/**
234-
* Register a search provider.
261+
* Register a file index provider.
235262
*
236263
* Only one provider can be registered per scheme.
237264
*
238265
* @param scheme The provider will be invoked for workspace folders that have this file scheme.
239266
* @param provider The provider.
240267
* @return A [disposable](#Disposable) that unregisters this provider when being disposed.
241268
*/
242-
export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable;
269+
export function registerFileIndexProvider(scheme: string, provider: FileIndexProvider): Disposable;
243270

244271
/**
245-
* Register a text search provider.
272+
* Register a search provider.
246273
*
247274
* Only one provider can be registered per scheme.
248275
*
249276
* @param scheme The provider will be invoked for workspace folders that have this file scheme.
250277
* @param provider The provider.
251278
* @return A [disposable](#Disposable) that unregisters this provider when being disposed.
252279
*/
253-
export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable;
280+
export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable;
254281

255282
/**
256-
* Register a file index provider.
283+
* Register a text search provider.
257284
*
258285
* Only one provider can be registered per scheme.
259286
*
260287
* @param scheme The provider will be invoked for workspace folders that have this file scheme.
261288
* @param provider The provider.
262289
* @return A [disposable](#Disposable) that unregisters this provider when being disposed.
263290
*/
264-
export function registerFileIndexProvider(scheme: string, provider: FileIndexProvider): Disposable;
265-
291+
export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable;
266292

267293
/**
268294
* Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace.

0 commit comments

Comments
 (0)