The nxd-vsx library is provided to allow users to parse and construct content that is formatted using NextraData's VSX language.

API

Parsing

These exported functions convert a content string into a tree of AST nodes.

function ParseVSX(text: string): AstNode;

ParseVSX parses a string containing content formatted in VSX language and returns it as a tree of AstNode objects.

function ParseExpression(text: string): AstNode;

ParseExpression parses a string containing content formatted in the expression subset of the VSX language (anything that is legal inside of double curly brackets, i.e. '{{<expression>}}') and returns it as a tree of AstNode objects.

interface ParseResult {
    ast?: t.AstNode;
    error?: Error;    // the first error if any.
}

function TryParseVSX(text: string): ParseResult;

TryParseVSX parses a string containing content formatted in VSX language and returns it as a tree of AstNode objects in the ast field of the ParseResult object. If an error is encountered during parsing, the error field of the ParseResult will be populated and the ast field will be returned if possible.

function TryParseExpression(text: string): ParseResult;

ParseExpression parses a string containing content formatted in the expression subset of the VSX language (anything that is legal inside of double curly brackets, i.e. '{{<expression>}}') and returns it as a tree of AstNode objects in the ast field of the ParseResult object. If an error is encountered during parsing, the error field of the ParseResult will be populated and the ast field will be returned if possible.

function FindVariableBindings(ast: AstNode): string[];

FindVariableBindings returns a list of the variables that must be supplied to resolve the expression.

function FindAllErrors(ast: AstNode): Error[];

FindAllErrors returns a list of the errors that are found by traversing the entire AST.

Generating VSX

All AST objects implement the AstNode interface which has the following methods.

interface AstNode {
    // returns false if the AST node is not populated
    isEmpty: () => boolean;
    // returns a VSX formatted string that represents the node's content
    toString: () => string;
    // returns an array of AST nodes that are children of this `AstNode`
    operands: () => AstNode[];
    // returns the name of the AST node
    nodeType: () => string;
    // returns any parsing errors related to this node
    errors: () => Error[] | undefined;
}

Types that implement AstNode

AstVsxBlock

new AstVsxBlock(n: AstNode[])

AstVsxBlock represents a block of VSX-formatted content.

AstError

new AstError(error: string)

AstError represents a parsing error. This would not be used normally when generating VSX content.

AstTextContent

new AstTextContent(content: string)

AstTextContent represents raw text that will be passed through to the renderer.

AstExpressionContent

new AstExpressionContent(expr: AstNode)

AstExpressionContent represents an expression that is embedded in VSX.

AstConditionalContent

new AstConditionalContent({conditionals: conditionalBlock[], defaultContent: AstNode})

conditionalBlock = {condition: AstNode, content: AstNode}

AstConditionalContent represents conditional statements embedded in VSX.

AstTaggedContent

new AstTaggedContent({tagName: string, contents: AstNode, properties: Map<string, AstNode>})

AstTaggedContent represents a tag along with its contents and properties in VSX.

AstString

new AstString(v: string)

AstString represents a string value.

AstNumber

new AstNumber(v: number)

AstNumber represents a number value.

AstBoolean

new AstBoolean(v: boolean)

AstBoolean represents a boolean value.

AstNull

new AstNull()

AstNull represents a null value.

AstOpNegate

new AstOpNegate(v: AstNode)

AstOpNegate represents the negation operator.

AstOpNegate

new AstOpNullCoalesce(l: AstNode, r: AstNode)

AstOpNullCoalesce represents the null coalescing operator.

AstOpAdd

new AstOpAdd(l: AstNode, r: AstNode)

AstOpAdd represents the addition operator.

AstOpSubtract

new AstOpSubtract(l: AstNode, r: AstNode)

AstOpSubtract represents the subtraction operator.

AstOpMultiply

new AstOpMultiply(l: AstNode, r: AstNode)

AstOpMultiply represents the multiplication operator.

AstOpExp

new AstOpExp(l: AstNode, r: AstNode)

AstOpExp represents the exponentiation operator.

AstOpDivide

new AstOpDivide(l: AstNode, r: AstNode)

AstOpDivide represents the division operator.

AstOpModulo

new AstOpModulo(l: AstNode, r: AstNode)

AstOpModulo represents the modulo operator.

AstOpConcat

new AstOpConcat(l: AstNode, r: AstNode)

AstOpConcat represents the string contatenation operator.

AstOpSpacedConcat

new AstOpSpacedConcat(l: AstNode, r: AstNode)

AstOpSpacedConcat represents the spaced contatenation operator.

AstOpAnd

new AstOpAnd(l: AstNode, r: AstNode)

AstOpAnd represents the boolean 'AND' operator.

AstOpOr

new AstOpOr(l: AstNode, r: AstNode)

AstOpOr represents the boolean 'OR' operator.

AstOpNot

new AstOpNot(v: AstNode)

AstOpNot represents the boolean 'NOT' operator.

AstOpEqual

new AstOpEqual(l: AstNode, r: AstNode)

AstOpEqual represents the equal comparison operator.

AstOpNotEqual

new AstOpNotEqual(l: AstNode, r: AstNode)

AstOpNotEqual represents the not equal comparison operator.

AstOpGreaterThan

new AstOpGreaterThan(l: AstNode, r: AstNode)

AstOpGreaterThan represents the greater than comparison operator.

AstOpGreaterThanOrEqual

new AstOpGreaterThanOrEqual(l: AstNode, r: AstNode)

AstOpGreaterThanOrEqual represents the greater than or equal comparison operator.

AstOpLessThan

new AstOpLessThan(l: AstNode, r: AstNode)

AstOpLessThan represents the less than comparison operator.

AstOpLessThanOrEqual

new AstOpLessThanOrEqual(l: AstNode, r: AstNode)

AstOpLessThanOrEqual represents the less than or equal comparison operator.

AstVariable

new AstVariable(identifier: string)

AstVariable represents a variable reference.

AstOpTernary

new AstOpTernary({condition: AstNode, content: AstNode, elseContent: AstNode})

AstOpTernary represents a ternary expression.

AstFunction

new AstFunction({ident: string, params: AstNode[]})

AstFunction represents a function call.