Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace for dealing with the current workspace. A workspace is the representation of the folder that has been opened. There is no workspace when just a file but not a folder has been opened.

The workspace offers support for listening to fs events and for finding files. Both perform well and run outside the editor-process so that they should be always used instead of nodejs-equivalents.

Index

Variables

Const fs

A file system instance that allows to interact with local and remote files, e.g. workspace.fs.readDirectory(someUri) allows to retrieve all entries of a directory or workspace.fs.stat(anotherUri) returns the meta data for a file.

Let name

name: string | undefined

The name of the workspace. undefined when no folder has been opened.

readonly

Const onDidChangeConfiguration

onDidChangeConfiguration: Event<ConfigurationChangeEvent>

An event that is emitted when the configuration changed.

Const onDidChangeTextDocument

onDidChangeTextDocument: Event<TextDocumentChangeEvent>

An event that is emitted when a text document is changed. This usually happens when the contents changes but also when other things like the dirty-state changes.

Const onDidChangeWorkspaceFolders

onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent>

An event that is emitted when a workspace folder is added or removed.

Const onDidCloseTextDocument

onDidCloseTextDocument: Event<TextDocument>

An event that is emitted when a text document is disposed.

To add an event listener when a visible text document is closed, use the TextEditor events in the window namespace. Note that this event is not emitted when a TextEditor is closed but the document remains open in another visible text editor.

Const onDidCreateFiles

onDidCreateFiles: Event<FileCreateEvent>

An event that is emitted when files have been created.

Note: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Const onDidDeleteFiles

onDidDeleteFiles: Event<FileDeleteEvent>

An event that is emitted when files have been deleted.

Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When deleting a folder with children only one event is fired.

Const onDidOpenTextDocument

onDidOpenTextDocument: Event<TextDocument>

An event that is emitted when a text document is opened.

To add an event listener when a visible text document is opened, use the TextEditor events in the window namespace. Note that:

Const onDidRenameFiles

onDidRenameFiles: Event<FileRenameEvent>

An event that is emitted when files have been renamed.

Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When renaming a folder with children only one event is fired.

Const onDidSaveTextDocument

onDidSaveTextDocument: Event<TextDocument>

An event that is emitted when a text document is saved to disk.

Const onWillCreateFiles

onWillCreateFiles: Event<FileWillCreateEvent>

An event that is emitted when files are being created.

Note 1: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api. This event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When this event is fired, edits to files thare are being created cannot be applied.

Const onWillDeleteFiles

onWillDeleteFiles: Event<FileWillDeleteEvent>

An event that is emitted when files are being deleted.

Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When deleting a folder with children only one event is fired.

Const onWillRenameFiles

onWillRenameFiles: Event<FileWillRenameEvent>

An event that is emitted when files are being renamed.

Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

Note 2: When renaming a folder with children only one event is fired.

Const onWillSaveTextDocument

onWillSaveTextDocument: Event<TextDocumentWillSaveEvent>

An event that is emitted when a text document will be saved to disk.

Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

  • there is an overall time budget that all listeners share and if that is exhausted no further listener is called
  • listeners that take a long time or produce errors frequently will not be called anymore

The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

Let rootPath

rootPath: string | undefined

The folder that is open in the editor. undefined when no folder has been opened.

deprecated

Use workspaceFolders instead.

readonly

Let textDocuments

textDocuments: TextDocument[]

All text documents currently known to the system.

readonly

Let workspaceFolders

workspaceFolders: WorkspaceFolder[] | undefined

List of workspace folders or undefined when no folder is open. Note that the first entry corresponds to the value of rootPath.

readonly

Functions

applyEdit

  • Make changes to one or many resources or create, delete, and rename resources as defined by the given workspace edit.

    All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the 'inserts' were made. Invalid sequences like 'delete file a' -> 'insert text in file a' cause failure of the operation.

    When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consective edits will not be attempted, when a single edit fails.

    Parameters

    Returns PromiseLike<boolean>

    A thenable that resolves when the edit could be applied.

asRelativePath

  • asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: undefined | false | true): string | undefined
  • Returns a path that is relative to the workspace folder or folders.

    When there are no workspace folders or when the path is not contained in them, the input is returned.

    Parameters

    • pathOrUri: string | Uri

      A path or uri. When a uri is given its fsPath is used.

    • Optional includeWorkspaceFolder: undefined | false | true

      When true and when the given path is contained inside a workspace folder the name of the workspace is prepended. Defaults to true when there are multiple workspace folders and false otherwise.

    Returns string | undefined

    A path relative to the root or the input.

