@theia/plugin 1.63.0-next.52 → 1.63.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.63.0-next.52+176018e53",
+  "version": "1.63.1",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.62.0"
+    "@theia/ext-scripts": "1.63.1"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "176018e53e62cafec9b25b23ac9f0b4826b6d0f7"
+  "gitHead": "c1f24d58391fec06087b0c4526ce97aa248c3405"
 }

package/src/theia.d.ts

@@ -1454,6 +1454,24 @@ export module '@theia/plugin' {
          */
         readonly languageId: string;
 
+        /**
+         * The file encoding of this document that will be used when the document is saved.
+         *
+         * Use the {@link workspace.onDidChangeTextDocument onDidChangeTextDocument}-event to
+         * get notified when the document encoding changes.
+         *
+         * Note that the possible encoding values are currently defined as any of the following:
+         * 'utf8', 'utf8bom', 'utf16le', 'utf16be', 'windows1252', 'iso88591', 'iso88593',
+         * 'iso885915', 'macroman', 'cp437', 'windows1256', 'iso88596', 'windows1257',
+         * 'iso88594', 'iso885914', 'windows1250', 'iso88592', 'cp852', 'windows1251',
+         * 'cp866', 'cp1125', 'iso88595', 'koi8r', 'koi8u', 'iso885913', 'windows1253',
+         * 'iso88597', 'windows1255', 'iso88598', 'iso885910', 'iso885916', 'windows1254',
+         * 'iso88599', 'windows1258', 'gbk', 'gb18030', 'cp950', 'big5hkscs', 'shiftjis',
+         * 'eucjp', 'euckr', 'windows874', 'iso885911', 'koi8ru', 'koi8t', 'gb2312',
+         * 'cp865', 'cp850'.
+         */
+        readonly encoding: string;
+
         /**
          * The version number of this document (it will strictly increase after each
          * change, including undo/redo).
@@ -7871,29 +7889,75 @@ export module '@theia/plugin' {
          * Opens a document. Will return early if this document is already open. Otherwise
          * the document is loaded and the {@link workspace.onDidOpenTextDocument didOpen}-event fires.
          *
-         * The document is denoted by an {@link Uri uri}. Depending on the {@link Uri.scheme scheme} the
+         * The document is denoted by an {@link Uri}. Depending on the {@link Uri.scheme 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 {@link TextDocumentContentProvider providers} are consulted.
+         * * `file`-scheme: Open a file on disk (`openTextDocument(Uri.file(path))`). Will be rejected if the file
+         * does not exist or cannot be loaded.
+         * * `untitled`-scheme: Open a blank untitled file with associated path (`openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))`).
+         * The language will be derived from the file name.
+         * * For all other schemes contributed {@link TextDocumentContentProvider text document content providers} and
+         * {@link FileSystemProvider file system 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`](#workspace.onDidCloseTextDocument)-event can occur at any time after opening it.
+         * {@linkcode workspace.onDidCloseTextDocument onDidClose}-event can occur at any time after opening it.
          *
          * @param uri Identifies the resource to open.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(uri: Uri): Thenable<TextDocument | undefined>;
+        export function openTextDocument(uri: Uri, options?: {
+            /**
+             * The {@link TextDocument.encoding encoding} of the document to use
+             * for decoding the underlying buffer to text. If omitted, the encoding
+             * will be guessed based on the file content and/or the editor settings
+             * unless the document is already opened.
+             *
+             * Opening a text document that was already opened with a different encoding
+             * has the potential of changing the text contents of the text document.
+             * Specifically, when the encoding results in a different set of characters
+             * than the previous encoding. As such, an error is thrown for dirty documents
+             * when the specified encoding is different from the encoding of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             *
+             * *Note* that if you open a document with an encoding that does not
+             * support decoding the underlying bytes, content may be replaced with
+             * substitution characters as appropriate.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
-         * A short-hand for `openTextDocument(Uri.file(fileName))`.
+         * A short-hand for `openTextDocument(Uri.file(path))`.
          *
-         * @see {@link openTextDocument openTextDocument}
-         * @param fileName A name of a file on disk.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @see {@link workspace.openTextDocument}
+         * @param path A path of a file on disk.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(fileName: string): Thenable<TextDocument | undefined>;
+        export function openTextDocument(path: string, options?: {
+            /**
+             * The {@link TextDocument.encoding encoding} of the document to use
+             * for decoding the underlying buffer to text. If omitted, the encoding
+             * will be guessed based on the file content and/or the editor settings
+             * unless the document is already opened.
+             *
+             * Opening a text document that was already opened with a different encoding
+             * has the potential of changing the text contents of the text document.
+             * Specifically, when the encoding results in a different set of characters
+             * than the previous encoding. As such, an error is thrown for dirty documents
+             * when the specified encoding is different from the encoding of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             *
+             * *Note* that if you open a document with an encoding that does not
+             * support decoding the underlying bytes, content may be replaced with
+             * substitution characters as appropriate.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
          * Opens an untitled text document. The editor will prompt the user for a file
@@ -7901,9 +7965,26 @@ export module '@theia/plugin' {
          * specify the *language* and/or the *content* of the document.
          *
          * @param options Options to control how the document will be created.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(options?: { language?: string; content?: string; }): Thenable<TextDocument | undefined>;
+        export function openTextDocument(options?: {
+            /**
+             * The {@link TextDocument.languageId language} of the document.
+             */
+            language?: string;
+            /**
+             * The initial contents of the document.
+             */
+            content?: string;
+            /**
+             * The {@link TextDocument.encoding encoding} of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
          *  Open a notebook. Will return early if this notebook is already {@link NotebookDocument loaded}.
@@ -8138,6 +8219,130 @@ export module '@theia/plugin' {
          * Event that fires when the current workspace has been trusted.
          */
         export const onDidGrantWorkspaceTrust: Event<void>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string`. You MUST
+         * provide the entire content at once to ensure that the encoding
+         * can properly apply. Do not use this method to decode content
+         * in chunks, as that may lead to incorrect results.
+         *
+         * Will pick an encoding based on settings and the content of the
+         * buffer (for example byte order marks).
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The text content to decode as a `Uint8Array`.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array): Thenable<string>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string` using the
+         * provided encoding. You MUST provide the entire content at once
+         * to ensure that the encoding can properly apply. Do not use this
+         * method to decode content in chunks, as that may lead to incorrect
+         * results.
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The text content to decode as a `Uint8Array`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array, options: {
+            /**
+             * Allows to explicitly pick the encoding to use.
+             * See {@link TextDocument.encoding} for more information
+             * about valid values for encoding.
+             * Using an unsupported encoding will fallback to the
+             * default configured encoding.
+             */
+            readonly encoding: string;
+        }): Thenable<string>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string`. You MUST
+         * provide the entire content at once to ensure that the encoding
+         * can properly apply. Do not use this method to decode content
+         * in chunks, as that may lead to incorrect results.
+         *
+         * The encoding is picked based on settings and the content
+         * of the buffer (for example byte order marks).
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The content to decode as a `Uint8Array`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array, options: {
+            /**
+             * The URI that represents the file if known. This information
+             * is used to figure out the encoding related configuration
+             * for the file if any.
+             */
+            readonly uri: Uri;
+        }): Thenable<string>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array`.
+         *
+         * Will pick an encoding based on settings.
+         *
+         * @param content The content to decode as a `string`.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string): Thenable<Uint8Array>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array` using the
+         * provided encoding.
+         *
+         * @param content The content to decode as a `string`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string, options: {
+            /**
+             * Allows to explicitly pick the encoding to use.
+             * See {@link TextDocument.encoding} for more information
+             * about valid values for encoding.
+             * Using an unsupported encoding will fallback to the
+             * default configured encoding.
+             */
+            readonly encoding: string;
+        }): Thenable<Uint8Array>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array`.
+         *
+         * The encoding is picked based on settings.
+         *
+         * @param content The content to decode as a `string`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string, options: {
+            /**
+             * The URI that represents the file if known. This information
+             * is used to figure out the encoding related configuration
+             * for the file if any.
+             */
+            readonly uri: Uri;
+        }): Thenable<Uint8Array>;
+
     }
 
     export interface WorkspaceTrustRequestButton {