@unified-latex/unified-latex-util-replace
v1.8.0
Published
Functions for modifying a unified-latex AST
Downloads
16,131
Maintainers
Readme
unified-latex-util-replace
What is this?
Functions to help modify a unified-latex
Abstract Syntax Tree (AST).
When should I use this?
If you want to recursively replace particular AST nodes.
Install
npm install @unified-latex/unified-latex-util-replace
This package contains both esm and commonjs exports. To explicitly access the esm export,
import the .js
file. To explicitly access the commonjs export, import the .cjs
file.
Plugins
unifiedLatexReplaceStreamingCommands
Unified plugin to replace all found streaming commands with their argument-style equivalents. This only applies to sections of the tree with no math ancestor.
Usage
unified().use(unifiedLatexReplaceStreamingCommands[, options])
options
PluginOptions
Type
Plugin<PluginOptions[], Ast.Root, Ast.Root>
function unifiedLatexReplaceStreamingCommands(
options: PluginOptions
): (tree: Ast.Root) => void;
where
type PluginOptions = {
replacers: Record<
string,
(content: Ast.Node[], streamingCommand: Ast.Macro) => Ast.Node | Ast.Node[]
>;
};
Functions
firstSignificantNode(nodes, parbreaksAreInsignificant)
Returns the first non-whitespace/non-comment node in nodes
. If there is no such
node, null
is returned.
function firstSignificantNode(
nodes: Ast.Node[],
parbreaksAreInsignificant: Boolean
): Ast.Node;
Parameters
| Param | Type |
| :------------------------ | :----------- |
| nodes | Ast.Node[]
|
| parbreaksAreInsignificant | Boolean
|
firstSignificantNodeIndex(nodes, parbreaksAreInsignificant)
Returns the index of the first non-whitespace/non-comment node in nodes
. If there is no such
node, null
is returned.
function firstSignificantNodeIndex(
nodes: Ast.Node[],
parbreaksAreInsignificant: Boolean
): number;
Parameters
| Param | Type |
| :------------------------ | :----------- |
| nodes | Ast.Node[]
|
| parbreaksAreInsignificant | Boolean
|
lastSignificantNode(nodes, parbreaksAreInsignificant)
Returns the last non-whitespace/non-comment node in nodes
. If there is no such
node, null
is returned.
function lastSignificantNode(
nodes: Ast.Node[],
parbreaksAreInsignificant: Boolean
): Ast.Node;
Parameters
| Param | Type |
| :------------------------ | :----------- |
| nodes | Ast.Node[]
|
| parbreaksAreInsignificant | Boolean
|
lastSignificantNodeIndex(nodes, parbreaksAreInsignificant)
Returns the index of the last non-whitespace/non-comment node in nodes
. If there is no such
node, null
is returned.
function lastSignificantNodeIndex(
nodes: Ast.Node[],
parbreaksAreInsignificant: Boolean
): number;
Parameters
| Param | Type |
| :------------------------ | :----------- |
| nodes | Ast.Node[]
|
| parbreaksAreInsignificant | Boolean
|
replaceNode(ast, visitor)
Recursively replace nodes in ast
. The visitor
function is called on each node. If
visitor
returns a node or an array of nodes, those nodes replace the node passed to visitor
.
If null
is returned, the node is deleted. If undefined
is returned, no replacement happens.
function replaceNode(
ast: Ast.Ast,
visitor: (
node: Ast.Node | Ast.Argument,
info: VisitInfo
) =>
| Ast.Node
| Ast.Argument
| (Ast.Node | Ast.Argument)[]
| null
| undefined
| void
): void;
Parameters
| Param | Type |
| :------ | :-------------------------------- |
| ast | Ast.Ast
|
| visitor | Omitted |
replaceNodeDuringVisit(replacement, info)
Replaces the current node with replacement
. It is assumed that the current
node is in an array that is a child of a parent element. If this is not the case,
the function will error.
function replaceNodeDuringVisit(
replacement: Ast.Node | Ast.Argument | (Ast.Node | Ast.Argument)[],
info: VisitInfo
): void;
Parameters
| Param | Type |
| :---------- | :-------------------------------- |
| replacement | Omitted |
| info | VisitInfo
|
where
type VisitInfo = {
/**
* If the element was accessed via an attribute, the attribute key is specified.
*/
readonly key: string | undefined;
/**
* If the element was accessed in an array, the index is specified.
*/
readonly index: number | undefined;
/**
* A list of ancestor nodes, `[parent, grandparent, great-grandparent, ...]`
*/
readonly parents: (Ast.Node | Ast.Argument)[];
/**
* If the element was accessed in an array, the array that it is part of.
*/
readonly containingArray: (Ast.Node | Ast.Argument)[] | undefined;
/**
* The LaTeX context of the current match.
*/
readonly context: VisitorContext;
};
replaceStreamingCommand(ast, isStreamingCommand, replacer, options)
Given a group or a node array, look for streaming commands (e.g., \bfseries
) and replace them
with the specified macro. The "arguments" of the streaming command are passed to replacer
and the return
value of replacer
is inserted into the stream.
By default, this command will split at parbreaks (since commands like \textbf{...} do not accept parbreaks in their
contents) and call
replacer` multiple times, once per paragraph.
Commands are also split at environments and at any macros listed in macrosThatBreakPars
.
function replaceStreamingCommand(
ast: Ast.Group | Ast.Node[],
isStreamingCommand: (node: any) => node is Ast.Macro,
replacer: (
content: Ast.Node[],
streamingCommand: Ast.Macro
) => Ast.Node | Ast.Node[],
options: {
macrosThatBreakPars?: string[];
environmentsThatDontBreakPars?: string[];
}
): Ast.Node[];
Parameters
| Param | Type |
| :----------------- | :-------------------------------- |
| ast | Ast.Group \| Ast.Node[]
|
| isStreamingCommand | Omitted |
| replacer | Omitted |
| options | Omitted |
replaceStreamingCommandInGroup(group, isStreamingCommand, replacer, options)
Process streaming commands in a group. If needed, "escape" the group.
For example, {\bfseries xx}
-> \textbf{xx}
, but {foo \bfseries xx}
-> {foo \textbf{xx}}
.
function replaceStreamingCommandInGroup(
group: Ast.Group,
isStreamingCommand: (node: any) => node is Ast.Macro,
replacer: (
content: Ast.Node[],
streamingCommand: Ast.Macro
) => Ast.Node | Ast.Node[],
options: {
macrosThatBreakPars?: string[];
environmentsThatDontBreakPars?: string[];
}
): Ast.Node[];
Parameters
| Param | Type |
| :----------------- | :-------------------------------- |
| group | Ast.Group
|
| isStreamingCommand | Omitted |
| replacer | Omitted |
| options | Omitted |