@codingame/monaco-vscode-api 20.1.0 → 20.2.0

package/vscode/src/vs/editor/common/languages/languageConfiguration.d.ts

@@ -1,56 +1,193 @@
 import { StandardTokenType } from "../encodedTokenAttributes.js";
 import { ScopedLineTokens } from "./supports.js";
+/**
+ * Configuration for line comments.
+ */
 export interface LineCommentConfig {
+    /**
+     * The line comment token, like `//`
+     */
     comment: string;
+    /**
+     * Whether the comment token should not be indented and placed at the first column.
+     * Defaults to false.
+     */
     noIndent?: boolean;
 }
+/**
+ * Describes how comments for a language work.
+ */
 export interface CommentRule {
+    /**
+     * The line comment token, like `// this is a comment`.
+     * Can be a string or an object with comment and optional noIndent properties.
+     */
     lineComment?: string | LineCommentConfig | null;
+    /**
+     * The block comment character pair, like `/* block comment */`
+     */
     blockComment?: CharacterPair | null;
 }
+/**
+ * The language configuration interface defines the contract between extensions and
+ * various editor features, like automatic bracket insertion, automatic indentation etc.
+ */
 export interface LanguageConfiguration {
+    /**
+     * The language's comment settings.
+     */
     comments?: CommentRule;
+    /**
+     * The language's brackets.
+     * This configuration implicitly affects pressing Enter around these brackets.
+     */
     brackets?: CharacterPair[];
+    /**
+     * The language's word definition.
+     * If the language supports Unicode identifiers (e.g. JavaScript), it is preferable
+     * to provide a word definition that uses exclusion of known separators.
+     * e.g.: A regex that matches anything except known separators (and dot is allowed to occur in a floating point number):
+     *   /(-?\d*\.\d\w*)|([^\`\~\!\@\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g
+     */
     wordPattern?: RegExp;
+    /**
+     * The language's indentation settings.
+     */
     indentationRules?: IndentationRule;
+    /**
+     * The language's rules to be evaluated when pressing Enter.
+     */
     onEnterRules?: OnEnterRule[];
+    /**
+     * The language's auto closing pairs. The 'close' character is automatically inserted with the
+     * 'open' character is typed. If not set, the configured brackets will be used.
+     */
     autoClosingPairs?: IAutoClosingPairConditional[];
+    /**
+     * The language's surrounding pairs. When the 'open' character is typed on a selection, the
+     * selected string is surrounded by the open and close characters. If not set, the autoclosing pairs
+     * settings will be used.
+     */
     surroundingPairs?: IAutoClosingPair[];
+    /**
+     * Defines a list of bracket pairs that are colorized depending on their nesting level.
+     * If not set, the configured brackets will be used.
+    */
     colorizedBracketPairs?: CharacterPair[];
+    /**
+     * Defines what characters must be after the cursor for bracket or quote autoclosing to occur when using the \'languageDefined\' autoclosing setting.
+     *
+     * This is typically the set of characters which can not start an expression, such as whitespace, closing brackets, non-unary operators, etc.
+     */
     autoCloseBefore?: string;
+    /**
+     * The language's folding rules.
+     */
     folding?: FoldingRules;
+    /**
+     * **Deprecated** Do not use.
+     *
+     * @deprecated Will be replaced by a better API soon.
+     */
     __electricCharacterSupport?: {
         docComment?: IDocComment;
     };
 }
+/**
+ * @internal
+ */
 type OrUndefined<T> = {
     [P in keyof T]: T[P] | undefined;
 };
+/**
+ * @internal
+ */
 export type ExplicitLanguageConfiguration = OrUndefined<Required<LanguageConfiguration>>;
+/**
+ * Describes indentation rules for a language.
+ */
 export interface IndentationRule {
+    /**
+     * If a line matches this pattern, then all the lines after it should be unindented once (until another rule matches).
+     */
     decreaseIndentPattern: RegExp;
+    /**
+     * If a line matches this pattern, then all the lines after it should be indented once (until another rule matches).
+     */
     increaseIndentPattern: RegExp;
+    /**
+     * If a line matches this pattern, then **only the next line** after it should be indented once.
+     */
     indentNextLinePattern?: RegExp | null;
+    /**
+     * If a line matches this pattern, then its indentation should not be changed and it should not be evaluated against the other rules.
+     */
     unIndentedLinePattern?: RegExp | null;
 }
+/**
+ * Describes language specific folding markers such as '#region' and '#endregion'.
+ * The start and end regexes will be tested against the contents of all lines and must be designed efficiently:
+ * - the regex should start with '^'
+ * - regexp flags (i, g) are ignored
+ */
 export interface FoldingMarkers {
     start: RegExp;
     end: RegExp;
 }
+/**
+ * Describes folding rules for a language.
+ */
 export interface FoldingRules {
+    /**
+     * Used by the indentation based strategy to decide whether empty lines belong to the previous or the next block.
+     * A language adheres to the off-side rule if blocks in that language are expressed by their indentation.
+     * See [wikipedia](https://en.wikipedia.org/wiki/Off-side_rule) for more information.
+     * If not set, `false` is used and empty lines belong to the previous block.
+     */
     offSide?: boolean;
+    /**
+     * Region markers used by the language.
+     */
     markers?: FoldingMarkers;
 }
+/**
+ * Describes a rule to be evaluated when pressing Enter.
+ */
 export interface OnEnterRule {
+    /**
+     * This rule will only execute if the text before the cursor matches this regular expression.
+     */
     beforeText: RegExp;
+    /**
+     * This rule will only execute if the text after the cursor matches this regular expression.
+     */
     afterText?: RegExp;
+    /**
+     * This rule will only execute if the text above the this line matches this regular expression.
+     */
     previousLineText?: RegExp;
+    /**
+     * The action to execute.
+     */
     action: EnterAction;
 }
+/**
+ * Definition of documentation comments (e.g. Javadoc/JSdoc)
+ */
 export interface IDocComment {
+    /**
+     * The string that starts a doc comment (e.g. '/**')
+     */
     open: string;
+    /**
+     * The string that appears on the last line and closes the doc comment (e.g. ' * /').
+     */
     close?: string;
 }
+/**
+ * A tuple of two characters, like a pair of
+ * opening and closing brackets.
+ */
 export type CharacterPair = [
     string,
     string
@@ -62,23 +199,70 @@ export interface IAutoClosingPair {
 export interface IAutoClosingPairConditional extends IAutoClosingPair {
     notIn?: string[];
 }
+/**
+ * Describes what to do with the indentation when pressing Enter.
+ */
 export declare enum IndentAction {
+    /**
+     * Insert new line and copy the previous line's indentation.
+     */
     None = 0,
+    /**
+     * Insert new line and indent once (relative to the previous line's indentation).
+     */
     Indent = 1,
+    /**
+     * Insert two new lines:
+     *  - the first one indented which will hold the cursor
+     *  - the second one at the same indentation level
+     */
     IndentOutdent = 2,
+    /**
+     * Insert new line and outdent once (relative to the previous line's indentation).
+     */
     Outdent = 3
 }
+/**
+ * Describes what to do when pressing Enter.
+ */
 export interface EnterAction {
+    /**
+     * Describe what to do with the indentation.
+     */
     indentAction: IndentAction;
+    /**
+     * Describes text to be appended after the new line and after the indentation.
+     */
     appendText?: string;
+    /**
+     * Describes the number of characters to remove from the new line's indentation.
+     */
     removeText?: number;
 }
+/**
+ * @internal
+ */
 export interface CompleteEnterAction {
+    /**
+     * Describe what to do with the indentation.
+     */
     indentAction: IndentAction;
+    /**
+     * Describes text to be appended after the new line and after the indentation.
+     */
     appendText: string;
+    /**
+     * Describes the number of characters to remove from the new line's indentation.
+     */
     removeText: number;
+    /**
+     * The line's indentation minus removeText
+     */
     indentation: string;
 }
+/**
+ * @internal
+ */
 export declare class StandardAutoClosingPairConditional {
     readonly open: string;
     readonly close: string;
@@ -91,13 +275,24 @@ export declare class StandardAutoClosingPairConditional {
     isOK(standardToken: StandardTokenType): boolean;
     shouldAutoClose(context: ScopedLineTokens, column: number): boolean;
     private _findNeutralCharacterInRange;
+    /**
+     * Find a character in the range [0-9a-zA-Z] that does not appear in the open or close
+     */
     findNeutralCharacter(): string | null;
 }
+/**
+ * @internal
+ */
 export declare class AutoClosingPairs {
+    /** Key is first character of open */
     readonly autoClosingPairsOpenByStart: Map<string, StandardAutoClosingPairConditional[]>;
+    /** Key is last character of open */
     readonly autoClosingPairsOpenByEnd: Map<string, StandardAutoClosingPairConditional[]>;
+    /** Key is first character of close */
     readonly autoClosingPairsCloseByStart: Map<string, StandardAutoClosingPairConditional[]>;
+    /** Key is last character of close */
     readonly autoClosingPairsCloseByEnd: Map<string, StandardAutoClosingPairConditional[]>;
+    /** Key is close. Only has pairs that are a single character */
     readonly autoClosingPairsCloseSingleChar: Map<string, StandardAutoClosingPairConditional[]>;
     constructor(autoClosingPairs: StandardAutoClosingPairConditional[]);
 }

package/vscode/src/vs/editor/common/languages/languageConfigurationRegistry.d.ts

@@ -11,6 +11,9 @@ import { IConfigurationService } from "../../../platform/configuration/common/co
 import { ILanguageService } from "./language.service.js";
 import { LanguageBracketsConfiguration } from "./supports/languageBracketsConfiguration.js";
 import { ILanguageConfigurationService } from "./languageConfigurationRegistry.service.js";
+/**
+ * Interface used to support insertion of mode specific comments.
+ */
 export interface ICommentsConfiguration {
     lineCommentToken?: string;
     lineCommentNoIndent?: boolean;
@@ -44,9 +47,15 @@ export declare class LanguageConfigurationRegistry extends Disposable {
     private readonly _onDidChange;
     readonly onDidChange: Event<LanguageConfigurationChangeEvent>;
     constructor();
+    /**
+     * @param priority Use a higher number for higher priority
+     */
     register(languageId: string, configuration: LanguageConfiguration, priority?: number): IDisposable;
     getLanguageConfiguration(languageId: string): ResolvedLanguageConfiguration | null;
 }
+/**
+ * Immutable.
+*/
 export declare class ResolvedLanguageConfiguration {
     readonly languageId: string;
     readonly underlyingConfig: LanguageConfiguration;

package/vscode/src/vs/editor/common/languages/languageConfigurationRegistry.service.d.ts

@@ -6,6 +6,9 @@ export declare const ILanguageConfigurationService: import("../../../platform/in
 export interface ILanguageConfigurationService {
     readonly _serviceBrand: undefined;
     onDidChange: Event<LanguageConfigurationServiceChangeEvent>;
+    /**
+    * @param priority Use a higher number for higher priority
+    */
     register(languageId: string, configuration: LanguageConfiguration, priority?: number): IDisposable;
     getLanguageConfiguration(languageId: string): ResolvedLanguageConfiguration;
 }

package/vscode/src/vs/editor/common/languages/linkComputer.d.ts

@@ -35,4 +35,9 @@ export declare class LinkComputer {
     private static _createLink;
     static computeLinks(model: ILinkComputerTarget, stateMachine?: StateMachine): ILink[];
 }
+/**
+ * Returns an array of all links contains in the provided
+ * document. *Note* that this operation is computational
+ * expensive and should not run in the UI thread.
+ */
 export declare function computeLinks(model: ILinkComputerTarget | null): ILink[];

package/vscode/src/vs/editor/common/languages/supports/electricCharacter.d.ts

@@ -1,5 +1,9 @@
 import { ScopedLineTokens } from "../supports.js";
 import { RichEditBrackets } from "./richEditBrackets.js";
+/**
+ * Interface used to support electric characters
+ * @internal
+ */
 export interface IElectricAction {
     matchOpenBracket: string;
 }

package/vscode/src/vs/editor/common/languages/supports/indentationLineProcessor.d.ts

@@ -5,19 +5,46 @@ import { IVirtualModel } from "../autoIndent.js";
 import { IViewLineTokens } from "../../tokens/lineTokens.js";
 import { IndentRulesSupport } from "./indentRules.js";
 import { Position } from "../../core/position.js";
+/**
+ * This class is a wrapper class around {@link IndentRulesSupport}.
+ * It processes the lines by removing the language configuration brackets from the regex, string and comment tokens.
+ * It then calls into the {@link IndentRulesSupport} to validate the indentation conditions.
+ */
 export declare class ProcessedIndentRulesSupport {
     private readonly _indentRulesSupport;
     private readonly _indentationLineProcessor;
     constructor(model: IVirtualModel, indentRulesSupport: IndentRulesSupport, languageConfigurationService: ILanguageConfigurationService);
+    /**
+     * Apply the new indentation and return whether the indentation level should be increased after the given line number
+     */
     shouldIncrease(lineNumber: number, newIndentation?: string): boolean;
+    /**
+     * Apply the new indentation and return whether the indentation level should be decreased after the given line number
+     */
     shouldDecrease(lineNumber: number, newIndentation?: string): boolean;
+    /**
+     * Apply the new indentation and return whether the indentation level should remain unchanged at the given line number
+     */
     shouldIgnore(lineNumber: number, newIndentation?: string): boolean;
+    /**
+     * Apply the new indentation and return whether the indentation level should increase on the line after the given line number
+     */
     shouldIndentNextLine(lineNumber: number, newIndentation?: string): boolean;
 }
+/**
+ * This class fetches the processed text around a range which can be used for indentation evaluation.
+ * It returns:
+ * - The processed text before the given range and on the same start line
+ * - The processed text after the given range and on the same end line
+ * - The processed text on the previous line
+ */
 export declare class IndentationContextProcessor {
     private readonly model;
     private readonly indentationLineProcessor;
     constructor(model: ITextModel, languageConfigurationService: ILanguageConfigurationService);
+    /**
+     * Returns the processed text, stripped from the language configuration brackets within the string, comment and regex tokens, around the given range
+     */
     getProcessedTokenContextAroundRange(range: Range): {
         beforeRangeProcessedTokens: IViewLineTokens;
         afterRangeProcessedTokens: IViewLineTokens;

package/vscode/src/vs/editor/common/languages/supports/languageBracketsConfiguration.d.ts

@@ -1,11 +1,21 @@
 import { RegExpOptions } from "../../../../base/common/strings.js";
 import { LanguageConfiguration } from "../languageConfiguration.js";
+/**
+ * Captures all bracket related configurations for a single language.
+ * Immutable.
+*/
 export declare class LanguageBracketsConfiguration {
     readonly languageId: string;
     private readonly _openingBrackets;
     private readonly _closingBrackets;
     constructor(languageId: string, config: LanguageConfiguration);
+    /**
+     * No two brackets have the same bracket text.
+    */
     get openingBrackets(): readonly OpeningBracketKind[];
+    /**
+     * No two brackets have the same bracket text.
+    */
     get closingBrackets(): readonly ClosingBracketKind[];
     getOpeningBracketInfo(bracketText: string): OpeningBracketKind | undefined;
     getClosingBracketInfo(bracketText: string): ClosingBracketKind | undefined;
@@ -25,10 +35,21 @@ export declare class OpeningBracketKind extends BracketKindBase {
     constructor(config: LanguageBracketsConfiguration, bracketText: string, openedBrackets: ReadonlySet<ClosingBracketKind>);
 }
 export declare class ClosingBracketKind extends BracketKindBase {
+    /**
+     * Non empty array of all opening brackets this bracket closes.
+    */
     readonly openingBrackets: ReadonlySet<OpeningBracketKind>;
     private readonly openingColorizedBrackets;
     readonly isOpeningBracket = false;
-    constructor(config: LanguageBracketsConfiguration, bracketText: string, openingBrackets: ReadonlySet<OpeningBracketKind>, openingColorizedBrackets: ReadonlySet<OpeningBracketKind>);
+    constructor(config: LanguageBracketsConfiguration, bracketText: string, 
+    /**
+     * Non empty array of all opening brackets this bracket closes.
+    */
+    openingBrackets: ReadonlySet<OpeningBracketKind>, openingColorizedBrackets: ReadonlySet<OpeningBracketKind>);
+    /**
+     * Checks if this bracket closes the given other bracket.
+     * If the bracket infos come from different configurations, this method will return false.
+    */
     closes(other: OpeningBracketKind): boolean;
     closesColorized(other: OpeningBracketKind): boolean;
     getOpeningBrackets(): readonly OpeningBracketKind[];

package/vscode/src/vs/editor/common/languages/supports/richEditBrackets.d.ts

@@ -1,30 +1,110 @@
 import * as strings from "../../../../base/common/strings.js";
 import { Range } from "../../core/range.js";
 import { CharacterPair } from "../languageConfiguration.js";
+/**
+ * Represents a grouping of colliding bracket pairs.
+ *
+ * Most of the times this contains a single bracket pair,
+ * but sometimes this contains multiple bracket pairs in cases
+ * where the same string appears as a closing bracket for multiple
+ * bracket pairs, or the same string appears an opening bracket for
+ * multiple bracket pairs.
+ *
+ * e.g. of a group containing a single pair:
+ *   open: ['{'], close: ['}']
+ *
+ * e.g. of a group containing multiple pairs:
+ *   open: ['if', 'for'], close: ['end', 'end']
+ */
 export declare class RichEditBracket {
     _richEditBracketBrand: void;
     readonly languageId: string;
+    /**
+     * A 0-based consecutive unique identifier for this bracket pair.
+     * If a language has 5 bracket pairs, out of which 2 are grouped together,
+     * it is expected that the `index` goes from 0 to 4.
+     */
     readonly index: number;
+    /**
+     * The open sequence for each bracket pair contained in this group.
+     *
+     * The open sequence at a specific index corresponds to the
+     * closing sequence at the same index.
+     *
+     * [ open[i], closed[i] ] represent a bracket pair.
+     */
     readonly open: string[];
+    /**
+     * The close sequence for each bracket pair contained in this group.
+     *
+     * The close sequence at a specific index corresponds to the
+     * opening sequence at the same index.
+     *
+     * [ open[i], closed[i] ] represent a bracket pair.
+     */
     readonly close: string[];
+    /**
+     * A regular expression that is useful to search for this bracket pair group in a string.
+     *
+     * This regular expression is built in a way that it is aware of the other bracket
+     * pairs defined for the language, so it might match brackets from other groups.
+     *
+     * See the fine details in `getRegexForBracketPair`.
+     */
     readonly forwardRegex: RegExp;
+    /**
+     * A regular expression that is useful to search for this bracket pair group in a string backwards.
+     *
+     * This regular expression is built in a way that it is aware of the other bracket
+     * pairs defined for the language, so it might match brackets from other groups.
+     *
+     * See the fine defails in `getReversedRegexForBracketPair`.
+     */
     readonly reversedRegex: RegExp;
     private readonly _openSet;
     private readonly _closeSet;
     constructor(languageId: string, index: number, open: string[], close: string[], forwardRegex: RegExp, reversedRegex: RegExp);
+    /**
+     * Check if the provided `text` is an open bracket in this group.
+     */
     isOpen(text: string): boolean;
+    /**
+     * Check if the provided `text` is a close bracket in this group.
+     */
     isClose(text: string): boolean;
     private static _toSet;
 }
 export declare class RichEditBrackets {
     _richEditBracketsBrand: void;
+    /**
+     * All groups of brackets defined for this language.
+     */
     readonly brackets: RichEditBracket[];
+    /**
+     * A regular expression that is useful to search for all bracket pairs in a string.
+     *
+     * See the fine details in `getRegexForBrackets`.
+     */
     readonly forwardRegex: RegExp;
+    /**
+     * A regular expression that is useful to search for all bracket pairs in a string backwards.
+     *
+     * See the fine details in `getReversedRegexForBrackets`.
+     */
     readonly reversedRegex: RegExp;
+    /**
+     * The length (i.e. str.length) for the longest bracket pair.
+     */
     readonly maxBracketLength: number;
+    /**
+     * A map useful for decoding a regex match and finding which bracket group was matched.
+     */
     readonly textIsBracket: {
         [text: string]: RichEditBracket;
     };
+    /**
+     * A set useful for decoding if a regex match is the open bracket of a bracket pair.
+     */
     readonly textIsOpenBracket: {
         [text: string]: boolean;
     };

package/vscode/src/vs/editor/common/languages/supports/tokenization.d.ts

@@ -10,11 +10,17 @@ export declare class ParsedTokenThemeRule {
     _parsedThemeRuleBrand: void;
     readonly token: string;
     readonly index: number;
+    /**
+     * -1 if not set. An or mask of `FontStyle` otherwise.
+     */
     readonly fontStyle: FontStyle;
     readonly foreground: string | null;
     readonly background: string | null;
     constructor(token: string, index: number, fontStyle: number, foreground: string | null, background: string | null);
 }
+/**
+ * Parse a raw theme into rules.
+ */
 export declare function parseTokenTheme(source: ITokenThemeRule[]): ParsedTokenThemeRule[];
 export declare class ColorMap {
     private _lastColorId;
@@ -32,6 +38,9 @@ export declare class TokenTheme {
     private readonly _cache;
     constructor(colorMap: ColorMap, root: ThemeTrieElement);
     getColorMap(): Color[];
+    /**
+     * used for testing purposes
+     */
     getThemeTrieElement(): ExternalThemeTrieElement;
     _match(token: string): ThemeTrieElementRule;
     match(languageId: LanguageId, token: string): number;
@@ -60,6 +69,9 @@ export declare class ThemeTrieElement {
     private readonly _mainRule;
     private readonly _children;
     constructor(mainRule: ThemeTrieElementRule);
+    /**
+     * used for testing purposes
+     */
     toExternalThemeTrieElement(): ExternalThemeTrieElement;
     match(token: string): ThemeTrieElementRule;
     insert(token: string, fontStyle: FontStyle, foreground: ColorId, background: ColorId): void;