Reads a formula as formula help needs it: its tokens, the references to
colour, the function call and argument at cursor, the functions that
complete the name at cursor, and syntax and call errors.
text is the whole editor text, starting with =; any other text is not a
formula and gives an empty result. cursor and every from and to are
UTF-16 offsets into text. functions is the list from listFunctions,
which holds the active engine's built-in functions and the store's host
functions. With an empty list, completion is empty and no name is reported
as unknown.
The tokens and the syntax error come from the engine's own lexer and
parser, so call it after initSheetwrite. The analysis never calculates:
it reads text and metadata only.
interface StoreinterfaceStoreinterfaceStoreColumnar workbook storage, query, transaction, and subscription contract.API reference →function analyzeFormula(text: string, cursor: number, functions: readonly FormulaFunctionMetadata[]): FormulaAnalysisfunctionanalyzeFormula(text:string,cursor:number,functions:readonlyFormulaFunctionMetadata[],):FormulaAnalysisfunctionanalyzeFormula(text:string,cursor:number,functions:readonlyFormulaFunctionMetadata[],):FormulaAnalysisReads a formula as formula help needs it: its tokens, the references to colour, the function call and argument at cursor, the functions that complete the name at cursor, and syntax and call errors. text is the whole editor text, starting with =; any other text is not a formula and gives an empty result. cursor and every from and to are UTF-16 offsets into text. functions is the list from listFunctions, which holds the active engine's built-in functions and the store's host functions. With an empty list, completion is empty and no name is reported as unknown. The tokens and the syntax error come from the engine's own lexer and parser, so call it after initSheetwrite. The analysis never calculates: it reads text and metadata only.Exampleimporttype { Store } from"@sheetwrite/core";import { analyzeFormula, listFunctions } from"@sheetwrite/core/functions";asyncfunctioncurrentArgument(store:Store, text:string, cursor:number) {constanalysis=analyzeFormula(text, cursor, awaitlistFunctions(store));return analysis.call?.argument?.name ??null;}See also/docs/features/formulas/formula-help/API reference →function listFunctions(store: Store): Promise<readonly FormulaFunctionMetadata[]>functionlistFunctions(store:Store,):Promise<readonlyFormulaFunctionMetadata[]>functionlistFunctions(store:Store,):Promise<readonlyFormulaFunctionMetadata[]>Metadata of every function that formulas in store can call: the built-in functions of the active engine, then the host functions of store in registration order. Formula help reads this one list. The built-in table loads on the first call, so the result is a promise.API reference →function currentArgument(store: Store, text: string, cursor: number): Promise<string | null>functioncurrentArgument(store:Store,text:string,cursor:number,):Promise<string|null>functioncurrentArgument(store:Store,text:string,cursor:number,):Promise<string|null>API reference →text: stringlet text:stringlet text:stringFormula source when the cell is a formula, else the literal display text.API reference →const analysis: FormulaAnalysisconstanalysis:FormulaAnalysisconstanalysis:FormulaAnalysisAPI reference →cursor: numberlet cursor:numberlet cursor:numberstore: Storelet store:Storelet store:StoreAPI reference →FormulaAnalysis.call: FormulaCall | nullinterfaceFormulaAnalysis {call:FormulaCall|null;}interfaceFormulaAnalysis {call:FormulaCall|null;}FormulaCall.argument: FormulaArgumentMetadata | undefinedinterfaceFormulaCall {argument:FormulaArgumentMetadata|undefined;}interfaceFormulaCall {argument:|FormulaArgumentMetadata|undefined;}FormulaArgumentMetadata.name: string | undefinedinterfaceFormulaArgumentMetadata {name:string|undefined;}interfaceFormulaArgumentMetadata {name:string|undefined;}User-facing caption.API reference →interface FormulaFunctionMetadata {
readonly name: string;
readonly description: string;
readonly arguments: readonly FormulaArgumentMetadata[];
readonly returnKind: string;
readonly examples?: readonly string[];
readonly volatile?: boolean;
}interfaceFormulaFunctionMetadata {readonlyname:string;readonlydescription:string;readonlyarguments:readonlyFormulaArgumentMetadata[];readonlyreturnKind:string;readonlyexamples?:readonlystring[];readonlyvolatile?:boolean;}interfaceFormulaFunctionMetadata {readonlyname:string;readonlydescription:string;readonlyarguments:readonlyFormulaArgumentMetadata[];readonlyreturnKind:string;readonlyexamples?:readonlystring[];readonlyvolatile?:boolean;}One metadata format for built-in and host functions.API reference →interface FormulaAnalysis {
readonly tokens: readonly FormulaToken[];
readonly references: readonly FormulaReference[];
readonly call: FormulaCall | null;
readonly completion: FormulaCompletion | null;
readonly diagnostics: readonly FormulaDiagnostic[];
}interfaceFormulaAnalysis {readonlytokens:readonlyFormulaToken[];readonlyreferences:readonlyFormulaReference[];readonlycall:FormulaCall|null;readonlycompletion:FormulaCompletion|null;readonlydiagnostics:readonlyFormulaDiagnostic[];}interfaceFormulaAnalysis {readonlytokens:readonlyFormulaToken[];readonlyreferences:readonlyFormulaReference[];readonlycall:FormulaCall|null;readonlycompletion:FormulaCompletion|null;readonlydiagnostics:readonlyFormulaDiagnostic[];}Everything formula help shows for one formula text and cursor offset.API reference →