--- url: https://adecore.dev/editor-core/commands.md --- # Typing and commands Three methods turn what a person does into edits on every caret at once. Each returns whether anything changed, and each reads the `language` option to tell code from comments and strings. Without a language, `typeText` and `paste` assume `typescript`. ## typeText `typeText(text, options?)` is one keystroke. With a single character it does what a code editor does on that key: * An opening bracket brings its closer when nothing after the caret already closes it. A quote pairs only when no identifier character follows. * Typing a closer the editor added steps over it. That counts as a change, so `typeText` returns `true` with the text unchanged. * A bracket, quote or `<` typed over a selection wraps it. A quote typed over one quote of a string swaps both. * A closing bracket typed alone on its line moves back to the indentation of its opener. * In TypeScript, JavaScript and PHP a `;` typed just before the `)` and `]` that close a call goes past them, to the end of the statement. * In PHP a `-` typed right after a variable, a property or method name after `->`, or a `)` or `]` becomes `->`, with the `>` as an undo step of its own. A `>` typed next goes over it, and so does Backspace, which takes both. A key that cannot follow `->` (anything but a letter, `_` or `{`) makes it a minus again, typed with that key. ```ts const document = new DocumentModel('call(x)'); document.setSelections([{ anchor: 6, head: 6 }]); document.typeText(';', { language: 'typescript' }); document.getText(); // 'call(x);' ``` Nothing pairs in plain text (`text`, `plaintext`, `txt` or `log`), inside a comment, or inside a string. Longer text is inserted as it is. Consecutive calls join one undo step, the `typing` group. ## paste `paste(text, options?)` writes the text with the document's own line breaks. With as many lines as carets, each caret takes one line. With `wholeLines: true`, for text copied from a bare caret, the text goes above the line of each bare caret. A block that lands in code moves to the indentation of the line it lands on, unless `indentOnPaste` is `false`. ## execute `execute(command, options?)` runs an `EditorCommand` on every caret. | Group | Commands | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | History and selection | `undo`, `redo`, `selectAll`, `expandSelection`, `shrinkSelection` | | Words | `wordLeft`, `wordRight`, `selectWordLeft`, `selectWordRight`, `deleteWordLeft`, `deleteWordRight` and the same six with `camel` | | Line edges | `smartHome`, `smartEnd`, `selectSmartHome`, `selectSmartEnd` | | Deleting | `smartBackspace`, `deleteForward` | | Lines | `duplicateLine`, `deleteLine`, `moveLineUp`, `moveLineDown`, `joinLines`, `toggleCase`, `autoIndentLines` | | Indentation | `insertTab`, `indent`, `outdent` | | Comments | `toggleLineComment`, `toggleBlockComment` | | New lines | `insertNewline`, `startNewLine`, `startNewLineBefore`, `splitLine` | | Carets | `addCaretAbove`, `addCaretBelow`, `addCaretPerSelectedLine`, `selectNextOccurrence`, `unselectOccurrence`, `selectAllOccurrences` | A few of them do more than their name says: * `insertNewline` continues a line comment when text follows the caret, closes and continues a `/**` block, splits a string with the language's concatenation, indents after an opener or a `case` label, and closes a brace nothing closes. * `smartHome` goes to the first non-blank character, and from there to the start of the line. * `smartBackspace` with only whitespace before the caret, in a language whose brackets set the indentation, works from where the brackets put the line. A line indented past that goes back to it in one step. A line at or before it joins the line above, with the spacing of `joinLines` and no space when the line is empty, so an empty line under `{` goes to the end of the `{`; a blank line above is taken instead. Elsewhere, in comments and strings, it goes back a tab stop, and at the start of a line it also takes the whitespace that trails the line above. * `insertTab` steps over a closer the editor added before it inserts anything. * `selectNextOccurrence` from a bare caret selects the word, then the next whole word with the same case. From a selection it finds the text anywhere, also inside other words. When there is no further match, `occurrencesExhausted` on the model is `true` until the next press starts over. * `expandSelection` grows through the word, the inside of a string or bracket pair, the pair itself, the line and the document, and `shrinkSelection` walks back. A host with better ranges, such as those of a language server, passes them to `expandSelectionTo(ranges)`, one `OffsetRange` or `null` per selection. The plain word commands stop at camel humps only with `camelCase: true`; the `camel` variants always do. `wordSelectionAt`, `wordStartBefore` and `wordEndAfter` give the same word stops for a double click and a drag. ## Options `CommandOptions` reaches all three methods. Every switch is on unless it says otherwise. | Option | Default | Meaning | | -------------------------------------------- | -------------- | --------------------------------------------------------------------- | | `language` | `'typescript'` | The language id, for comments, strings, brackets and indentation | | `tabSize` | `4` | Clamped to 1 through 16 | | `insertSpaces` | `true` | Indent with spaces | | `commentToken` | | Replaces the line comment marker of the language | | `camelCase` | `false` | Plain word commands stop at camel humps | | `autoClosingPairs` | on | Brackets and quotes together; the next two turn off one kind | | `autoClosingBrackets`, `autoClosingQuotes` | on | | | `surroundSelection` | on | A bracket or quote typed over a selection wraps it | | `smartSemicolon` | on | Only in TypeScript, JavaScript and PHP | | `smartArrow` | on | In PHP a `-` after a variable, a member, `)` or `]` becomes `->` | | `tabOutOfClosers` | on | Tab steps over a closer the editor added | | `smartEnter` | on | Enter computes indentation, continues comments and closes braces | | `indentOnPaste` | on | A pasted block takes the indentation of its line | | `visualLine(offset)` | | The wrapped row an offset is on, so Home and End go by rows | | `lineSpan(line)` | | The lines that stand on one row, such as a collapsed fold | | `onLinesMoved(moves)` | | Where each line went after a move, as `{ from, to }` pairs | `typeText` also takes `historyGroup` and `expectedRevision`, and `paste` takes `wholeLines`. A view with folds passes `lineSpan`: a collapsed fold is then one line to delete, duplicate, comment and move, one word stop, and a row that `addCaretAbove` and `addCaretBelow` skip. `onLinesMoved` lets the view move whatever it keeps by line, such as a fold, along with the text. ## Comments `toggleLineComment` and `toggleBlockComment` read a table of markers per language: `//` and `/* */` for the C family, PHP, JSON and the like, `#` for Python, shell, YAML and others, `` for HTML, XML and Markdown, `--` for SQL, Lua and Haskell. In a Vue file the marker follows the block the caret is in. A language with block comments only, such as CSS, wraps each line. An id the table does not know has no markers, and the toggle does nothing.