@codemirror/language 0.19.8 → 0.20.0

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-import { NodeProp, NodeType, Parser, Tree, TreeFragment, Input, PartialParse, SyntaxNode } from '@lezer/common';
+import { NodeProp, Parser, Tree, TreeFragment, SyntaxNode, NodeType } from '@lezer/common';
 import { LRParser, ParserConfig } from '@lezer/lr';
-import { Facet, Extension, EditorState } from '@codemirror/state';
-import { EditorView } from '@codemirror/view';
+import * as _codemirror_state from '@codemirror/state';
+import { Facet, Extension, EditorState, Range } from '@codemirror/state';
+import { EditorView, DecorationSet, Command, KeyBinding, BlockInfo, Decoration } from '@codemirror/view';
+import { Highlighter, Tag } from '@lezer/highlight';
+import { StyleModule, StyleSpec } from 'style-mod';
 
 /**
-Node prop stored in a grammar's top syntax node to provide the
-facet that stores language data for that language.
+Node prop stored in a parser's top syntax node to provide the
+facet that stores language-specific data for that language.
 */
 declare const languageDataProp: NodeProp<Facet<{
     [name: string]: any;
@@ -30,26 +33,22 @@ declare function defineLanguageFacet(baseData?: {
 /**
 A language object manages parsing and per-language
 [metadata](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt). Parse data is
-managed as a [Lezer](https://lezer.codemirror.net) tree. You'll
-want to subclass this class for custom parsers, or use the
-[`LRLanguage`](https://codemirror.net/6/docs/ref/#language.LRLanguage) or
-[`StreamLanguage`](https://codemirror.net/6/docs/ref/#stream-parser.StreamLanguage) abstractions for
-[Lezer](https://lezer.codemirror.net/) or stream parsers.
+managed as a [Lezer](https://lezer.codemirror.net) tree. The class
+can be used directly, via the [`LRLanguage`](https://codemirror.net/6/docs/ref/#language.LRLanguage)
+subclass for [Lezer](https://lezer.codemirror.net/) LR parsers, or
+via the [`StreamLanguage`](https://codemirror.net/6/docs/ref/#language.StreamLanguage) subclass
+for stream parsers.
 */
 declare class Language {
     /**
-    The [language data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) data
-    facet used for this language.
+    The [language data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) facet
+    used for this language.
     */
     readonly data: Facet<{
         [name: string]: any;
     }>;
     /**
-    The node type of the top node of trees produced by this parser.
-    */
-    readonly topNode: NodeType;
-    /**
-    The extension value to install this provider.
+    The extension value to install this as the document language.
     */
     readonly extension: Extension;
     /**
@@ -58,23 +57,20 @@ declare class Language {
     */
     parser: Parser;
     /**
-    Construct a language object. You usually don't need to invoke
-    this directly. But when you do, make sure you use
-    [`defineLanguageFacet`](https://codemirror.net/6/docs/ref/#language.defineLanguageFacet) to create
-    the first argument.
+    Construct a language object. If you need to invoke this
+    directly, first define a data facet with
+    [`defineLanguageFacet`](https://codemirror.net/6/docs/ref/#language.defineLanguageFacet), and then
+    configure your parser to [attach](https://codemirror.net/6/docs/ref/#language.languageDataProp) it
+    to the language's outer syntax node.
     */
     constructor(
     /**
-    The [language data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) data
-    facet used for this language.
+    The [language data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) facet
+    used for this language.
     */
     data: Facet<{
         [name: string]: any;
-    }>, parser: Parser, 
-    /**
-    The node type of the top node of trees produced by this parser.
-    */
-    topNode: NodeType, extraExtensions?: Extension[]);
+    }>, parser: Parser, extraExtensions?: Extension[]);
     /**
     Query whether this language is active at the given position.
     */
@@ -129,8 +125,9 @@ declare class LRLanguage extends Language {
 }
 /**
 Get the syntax tree for a state, which is the current (possibly
-incomplete) parse tree of active [language](https://codemirror.net/6/docs/ref/#language.Language),
-or the empty tree if there is no language available.
+incomplete) parse tree of the active
+[language](https://codemirror.net/6/docs/ref/#language.Language), or the empty tree if there is no
+language available.
 */
 declare function syntaxTree(state: EditorState): Tree;
 /**
@@ -144,19 +141,26 @@ Queries whether there is a full syntax tree available up to the
 given document position. If there isn't, the background parse
 process _might_ still be working and update the tree further, but
 there is no guarantee of that—the parser will [stop
-working](https://codemirror.net/6/docs/ref/#language.syntaxParserStopped) when it has spent a
+working](https://codemirror.net/6/docs/ref/#language.syntaxParserRunning) when it has spent a
 certain amount of time or has moved beyond the visible viewport.
 Always returns false if no language has been enabled.
 */
 declare function syntaxTreeAvailable(state: EditorState, upto?: number): boolean;
 /**
+Move parsing forward, and update the editor state afterwards to
+reflect the new tree. Will work for at most `timeout`
+milliseconds. Returns true if the parser managed get to the given
+position in that time.
+*/
+declare function forceParsing(view: EditorView, upto?: number, timeout?: number): boolean;
+/**
 Tells you whether the language parser is planning to do more
 parsing work (in a `requestIdleCallback` pseudo-thread) or has
 stopped running, either because it parsed the entire document,
 because it spent too much time and was cut off, or because there
 is no language parser enabled.
 */
-declare function syntaxParserRunning(view: EditorView): boolean | (() => void);
+declare function syntaxParserRunning(view: EditorView): boolean;
 /**
 A parse context provided to parsers working on the editor content.
 */
@@ -170,7 +174,6 @@ declare class ParseContext {
     Tree fragments that can be reused by incremental re-parses.
     */
     fragments: readonly TreeFragment[];
-    treeLen: number;
     /**
     The current editor viewport (or some overapproximation
     thereof). Intended to be used for opportunistically avoiding
@@ -202,20 +205,7 @@ declare class ParseContext {
     When `until` is given, a reparse will be scheduled when that
     promise resolves.
     */
-    static getSkippingParser(until?: Promise<unknown>): {
-        createParse(input: Input, fragments: readonly TreeFragment[], ranges: readonly {
-            from: number;
-            to: number;
-        }[]): PartialParse;
-        startParse(input: string | Input, fragments?: readonly TreeFragment[] | undefined, ranges?: readonly {
-            from: number;
-            to: number;
-        }[] | undefined): PartialParse;
-        parse(input: string | Input, fragments?: readonly TreeFragment[] | undefined, ranges?: readonly {
-            from: number;
-            to: number;
-        }[] | undefined): Tree;
-    };
+    static getSkippingParser(until?: Promise<unknown>): Parser;
     /**
     Get the context for the current parse, or `null` if no editor
     parse is in progress.
@@ -227,7 +217,7 @@ The facet used to associate a language with an editor state.
 */
 declare const language: Facet<Language, Language | null>;
 /**
-This class bundles a [language object](https://codemirror.net/6/docs/ref/#language.Language) with an
+This class bundles a [language](https://codemirror.net/6/docs/ref/#language.Language) with an
 optional set of supporting extensions. Language packages are
 encouraged to export a function that optionally takes a
 configuration object and returns a `LanguageSupport` instance, as
@@ -252,7 +242,7 @@ declare class LanguageSupport {
     */
     extension: Extension;
     /**
-    Create a support object.
+    Create a language support object.
     */
     constructor(
     /**
@@ -484,7 +474,7 @@ definitive indentation can be determined.
 declare const indentNodeProp: NodeProp<(context: TreeIndentContext) => number | null>;
 /**
 Objects of this type provide context information and helper
-methods to indentation functions.
+methods to indentation functions registered on syntax nodes.
 */
 declare class TreeIndentContext extends IndentContext {
     private base;
@@ -608,5 +598,448 @@ declare function foldable(state: EditorState, lineStart: number, lineEnd: number
     from: number;
     to: number;
 } | null;
+declare type DocRange = {
+    from: number;
+    to: number;
+};
+/**
+State effect that can be attached to a transaction to fold the
+given range. (You probably only need this in exceptional
+circumstances—usually you'll just want to let
+[`foldCode`](https://codemirror.net/6/docs/ref/#language.foldCode) and the [fold
+gutter](https://codemirror.net/6/docs/ref/#language.foldGutter) create the transactions.)
+*/
+declare const foldEffect: _codemirror_state.StateEffectType<DocRange>;
+/**
+State effect that unfolds the given range (if it was folded).
+*/
+declare const unfoldEffect: _codemirror_state.StateEffectType<DocRange>;
+/**
+Get a [range set](https://codemirror.net/6/docs/ref/#state.RangeSet) containing the folded ranges
+in the given state.
+*/
+declare function foldedRanges(state: EditorState): DecorationSet;
+/**
+Fold the lines that are selected, if possible.
+*/
+declare const foldCode: Command;
+/**
+Unfold folded ranges on selected lines.
+*/
+declare const unfoldCode: Command;
+/**
+Fold all top-level foldable ranges. Note that, in most cases,
+folding information will depend on the [syntax
+tree](https://codemirror.net/6/docs/ref/#language.syntaxTree), and folding everything may not work
+reliably when the document hasn't been fully parsed (either
+because the editor state was only just initialized, or because the
+document is so big that the parser decided not to parse it
+entirely).
+*/
+declare const foldAll: Command;
+/**
+Unfold all folded code.
+*/
+declare const unfoldAll: Command;
+/**
+Default fold-related key bindings.
+
+ - Ctrl-Shift-[ (Cmd-Alt-[ on macOS): [`foldCode`](https://codemirror.net/6/docs/ref/#language.foldCode).
+ - Ctrl-Shift-] (Cmd-Alt-] on macOS): [`unfoldCode`](https://codemirror.net/6/docs/ref/#language.unfoldCode).
+ - Ctrl-Alt-[: [`foldAll`](https://codemirror.net/6/docs/ref/#language.foldAll).
+ - Ctrl-Alt-]: [`unfoldAll`](https://codemirror.net/6/docs/ref/#language.unfoldAll).
+*/
+declare const foldKeymap: readonly KeyBinding[];
+interface FoldConfig {
+    /**
+    A function that creates the DOM element used to indicate the
+    position of folded code. The `onclick` argument is the default
+    click event handler, which toggles folding on the line that
+    holds the element, and should probably be added as an event
+    handler to the returned element.
+    
+    When this option isn't given, the `placeholderText` option will
+    be used to create the placeholder element.
+    */
+    placeholderDOM?: ((view: EditorView, onclick: (event: Event) => void) => HTMLElement) | null;
+    /**
+    Text to use as placeholder for folded text. Defaults to `"…"`.
+    Will be styled with the `"cm-foldPlaceholder"` class.
+    */
+    placeholderText?: string;
+}
+/**
+Create an extension that configures code folding.
+*/
+declare function codeFolding(config?: FoldConfig): Extension;
+declare type Handlers = {
+    [event: string]: (view: EditorView, line: BlockInfo, event: Event) => boolean;
+};
+interface FoldGutterConfig {
+    /**
+    A function that creates the DOM element used to indicate a
+    given line is folded or can be folded.
+    When not given, the `openText`/`closeText` option will be used instead.
+    */
+    markerDOM?: ((open: boolean) => HTMLElement) | null;
+    /**
+    Text used to indicate that a given line can be folded.
+    Defaults to `"⌄"`.
+    */
+    openText?: string;
+    /**
+    Text used to indicate that a given line is folded.
+    Defaults to `"›"`.
+    */
+    closedText?: string;
+    /**
+    Supply event handlers for DOM events on this gutter.
+    */
+    domEventHandlers?: Handlers;
+}
+/**
+Create an extension that registers a fold gutter, which shows a
+fold status indicator before foldable lines (which can be clicked
+to fold or unfold the line).
+*/
+declare function foldGutter(config?: FoldGutterConfig): Extension;
+
+/**
+A highlight style associates CSS styles with higlighting
+[tags](https://lezer.codemirror.net/docs/ref#highlight.Tag).
+*/
+declare class HighlightStyle implements Highlighter {
+    /**
+    A style module holding the CSS rules for this highlight style.
+    When using
+    [`highlightTree`](https://lezer.codemirror.net/docs/ref#highlight.highlightTree)
+    outside of the editor, you may want to manually mount this
+    module to show the highlighting.
+    */
+    readonly module: StyleModule | null;
+    readonly style: (tags: readonly Tag[]) => string | null;
+    readonly scope: ((type: NodeType) => boolean) | undefined;
+    private constructor();
+    /**
+    Create a highlighter style that associates the given styles to
+    the given tags. The specs must be objects that hold a style tag
+    or array of tags in their `tag` property, and either a single
+    `class` property providing a static CSS class (for highlighter
+    that rely on external styling), or a
+    [`style-mod`](https://github.com/marijnh/style-mod#documentation)-style
+    set of CSS properties (which define the styling for those tags).
+    
+    The CSS rules created for a highlighter will be emitted in the
+    order of the spec's properties. That means that for elements that
+    have multiple tags associated with them, styles defined further
+    down in the list will have a higher CSS precedence than styles
+    defined earlier.
+    */
+    static define(specs: readonly TagStyle[], options?: {
+        /**
+        By default, highlighters apply to the entire document. You can
+        scope them to a single language by providing the language
+        object or a language's top node type here.
+        */
+        scope?: Language | NodeType;
+        /**
+        Add a style to _all_ content. Probably only useful in
+        combination with `scope`.
+        */
+        all?: string | StyleSpec;
+        /**
+        Specify that this highlight style should only be active then
+        the theme is dark or light. By default, it is active
+        regardless of theme.
+        */
+        themeType?: "dark" | "light";
+    }): HighlightStyle;
+}
+/**
+Wrap a highlighter in an editor extension that uses it to apply
+syntax highlighting to the editor content.
+
+When multiple (non-fallback) styles are provided, the styling
+applied is the union of the classes they emit.
+*/
+declare function syntaxHighlighting(highlighter: Highlighter, options?: {
+    /**
+    When enabled, this marks the highlighter as a fallback, which
+    only takes effect if no other highlighters are registered.
+    */
+    fallback: boolean;
+}): Extension;
+/**
+Returns the CSS classes (if any) that the highlighters active in
+the state would assign to the given style
+[tags](https://lezer.codemirror.net/docs/ref#highlight.Tag) and
+(optional) language
+[scope](https://codemirror.net/6/docs/ref/#language.HighlightStyle^define^options.scope).
+*/
+declare function highlightingFor(state: EditorState, tags: readonly Tag[], scope?: NodeType): string | null;
+/**
+The type of object used in
+[`HighlightStyle.define`](https://codemirror.net/6/docs/ref/#language.HighlightStyle^define).
+Assigns a style to one or more highlighting
+[tags](https://lezer.codemirror.net/docs/ref#highlight.Tag), which can either be a fixed class name
+(which must be defined elsewhere), or a set of CSS properties, for
+which the library will define an anonymous class.
+*/
+interface TagStyle {
+    /**
+    The tag or tags to target.
+    */
+    tag: Tag | readonly Tag[];
+    /**
+    If given, this maps the tags to a fixed class name.
+    */
+    class?: string;
+    /**
+    Any further properties (if `class` isn't given) will be
+    interpreted as in style objects given to
+    [style-mod](https://github.com/marijnh/style-mod#documentation).
+    (The type here is `any` because of TypeScript limitations.)
+    */
+    [styleProperty: string]: any;
+}
+/**
+A default highlight style (works well with light themes).
+*/
+declare const defaultHighlightStyle: HighlightStyle;
+
+interface Config {
+    /**
+    Whether the bracket matching should look at the character after
+    the cursor when matching (if the one before isn't a bracket).
+    Defaults to true.
+    */
+    afterCursor?: boolean;
+    /**
+    The bracket characters to match, as a string of pairs. Defaults
+    to `"()[]{}"`. Note that these are only used as fallback when
+    there is no [matching
+    information](https://lezer.codemirror.net/docs/ref/#common.NodeProp^closedBy)
+    in the syntax tree.
+    */
+    brackets?: string;
+    /**
+    The maximum distance to scan for matching brackets. This is only
+    relevant for brackets not encoded in the syntax tree. Defaults
+    to 10 000.
+    */
+    maxScanDistance?: number;
+    /**
+    Can be used to configure the way in which brackets are
+    decorated. The default behavior is to add the
+    `cm-matchingBracket` class for matching pairs, and
+    `cm-nonmatchingBracket` for mismatched pairs or single brackets.
+    */
+    renderMatch?: (match: MatchResult, state: EditorState) => readonly Range<Decoration>[];
+}
+/**
+Create an extension that enables bracket matching. Whenever the
+cursor is next to a bracket, that bracket and the one it matches
+are highlighted. Or, when no matching bracket is found, another
+highlighting style is used to indicate this.
+*/
+declare function bracketMatching(config?: Config): Extension;
+/**
+The result returned from `matchBrackets`.
+*/
+interface MatchResult {
+    /**
+    The extent of the bracket token found.
+    */
+    start: {
+        from: number;
+        to: number;
+    };
+    /**
+    The extent of the matched token, if any was found.
+    */
+    end?: {
+        from: number;
+        to: number;
+    };
+    /**
+    Whether the tokens match. This can be false even when `end` has
+    a value, if that token doesn't match the opening token.
+    */
+    matched: boolean;
+}
+/**
+Find the matching bracket for the token at `pos`, scanning
+direction `dir`. Only the `brackets` and `maxScanDistance`
+properties are used from `config`, if given. Returns null if no
+bracket was found at `pos`, or a match result otherwise.
+*/
+declare function matchBrackets(state: EditorState, pos: number, dir: -1 | 1, config?: Config): MatchResult | null;
+
+/**
+Encapsulates a single line of input. Given to stream syntax code,
+which uses it to tokenize the content.
+*/
+declare class StringStream {
+    /**
+    The line.
+    */
+    string: string;
+    private tabSize;
+    /**
+    The current indent unit size.
+    */
+    indentUnit: number;
+    /**
+    The current position on the line.
+    */
+    pos: number;
+    /**
+    The start position of the current token.
+    */
+    start: number;
+    private lastColumnPos;
+    private lastColumnValue;
+    /**
+    True if we are at the end of the line.
+    */
+    eol(): boolean;
+    /**
+    True if we are at the start of the line.
+    */
+    sol(): boolean;
+    /**
+    Get the next code unit after the current position, or undefined
+    if we're at the end of the line.
+    */
+    peek(): string | undefined;
+    /**
+    Read the next code unit and advance `this.pos`.
+    */
+    next(): string | void;
+    /**
+    Match the next character against the given string, regular
+    expression, or predicate. Consume and return it if it matches.
+    */
+    eat(match: string | RegExp | ((ch: string) => boolean)): string | void;
+    /**
+    Continue matching characters that match the given string,
+    regular expression, or predicate function. Return true if any
+    characters were consumed.
+    */
+    eatWhile(match: string | RegExp | ((ch: string) => boolean)): boolean;
+    /**
+    Consume whitespace ahead of `this.pos`. Return true if any was
+    found.
+    */
+    eatSpace(): boolean;
+    /**
+    Move to the end of the line.
+    */
+    skipToEnd(): void;
+    /**
+    Move to directly before the given character, if found on the
+    current line.
+    */
+    skipTo(ch: string): boolean | void;
+    /**
+    Move back `n` characters.
+    */
+    backUp(n: number): void;
+    /**
+    Get the column position at `this.pos`.
+    */
+    column(): number;
+    /**
+    Get the indentation column of the current line.
+    */
+    indentation(): number;
+    /**
+    Match the input against the given string or regular expression
+    (which should start with a `^`). Return true or the regexp match
+    if it matches.
+    
+    Unless `consume` is set to `false`, this will move `this.pos`
+    past the matched text.
+    
+    When matching a string `caseInsensitive` can be set to true to
+    make the match case-insensitive.
+    */
+    match(pattern: string | RegExp, consume?: boolean, caseInsensitive?: boolean): boolean | RegExpMatchArray | null;
+    /**
+    Get the current token.
+    */
+    current(): string;
+}
+
+/**
+A stream parser parses or tokenizes content from start to end,
+emitting tokens as it goes over it. It keeps a mutable (but
+copyable) object with state, in which it can store information
+about the current context.
+*/
+interface StreamParser<State> {
+    /**
+    Produce a start state for the parser.
+    */
+    startState?(indentUnit: number): State;
+    /**
+    Read one token, advancing the stream past it, and returning a
+    string indicating the token's style tag—either the name of one
+    of the tags in
+    [`tags`](https://lezer.codemirror.net/docs/ref#highlight.tags),
+    or such a name suffixed by one or more tag
+    [modifier](https://lezer.codemirror.net/docs/ref#highlight.Tag^defineModifier)
+    names, separated by periods. For example `"keyword"` or
+    "`variableName.constant"`.
+    
+    It is okay to return a zero-length token, but only if that
+    updates the state so that the next call will return a non-empty
+    token again.
+    */
+    token(stream: StringStream, state: State): string | null;
+    /**
+    This notifies the parser of a blank line in the input. It can
+    update its state here if it needs to.
+    */
+    blankLine?(state: State, indentUnit: number): void;
+    /**
+    Copy a given state. By default, a shallow object copy is done
+    which also copies arrays held at the top level of the object.
+    */
+    copyState?(state: State): State;
+    /**
+    Compute automatic indentation for the line that starts with the
+    given state and text.
+    */
+    indent?(state: State, textAfter: string, context: IndentContext): number | null;
+    /**
+    Default [language data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) to
+    attach to this language.
+    */
+    languageData?: {
+        [name: string]: any;
+    };
+    /**
+    Extra tokens to use in this parser. When the tokenizer returns a
+    token name that exists as a property in this object, the
+    corresponding tag will be assigned to the token.
+    */
+    tokenTable?: {
+        [name: string]: Tag;
+    };
+}
+/**
+A [language](https://codemirror.net/6/docs/ref/#language.Language) class based on a CodeMirror
+5-style [streaming parser](https://codemirror.net/6/docs/ref/#language.StreamParser).
+*/
+declare class StreamLanguage<State> extends Language {
+    private constructor();
+    /**
+    Define a stream language.
+    */
+    static define<State>(spec: StreamParser<State>): StreamLanguage<State>;
+    private getIndent;
+    get allowsNesting(): boolean;
+}
 
-export { IndentContext, LRLanguage, Language, LanguageDescription, LanguageSupport, ParseContext, TreeIndentContext, continuedIndent, defineLanguageFacet, delimitedIndent, ensureSyntaxTree, flatIndent, foldInside, foldNodeProp, foldService, foldable, getIndentUnit, getIndentation, indentNodeProp, indentOnInput, indentService, indentString, indentUnit, language, languageDataProp, syntaxParserRunning, syntaxTree, syntaxTreeAvailable };
+export { Config, HighlightStyle, IndentContext, LRLanguage, Language, LanguageDescription, LanguageSupport, MatchResult, ParseContext, StreamLanguage, StreamParser, StringStream, TagStyle, TreeIndentContext, bracketMatching, codeFolding, continuedIndent, defaultHighlightStyle, defineLanguageFacet, delimitedIndent, ensureSyntaxTree, flatIndent, foldAll, foldCode, foldEffect, foldGutter, foldInside, foldKeymap, foldNodeProp, foldService, foldable, foldedRanges, forceParsing, getIndentUnit, getIndentation, highlightingFor, indentNodeProp, indentOnInput, indentService, indentString, indentUnit, language, languageDataProp, matchBrackets, syntaxHighlighting, syntaxParserRunning, syntaxTree, syntaxTreeAvailable, unfoldAll, unfoldCode, unfoldEffect };