@mrhenry/twig-parser 0.1.0

package/src/expression-parser.js

@@ -0,0 +1,1103 @@
+// @ts-check
+/**
+ * The expression parser: implements a precedence-climbing algorithm.
+ *
+ * Mirrors `Twig\Parser::parseExpression()` plus the prefix/infix expression
+ * parsers from `src/ExpressionParser/*` of the reference implementation.
+ * See `spec/03-expressions.md`.
+ *
+ * @module twig-parser
+ */
+import { TokenType } from '@mrhenry/twig-tokenizer';
+import { SyntaxError } from '@mrhenry/twig-tokenizer';
+// eslint-disable-next-line no-unused-vars -- used in JSDoc type annotations
+import { Node, NodeType, n } from './node.js';
+import { ArrayExpression } from './array-expression.js';
+
+/**
+ * @typedef {import('@mrhenry/twig-tokenizer').Token} Token
+ */
+
+/** Name pattern used to accept word-operators as variable names. */
+const REGULAR_EXPRESSION_NAME = /^[a-zA-Z_\u007f-\uffff][a-zA-Z0-9_\u007f-\uffff]*$/;
+
+/**
+ * Binary operator metadata: precedence and associativity.
+ *
+ * @type {Record<string, {precedence: number, right: boolean}>}
+ */
+export const BINARY_INFORMATION = {
+	'?:': { precedence: 5, right: true },
+	'? :': { precedence: 5, right: true },
+	'??': { precedence: 300, right: true },
+	or: { precedence: 10, right: false },
+	xor: { precedence: 12, right: false },
+	and: { precedence: 15, right: false },
+	'b-or': { precedence: 16, right: false },
+	'b-xor': { precedence: 17, right: false },
+	'b-and': { precedence: 18, right: false },
+	'==': { precedence: 20, right: false },
+	'!=': { precedence: 20, right: false },
+	'<=>': { precedence: 20, right: false },
+	'<': { precedence: 20, right: false },
+	'>': { precedence: 20, right: false },
+	'>=': { precedence: 20, right: false },
+	'<=': { precedence: 20, right: false },
+	'not in': { precedence: 20, right: false },
+	in: { precedence: 20, right: false },
+	matches: { precedence: 20, right: false },
+	'starts with': { precedence: 20, right: false },
+	'ends with': { precedence: 20, right: false },
+	'has some': { precedence: 20, right: false },
+	'has every': { precedence: 20, right: false },
+	'===': { precedence: 20, right: false },
+	'!==': { precedence: 20, right: false },
+	'..': { precedence: 25, right: false },
+	'+': { precedence: 30, right: false },
+	'-': { precedence: 30, right: false },
+	'~': { precedence: 40, right: false },
+	'*': { precedence: 60, right: false },
+	'/': { precedence: 60, right: false },
+	'//': { precedence: 60, right: false },
+	'%': { precedence: 60, right: false },
+	'**': { precedence: 200, right: true },
+	'=': { precedence: 0, right: true },
+	is: { precedence: 100, right: false },
+	'is not': { precedence: 100, right: false },
+	'|': { precedence: 512, right: false },
+	'.': { precedence: 512, right: false },
+	'?.': { precedence: 512, right: false },
+	'[': { precedence: 512, right: false },
+	'(': { precedence: 512, right: false },
+	'?': { precedence: 0, right: false },
+	'=>': { precedence: 250, right: false },
+};
+
+/**
+ * Prefix (unary) operators: operator name → operand precedence bound.
+ *
+ * Mirrors the prefix parsers registered by `CoreExtension` (`not`, spread `...`)
+ * and `UnaryOperatorExpressionParser` (`-`, `+`).
+ *
+ * @type {Record<string, number>}
+ */
+export const PREFIX_OPERATORS = {
+	'...': 0,
+	not: 50,
+	'-': 500,
+	'+': 500,
+};
+
+/**
+ * Operators that may follow an expression (postfix), beyond the binary set in
+ * {@link BINARY_INFORMATION}: function call `(`, subscript `[`, and the
+ * attribute operators `.` / `?.` and filter `|`.
+ *
+ * @type {string[]}
+ */
+export const POSTFIX_OPERATORS = ['(', '[', '.', '?.', '|'];
+
+/**
+ * Functions with required (non-defaulted) arguments that the *parser* enforces.
+ *
+ * Mirrors the reference implementation: only the parser callables (`block`,
+ * `attribute`) are validated at parse time; ordinary functions such as
+ * `min`, `max`, `range` and `cycle` defer argument checking to runtime.
+ *
+ * @type {Record<string, string[]>}
+ */
+const REQUIRED_FUNCTION_ARGS = {
+	block: ['name'],
+	attribute: ['variable', 'attribute'],
+};
+
+/**
+ * The expression parser.
+ *
+ * Relies on a host {@link Parser} for the token stream, callable resolution
+ * and imported-symbol tracking.
+ */
+export class ExpressionParser {
+	/**
+	 * @param {import('./parser.js').Parser} parser The host parser.
+	 */
+	constructor(parser) {
+		/** @type {import('./parser.js').Parser} */
+		this.parser = parser;
+	}
+
+	/**
+	 * @returns {import('@mrhenry/twig-tokenizer').TokenStream} The token stream.
+	 */
+	getStream() {
+		return this.parser.getStream();
+	}
+
+	/**
+	 * @returns {Token} The current token.
+	 */
+	current() {
+		return this.parser.getCurrentToken();
+	}
+
+	/**
+	 * Parses an expression at the given precedence bound.
+	 *
+	 * @param {number} [precedence] The minimum precedence of infix operators to consume.
+	 * @returns {Node} The parsed expression node.
+	 */
+	parseExpression(precedence = 0) {
+		const stream = this.getStream();
+		const token = this.current();
+		let expression;
+
+		if (token.test(TokenType.OPERATOR)) {
+			switch (token.value) {
+				case '(':
+					stream.next();
+					expression = this.parseGrouping();
+					break;
+				case 'not':
+				case '-':
+				case '+':
+				case '...':
+					stream.next();
+					expression = this.parseUnary(token.value, token);
+					break;
+				default:
+					expression = this.parsePrimary();
+					break;
+			}
+		} else {
+			expression = this.parsePrimary();
+		}
+
+		// infix loop
+		for (;;) {
+			const t = this.current();
+			if (!t.test(TokenType.OPERATOR)) {
+				break;
+			}
+			const operator = String(t.value);
+			const operatorInfo = BINARY_INFORMATION[operator];
+			if (!operatorInfo || operatorInfo.precedence < precedence) {
+				break;
+			}
+			stream.next();
+			switch (operator) {
+				case '?':
+					expression = this.parseConditional(expression);
+					break;
+				case '=':
+					expression = this.parseAssignment(expression);
+					break;
+				case 'is':
+					expression = this.parseTest(expression, false);
+					break;
+				case 'is not':
+					expression = this.parseTest(expression, true);
+					break;
+				case '|':
+					expression = this.parseFilter(expression);
+					break;
+				case '(':
+					expression = this.parseFunction(expression);
+					break;
+				case '.':
+				case '?.':
+					expression = this.parseDot(expression, operator);
+					break;
+				case '[':
+					expression = this.parseSquareBracket(expression);
+					break;
+				case '=>':
+					expression = this.parseArrow(expression);
+					break;
+				default:
+					expression = this.parseBinary(operator, expression, operatorInfo);
+					break;
+			}
+		}
+
+		return expression;
+	}
+
+	/**
+	 * Parses a prefix unary expression.
+	 *
+	 * @param {string} operator The operator (`not`, `-`, `+` or `...`).
+	 * @param {Token} token The operator token.
+	 * @returns {Node} A `unary` node.
+	 */
+	parseUnary(operator, token) {
+		let operandPrecedence;
+		switch (operator) {
+			case '...':
+				operandPrecedence = 0;
+				break;
+			case 'not':
+				operandPrecedence = 50;
+				break;
+			default:
+				operandPrecedence = 500;
+				break;
+		}
+		const operand = this.parseExpression(operandPrecedence);
+		return n(NodeType.Unary, { node: operand }, { operator: operator }, token.getLine());
+	}
+
+	/**
+	 * Parses a literal primary expression (name, number, string, sequence, mapping).
+	 *
+	 * @returns {Node} The literal expression node.
+	 */
+	parsePrimary() {
+		const stream = this.getStream();
+		const token = this.current();
+
+		if (token.test(TokenType.NAME)) {
+			stream.next();
+			switch (token.value) {
+				case 'true':
+				case 'TRUE':
+					return n(NodeType.Constant, {}, { value: true }, token.getLine());
+				case 'false':
+				case 'FALSE':
+					return n(NodeType.Constant, {}, { value: false }, token.getLine());
+				case 'none':
+				case 'NONE':
+				case 'null':
+				case 'NULL':
+					return n(NodeType.Constant, {}, { value: null }, token.getLine());
+				default:
+					return n(NodeType.ContextVariable, {}, { name: token.value }, token.getLine());
+			}
+		}
+
+		if (token.test(TokenType.NUMBER)) {
+			stream.next();
+			return n(NodeType.Constant, {}, { value: token.value }, token.getLine());
+		}
+
+		if (token.test(TokenType.STRING) || token.test(TokenType.INTERPOLATION_START)) {
+			return this.parseStringExpression();
+		}
+
+		if (token.test(TokenType.PUNCTUATION)) {
+			if (token.value === '{') {
+				return this.parseMappingExpression();
+			}
+		}
+
+		if (token.test(TokenType.OPERATOR)) {
+			if (token.value === '[') {
+				return this.parseSequenceExpression();
+			}
+			if (REGULAR_EXPRESSION_NAME.test(String(token.value))) {
+				// in this context, string operators are variable names
+				stream.next();
+				return n(NodeType.ContextVariable, {}, { name: token.value }, token.getLine());
+			}
+		}
+
+		throw new SyntaxError(
+			`Unexpected token "${token.toEnglish()}" of value "${token.value}".`,
+			token.getLine(),
+			this.getStream().getSourceContext(),
+		);
+	}
+
+	/**
+	 * Parses a string expression with adjacent fragments and interpolations.
+	 *
+	 * @returns {Node} A concatenation of string constants and interpolations.
+	 */
+	parseStringExpression() {
+		const stream = this.getStream();
+		/** @type {Node[]} */
+		const nodes = [];
+		let nextCanBeString = true;
+		for (;;) {
+			const stringToken = nextCanBeString ? stream.nextIf(TokenType.STRING) : null;
+			if (stringToken) {
+				nodes.push(n(NodeType.Constant, {}, { value: stringToken.value }, stringToken.getLine()));
+				nextCanBeString = false;
+			} else if (stream.nextIf(TokenType.INTERPOLATION_START)) {
+				nodes.push(this.parseExpression());
+				stream.expect(TokenType.INTERPOLATION_END);
+				nextCanBeString = true;
+			} else {
+				break;
+			}
+		}
+
+		let expression = nodes.shift() ?? n(NodeType.Constant, {}, { value: '' }, this.current().getLine());
+		for (const node of nodes) {
+			expression = n(NodeType.Binary, { left: expression, right: node }, { operator: '~' }, node.getTemplateLine());
+		}
+		return expression;
+	}
+
+	/**
+	 * Parses a sequence literal `[a, b, c]`.
+	 *
+	 * @returns {Node} An `array` node.
+	 */
+	parseSequenceExpression() {
+		const stream = this.getStream();
+		stream.expect(TokenType.OPERATOR, '[', 'A sequence element was expected');
+
+		const node = this.makeArray(stream.getCurrent().getLine());
+		let first = true;
+		while (!stream.test(TokenType.PUNCTUATION, ']')) {
+			if (!first) {
+				stream.expect(TokenType.PUNCTUATION, ',', 'A sequence element must be followed by a comma');
+				// trailing comma?
+				if (stream.test(TokenType.PUNCTUATION, ']')) {
+					break;
+				}
+			}
+			first = false;
+
+			// empty slot?
+			if (stream.test(TokenType.PUNCTUATION, ',')) {
+				node.addElement(n(NodeType.Empty, {}, {}, stream.getCurrent().getLine()));
+			} else {
+				node.addElement(this.parseExpression());
+			}
+		}
+		stream.expect(TokenType.PUNCTUATION, ']', 'An opened sequence is not properly closed');
+		return node;
+	}
+
+	/**
+	 * Parses a mapping literal `{key: value}`.
+	 *
+	 * @returns {Node} An `array` node.
+	 */
+	parseMappingExpression() {
+		const stream = this.getStream();
+		stream.expect(TokenType.PUNCTUATION, '{', 'A mapping element was expected');
+
+		const node = this.makeArray(stream.getCurrent().getLine());
+		let first = true;
+		while (!stream.test(TokenType.PUNCTUATION, '}')) {
+			if (!first) {
+				stream.expect(TokenType.PUNCTUATION, ',', 'A mapping value must be followed by a comma');
+				// trailing comma?
+				if (stream.test(TokenType.PUNCTUATION, '}')) {
+					break;
+				}
+			}
+			first = false;
+
+			if (stream.test(TokenType.OPERATOR, '...')) {
+				node.addElement(this.parseExpression());
+				continue;
+			}
+
+			/** @type {Node} */
+			let key;
+			/** @type {import('@mrhenry/twig-tokenizer').Token|null} */
+			let keyToken;
+			if ((keyToken = stream.nextIf(TokenType.NAME))) {
+				key = n(NodeType.Constant, {}, { value: keyToken.value }, keyToken.getLine());
+				// {a} is a shortcut for {a: a}
+				if (stream.test(TokenType.PUNCTUATION, [',', '}'])) {
+					const value = n(
+						NodeType.ContextVariable,
+						{},
+						{ name: key.getAttribute('value') },
+						key.getTemplateLine(),
+					);
+					node.addElement(value, key);
+					continue;
+				}
+			} else if ((keyToken = stream.nextIf(TokenType.STRING)) || (keyToken = stream.nextIf(TokenType.NUMBER))) {
+				key = n(NodeType.Constant, {}, { value: keyToken.value }, keyToken.getLine());
+			} else if (stream.test(TokenType.OPERATOR, '(')) {
+				key = this.parseExpression();
+			} else {
+				const current = stream.getCurrent();
+				throw new SyntaxError(
+					`A mapping key must be a quoted string, a number, a name, or an expression enclosed in parentheses (unexpected token "${current.toEnglish()}" of value "${current.value}".`,
+					current.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+
+			stream.expect(TokenType.PUNCTUATION, ':', 'A mapping key must be followed by a colon (:)');
+			const value = this.parseExpression();
+			node.addElement(value, key);
+		}
+		stream.expect(TokenType.PUNCTUATION, '}', 'An opened mapping is not properly closed');
+		return node;
+	}
+
+	/**
+	 * Parses a parenthesized grouping or an arrow-function parameter list.
+	 *
+	 * @returns {Node} A grouped expression or a `list` node.
+	 */
+	parseGrouping() {
+		const stream = this.getStream();
+		const token = this.current();
+		const expression = this.parseExpression(0);
+
+		if (stream.nextIf(TokenType.PUNCTUATION, ')')) {
+			if (!stream.test(TokenType.OPERATOR, '=>')) {
+				return expression.setExplicitParentheses();
+			}
+			// (x) => ...
+			return n(
+				NodeType.ListExpr,
+				{},
+				{ names: [this.toAssignContextVariable(expression)] },
+				token.getLine(),
+			);
+		}
+
+		// arrow function arguments: (value, key) => ...
+		if (!stream.test(TokenType.PUNCTUATION, ',')) {
+			stream.expect(TokenType.PUNCTUATION, ')', 'An opened parenthesis is not properly closed');
+		}
+
+		/** @type {Node[]} */
+		const names = [expression];
+		for (;;) {
+			if (stream.nextIf(TokenType.PUNCTUATION, ')')) {
+				break;
+			}
+			stream.expect(TokenType.PUNCTUATION, ',');
+			const nameToken = stream.expect(TokenType.NAME);
+			names.push(n(NodeType.ContextVariable, {}, { name: nameToken.value }, nameToken.getLine()));
+		}
+
+		if (!stream.test(TokenType.OPERATOR, '=>')) {
+			throw new SyntaxError(
+				'A list of variables must be followed by an arrow.',
+				stream.getCurrent().getLine(),
+				stream.getSourceContext(),
+			);
+		}
+
+		return n(
+			NodeType.ListExpr,
+			{},
+			{ names: names.map((name) => this.toAssignContextVariable(name)) },
+			token.getLine(),
+		);
+	}
+
+	/**
+	 * Converts an expression to an assignable context variable.
+	 *
+	 * @param {Node} expression
+	 * @returns {Node} An `assign_context_variable` node.
+	 */
+	toAssignContextVariable(expression) {
+		if (expression.type !== NodeType.ContextVariable) {
+			throw new SyntaxError(
+				'A list must only contain variables.',
+				expression.getTemplateLine(),
+				expression.getSourceContext(),
+			);
+		}
+		if (expression.type === NodeType.AssignContextVariable) {
+			return expression;
+		}
+		return n(
+			NodeType.AssignContextVariable,
+			{},
+			{ name: expression.getAttribute('name') },
+			expression.getTemplateLine(),
+		);
+	}
+
+	/**
+	 * Parses `.` / `?.` attribute access (and macro references).
+	 *
+	 * @param {Node} expression The base expression.
+	 * @param {string} operator The operator (`.` or `?.`).
+	 * @returns {Node} A `get_attr`, `macro_reference` or `filter` node.
+	 */
+	parseDot(expression, operator) {
+		const nullSafe = operator === '?.';
+		const stream = this.getStream();
+		const token = stream.getCurrent();
+		const lineNumber = token.getLine();
+
+		/** @type {Node} */
+		let attribute;
+		if (stream.nextIf(TokenType.OPERATOR, '(')) {
+			attribute = this.parseExpression();
+			stream.expect(TokenType.PUNCTUATION, ')');
+		} else {
+			const attributeToken = stream.next();
+			if (
+				attributeToken.test(TokenType.NAME) ||
+				attributeToken.test(TokenType.NUMBER) ||
+				(attributeToken.test(TokenType.OPERATOR) && REGULAR_EXPRESSION_NAME.test(String(attributeToken.value)))
+			) {
+				attribute = n(NodeType.Constant, {}, { value: attributeToken.value }, attributeToken.getLine());
+			} else {
+				throw new SyntaxError(
+					`Expected name or number, got value "${attributeToken.value}" of type "${attributeToken.toEnglish()}".`,
+					attributeToken.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+		}
+
+		const isMacroTarget =
+			expression.type === NodeType.ContextVariable &&
+			(this.parser.getImportedSymbol('template', String(expression.getAttribute('name'))) !== null ||
+				expression.getAttribute('name') === '_self');
+
+		let type = 'any';
+		/** @type {import('./array-expression.js').ArrayExpression} */
+		let argumentsNode = this.makeArray(lineNumber);
+		if (stream.test(TokenType.OPERATOR, '(')) {
+			type = 'method';
+			// preserve named-argument keys so the runtime can resolve them against
+			// the method's parameter names
+			argumentsNode = this.parseCallableArguments(lineNumber, true, true);
+		}
+
+		if (isMacroTarget) {
+			const node = n(
+				NodeType.MacroReference,
+				{ var: n(NodeType.LocalVariable, {}, { name: expression.getAttribute('name') }, expression.getTemplateLine()), name: attribute, arguments: argumentsNode },
+				{ hasCallParentheses: type === 'method' },
+				expression.getTemplateLine(),
+			);
+			return node;
+		}
+
+		return n(
+			NodeType.GetAttr,
+			{ node: expression, attribute, arguments: argumentsNode },
+			{ type, nullSafe },
+			lineNumber,
+		);
+	}
+
+	/**
+	 * Parses `[` subscript access (including the `[:]` slice syntax).
+	 *
+	 * @param {Node} expression The base expression.
+	 * @returns {Node} A `get_attr` or `filter` (`slice`) node.
+	 */
+	parseSquareBracket(expression) {
+		const stream = this.getStream();
+		const token = this.current();
+		const lineNumber = token.getLine();
+		const argumentsNode = this.makeArray(lineNumber);
+
+		// slice?
+		let slice = false;
+		let attribute;
+		if (stream.test(TokenType.PUNCTUATION, ':')) {
+			slice = true;
+			attribute = n(NodeType.Constant, {}, { value: 0 }, token.getLine());
+		} else {
+			attribute = this.parseExpression();
+		}
+
+		if (stream.nextIf(TokenType.PUNCTUATION, ':')) {
+			slice = true;
+		}
+
+		if (slice) {
+			let length;
+			if (stream.test(TokenType.PUNCTUATION, ']')) {
+				length = n(NodeType.Constant, {}, { value: null }, token.getLine());
+			} else {
+				length = this.parseExpression();
+			}
+			stream.expect(TokenType.PUNCTUATION, ']');
+			return n(
+				NodeType.Filter,
+				{ node: expression, arguments: [ { name: null, value: attribute }, { name: null, value: length } ] },
+				{ name: 'slice' },
+				lineNumber,
+			);
+		}
+
+		stream.expect(TokenType.PUNCTUATION, ']');
+		return n(
+			NodeType.GetAttr,
+			{ node: expression, attribute, arguments: argumentsNode },
+			{ type: 'array' },
+			lineNumber,
+		);
+	}
+
+	/**
+	 * Parses a filter call chain (`expression|name(args)`).
+	 *
+	 * @param {Node} expression The piped value.
+	 * @returns {Node} A `filter` node.
+	 */
+	parseFilter(expression) {
+		const stream = this.getStream();
+		const token = stream.expect(TokenType.NAME);
+		const line = token.getLine();
+
+		/** @type {Array<{name: string|null, value: Node}>} */
+		let args;
+		if (!stream.test(TokenType.OPERATOR, '(')) {
+			args = [];
+		} else {
+			args = this.parseNamedArguments(true, `for filter "${token.value}"`);
+		}
+
+		const filter = this.parser.getFilter(token.value, line);
+		if (filter.parameters) {
+			this.validateNamedArgs(args, filter.parameters, `for filter "${filter.name}"`);
+		}
+
+		return n(NodeType.Filter, { node: expression, arguments: args }, { name: filter.name }, line);
+	}
+
+	/**
+	 * Parses a filter chain starting at the given node (used by `apply`).
+	 *
+	 * @param {Node} expression The base node (a captured variable).
+	 * @returns {Node} The filter chain node.
+	 */
+	parseFilterChain(expression) {
+		const stream = this.getStream();
+		let filter = expression;
+		for (;;) {
+			filter = this.parseFilter(filter);
+			if (!stream.test(TokenType.OPERATOR, '|')) {
+				break;
+			}
+			stream.next();
+		}
+		return filter;
+	}
+
+	/**
+	 * Parses a function call (`name(args)`).
+	 *
+	 * @param {Node} expression The function-name expression.
+	 * @returns {Node} A `function` or `macro_reference` node.
+	 */
+	parseFunction(expression) {
+		const stream = this.getStream();
+		const line = this.current().getLine();
+		if (expression.type !== NodeType.ContextVariable) {
+			throw new SyntaxError(
+				'Function name must be an identifier.',
+				line,
+				stream.getSourceContext(),
+			);
+		}
+		const name = String(expression.getAttribute('name'));
+
+		// a bare call to a macro imported via "from"
+		const alias = this.parser.getImportedSymbol('function', name);
+		if (alias) {
+			const args = this.parseCallableArguments(line, false, true);
+			const node = n(
+				NodeType.MacroReference,
+				{ var: alias.node, name: n(NodeType.Constant, {}, { value: alias.name }, line), arguments: args },
+				{ hasCallParentheses: true },
+				line,
+			);
+			return node;
+		}
+
+		const args = this.parseNamedArguments(false, `for function "${name}"`);
+		const callable = this.parser.getFunction(name, line);
+		if (callable.parameters) {
+			this.validateNamedArgs(args, callable.parameters, `for function "${callable.name}(${callable.parameters.join(', ')})"`, `for function "${callable.name}"`);
+			this.validateRequiredArgs(args, callable.parameters, callable.name, line);
+		}
+
+		if (name === 'parent') {
+			if (!this.parser.peekBlockStack()) {
+				throw new SyntaxError(
+					'Calling the "parent" function outside of a block is forbidden.',
+					line,
+					this.getStream().getSourceContext(),
+				);
+			}
+			if (!this.parser.hasInheritance()) {
+				throw new SyntaxError(
+					'Calling the "parent" function on a template that does not call "extends" or "use" is forbidden.',
+					line,
+					this.getStream().getSourceContext(),
+				);
+			}
+		}
+
+		return n(NodeType.FunctionCall, { arguments: args }, { name: callable.name }, line);
+	}
+
+	/**
+	 * Validates that required arguments are present (e.g. `block(name)`).
+	 *
+	 * @param {Array<{name: string|null, value: Node}>} args
+	 * @param {string[]} parameters
+	 * @param {string} name
+	 * @param {number} line
+	 */
+	validateRequiredArgs(args, parameters, name, line) {
+		const required = REQUIRED_FUNCTION_ARGS[name];
+		if (!required) {
+			return;
+		}
+		const provided = new Set();
+		let positional = 0;
+		for (const arg of args) {
+			if (arg.name === null) {
+				while (positional < parameters.length && provided.has(parameters[positional])) {
+					positional += 1;
+				}
+				if (positional < parameters.length) {
+					provided.add(parameters[positional]);
+					positional += 1;
+				}
+			} else {
+				const normalized = arg.name.toLowerCase().replace(/_/g, '');
+				const index = parameters.map((p) => p.toLowerCase().replace(/_/g, '')).indexOf(normalized);
+				if (index >= 0) {
+					provided.add(parameters[index]);
+				}
+			}
+		}
+		for (const requiredParam of required) {
+			if (!provided.has(requiredParam)) {
+				throw new SyntaxError(
+					`Value for argument "${requiredParam}" is required for function "${name}".`,
+					line,
+					this.getStream().getSourceContext(),
+				);
+			}
+		}
+	}
+
+	/**
+	 * Parses a test (`expression is name(...)`).
+	 *
+	 * @param {Node} expression The tested expression.
+	 * @param {boolean} negate Whether to wrap in `not`.
+	 * @returns {Node} A `test` node (possibly wrapped in `not`).
+	 */
+	parseTest(expression, negate) {
+		const stream = this.getStream();
+		const line = stream.getCurrent().getLine();
+		const test = this.parser.getTest(line);
+
+		/** @type {Array<{name: string|null, value: Node}>|null} */
+		let args = null;
+		if (stream.test(TokenType.OPERATOR, '(')) {
+			args = this.parseNamedArguments(true, `for test "${test.name}"`);
+		} else if (test.oneMandatoryArgument) {
+			args = [{ name: null, value: this.parseExpression(100) }];
+		}
+		if (args && test.parameters) {
+			this.validateNamedArgs(args, test.parameters, `for test "${test.name}"`);
+		}
+
+		let node = n(NodeType.Test, { node: expression, arguments: args }, { name: test.name }, line);
+
+		// `x is defined` where x is a from-imported macro resolves the macro
+		if (test.name === 'defined' && expression.type === NodeType.ContextVariable) {
+			const alias = this.parser.getImportedSymbol('function', String(expression.getAttribute('name')));
+			if (alias) {
+				const macroReference = n(
+					NodeType.MacroReference,
+					{ var: alias.node, name: n(NodeType.Constant, {}, { value: alias.name }, line), arguments: this.makeArray(line) },
+					{ hasCallParentheses: false },
+					line,
+				);
+				node = n(NodeType.Test, { node: macroReference, arguments: args }, { name: test.name }, line);
+			}
+		}
+
+		if (negate) {
+			node = n(NodeType.Unary, { node }, { operator: 'not' }, line);
+		}
+		return node;
+	}
+
+	/**
+	 * Parses a binary operator expression.
+	 *
+	 * @param {string} operator The operator.
+	 * @param {Node} left
+	 * @param {{precedence: number, right: boolean}} operatorInfo Operator metadata.
+	 * @returns {Node} A `binary` node.
+	 */
+	parseBinary(operator, left, operatorInfo) {
+		const right = this.parseExpression(operatorInfo.right ? operatorInfo.precedence : operatorInfo.precedence + 1);
+		return n(NodeType.Binary, { left, right }, { operator: operator }, left.getTemplateLine());
+	}
+
+	/**
+	 * Parses the conditional operator (`a ? b : c`).
+	 *
+	 * @param {Node} left
+	 * @returns {Node} A `conditional` node.
+	 */
+	parseConditional(left) {
+		const stream = this.getStream();
+		const then = this.parseExpression(0);
+		let els;
+		if (stream.nextIf(TokenType.PUNCTUATION, ':')) {
+			els = this.parseExpression(0);
+		} else {
+			els = n(NodeType.Constant, {}, { value: '' }, left.getTemplateLine());
+		}
+		return n(NodeType.Conditional, { cond: left, then, else: els }, {}, left.getTemplateLine());
+	}
+
+	/**
+	 * Parses an assignment (`target = expression`) including destructuring.
+	 *
+	 * @param {Node} left The assignment target.
+	 * @returns {Node} A `set`, `sequence_destructuring_set` or `object_destructuring_set` node.
+	 */
+	parseAssignment(left) {
+		const stream = this.getStream();
+		const line = left.getTemplateLine();
+		if (left.type !== NodeType.ContextVariable && !(left instanceof ArrayExpression)) {
+			throw new SyntaxError(
+				`Cannot assign to "${left.type}", only variables can be assigned.`,
+				line,
+				stream.getSourceContext(),
+			);
+		}
+		const right = this.parseExpression(0);
+
+		if (left instanceof ArrayExpression) {
+			/** @type {Array<[Node, Node]>} */
+			const pairs = left.getKeyValuePairs();
+			const isSequence = left.isSequence();
+
+			const hasVar = pairs.some(([, value]) => value.type !== NodeType.Empty);
+			if (!pairs.length || (isSequence && !hasVar)) {
+				throw new SyntaxError(
+					'Cannot destructure to an empty list of variables.',
+					line,
+					stream.getSourceContext(),
+				);
+			}
+
+			// convert plain ContextVariable elements to assignable variables
+			for (const pair of pairs) {
+				if (pair[1] && pair[1].type === NodeType.ContextVariable) {
+					const v = pair[1];
+					pair[1] = n(NodeType.AssignContextVariable, {}, { name: v.getAttribute('name') }, v.getTemplateLine());
+				}
+			}
+
+			if (isSequence) {
+				return n(
+					NodeType.SequenceDestructuringSet,
+					{ left, right },
+					{},
+					line,
+				);
+			}
+			return n(NodeType.ObjectDestructuringSet, { left, right }, {}, line);
+		}
+
+		return n(NodeType.SetBinary, { left, right }, {}, line);
+	}
+
+	/**
+	 * Parses an arrow function (`x => expression`).
+	 *
+	 * @param {Node} left The parameter(s).
+	 * @returns {Node} An `arrow_function` node.
+	 */
+	parseArrow(left) {
+		const token = this.current();
+		if (
+			left.type !== NodeType.ContextVariable &&
+			left.type !== NodeType.ListExpr &&
+			left.type !== NodeType.AssignContextVariable
+		) {
+			throw new SyntaxError(
+				'The arrow function argument must be a list of variables or a single variable.',
+				token.getLine(),
+				this.getStream().getSourceContext(),
+			);
+		}
+		const body = this.parseExpression(0);
+		return n(NodeType.ArrowFunction, { body, arguments: left }, {}, token.getLine());
+	}
+
+	/**
+	 * Parses a named/positional argument list (already positioned after `(`).
+	 *
+	 * @param {boolean} parseOpenParenthesis Whether to expect and consume `(`.
+	 * @param {string} [context] Callable context appended to errors (e.g. `for function "date"`).
+	 * @returns {Array<{name: string|null, value: Node}>} Parsed arguments.
+	 */
+	parseNamedArguments(parseOpenParenthesis = true, context = '') {
+		const stream = this.getStream();
+		if (parseOpenParenthesis) {
+			stream.expect(TokenType.OPERATOR, '(', 'A list of arguments must begin with an opening parenthesis');
+		}
+		/** @type {Array<{name: string|null, value: Node}>} */
+		const args = [];
+		let hasSpread = false;
+		let sawNamed = false;
+		while (!stream.test(TokenType.PUNCTUATION, ')')) {
+			if (args.length) {
+				stream.expect(TokenType.PUNCTUATION, ',', 'Arguments must be separated by a comma');
+				// trailing comma
+				if (stream.test(TokenType.PUNCTUATION, ')')) {
+					break;
+				}
+			}
+
+			let value = this.parseExpression();
+			if (value.type === NodeType.Unary && value.getAttribute('operator') === '...') {
+				hasSpread = true;
+			} else if (hasSpread) {
+				throw new SyntaxError(
+					'Normal arguments must be placed before argument unpacking.',
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+
+			let name = null;
+			if (value.type === NodeType.SetBinary) {
+				const left = /** @type {Node} */ (value.getNode('left'));
+				name = String(left.getAttribute('name'));
+				value = /** @type {Node} */ (value.getNode('right'));
+			} else if (
+				stream.nextIf(TokenType.OPERATOR, '=') ||
+				stream.nextIf(TokenType.PUNCTUATION, ':')
+			) {
+				if (value.type !== NodeType.ContextVariable) {
+					throw new SyntaxError(
+						`A parameter name must be a string, "${value.type}" given.`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+				}
+				name = String(value.getAttribute('name'));
+				value = this.parseExpression();
+			}
+
+			if (name === null) {
+				if (sawNamed) {
+					throw new SyntaxError(
+						`Positional arguments cannot be used after named arguments${context ? ` ${context}` : ''}.`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+				}
+				args.push({ name: null, value });
+			} else {
+				if (args.some((a) => a.name === name)) {
+					throw new SyntaxError(
+						`Argument "${name}" is defined twice${context ? ` ${context}` : ''}.`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+				}
+				sawNamed = true;
+				args.push({ name, value });
+			}
+		}
+		stream.expect(TokenType.PUNCTUATION, ')', 'A list of arguments must be closed by a parenthesis');
+		return args;
+	}
+
+	/**
+	 * Validates named arguments against a callable's parameter names.
+	 *
+	 * @param {Array<{name: string|null, value: Node}>} args
+	 * @param {string[]} parameters
+	 * @param {string} context e.g. `function "include(template, variables)"`.
+	 * @param {string} [definedContext] Context for the "defined twice" error
+	 *   (e.g. `function "date"` without the signature).
+	 */
+	validateNamedArgs(args, parameters, context, definedContext) {
+		const normalize = (/** @type {string} */ p) => p.toLowerCase().replace(/_/g, '');
+		const normalizedParameters = parameters.map(normalize);
+		const twiceContext = definedContext ?? context;
+		/** @type {Set<string>} */
+		const used = new Set();
+		let positionalIndex = 0;
+		for (const arg of args) {
+			if (arg.name === null) {
+				while (positionalIndex < parameters.length && used.has(parameters[positionalIndex])) {
+					positionalIndex += 1;
+				}
+				if (positionalIndex < parameters.length) {
+					const parameter = parameters[positionalIndex];
+					if (used.has(parameter)) {
+						throw new SyntaxError(
+							`Argument "${arg.name ?? ''}" is defined twice ${twiceContext}.`,
+							arg.value.getTemplateLine(),
+							this.getStream().getSourceContext(),
+						);
+					}
+					used.add(parameter);
+					positionalIndex += 1;
+				}
+				continue;
+			}
+			const normalized = normalize(arg.name);
+			const index = normalizedParameters.indexOf(normalized);
+			if (index === -1) {
+				throw new SyntaxError(
+					`Unknown argument "${arg.name}" ${context}.`,
+					arg.value.getTemplateLine(),
+					this.getStream().getSourceContext(),
+				);
+			}
+			if (used.has(parameters[index])) {
+				throw new SyntaxError(
+					`Argument "${arg.name}" is defined twice ${twiceContext}.`,
+					arg.value.getTemplateLine(),
+					this.getStream().getSourceContext(),
+				);
+			}
+			used.add(parameters[index]);
+		}
+	}
+
+	/**
+	 * Parses callable arguments into an array node (for method calls / macros).
+	 *
+	 * @param {number} line
+	 * @param {boolean} [parseOpenParenthesis]
+	 * @param {boolean} [preserveNames]
+	 * @returns {ArrayExpression} An `array` node.
+	 */
+	parseCallableArguments(line, parseOpenParenthesis = true, preserveNames = false) {
+		const node = this.makeArray(line);
+		const args = this.parseNamedArguments(parseOpenParenthesis);
+		for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			const keyNode =
+				arg.name === null || !preserveNames
+					? n(NodeType.LocalVariable, {}, { name: i }, line)
+					: n(NodeType.Constant, {}, { value: arg.name }, line);
+			node.addElement(arg.value, keyNode);
+		}
+		return node;
+	}
+
+	/**
+	 * Creates an array expression node.
+	 *
+	 * @param {number} line
+	 * @returns {import('./array-expression.js').ArrayExpression} The array node.
+	 */
+	makeArray(line) {
+		return new ArrayExpression(line);
+	}
+}