Search and folding

Find

find(query, options?) returns every FindMatch in the document: from, to, text, the regular expression's captures and named groups, and the revision it was found in. findNext(query, from?, options?) returns the first match at or after from, the primary caret by default, and wraps around unless wrap is false; backwards: true searches the other way.

FindOptions	Default	Meaning
caseSensitive	false
wholeWord	false	A match may not touch a letter, digit, _ or $ on either side
regex	false	The query is a JavaScript regular expression, run with the m and u flags
from, to	whole	Keep only matches inside these offsets; the expression still sees the rest
maxResults	none	Stop after this many

An empty plain query finds nothing. Bounds outside the document throw a RangeError and an invalid expression a SyntaxError. A regular expression has no time limit.

Replace

replace(match, replacement, options?) replaces one match and returns false, with nothing changed, when the match comes from another revision or its text no longer stands there. replaceAll(query, replacement, options?) replaces every match in one undo step and returns how many it replaced, or 0 when nothing changed.

const document = new DocumentModel('Item one, item two, ITEM three');

document.replaceAll('item', 'entry', { preserveCase: true });
document.getText(); // 'Entry one, entry two, ENTRY three'

With a regular expression the replacement expands $1, $<name>, $& and the other JavaScript patterns; literal: true turns that off. preserveCase: true gives the replacement the case of the text it replaces. findMatches and replacementText are the same search and expansion without a model.

Folding ranges

getFoldingRanges(options?) reads the folds of the document. Without options it returns bracket pairs and block comments that span more than one line. Pass a language for the rest:

kind	What folds	Needs
bracket	A {}, [] or () pair over several lines
comment	A block comment
indentation	Lines indented deeper than the one above them	indentation: true
imports	A run of import lines	a language
line-comments	A run of line comments	a language
region	What stands between // region and // endregion markers	a language
block	A Markdown front matter, code fence or table, a PHP heredoc or <?php ?> block	a language
section	What a Markdown heading holds	a language
server	A range a language server named that the text has no fold for	hints

brackets, comments, imports, regions and lineComments turn one kind off with false. minLines, 1 by default, is how many lines past its first a range spans before it folds. Lines are zero-based and inclusive; from and to are the offsets of the folded stretch.

Roles

A range may carry a role, which a view uses to fold a kind of range when a file opens. The text gives file-header (the first comment of a file), imports, doc-comment, region, object-literal and array-literal (in TypeScript and JavaScript), attribute (a PHP #[ list), php-tag, heredoc, front-matter, code-fence and table. The text cannot tell a function body from any other brace pair, so function-body, method-body, class-body and tag come from hints, which a host fills from a language server's symbols and folding ranges:

const text = 'function total(items) {\n    return items.length;\n}\n';
const document = new DocumentModel(text);

document.getFoldingRanges({
    language: 'typescript',
    hints: { symbols: [{ from: 0, to: 50, body: 'function' }] }
});
// [{ startLine: 0, endLine: 2, kind: 'bracket', role: 'function-body', from: 22, to: 50 }]

A symbol hint names the bracket pair or indented block that ends where the symbol ends. A range hint the text has no fold for becomes a server range. A role describes what the scanner found; it is not a parsed syntax tree.