1
>
/*---------------------------------------------------------------------------------------------
textfiles.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { URI } from '../../../../base/common/uri.js';
7
>
import { Event } from '../../../../base/common/event.js';
8
>
import { IDisposable } from '../../../../base/common/lifecycle.js';
9
>
import { ISaveOptions, IRevertOptions, SaveReason } from '../../../common/editor.js';
10
>
import { ReadableStream } from '../../../../base/common/stream.js';
11
>
import { IBaseFileStatWithMetadata, IFileStatWithMetadata, IWriteFileOptions, FileOperationError, FileOperationResult, IReadFileStreamOptions, IFileReadLimits } from '../../../../platform/files/common/files.js';
12
>
import { createDecorator } from '../../../../platform/instantiation/common/instantiation.js';
13
>
import { ITextEditorModel } from '../../../../editor/common/services/resolverService.js';
14
>
import { ITextBufferFactory, ITextModel, ITextSnapshot } from '../../../../editor/common/model.js';
15
>
import { VSBuffer, VSBufferReadable, VSBufferReadableStream } from '../../../../base/common/buffer.js';
16
>
import { areFunctions, isUndefinedOrNull } from '../../../../base/common/types.js';
17
>
import { IWorkingCopy, IWorkingCopySaveEvent } from '../../workingCopy/common/workingCopy.js';
18
>
import { IUntitledTextEditorModelManager } from '../../untitled/common/untitledTextEditorService.js';
19
>
import { CancellationToken } from '../../../../base/common/cancellation.js';
20
>
import { IProgress, IProgressStep } from '../../../../platform/progress/common/progress.js';
21
>
import { IFileOperationUndoRedoInfo } from '../../workingCopy/common/workingCopyFileService.js';
22
>
23
>
export const ITextFileService = createDecorator<ITextFileService>('textFileService');
24
>
25
>
export interface ITextFileService extends IDisposable {
26
>
27
>
readonly _serviceBrand: undefined;
28
>
29
>
/**
30
>
* Access to the manager of text file editor models providing further
31
>
* methods to work with them.
32
>
*/
33
>
readonly files: ITextFileEditorModelManager;
34
>
35
>
/**
36
>
* Access to the manager of untitled text editor models providing further
37
>
* methods to work with them.
38
>
*/
39
>
readonly untitled: IUntitledTextEditorModelManager;
40
>
41
>
/**
42
>
* Helper to determine encoding for resources.
43
>
*/
44
>
readonly encoding: IResourceEncodings;
45
>
46
>
/**
47
>
* A resource is dirty if it has unsaved changes or is an untitled file not yet saved.
48
>
*
49
>
* @param resource the resource to check for being dirty
50
>
*/
51
>
isDirty(resource: URI): boolean;
52
>
53
>
/**
54
>
* Saves the resource.
55
>
*
56
>
* @param resource the resource to save
57
>
* @param options optional save options
58
>
* @return Path of the saved resource or undefined if canceled.
59
>
*/
60
>
save(resource: URI, options?: ITextFileSaveOptions): Promise<URI | undefined>;
61
>
62
>
/**
63
>
* Saves the provided resource asking the user for a file name or using the provided one.
64
>
*
65
>
* @param resource the resource to save as.
66
>
* @param targetResource the optional target to save to.
67
>
* @param options optional save options
68
>
* @return Path of the saved resource or undefined if canceled.
69
>
*/
70
>
saveAs(resource: URI, targetResource?: URI, options?: ITextFileSaveAsOptions): Promise<URI | undefined>;
71
>
72
>
/**
73
>
* Reverts the provided resource.
74
>
*
75
>
* @param resource the resource of the file to revert.
76
>
* @param force to force revert even when the file is not dirty
77
>
*/
78
>
revert(resource: URI, options?: IRevertOptions): Promise<void>;
79
>
80
>
/**
81
>
* Read the contents of a file identified by the resource.
82
>
*/
83
>
read(resource: URI, options?: IReadTextFileOptions): Promise<ITextFileContent>;
84
>
85
>
/**
86
>
* Read the contents of a file identified by the resource as stream.
87
>
*/
88
>
readStream(resource: URI, options?: IReadTextFileOptions): Promise<ITextFileStreamContent>;
89
>
90
>
/**
91
>
* Update a file with given contents.
92
>
*/
93
>
write(resource: URI, value: string | ITextSnapshot, options?: IWriteTextFileOptions): Promise<IFileStatWithMetadata>;
94
>
95
>
/**
96
>
* Create files. If the file exists it will be overwritten with the contents if
97
>
* the options enable to overwrite.
98
>
*/
99
>
create(operations: { resource: URI; value?: string | ITextSnapshot; options?: { overwrite?: boolean } }[], undoInfo?: IFileOperationUndoRedoInfo): Promise<readonly IFileStatWithMetadata[]>;
100
>
101
>
/**
102
>
* Returns the readable that uses the appropriate encoding. This method should
103
>
* be used whenever a `string` or `ITextSnapshot` is being persisted to the
104
>
* file system.
105
>
*/
106
>
getEncodedReadable(resource: URI | undefined, value: ITextSnapshot, options?: IWriteTextFileOptions): Promise<VSBufferReadable>;
107
>
getEncodedReadable(resource: URI | undefined, value: string, options?: IWriteTextFileOptions): Promise<VSBuffer | VSBufferReadable>;
108
>
getEncodedReadable(resource: URI | undefined, value?: ITextSnapshot, options?: IWriteTextFileOptions): Promise<VSBufferReadable | undefined>;
109
>
getEncodedReadable(resource: URI | undefined, value?: string, options?: IWriteTextFileOptions): Promise<VSBuffer | VSBufferReadable | undefined>;
110
>
getEncodedReadable(resource: URI | undefined, value?: string | ITextSnapshot, options?: IWriteTextFileOptions): Promise<VSBuffer | VSBufferReadable | undefined>;
111
>
112
>
/**
113
>
* Returns a stream of strings that uses the appropriate encoding. This method should
114
>
* be used whenever a `VSBufferReadableStream` is being loaded from the file system.
115
>
*
116
>
* Will throw an error if `acceptTextOnly: true` for resources that seem to be binary.
117
>
*/
118
>
getDecodedStream(resource: URI | undefined, value: VSBufferReadableStream, options?: IReadTextFileEncodingOptions): Promise<ReadableStream<string>>;
119
>
120
>
/**
121
>
* Get the encoding for the provided `resource`. Will try to determine the encoding
122
>
* from any existing model for that `resource` and fallback to the configured defaults.
123
>
*/
124
>
getEncoding(resource: URI): string;
125
>
126
>
/**
127
>
* Get the properties for decoding the provided `resource` based on configuration.
128
>
*/
129
>
resolveDecoding(resource: URI | undefined, options?: IReadTextFileEncodingOptions): Promise<{ preferredEncoding: string; guessEncoding: boolean; candidateGuessEncodings: string[] }>;
130
>
131
>
/**
132
>
* Get the properties for encoding the provided `resource` based on configuration.
133
>
*/
134
>
resolveEncoding(resource: URI | undefined, options?: IWriteTextFileOptions): Promise<{ encoding: string; addBOM: boolean }>;
135
>
136
>
/**
137
>
* Given a detected encoding, validate it against the configured encoding options.
138
>
*/
139
>
validateDetectedEncoding(resource: URI | undefined, detectedEncoding: string, options?: IReadTextFileEncodingOptions): Promise<string>;
140
>
}
141
>
142
>
export interface IReadTextFileEncodingOptions {
143
>
144
>
/**
145
>
* The optional encoding parameter allows to specify the desired encoding when resolving
146
>
* the contents of the file.
147
>
*/
148
>
readonly encoding?: string;
149
>
150
>
/**
151
>
* The optional guessEncoding parameter allows to guess encoding from content of the file.
152
>
*/
153
>
readonly autoGuessEncoding?: boolean;
154
>
155
>
/**
156
>
* The optional candidateGuessEncodings parameter limits the allowed encodings to guess from.
157
>
*/
158
>
readonly candidateGuessEncodings?: string[];
159
>
160
>
/**
161
>
* The optional acceptTextOnly parameter allows to fail this request early if the file
162
>
* contents are not textual.
163
>
*/
164
>
readonly acceptTextOnly?: boolean;
165
>
}
166
>
167
>
export interface IReadTextFileOptions extends IReadTextFileEncodingOptions, IReadFileStreamOptions { }
168
>
169
>
export interface IWriteTextFileOptions extends IWriteFileOptions {
170
>
171
>
/**
172
>
* The encoding to use when updating a file.
173
>
*/
174
>
readonly encoding?: string;
175
>
176
>
/**
177
>
* Whether to write to the file as elevated (admin) user. When setting this option a prompt will
178
>
* ask the user to authenticate as super user.
179
>
*/
180
>
readonly writeElevated?: boolean;
181
>
}
182
>
183
>
export const enum TextFileOperationResult {
184
>
FILE_IS_BINARY
185
>
}
186
>
187
>
export class TextFileOperationError extends FileOperationError {
188
>
189
>
static isTextFileOperationError(obj: unknown): obj is TextFileOperationError {
190
>
return obj instanceof Error && !isUndefinedOrNull((obj as TextFileOperationError).textFileOperationResult);
191
>
}
192
>
193
>
override readonly options?: IReadTextFileOptions & IWriteTextFileOptions;
194
>
195
>
constructor(
196
message: string,
197
public textFileOperationResult: TextFileOperationResult,