The filesystem provider defines what the editor needs to read, write, discover, and to manage files and folders. It allows extensions to serve files from remote places, like ftp-servers, and to seamlessly integrate those into the editor.
- Note 1: The filesystem provider API works with {@link Uri uris} and assumes hierarchical
paths, e.g.
foo:/my/pathis a child offoo:/my/and a parent offoo:/my/path/deeper. - Note 2: There is an activation event
onFileSystem:<scheme>that fires when a file or folder is being accessed. - Note 3: The word 'file' is often used to denote all {@link FileType kinds} of files, e.g. folders, symbolic links, and regular files.
Fields
writeFile(uri:Uri, content:Uint8Array, options:{overwrite:Bool, create:Bool}):EitherType<Void, Thenable<Void>>
Write data to a file, replacing its entire contents.
@linkcode FileSystemError.FileNotFound FileNotFound} when uri doesn't exist and create is not set.
@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of uri doesn't exist and create is set, e.g. no mkdirp-logic required.
@linkcode FileSystemError.FileExists FileExists} when uri already exists, create is set but overwrite is not set.
@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
Parameters:
uri | The uri of the file. |
|---|---|
content | The new content of the file. |
options | Defines if missing files should or must be created. |
Throws:
null | { |
|---|---|
null | { |
null | { |
null | { |
watch(uri:Uri, options:{recursive:Bool, excludes:Array<String>}):Disposable
Subscribe to events in the file or folder denoted by uri.
The editor will call this function for files and folders. In the latter case, the
options differ from defaults, e.g. what files/folders to exclude from watching
and if subfolders, sub-subfolder, etc. should be watched (recursive).
Parameters:
uri | The uri of the file to be watched. |
|---|---|
options | Configures the watch. |
Returns:
A disposable that tells the provider to stop watching the uri.
stat(uri:Uri):EitherType<FileStat, Thenable<FileStat>>
Retrieve metadata about a file.
Note that the metadata for symbolic links should be the metadata of the file they refer to.
Still, the {@link FileType.SymbolicLink SymbolicLink}-type must be used in addition to the actual type, e.g.
FileType.SymbolicLink | FileType.Directory.
@linkcode FileSystemError.FileNotFound FileNotFound} when uri doesn't exist.
Parameters:
uri | The uri of the file to retrieve metadata about. |
|---|
Returns:
The file metadata about the file.
Throws:
null | { |
|---|
rename(oldUri:Uri, newUri:Uri, options:{overwrite:Bool}):EitherType<Void, Thenable<Void>>
Rename a file or folder.
@linkcode FileSystemError.FileNotFound FileNotFound} when oldUri doesn't exist.
@linkcode FileSystemError.FileNotFound FileNotFound} when parent of newUri doesn't exist, e.g. no mkdirp-logic required.
@linkcode FileSystemError.FileExists FileExists} when newUri exists and when the overwrite option is not true.
@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
Parameters:
oldUri | The existing file. |
|---|---|
newUri | The new location. |
options | Defines if existing files should be overwritten. |
Throws:
null | { |
|---|---|
null | { |
null | { |
null | { |
readFile(uri:Uri):EitherType<Uint8Array, Thenable<Uint8Array>>
Read the entire contents of a file.
@linkcode FileSystemError.FileNotFound FileNotFound} when uri doesn't exist.
Parameters:
uri | The uri of the file. |
|---|
Returns:
An array of bytes or a thenable that resolves to such.
Throws:
null | { |
|---|
readDirectory(uri:Uri):EitherType<Array<FileSystemReadDirectoryTuple>, Thenable<Array<FileSystemReadDirectoryTuple>>>
Retrieve all entries of a {@link FileType.Directory directory}.
@linkcode FileSystemError.FileNotFound FileNotFound} when uri doesn't exist.
Parameters:
uri | The uri of the folder. |
|---|
Returns:
An array of name/type-tuples or a thenable that resolves to such.
Throws:
null | { |
|---|
read onlyonDidChangeFile:Event<Array<FileChangeEvent>>
An event to signal that a resource has been created, changed, or deleted. This event should fire for resources that are being {@link FileSystemProvider.watch watched} by clients of this provider.
Note: It is important that the metadata of the file that changed provides an
updated mtime that advanced from the previous value in the {@link FileStat stat} and a
correct size value. Otherwise there may be optimizations in place that will not show
the change in an editor for example.
delete(uri:Uri, options:{recursive:Bool}):EitherType<Void, Thenable<Void>>
Delete a file.
@linkcode FileSystemError.FileNotFound FileNotFound} when uri doesn't exist.
@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
Parameters:
uri | The resource that is to be deleted. |
|---|---|
options | Defines if deletion of folders is recursive. |
Throws:
null | { |
|---|---|
null | { |
createDirectory(uri:Uri):EitherType<Void, Thenable<Void>>
Create a new directory (Note, that new files are created via write-calls).
@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of uri doesn't exist, e.g. no mkdirp-logic required.
@linkcode FileSystemError.FileExists FileExists} when uri already exists.
@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
Parameters:
uri | The uri of the new folder. |
|---|
Throws:
null | { |
|---|---|
null | { |
null | { |
optionalcopy:Null<(source:Uri, destination:Uri, options:{overwrite:Bool}) ‑> EitherType<Void, Thenable<Void>>>
Copy files or folders. Implementing this function is optional but it will speedup the copy operation.
@linkcode FileSystemError.FileNotFound FileNotFound} when source doesn't exist.
@linkcode FileSystemError.FileNotFound FileNotFound} when parent of destination doesn't exist, e.g. no mkdirp-logic required.
@linkcode FileSystemError.FileExists FileExists} when destination exists and when the overwrite option is not true.
@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
Parameters:
source | The existing file. |
|---|---|
destination | The destination location. |
options | Defines if existing files should be overwritten. |
Throws:
null | { |
|---|---|
null | { |
null | { |
null | { |