replaceLatexCommandCalls

How to read this API

These are TypeScript APIs compiled into SnapTeX; a .tex project cannot load them at runtime.

• function name(...) is a helper that your rule imports and calls.
• apply(...), render(...), extract(...), and collect(...) are callbacks that your rule implements and SnapTeX calls.
• renderer.name(...), context.name(...), input.name(...), and deps.name(...) are methods SnapTeX supplies to callbacks; do not import or construct them.
• service.name(...) is an instance method called after your host or test constructs PreviewUpdateService.

Register extension declarations through SNAP_TEX_RULES in src/rules.ts. See Source API Scope for imports, value ownership, output safety, rebuilds, and testing.

Finds and replaces valid calls to one or more named LaTeX commands while preserving unmatched source. Use it for command-wide replacement in legacy rules; use readLatexCommandAt when you already know the exact source position to inspect.

Signature

function replaceLatexCommandCalls(
    text: string,
    rules: LatexCommandReplacementRule | LatexCommandReplacementRule[]
): string

interface LatexCommandReplacementRule {
    name: string | readonly string[];
    requiredArgs?: number;
    optionalArgs?: number;
    allowStar?: boolean;
    render(call: LatexCommandCall): string;
}

Parameters

Value	Supplied by	Meaning
text	Calling rule	Source to scan
rules	Calling rule	Command names, argument counts, and replacement callbacks
call	replaceLatexCommandCalls	One validated command with balanced groups and source offsets

Access brace content with call.requiredArgs[index].content and bracket content with call.optionalArgs[index].content.

Returns

The transformed string. Commands with missing/unbalanced required arguments are preserved and do not invoke render.

Call relationships

• Searches for: configured command names.
• Calls: readLatexCommandAt for validation and argument reading.
• Usually called by: a legacy PreprocessRule.apply callback.

block text -> command search -> readLatexCommandAt -> render(call) -> replaced block text

Example

const output = replaceLatexCommandCalls(source, {
    name: 'badge',
    requiredArgs: 1,
    render: call => renderer.protectHtml(
        'badge',
        `<span>${escapeHtml(call.requiredArgs[0].content)}</span>`,
        'inline'
    )
});

Use one rule with name: ['aliasA', 'aliasB'] when aliases have identical syntax and rendering. Use separate rules when argument counts or behavior differ.

The nested render(call) function is a replacement callback owned by this helper. It is unrelated to the AstRenderRule callback.

See also

• readLatexCommandAt
• renderer.protectHtml