createFileSystemWatcher

  • createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: undefined | false | true, ignoreChangeEvents?: undefined | false | true, ignoreDeleteEvents?: undefined | false | true): FileSystemWatcher

findFiles

  • Find files across all workspace folders in the workspace.

    sample

    findFiles('**​/*.js', '**​/node_modules/**', 10)

    Parameters

    • include: GlobPattern

      A glob pattern that defines the files to search for. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern to restrict the search results to a workspace folder.

    • Optional exclude: GlobPattern | null

      A glob pattern that defines files and folders to exclude. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. When undefined only default excludes will apply, when null no excludes will apply.

    • Optional maxResults: undefined | number

      An upper-bound for the result.

    • Optional token: CancellationToken

      A token that can be used to signal cancellation to the underlying search engine.

    Returns PromiseLike<Uri[]>

    A thenable that resolves to an array of resource identifiers. Will return no results if no workspace folders are opened.

getConfiguration

  • Get a workspace configuration object.

    When a section-identifier is provided only that part of the configuration is returned. Dots in the section-identifier are interpreted as child-access, like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

    When a resource is provided, configuration scoped to that resource is returned.

    Parameters

    • Optional section: undefined | string

      A dot-separated identifier.

    • Optional resource: Uri | null

      A resource for which the configuration is asked for

    Returns WorkspaceConfiguration

    The full configuration or a subset.

getWorkspaceFolder

openTextDocument

  • openTextDocument(uri: Uri): PromiseLike<TextDocument | undefined>
  • openTextDocument(fileName: string): PromiseLike<TextDocument | undefined>
  • openTextDocument(options?: undefined | object): PromiseLike<TextDocument | undefined>
  • Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the didOpen-event fires.

    The document is denoted by an uri. Depending on the scheme the following rules apply:

    • file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
    • untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language will be derived from the file name.
    • For all other schemes the registered text document content providers are consulted.

    Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.

    Parameters

    • uri: Uri

      Identifies the resource to open.

    Returns PromiseLike<TextDocument | undefined>

    A promise that resolves to a document.

  • A short-hand for openTextDocument(Uri.file(fileName)).

    see

    openTextDocument

    Parameters

    • fileName: string

      A name of a file on disk.

    Returns PromiseLike<TextDocument | undefined>

    A promise that resolves to a document.

  • Opens an untitled text document. The editor will prompt the user for a file path when the document is to be saved. The options parameter allows to specify the language and/or the content of the document.

    Parameters

    • Optional options: undefined | object

      Options to control how the document will be created.

    Returns PromiseLike<TextDocument | undefined>

    A promise that resolves to a document.

registerFileSystemProvider

  • Register a filesystem provider for a given scheme, e.g. ftp.

    There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.

    Parameters

    • scheme: string

      The uri-scheme the provider registers for.

    • provider: FileSystemProvider

      The filesystem provider.

    • Optional options: undefined | object

      Immutable metadata about the provider.

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

registerTaskProvider

  • Register a task provider.

    deprecated

    Use the corresponding function on the tasks namespace instead

    Parameters

    • type: string

      The task kind type this provider is registered for.

    • provider: TaskProvider

      A task provider.

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

registerTextDocumentContentProvider

saveAll

  • saveAll(includeUntitled?: undefined | false | true): PromiseLike<boolean>
  • Save all dirty files.

    Parameters

    • Optional includeUntitled: undefined | false | true

      Also save files that have been created during this session.

    Returns PromiseLike<boolean>

    A thenable that resolves when the files have been saved.

updateWorkspaceFolders

  • updateWorkspaceFolders(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: object[]): boolean
  • This method replaces deleteCount workspace folders starting at index start by an optional set of workspaceFoldersToAdd on the theia.workspace.workspaceFolders array. This "splice" behavior can be used to add, remove and change workspace folders in a single operation.

    If the first workspace folder is added, removed or changed, the currently executing extensions (including the one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is updated to point to the first workspace folder.

    Use the onDidChangeWorkspaceFolders() event to get notified when the workspace folders have been updated.

    Example: adding a new workspace folder at the end of workspace folders

    workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});

    Example: removing the first workspace folder

    workspace.updateWorkspaceFolders(0, 1);

    Example: replacing an existing workspace folder with a new one

    workspace.updateWorkspaceFolders(0, 1, { uri: ...});

    It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.

    Note: it is not valid to call updateWorkspaceFolders() multiple times without waiting for the onDidChangeWorkspaceFolders() to fire.

    Parameters

    • start: number

      the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders.

    • deleteCount: number | undefined | null

      the optional number of workspace folders to remove.

    • Rest ...workspaceFoldersToAdd: object[]

      the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name.

    Returns boolean

    true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).