@mrhenry/twig-parser 0.1.0

package/src/parser.js

@@ -0,0 +1,1776 @@
+// @ts-check
+/**
+ * The Twig parser: builds an AST from a token stream.
+ *
+ * Mirrors `src/Parser.php` plus the core token parsers from
+ * `src/TokenParser/*` of the reference implementation. See
+ * `spec/04-tags.md`.
+ *
+ * @module twig-parser
+ */
+import { TokenType, SyntaxError, Token } from '@mrhenry/twig-tokenizer';
+import { Node, NodeType, n, captureSignatures } from './node.js';
+import { ExpressionParser } from './expression-parser.js';
+import {
+	CORE_FILTER_NAMES,
+	CORE_FUNCTION_NAMES,
+	CORE_TEST_NAMES,
+} from './callables.js';
+
+/**
+ * @typedef {import('@mrhenry/twig-tokenizer').TokenStream} TokenStream
+ * @typedef {import('@mrhenry/twig-tokenizer').Source} Source
+ */
+
+/**
+ * A callable descriptor resolved from the environment.
+ *
+ * @typedef {object} CallableDescriptor
+ * @property {string} name
+ * @property {boolean} [oneMandatoryArgument]
+ * @property {string[]} [parameters]
+ */
+
+/**
+ * The environment contract the parser requires.
+ *
+ * @typedef {object} ParserEnvironment
+ * @property {(name: string, line: number) => CallableDescriptor|null} getFunction
+ * @property {(name: string, line: number) => CallableDescriptor|null} getFilter
+ * @property {(name: string) => CallableDescriptor|null} getTest
+ */
+
+/** Name pattern for word-operators used as variable names. */
+const REGULAR_EXPRESSION_NAME = /^[a-zA-Z_\u007f-\uffff][a-zA-Z0-9_\u007f-\uffff]*$/;
+
+/** Reserved literal words that cannot be assigned to. */
+const RESERVED_WORDS = new Set(['true', 'TRUE', 'false', 'FALSE', 'none', 'NONE', 'null', 'NULL']);
+
+/**
+ * An imported macro symbol.
+ *
+ * @typedef {object} ImportedSymbol
+ * @property {string|null} name The macro name in the source template.
+ * @property {Node|null} node The internal macro variable node.
+ */
+
+/**
+ * The parser state saved across nested (embed) parses.
+ *
+ * @typedef {object} ParserSavedState
+ * @property {TokenStream|null} stream
+ * @property {Node|null} parent
+ * @property {Record<string, Node>} blocks
+ * @property {Record<string, Node>} macros
+ * @property {Node[]} traits
+ * @property {Array<Record<string, Record<string, ImportedSymbol>>>} importedSymbols
+ * @property {string[]} blockStack
+ * @property {boolean} hasExtends
+ * @property {number} blockDepth
+ * @property {number} macroDepth
+ * @property {number} capturingNodeDepth
+ * @property {Array<Node|null>} tagStack
+ * @property {string|null} currentTag
+ * @property {Node[]} embeddedTemplates
+ * @property {number} lastEmbedIndex
+ */
+
+/**
+ * The template parser.
+ */
+export class Parser {
+	/**
+	 * @param {ParserEnvironment} environment The parser environment.
+	 */
+	constructor(environment) {
+		/** @type {ParserEnvironment} */
+		this.environment = environment;
+		/** @type {ExpressionParser} */
+		this.expressionParser = new ExpressionParser(this);
+		/** @type {TokenStream|null} */
+		this.stream = null;
+		/** @type {Node|null} */
+		this.parent = null;
+		/** @type {Record<string, Node>} */
+		this.blocks = {};
+		/** @type {Node[]} */
+		this.blockNodes = [];
+		/** @type {string[]} */
+		this.blockStack = [];
+		/** @type {Record<string, Node>} */
+		this.macros = {};
+		/** @type {Node[]} */
+		this.traits = [];
+		/** @type {Array<Record<string, Record<string, ImportedSymbol>>>} */
+		this.importedSymbols = [{}];
+		/** @type {Node[]} */
+		this.embeddedTemplates = [];
+		/** @type {number} */
+		this.lastEmbedIndex = 0;
+		/** @type {boolean} */
+		this.ignoreUnknownTwigCallables = false;
+		/** @type {boolean} */
+		this.hasExtends = false;
+		/** @type {number} */
+		this.blockDepth = 0;
+		/** @type {number} */
+		this.macroDepth = 0;
+		/** @type {number} */
+		this.capturingNodeDepth = 0;
+		/** @type {Array<Node|null>} */
+		this.tagStack = [];
+		/** @type {string|null} */
+		this.currentTag = null;
+		/** @type {ParserSavedState[]} */
+		this.saveStack = [];
+	}
+
+	/**
+	 * @returns {TokenStream} The token stream.
+	 */
+	getStream() {
+		return /** @type {TokenStream} */ (this.stream);
+	}
+
+	/**
+	 * @returns {Token} The current token.
+	 */
+	getCurrentToken() {
+		return this.getStream().getCurrent();
+	}
+
+	/**
+	 * @returns {ParserEnvironment} The environment.
+	 */
+	getEnvironment() {
+		return this.environment;
+	}
+
+	/**
+	 * Parses a full template into a module node.
+	 *
+	 * @param {TokenStream} stream
+	 * @param {((token: Token) => boolean)|null} [test]
+	 * @param {boolean} [dropNeedle]
+	 * @returns {Node} The module node.
+	 */
+	parse(stream, test = null, dropNeedle = false) {
+		if (!this.stream) {
+			this.lastEmbedIndex = 0;
+		}
+
+		// save the current state so nested (embed) parses can restore it
+		const saved = {
+			stream: this.stream,
+			parent: this.parent,
+			blocks: this.blocks,
+			macros: this.macros,
+			traits: this.traits,
+			importedSymbols: this.importedSymbols,
+			blockStack: this.blockStack,
+			hasExtends: this.hasExtends,
+			blockDepth: this.blockDepth,
+			macroDepth: this.macroDepth,
+			capturingNodeDepth: this.capturingNodeDepth,
+			tagStack: this.tagStack,
+			currentTag: this.currentTag,
+			embeddedTemplates: this.embeddedTemplates,
+			lastEmbedIndex: this.lastEmbedIndex,
+		};
+		this.saveStack.push(saved);
+
+		this.stream = stream;
+		this.parent = null;
+		this.blocks = {};
+		this.blockStack = [];
+		this.macros = {};
+		this.traits = [];
+		this.importedSymbols = [{}];
+		this.embeddedTemplates = [];
+		this.hasExtends = false;
+		this.blockDepth = 0;
+		this.macroDepth = 0;
+		this.capturingNodeDepth = 0;
+		this.tagStack = [];
+
+		let body;
+		try {
+			body = this.subparse(test, dropNeedle);
+		} catch (e) {
+			if (e instanceof SyntaxError) {
+				if (!e.getSourceContext()) {
+					e.setSourceContext(stream.getSourceContext());
+				}
+				if (e.getTemplateLine() < 0) {
+					e.setTemplateLine(this.getCurrentToken().getLine());
+				}
+			}
+			throw e;
+		}
+
+		if (this.parent) {
+			body = this.cleanupBodyForChildTemplates(body);
+		}
+
+		const module = n(
+			NodeType.Module,
+			{
+				body: n(NodeType.Body, { nodes: [body] }, {}, body.getTemplateLine()),
+				parent: this.parent,
+				blocks: Object.keys(this.blocks).length ? this.blocks : null,
+				macros: this.macros,
+				traits: this.traits.length ? this.traits : null,
+				embeddedTemplates: this.embeddedTemplates.length ? this.embeddedTemplates : null,
+			},
+			{},
+			stream.getCurrent().getLine(),
+			'module',
+		);
+		module.setSourceContext(stream.getSourceContext());
+		module.setAttribute('name', stream.getSourceContext()?.getName() ?? 'index.twig');
+		if (this.parent) {
+			module.setAttribute('parentLine', /** @type {Node} */ (this.parent).getTemplateLine());
+		}
+
+		const source = stream.getSourceContext();
+		if (source) {
+			module.leading = '';
+			module.rawStart = 0;
+			module.rawEnd = source.getCode().length;
+			module.raw = source.getCode();
+		}
+		module.setAttribute('trailing', stream.getCurrent().leading ?? '');
+
+		this.correctnessCheck(module);
+		captureSignatures(module);
+
+		// restore the previous state so an enclosing (outer) parse can resume
+		const previous = this.saveStack.pop();
+		if (previous) {
+			this.stream = previous.stream;
+			this.parent = previous.parent;
+			this.blocks = previous.blocks;
+			this.macros = previous.macros;
+			this.traits = previous.traits;
+			this.importedSymbols = previous.importedSymbols;
+			this.blockStack = previous.blockStack;
+			this.hasExtends = previous.hasExtends;
+			this.blockDepth = previous.blockDepth;
+			this.macroDepth = previous.macroDepth;
+			this.capturingNodeDepth = previous.capturingNodeDepth;
+			this.tagStack = previous.tagStack;
+			this.currentTag = previous.currentTag;
+			this.embeddedTemplates = previous.embeddedTemplates;
+			this.lastEmbedIndex = previous.lastEmbedIndex;
+		}
+
+		return module;
+	}
+
+	/**
+	 * Parses template content until the given test returns true.
+	 *
+	 * @param {((token: Token) => boolean)|null} [test]
+	 * @param {boolean} [dropNeedle]
+	 * @returns {Node} The parsed body (single node or a `nodes` list).
+	 */
+	subparse(test = null, dropNeedle = false) {
+		const stream = this.getStream();
+		const lineNumber = this.getCurrentToken().getLine();
+		/** @type {Node[]} */
+		const rv = [];
+		while (!stream.isEOF()) {
+			const current = stream.getCurrent();
+			const spanStart = current.rawStart;
+			const spanLeading = current.leading;
+			if (current.test(TokenType.TEXT)) {
+				const token = stream.next();
+				const node = n(NodeType.Text, {}, { data: token.value }, token.getLine(), 'text');
+				this.attachSpan(node, spanLeading, spanStart);
+				rv.push(node);
+			} else if (current.test(TokenType.VAR_START)) {
+				const token = stream.next();
+				const expression = this.parseExpression();
+				stream.expect(TokenType.VAR_END);
+				const node = n(NodeType.Print, { expr: expression }, {}, token.getLine(), 'print');
+				this.attachSpan(node, spanLeading, spanStart);
+				rv.push(node);
+			} else if (current.test(TokenType.BLOCK_START)) {
+				stream.next();
+				const token = this.getCurrentToken();
+				if (!token.test(TokenType.NAME)) {
+					throw new SyntaxError(
+						'A block must start with a tag name.',
+						token.getLine(),
+						stream.getSourceContext(),
+					);
+				}
+				if (test && test(token)) {
+					if (dropNeedle) {
+						stream.next();
+					}
+					if (rv.length === 1) {
+						return rv[0];
+					}
+					const nodes = n(NodeType.Nodes, { nodes: rv }, {}, lineNumber);
+					this.attachContainerSpan(nodes, rv);
+					return nodes;
+				}
+
+				const tag = token.value;
+				const subparser = this.getTokenParser(tag);
+				if (!subparser) {
+					if (test) {
+						throw new SyntaxError(
+							`Unexpected "${tag}" tag (expecting closing tag for the "${this.currentTag ?? tag}" tag defined near line ${lineNumber}).`,
+							token.getLine(),
+							stream.getSourceContext(),
+						);
+					}
+					const e = new SyntaxError(`Unknown "${tag}" tag.`, token.getLine(), stream.getSourceContext());
+					e.addSuggestions(tag, Object.keys(TAG_PARSERS));
+					throw e;
+				}
+
+				stream.next();
+				this.tagStack.push(null);
+				const previousTag = this.currentTag;
+				this.currentTag = tag;
+				const node = subparser.parse(token);
+				this.currentTag = previousTag;
+				this.tagStack.pop();
+				node.setNodeTag(tag);
+				this.attachSpan(node, spanLeading, spanStart);
+				rv.push(node);
+			} else {
+				throw new SyntaxError(
+					'The lexer or the parser ended up in an unsupported state.',
+					this.getCurrentToken().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+		}
+
+		if (rv.length === 1) {
+			return rv[0];
+		}
+		const nodes = n(NodeType.Nodes, { nodes: rv }, {}, lineNumber);
+		this.attachContainerSpan(nodes, rv);
+		return nodes;
+	}
+
+	/**
+	 * Records the source span covered by a parsed node.
+	 *
+	 * @param {Node} node
+	 * @param {string} leading Trivia preceding the span.
+	 * @param {number} start Absolute start offset.
+	 */
+	attachSpan(node, leading, start) {
+		const source = this.getStream().getSourceContext();
+		if (!source) {
+			return;
+		}
+		const end = this.getCurrentToken().sourceStart;
+		node.leading = leading;
+		node.rawStart = start;
+		node.rawEnd = end;
+		node.raw = start <= end ? source.getCode().slice(start, end) : '';
+	}
+
+	/**
+	 * Records the source span covering a list of already-spanned children.
+	 *
+	 * @param {Node} node The container node (a `nodes` node).
+	 * @param {Node[]} children The spanned children.
+	 */
+	attachContainerSpan(node, children) {
+		const source = this.getStream().getSourceContext();
+		if (!source || children.length === 0) {
+			return;
+		}
+		const first = children[0];
+		const last = children[children.length - 1];
+		node.leading = first.leading;
+		node.rawStart = first.rawStart;
+		node.rawEnd = last.rawEnd;
+		node.raw = source.getCode().slice(first.rawStart, last.rawEnd);
+	}
+
+	/**
+	 * Runs `subparse` while ignoring unknown Twig callables (used by `guard`).
+	 *
+	 * @param {((token: Token) => boolean)|null} [test]
+	 * @param {boolean} [dropNeedle]
+	 * @returns {Node} The parsed body.
+	 */
+	subparseIgnoreUnknownTwigCallables(test = null, dropNeedle = false) {
+		const previous = this.ignoreUnknownTwigCallables;
+		this.ignoreUnknownTwigCallables = true;
+		try {
+			return this.subparse(test, dropNeedle);
+		} finally {
+			this.ignoreUnknownTwigCallables = previous;
+		}
+	}
+
+	/**
+	 * @returns {boolean} Whether unknown callables should be ignored.
+	 */
+	shouldIgnoreUnknownTwigCallables() {
+		return this.ignoreUnknownTwigCallables;
+	}
+
+	/**
+	 * Parses an expression.
+	 *
+	 * @param {number} [precedence]
+	 * @returns {Node} The expression node.
+	 */
+	parseExpression(precedence = 0) {
+		return this.expressionParser.parseExpression(precedence);
+	}
+
+	/**
+	 * Parses an assignment target list (`a, b`).
+	 *
+	 * @returns {Node[]} The target nodes.
+	 */
+	parseAssignmentExpression() {
+		const stream = this.getStream();
+		/** @type {Node[]} */
+		const targets = [];
+		for (;;) {
+			const token = stream.getCurrent();
+			if (stream.test(TokenType.OPERATOR) && REGULAR_EXPRESSION_NAME.test(String(token.value))) {
+				stream.next();
+			} else {
+				stream.expect(TokenType.NAME, null, 'Only variables can be assigned to');
+			}
+			const name = String(token.value);
+			if (['true', 'TRUE', 'false', 'FALSE', 'none', 'NONE', 'null', 'NULL'].includes(name)) {
+				throw new SyntaxError(
+					`You cannot assign a value to "${name}".`,
+					token.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			targets.push(
+				n(NodeType.AssignContextVariable, {}, { name }, token.getLine()),
+			);
+			if (!stream.nextIf(TokenType.PUNCTUATION, ',')) {
+				break;
+			}
+		}
+		return targets;
+	}
+
+	/**
+	 * Parses a multi-target expression list (`1, 2, 3`).
+	 *
+	 * @returns {Node[]} The parsed expressions.
+	 */
+	parseMultitargetExpression() {
+		const stream = this.getStream();
+		/** @type {Node[]} */
+		const targets = [];
+		for (;;) {
+			targets.push(this.parseExpression());
+			if (!stream.nextIf(TokenType.PUNCTUATION, ',')) {
+				break;
+			}
+		}
+		return targets;
+	}
+
+	/**
+	 * Resolves a function descriptor.
+	 *
+	 * @param {string} name
+	 * @param {number} line
+	 * @returns {CallableDescriptor}
+	 */
+	getFunction(name, line) {
+		let callable = null;
+		try {
+			callable = this.environment.getFunction(name, line);
+		} catch (e) {
+			if (!this.shouldIgnoreUnknownTwigCallables()) {
+				throw e;
+			}
+		}
+		if (!callable) {
+			if (this.shouldIgnoreUnknownTwigCallables()) {
+				return { name };
+			}
+			const e = new SyntaxError(`Unknown "${name}" function.`, line, this.getStream().getSourceContext());
+			e.addSuggestions(name, CORE_FUNCTION_NAMES);
+			throw e;
+		}
+		return callable;
+	}
+
+	/**
+	 * Resolves a filter descriptor.
+	 *
+	 * @param {string} name
+	 * @param {number} line
+	 * @returns {CallableDescriptor}
+	 */
+	getFilter(name, line) {
+		let filter = null;
+		try {
+			filter = this.environment.getFilter(name, line);
+		} catch (e) {
+			if (!this.shouldIgnoreUnknownTwigCallables()) {
+				throw e;
+			}
+		}
+		if (!filter) {
+			if (this.shouldIgnoreUnknownTwigCallables()) {
+				return { name };
+			}
+			const e = new SyntaxError(`Unknown "${name}" filter.`, line, this.getStream().getSourceContext());
+			e.addSuggestions(name, CORE_FILTER_NAMES);
+			throw e;
+		}
+		return filter;
+	}
+
+	/**
+	 * Resolves a test descriptor (consumes the test NAME token(s)).
+	 *
+	 * @param {number} line
+	 * @returns {CallableDescriptor}
+	 */
+	getTest(line) {
+		const stream = this.getStream();
+		const name = stream.expect(TokenType.NAME).getValue();
+		/** @type {CallableDescriptor|null} */
+		let test;
+		let name2 = null;
+
+		if (stream.test(TokenType.NAME)) {
+			name2 = `${name} ${this.getCurrentToken().getValue()}`;
+			try {
+				test = this.environment.getTest(name2);
+			} catch (e) {
+				if (!this.shouldIgnoreUnknownTwigCallables()) {
+					throw e;
+				}
+				test = null;
+			}
+			stream.next();
+		} else {
+			try {
+				test = this.environment.getTest(name);
+			} catch (e) {
+				if (!this.shouldIgnoreUnknownTwigCallables()) {
+					throw e;
+				}
+				test = null;
+			}
+		}
+
+		if (!test) {
+			if (this.shouldIgnoreUnknownTwigCallables()) {
+				return { name: name2 ?? name };
+			}
+			const e = new SyntaxError(
+				`Unknown "${name2 ?? name}" test.`,
+				line,
+				stream.getSourceContext(),
+			);
+			e.addSuggestions(name2 ?? name, CORE_TEST_NAMES);
+			throw e;
+		}
+		return test;
+	}
+
+	/**
+	 * Registers a block definition.
+	 *
+	 * @param {string} name
+	 * @param {Node} block
+	 */
+	setBlock(name, block) {
+		if (this.blocks[name]) {
+			const existing = /** @type {Node} */ (this.blocks[name]);
+			throw new SyntaxError(
+				`The block '${name}' has already been defined line ${existing.getTemplateLine()}.`,
+				this.getCurrentToken().getLine(),
+				existing.getSourceContext(),
+			);
+		}
+		block.setSourceContext(this.getStream().getSourceContext());
+		this.blocks[name] = block;
+	}
+
+	/**
+	 * Registers a macro.
+	 *
+	 * @param {string} name
+	 * @param {Node} node
+	 */
+	setMacro(name, node) {
+		this.macros[name] = node;
+	}
+
+	/**
+	 * Adds a trait (from `use`).
+	 *
+	 * @param {Node} trait
+	 */
+	addTrait(trait) {
+		this.traits.push(trait);
+	}
+
+	/**
+	 * @returns {boolean} Whether the template has a parent or traits.
+	 */
+	hasInheritance() {
+		return Boolean(this.parent) || this.traits.length > 0;
+	}
+
+	/**
+	 * Sets the parent template expression.
+	 *
+	 * @param {Node} parent
+	 * @param {boolean} [throwOnMultiple]
+	 */
+	setParent(parent, throwOnMultiple = true) {
+		if (this.parent) {
+			if (!throwOnMultiple) {
+				return;
+			}
+			throw new SyntaxError(
+				'Multiple extends tags are forbidden.',
+				parent.getTemplateLine(),
+				parent.getSourceContext(),
+			);
+		}
+		this.parent = parent;
+	}
+
+	/**
+	 * Registers an imported macro symbol.
+	 *
+	 * @param {string} type
+	 * @param {string} alias
+	 * @param {string|null} [name]
+	 * @param {Node|null} [internalReference]
+	 */
+	addImportedSymbol(type, alias, name = null, internalReference = null) {
+		this.importedSymbols[0][type] = this.importedSymbols[0][type] ?? {};
+		this.importedSymbols[0][type][alias] = { name, node: internalReference };
+	}
+
+	/**
+	 * Looks up an imported symbol in the current and main scope.
+	 *
+	 * @param {string} type
+	 * @param {string} alias
+	 * @returns {ImportedSymbol|null}
+	 */
+	getImportedSymbol(type, alias) {
+		const scope = this.importedSymbols[0][type]?.[alias];
+		if (scope) {
+			return scope;
+		}
+		const main = this.importedSymbols[this.importedSymbols.length - 1][type]?.[alias];
+		return main ?? null;
+	}
+
+	/**
+	 * @returns {boolean} Whether we are in the main scope.
+	 */
+	isMainScope() {
+		return this.importedSymbols.length === 1;
+	}
+
+	/** Pushes a local (block/macro) scope. */
+	pushLocalScope() {
+		this.importedSymbols.unshift({});
+	}
+
+	/** Pops a local scope. */
+	popLocalScope() {
+		this.importedSymbols.shift();
+	}
+
+	/**
+	 * @returns {string|null} The current block name.
+	 */
+	peekBlockStack() {
+		return this.blockStack[this.blockStack.length - 1] ?? null;
+	}
+
+	/**
+	 * @param {string} name
+	 */
+	pushBlockStack(name) {
+		this.blockStack.push(name);
+	}
+
+	/** Pops the block stack. */
+	popBlockStack() {
+		this.blockStack.pop();
+	}
+
+	/**
+	 * Registers an embedded template.
+	 *
+	 * @param {Node} template
+	 */
+	embedTemplate(template) {
+		this.lastEmbedIndex += 1;
+		template.setAttribute('index', this.lastEmbedIndex);
+		template.setAttribute('embeddedName', `__embedded_${this.lastEmbedIndex}`);
+		this.embeddedTemplates.push(template);
+	}
+
+	/**
+	 * Resolves the token parser for a tag name.
+	 *
+	 * @param {string} name
+	 * @returns {{parse: (token: Token) => Node}|null}
+	 */
+	getTokenParser(name) {
+		if (TAG_PARSERS[name]) {
+			return { parse: (token) => TAG_PARSERS[name](this, token) };
+		}
+		return null;
+	}
+
+	/**
+	 * Removes block references / blank text from child template bodies.
+	 *
+	 * @param {Node} body
+	 * @returns {Node}
+	 */
+	cleanupBodyForChildTemplates(body) {
+		if (body.type === NodeType.BlockReference) {
+			return n(NodeType.Empty, {}, {}, body.getTemplateLine());
+		}
+		if (body.type === NodeType.Text && isBlankText(String(body.getAttribute('data')))) {
+			return n(NodeType.Empty, {}, {}, body.getTemplateLine());
+		}
+		if (body.type === NodeType.Nodes) {
+			const nodes = body.getNodes('nodes').filter((node) => {
+				if (node.type === NodeType.BlockReference) {
+					return false;
+				}
+				if (node.type === NodeType.Text && isBlankText(String(node.getAttribute('data')))) {
+					return false;
+				}
+				return true;
+			});
+			if (nodes.length === 1) {
+				return nodes[0];
+			}
+			if (nodes.length === 0) {
+				return n(NodeType.Empty, {}, {}, body.getTemplateLine());
+			}
+			return n(NodeType.Nodes, { nodes }, {}, body.getTemplateLine());
+		}
+		return body;
+	}
+
+	/**
+	 * Runs the correctness checks equivalent to `CorrectnessNodeVisitor`.
+	 *
+	 * @param {Node} module
+	 */
+	correctnessCheck(module) {
+		const sourceContext = module.getSourceContext();
+		const hasParent = module.hasNode('parent');
+		const body = /** @type {Node} */ (module.getNode('body'));
+		const root = body.getNodes('nodes')[0] ?? body;
+
+		// 1. a template that extends another one cannot include content outside blocks
+		if (hasParent) {
+			const roots = root.type === NodeType.Nodes ? root.getNodes('nodes') : [root];
+			for (const r of roots) {
+				if (!this.isEmptyOutputNode(r)) {
+					throw new SyntaxError(
+						'A template that extends another one cannot include content outside Twig blocks. Did you forget to put the content inside a {% block %} tag?',
+						r.getTemplateLine(),
+						sourceContext,
+					);
+				}
+			}
+		}
+
+		// 2. extends / use / block nesting checks
+		this.blockDepth = 0;
+		this.macroDepth = 0;
+		this.capturingNodeDepth = 0;
+		this.tagStack = [];
+		this.hasExtends = false;
+		/** @param {Node} node */
+		const walk = (node) => {
+			if (node.type === NodeType.Block) {
+				this.blockDepth += 1;
+			} else if (node.type === NodeType.Macro) {
+				this.macroDepth += 1;
+			} else if (node.type === NodeType.Set && node.getAttribute('capture')) {
+				this.capturingNodeDepth += 1;
+			} else if (node.tag && node.tag !== 'module' && node.type !== NodeType.BlockReference && node.type !== NodeType.Macro && node.type !== NodeType.Text && node.type !== NodeType.Print) {
+				this.tagStack.push(node);
+			}
+
+			if (node.type === NodeType.Extends) {
+				if (this.blockDepth) {
+					throw new SyntaxError('Cannot use "extend" in a block.', node.getTemplateLine(), node.getSourceContext() ?? sourceContext);
+				}
+				if (this.macroDepth) {
+					throw new SyntaxError('Cannot use "extend" in a macro.', node.getTemplateLine(), node.getSourceContext() ?? sourceContext);
+				}
+				if (this.hasExtends) {
+					throw new SyntaxError('Multiple extends tags are forbidden.', node.getTemplateLine(), node.getSourceContext() ?? sourceContext);
+				}
+				this.hasExtends = true;
+			}
+
+			if (node.type === NodeType.BlockReference && hasParent && this.blockDepth === 0 && this.macroDepth === 0 && this.capturingNodeDepth === 0 && this.tagStack.length) {
+				const tag = /** @type {Node} */ (this.tagStack[this.tagStack.length - 1]);
+				throw new SyntaxError(
+					`A "block" tag cannot be under a "${tag.tag}" tag (line ${tag.getTemplateLine()}).`,
+					node.getTemplateLine(),
+					node.getSourceContext() ?? sourceContext,
+				);
+			}
+
+			// do not descend into embedded (separate) modules
+			for (const key of Object.keys(node.children)) {
+				if (key === 'embeddedTemplates') {
+					continue;
+				}
+				const child = node.children[key];
+				if (Array.isArray(child)) {
+					for (const c of child) {
+						if (c instanceof Node) {
+							walk(c);
+						}
+					}
+				} else if (child instanceof Node) {
+					walk(child);
+				} else if (child !== null && typeof child === 'object') {
+					// keyed records of nodes (e.g. module `blocks` / `macros`)
+					for (const value of Object.values(/** @type {Record<string, unknown>} */ (child))) {
+						if (value instanceof Node) {
+							walk(value);
+						}
+					}
+				}
+			}
+		};
+		walk(module);
+	}
+
+	/**
+	 * Returns true if a node never outputs anything.
+	 *
+	 * @param {Node} node
+	 * @returns {boolean}
+	 */
+	isEmptyOutputNode(node) {
+		switch (node.type) {
+			case NodeType.Text:
+				return isBlankText(String(node.getAttribute('data')));
+			case NodeType.Set:
+				if (node.getAttribute('capture')) {
+					return true;
+				}
+				break;
+			case NodeType.Empty:
+			case NodeType.Extends:
+			case NodeType.Use:
+			case NodeType.BlockReference:
+			case NodeType.Macro:
+			case NodeType.Types:
+				return true;
+			case NodeType.Print:
+				return false;
+			default:
+				break;
+		}
+		for (const child of node) {
+			if (!this.isEmptyOutputNode(child)) {
+				return false;
+			}
+		}
+		return true;
+	}
+}
+
+/**
+ * Whether text is blank (whitespace only).
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isBlankText(text) {
+	// eslint-disable-next-line no-control-regex -- \x0B and \0 are valid blank characters
+	return /^[ \t\n\r\0\x0B\f]*$/.test(text);
+}
+
+/* ------------------------------------------------------------------------ */
+/* Core token parsers                                                       */
+/* ------------------------------------------------------------------------ */
+
+/**
+ * @typedef {(parser: Parser, token: Token) => Node} TagParser
+ */
+
+/**
+ * Core tags whose body is closed by a matching `end<name>` tag.
+ *
+ * `set` is not listed: `{% set x %}` is a capture block only when it has no
+ * `=` (see {@link TAG_END_NAMES} and `spec/04-tags.md` §4.17).
+ *
+ * @type {string[]}
+ */
+export const BLOCK_TAGS = [
+	'apply',
+	'autoescape',
+	'block',
+	'embed',
+	'for',
+	'guard',
+	'if',
+	'macro',
+	'sandbox',
+	'with',
+];
+
+/**
+ * Core tags that occupy a single tag and have no body.
+ *
+ * @type {string[]}
+ */
+export const INLINE_TAGS = [
+	'deprecated',
+	'do',
+	'extends',
+	'flush',
+	'from',
+	'import',
+	'include',
+	'types',
+	'use',
+];
+
+/**
+ * Opening tag → matching closing tag for the block forms.
+ *
+ * Includes `set`, whose capture form (`{% set x %}...{% endset %}`) is a block
+ * even though the expression form is single-line.
+ *
+ * @type {Record<string, string>}
+ */
+export const TAG_END_NAMES = {
+	apply: 'endapply',
+	autoescape: 'endautoescape',
+	block: 'endblock',
+	embed: 'endembed',
+	for: 'endfor',
+	guard: 'endguard',
+	if: 'endif',
+	macro: 'endmacro',
+	sandbox: 'endsandbox',
+	set: 'endset',
+	with: 'endwith',
+};
+
+/**
+ * Tag parser registry.
+ *
+ * @type {Record<string, TagParser>}
+ */
+export const TAG_PARSERS = {
+	/** `{% set name = expression %}` / `{% set name %}...{% endset %}` */
+	set(parser, token) {
+		const lineNumber = token.getLine();
+		const stream = parser.getStream();
+		const names = parser.parseAssignmentExpression();
+
+		let capture = false;
+		/** @type {Node[]} */
+		let values;
+		if (stream.nextIf(TokenType.OPERATOR, '=')) {
+			values = parser.parseMultitargetExpression();
+			stream.expect(TokenType.BLOCK_END);
+			if (names.length !== values.length) {
+				throw new SyntaxError(
+					'When using set, you must have the same number of variables and assignments.',
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+		} else {
+			capture = true;
+			if (names.length > 1) {
+				throw new SyntaxError(
+					'When using set with a block, you cannot have a multi-target.',
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			stream.expect(TokenType.BLOCK_END);
+			values = [parser.subparse(decideTagEnd('endset'), true)];
+			stream.expect(TokenType.BLOCK_END);
+		}
+
+		return n(
+			NodeType.Set,
+			{ names: n(NodeType.Nodes, { nodes: names }, {}, lineNumber), values: n(NodeType.Nodes, { nodes: values }, {}, lineNumber), body: capture ? values[0] : null },
+			{ capture },
+			lineNumber,
+		);
+	},
+
+	/** `{% for target in expression %}...{% endfor %}` */
+	for(parser, token) {
+		const lineNumber = token.getLine();
+		const stream = parser.getStream();
+		const targets = parser.parseAssignmentExpression();
+		stream.expect(TokenType.OPERATOR, 'in');
+		const sequence = parser.parseExpression();
+
+		stream.expect(TokenType.BLOCK_END);
+		const body = parser.subparse(decideForFork);
+		let elseBody = null;
+		if ('else' === stream.next().value) {
+			stream.expect(TokenType.BLOCK_END);
+			elseBody = parser.subparse(decideTagEnd('endfor'), true);
+		}
+		stream.expect(TokenType.BLOCK_END);
+
+		let keyTarget;
+		let valueTarget;
+		if (targets.length > 1) {
+			keyTarget = targets[0];
+			valueTarget = targets[1];
+		} else {
+			keyTarget = n(NodeType.AssignContextVariable, {}, { name: '_key' }, lineNumber);
+			valueTarget = targets[0];
+		}
+
+		return n(
+			NodeType.For,
+			{ keyTarget, valueTarget, seq: sequence, body, elseBody },
+			{},
+			lineNumber,
+		);
+	},
+
+	/** `{% if cond %}...{% elseif %}...{% else %}...{% endif %}` */
+	if(parser, token) {
+		const lineNumber = token.getLine();
+		const expression = parser.parseExpression();
+		const stream = parser.getStream();
+		stream.expect(TokenType.BLOCK_END);
+		let body = parser.subparse(decideIfFork);
+		/** Flat list: [cond, body, cond, body, ...] */
+		const tests = [expression, body];
+		let elseBody = null;
+
+		let end = false;
+		while (!end) {
+			const value = stream.next().value;
+			switch (value) {
+				case 'else':
+					stream.expect(TokenType.BLOCK_END);
+					elseBody = parser.subparse(decideTagEnd('endif'));
+					break;
+				case 'elseif':
+					{
+						const e = parser.parseExpression();
+						stream.expect(TokenType.BLOCK_END);
+						body = parser.subparse(decideIfFork);
+						tests.push(e, body);
+					}
+					break;
+				case 'endif':
+					end = true;
+					break;
+				default:
+					throw new SyntaxError(
+						`Unexpected end of template. Twig was looking for the following tags "else", "elseif", or "endif" to close the "if" block started at line ${lineNumber}).`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+			}
+		}
+
+		stream.expect(TokenType.BLOCK_END);
+
+		return n(NodeType.If, { tests, elseBody }, {}, lineNumber);
+	},
+
+	/** `{% block name %}...{% endblock %}` */
+	block(parser, token) {
+		const lineNumber = token.getLine();
+		const stream = parser.getStream();
+		const name = stream.expect(TokenType.NAME).value;
+		const block = n(NodeType.Block, { body: n(NodeType.Empty, {}, {}, lineNumber) }, { name }, lineNumber);
+		parser.setBlock(name, block);
+		parser.pushLocalScope();
+		parser.pushBlockStack(name);
+
+		let body;
+		if (stream.nextIf(TokenType.BLOCK_END)) {
+			body = parser.subparse(decideTagEnd('endblock'), true);
+			const nameToken = stream.nextIf(TokenType.NAME);
+			if (nameToken) {
+				const value = nameToken.value;
+				if (value !== name) {
+					throw new SyntaxError(
+						`Expected endblock for block "${name}" (but "${value}" given).`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+				}
+			}
+		} else {
+			body = n(NodeType.Nodes, { nodes: [n(NodeType.Print, { expr: parser.parseExpression() }, {}, lineNumber)] }, {}, lineNumber);
+		}
+		stream.expect(TokenType.BLOCK_END);
+
+		block.setNode('body', body);
+		parser.popBlockStack();
+		parser.popLocalScope();
+
+		const reference = n(NodeType.BlockReference, {}, { name }, lineNumber);
+		reference.setAttribute('block', block);
+		return reference;
+	},
+
+	/** `{% macro name(args) %}...{% endmacro %}` */
+	macro(parser, token) {
+		const lineNumber = token.getLine();
+		const stream = parser.getStream();
+		const name = stream.expect(TokenType.NAME).value;
+		const [argumentsList, variadicName] = parseMacroDefinition(parser, name);
+
+		stream.expect(TokenType.BLOCK_END);
+		parser.pushLocalScope();
+		const body = parser.subparse(decideTagEnd('endmacro'), true);
+		const nameToken = stream.nextIf(TokenType.NAME);
+		if (nameToken) {
+			if (nameToken.value !== name) {
+				throw new SyntaxError(
+					`Expected endmacro for macro "${name}" (but "${nameToken.value}" given).`,
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+		}
+		parser.popLocalScope();
+		stream.expect(TokenType.BLOCK_END);
+
+		const macro = n(
+			NodeType.Macro,
+			{ body: n(NodeType.Body, { nodes: [body] }, {}, body.getTemplateLine()) },
+			{ name, arguments: argumentsList, variadicName },
+			lineNumber,
+		);
+		macro.setSourceContext(stream.getSourceContext());
+		parser.setMacro(name, macro);
+
+		const declaration = n(NodeType.MacroDeclaration, {}, { name }, lineNumber);
+		declaration.setAttribute('macro', macro);
+		return declaration;
+	},
+
+	/** `{% include expression [ignore missing] [with expression] [only] %}` */
+	include(parser, token) {
+		const expression = parser.parseExpression();
+		const [variables, only, ignoreMissing] = parseIncludeArguments(parser);
+		return n(
+			NodeType.Include,
+			{ expr: expression, variables, only: n(NodeType.Constant, {}, { value: only }, token.getLine()), ignoreMissing: n(NodeType.Constant, {}, { value: ignoreMissing }, token.getLine()) },
+			{},
+			token.getLine(),
+		);
+	},
+
+	/** `{% import expression as name %}` */
+	import(parser, token) {
+		const macro = parser.parseExpression();
+		parser.getStream().expect(TokenType.NAME, 'as');
+		const name = parser.getStream().expect(TokenType.NAME).value;
+		const variableNode = n(
+			NodeType.LocalVariable,
+			{},
+			{ name, global: parser.isMainScope() },
+			token.getLine(),
+		);
+		parser.getStream().expect(TokenType.BLOCK_END);
+		parser.addImportedSymbol('template', name);
+
+		return n(NodeType.Import, { expr: macro, var: variableNode }, {}, token.getLine());
+	},
+
+	/** `{% from expression import name [as alias], ... %}` */
+	from(parser, token) {
+		const macro = parser.parseExpression();
+		const stream = parser.getStream();
+		stream.expect(TokenType.NAME, 'import');
+
+		/** @type {Array<{name: string, alias: string}>} */
+		const targets = [];
+		for (;;) {
+			const name = stream.expect(TokenType.NAME).value;
+			let alias = name;
+			if (stream.nextIf('as')) {
+				alias = stream.expect(TokenType.NAME).value;
+			}
+			if (['true', 'TRUE', 'false', 'FALSE', 'none', 'NONE', 'null', 'NULL'].includes(alias)) {
+				throw new SyntaxError(
+					`You cannot assign a value to "${alias}".`,
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			targets.push({ name, alias });
+
+			if (!stream.nextIf(TokenType.PUNCTUATION, ',')) {
+				break;
+			}
+		}
+
+		stream.expect(TokenType.BLOCK_END);
+
+		const internalReference = n(
+			NodeType.LocalVariable,
+			{},
+			{ name: null, global: parser.isMainScope() },
+			token.getLine(),
+		);
+
+		for (const target of targets) {
+			parser.addImportedSymbol('function', target.alias, target.name, internalReference);
+		}
+
+		return n(
+			NodeType.Import,
+			{ expr: macro, var: internalReference, targets: n(NodeType.Nodes, { nodes: targets.map((t) => n(NodeType.Constant, {}, { value: { name: t.name, alias: t.alias } }, token.getLine())) }, {}, token.getLine()) },
+			{},
+			token.getLine(),
+		);
+	},
+
+	/** `{% extends expression %}` */
+	extends(parser, token) {
+		const stream = parser.getStream();
+		const parent = parser.parseExpression();
+		parser.setParent(parent, false);
+		stream.expect(TokenType.BLOCK_END);
+		const node = n(NodeType.Extends, {}, {}, token.getLine());
+		node.setAttribute('parent', parent);
+		return node;
+	},
+
+	/** `{% use expression [with name [as alias], ...] %}` */
+	use(parser, token) {
+		const template = parser.parseExpression();
+		const stream = parser.getStream();
+		if (template.type !== NodeType.Constant) {
+			throw new SyntaxError(
+				'The template references in a "use" statement must be a string.',
+				stream.getCurrent().getLine(),
+				stream.getSourceContext(),
+			);
+		}
+
+		/** @type {Array<[string, string]>} */
+		const targets = [];
+		if (stream.nextIf('with')) {
+			for (;;) {
+				const name = stream.expect(TokenType.NAME).value;
+				let alias = name;
+				if (stream.nextIf('as')) {
+					alias = stream.expect(TokenType.NAME).value;
+				}
+				targets.push([name, alias]);
+				if (!stream.nextIf(TokenType.PUNCTUATION, ',')) {
+					break;
+				}
+			}
+		}
+
+		stream.expect(TokenType.BLOCK_END);
+
+		parser.addTrait(n(NodeType.Use, { template, targets: n(NodeType.Nodes, { nodes: targets.map(([name, alias]) => n(NodeType.Constant, {}, { value: { name, alias } }, token.getLine())) }, {}, token.getLine()) }, {}, token.getLine()));
+
+		return n(NodeType.Use, { template, targets: n(NodeType.Nodes, { nodes: targets.map(([name, alias]) => n(NodeType.Constant, {}, { value: { name, alias } }, token.getLine())) }, {}, token.getLine()) }, {}, token.getLine());
+	},
+
+	/** `{% with [expression [only]] %}...{% endwith %}` */
+	with(parser, token) {
+		const stream = parser.getStream();
+		let variables = null;
+		let only = false;
+		if (!stream.test(TokenType.BLOCK_END)) {
+			variables = parser.parseExpression();
+			only = Boolean(stream.nextIf(TokenType.NAME, 'only'));
+		}
+		stream.expect(TokenType.BLOCK_END);
+		const body = parser.subparse(decideTagEnd('endwith'), true);
+		stream.expect(TokenType.BLOCK_END);
+
+		return n(NodeType.With, { body, variables }, { only }, token.getLine());
+	},
+
+	/** `{% do expression %}` */
+	do(parser, token) {
+		const expression = parser.parseExpression();
+		parser.getStream().expect(TokenType.BLOCK_END);
+		return n(NodeType.Do, { expr: expression }, {}, token.getLine());
+	},
+
+	/** `{% autoescape [strategy] %}...{% endautoescape %}` */
+	autoescape(parser, token) {
+		const lineNumber = token.getLine();
+		const stream = parser.getStream();
+		let value;
+		if (stream.test(TokenType.BLOCK_END)) {
+			value = 'html';
+		} else {
+			const expression = parser.parseExpression();
+			if (expression.type !== NodeType.Constant) {
+				throw new SyntaxError(
+					'An escaping strategy must be a string or false.',
+					stream.getCurrent().getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			value = expression.getAttribute('value');
+		}
+		stream.expect(TokenType.BLOCK_END);
+		const body = parser.subparse(decideTagEnd('endautoescape'), true);
+		stream.expect(TokenType.BLOCK_END);
+		return n(NodeType.AutoEscape, { body }, { value }, lineNumber);
+	},
+
+	/** `{% apply filter-chain %}...{% endapply %}` */
+	apply(parser, token) {
+		const lineNumber = token.getLine();
+		const reference = n(NodeType.LocalVariable, {}, { name: null }, lineNumber);
+		const filter = parser.expressionParser.parseFilterChain(reference);
+		parser.getStream().expect(TokenType.BLOCK_END);
+		const body = parser.subparse(decideTagEnd('endapply'), true);
+		parser.getStream().expect(TokenType.BLOCK_END);
+		const node = n(
+			NodeType.Nodes,
+			{
+				nodes: [
+					n(NodeType.Set, { names: n(NodeType.Nodes, { nodes: [reference] }, {}, lineNumber), values: n(NodeType.Nodes, { nodes: [body] }, {}, lineNumber), body }, { capture: true }, lineNumber),
+					n(NodeType.Print, { expr: filter }, {}, lineNumber),
+				],
+			},
+			{},
+			lineNumber,
+		);
+		node.setAttribute('desugared', 'apply');
+		return node;
+	},
+
+	/** `{% embed expression ... %}...{% endembed %}` */
+	embed(parser, token) {
+		const stream = parser.getStream();
+		const parent = parser.parseExpression();
+		const [variables, only, ignoreMissing] = parseIncludeArguments(parser);
+
+		let parentToken;
+		if (parent.type === NodeType.Constant) {
+			parentToken = new Token(TokenType.STRING, String(parent.getAttribute('value')), token.getLine());
+		} else if (parent.type === NodeType.ContextVariable) {
+			parentToken = new Token(TokenType.NAME, String(parent.getAttribute('name')), token.getLine());
+		} else {
+			parentToken = new Token(TokenType.STRING, '__parent__', token.getLine());
+		}
+
+		// inject a fake parent to make the parent() function work
+		parentToken.synthetic = true;
+		const injected = [
+			new Token(TokenType.BLOCK_START, '', token.getLine()),
+			new Token(TokenType.NAME, 'extends', token.getLine()),
+			parentToken,
+			new Token(TokenType.BLOCK_END, '', token.getLine()),
+		];
+		for (const injectedToken of injected) {
+			injectedToken.synthetic = true;
+		}
+		stream.injectTokens(injected);
+
+		const module = parser.parse(stream, decideTagEnd('endembed'), true);
+
+		// override the parent with the correct one
+		if (parentToken.value === '__parent__') {
+			module.setNode('parent', parent);
+		}
+
+		parser.embedTemplate(module);
+
+		stream.expect(TokenType.BLOCK_END);
+
+		const node = n(
+			NodeType.Embed,
+			{ variables, only: n(NodeType.Constant, {}, { value: only }, token.getLine()), ignoreMissing: n(NodeType.Constant, {}, { value: ignoreMissing }, token.getLine()) },
+			{ name: String(module.getAttribute('embeddedName')), index: module.getAttribute('index') },
+			token.getLine(),
+		);
+		node.setAttribute('parent', parent);
+		node.setAttribute('embedded', module);
+		return node;
+	},
+
+	/** `{% sandbox %}...{% endsandbox %}` */
+	sandbox(parser, token) {
+		const stream = parser.getStream();
+		stream.expect(TokenType.BLOCK_END);
+		const body = parser.subparse(decideTagEnd('endsandbox'), true);
+		stream.expect(TokenType.BLOCK_END);
+
+		// only include tags are allowed
+		if (body.type === NodeType.Include) {
+			body.setAttribute('sandboxed', true);
+		} else if (body.type === NodeType.Nodes) {
+			for (const node of body.getNodes('nodes')) {
+				if (node.type === NodeType.Text && isBlankText(String(node.getAttribute('data')))) {
+					continue;
+				}
+				if (node.type !== NodeType.Include) {
+					throw new SyntaxError(
+						'Only "include" tags are allowed within a "sandbox" section.',
+						node.getTemplateLine(),
+						stream.getSourceContext(),
+					);
+				}
+				node.setAttribute('sandboxed', true);
+			}
+		} else if (body.type !== NodeType.Text) {
+			throw new SyntaxError(
+				'Only "include" tags are allowed within a "sandbox" section.',
+				body.getTemplateLine(),
+				stream.getSourceContext(),
+			);
+		}
+
+		return n(NodeType.Sandbox, { body }, {}, token.getLine());
+	},
+
+	/** `{% guard (function|filter|test) name ... %}...{% endguard %}` */
+	guard(parser, token) {
+		const stream = parser.getStream();
+		const typeToken = stream.expect(TokenType.NAME);
+		if (!['function', 'filter', 'test'].includes(String(typeToken.value))) {
+			throw new SyntaxError(
+				`Supported guard types are function, filter and test, "${typeToken.value}" given.`,
+				typeToken.getLine(),
+				stream.getSourceContext(),
+			);
+		}
+		let name = stream.expect(TokenType.NAME).value;
+		if (typeToken.value === 'test' && stream.test(TokenType.NAME)) {
+			name = `${name} ${stream.getCurrent().value}`;
+			stream.next();
+		}
+
+		/** @type {boolean} */
+		let exists;
+		try {
+			if (typeToken.value === 'function') {
+				exists = parser.environment.getFunction(name, token.getLine()) !== null;
+			} else if (typeToken.value === 'filter') {
+				exists = parser.environment.getFilter(name, token.getLine()) !== null;
+			} else {
+				exists = parser.environment.getTest(name) !== null;
+			}
+		} catch (e) {
+			exists = false;
+		}
+
+		stream.expect(TokenType.BLOCK_END);
+		let body;
+		if (exists) {
+			body = parser.subparse(decideGuardFork);
+		} else {
+			body = n(NodeType.Empty, {}, {}, token.getLine());
+			parser.subparseIgnoreUnknownTwigCallables(decideGuardFork);
+		}
+		let elseBody = n(NodeType.Empty, {}, {}, token.getLine());
+		if ('else' === stream.next().value) {
+			stream.expect(TokenType.BLOCK_END);
+			elseBody = parser.subparse(decideTagEnd('endguard'), true);
+		}
+		stream.expect(TokenType.BLOCK_END);
+
+		const node = n(NodeType.Nodes, { nodes: [exists ? body : elseBody] }, {}, token.getLine());
+		node.setAttribute('guardType', typeToken.value);
+		node.setAttribute('guardName', name);
+		node.setAttribute('guardExists', exists);
+		return node;
+	},
+
+	/** `{% types ... %}` */
+	types(parser, token) {
+		const stream = parser.getStream();
+		const enclosed = stream.nextIf(TokenType.PUNCTUATION, '{') !== null;
+		/** @type {Array<{name: string, type: string, optional: boolean}>} */
+		const types = [];
+		let first = true;
+		while (!(stream.test(TokenType.PUNCTUATION, '}') || stream.test(TokenType.BLOCK_END))) {
+			if (!first) {
+				stream.expect(TokenType.PUNCTUATION, ',', 'A type string must be followed by a comma');
+				if (stream.test(TokenType.PUNCTUATION, '}') || stream.test(TokenType.BLOCK_END)) {
+					break;
+				}
+			}
+			first = false;
+
+			const nameToken = stream.expect(TokenType.NAME);
+			let isOptional;
+			if (stream.nextIf(TokenType.OPERATOR, '?:')) {
+				isOptional = true;
+			} else {
+				isOptional = stream.nextIf(TokenType.OPERATOR, '?') !== null;
+				stream.expect(TokenType.PUNCTUATION, ':', 'A type name must be followed by a colon (:)');
+			}
+			const valueToken = stream.expect(TokenType.STRING);
+			types.push({ name: String(nameToken.value), type: String(valueToken.value), optional: isOptional });
+		}
+		if (enclosed) {
+			stream.expect(TokenType.PUNCTUATION, '}', 'An opened mapping is not properly closed');
+		}
+		stream.expect(TokenType.BLOCK_END);
+		return n(NodeType.Types, {}, { types, enclosed }, token.getLine());
+	},
+
+	/** `{% deprecated expression [package=... version=...] %}` */
+	deprecated(parser, token) {
+		const stream = parser.getStream();
+		const expression = parser.parseExpression();
+		const node = n(NodeType.Deprecated, { expr: expression, package: null, version: null }, {}, token.getLine());
+
+		while (stream.test(TokenType.NAME)) {
+			const k = stream.getCurrent().value;
+			stream.next();
+			stream.expect(TokenType.OPERATOR, '=');
+			switch (k) {
+				case 'package':
+					node.setNode('package', parser.parseExpression());
+					break;
+				case 'version':
+					node.setNode('version', parser.parseExpression());
+					break;
+				default:
+					throw new SyntaxError(
+						`Unknown "${k}" option.`,
+						stream.getCurrent().getLine(),
+						stream.getSourceContext(),
+					);
+			}
+		}
+		stream.expect(TokenType.BLOCK_END);
+		return node;
+	},
+
+	/** `{% flush %}` */
+	flush(parser, token) {
+		parser.getStream().expect(TokenType.BLOCK_END);
+		return n(NodeType.Flush, {}, {}, token.getLine());
+	},
+};
+
+/**
+ * Builds a subparse end test for a simple closing tag.
+ *
+ * @param {string} tag The closing tag name (e.g. `endset`).
+ * @returns {(token: Token) => boolean}
+ */
+export function decideTagEnd(tag) {
+	return (token) => token.test(tag);
+}
+
+/**
+ * @param {Token} token
+ * @returns {boolean}
+ */
+function decideForFork(token) {
+	return token.test(['else', 'endfor']);
+}
+
+/**
+ * @param {Token} token
+ * @returns {boolean}
+ */
+function decideIfFork(token) {
+	return token.test(['elseif', 'else', 'endif']);
+}
+
+/**
+ * @param {Token} token
+ * @returns {boolean}
+ */
+function decideGuardFork(token) {
+	return token.test(['else', 'endguard']);
+}
+
+/**
+ * Parses the argument list of `include`-style tags.
+ *
+ * @param {Parser} parser
+ * @returns {[Node|null, boolean, boolean]} `[variables, only, ignoreMissing]`.
+ */
+function parseIncludeArguments(parser) {
+	const stream = parser.getStream();
+	let ignoreMissing = false;
+	if (stream.nextIf(TokenType.NAME, 'ignore')) {
+		stream.expect(TokenType.NAME, 'missing');
+		ignoreMissing = true;
+	}
+	let variables = null;
+	if (stream.nextIf(TokenType.NAME, 'with')) {
+		variables = parser.parseExpression();
+	}
+	let only = false;
+	if (stream.nextIf(TokenType.NAME, 'only')) {
+		only = true;
+	}
+	stream.expect(TokenType.BLOCK_END);
+	return [variables, only, ignoreMissing];
+}
+
+/**
+ * Parses a macro argument definition list.
+ *
+ * @param {Parser} parser
+ * @param {string} macroName
+ * @returns {[Array<[string, Node]>, string|null]} `[arguments, variadicName]`.
+ */
+function parseMacroDefinition(parser, macroName) {
+	const stream = parser.getStream();
+	/** @type {Array<[string, Node]>} */
+	const argumentsList = [];
+	/** @type {string|null} */
+	let variadicName = null;
+	stream.expect(TokenType.OPERATOR, '(', 'A list of arguments must begin with an opening parenthesis');
+	while (!stream.test(TokenType.PUNCTUATION, ')')) {
+		if (argumentsList.length) {
+			stream.expect(TokenType.PUNCTUATION, ',', 'Arguments must be separated by a comma');
+			if (stream.test(TokenType.PUNCTUATION, ')')) {
+				break;
+			}
+		}
+
+		if (stream.nextIf(TokenType.OPERATOR, '...')) {
+			const token = stream.expect(TokenType.NAME, null, 'A variadic argument must be a name');
+			variadicName = String(token.value);
+			if (RESERVED_WORDS.has(variadicName)) {
+				throw new SyntaxError(
+					`You cannot assign a value to "${variadicName}".`,
+					token.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			if (argumentsList.some(([existing]) => existing === variadicName)) {
+				throw new SyntaxError(
+					`The variadic argument "${variadicName}" in macro "${macroName}" cannot have the same name as another argument.`,
+					token.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			if (stream.test(TokenType.OPERATOR, '=')) {
+				throw new SyntaxError(
+					`The variadic argument "${variadicName}" in macro "${macroName}" cannot have a default value.`,
+					token.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			if (stream.nextIf(TokenType.PUNCTUATION, ',') && !stream.test(TokenType.PUNCTUATION, ')')) {
+				throw new SyntaxError(
+					`The variadic argument "${variadicName}" in macro "${macroName}" must be the last one.`,
+					token.getLine(),
+					stream.getSourceContext(),
+				);
+			}
+			break;
+		}
+
+		const token = stream.expect(TokenType.NAME, null, 'An argument must be a name');
+		const name = String(token.value);
+		if (RESERVED_WORDS.has(name)) {
+			throw new SyntaxError(
+				`You cannot assign a value to "${name}".`,
+				token.getLine(),
+				stream.getSourceContext(),
+			);
+		}
+		if (argumentsList.some(([existing]) => existing === name)) {
+			throw new SyntaxError(
+				`Argument "${name}" is defined twice for macro "${macroName}".`,
+				token.getLine(),
+				stream.getSourceContext(),
+			);
+		}
+		if (name === 'varargs') {
+			throw new SyntaxError(
+				`The argument "varargs" in macro "${macroName}" cannot be defined because the variable "varargs" is reserved for arbitrary arguments.`,
+				token.getLine(),
+				stream.getSourceContext(),
+			);
+		}
+		let defaultNode;
+		const equals = stream.nextIf(TokenType.OPERATOR, '=');
+		if (equals) {
+			defaultNode = parser.parseExpression();
+		} else {
+			defaultNode = n(NodeType.Constant, {}, { value: null }, stream.getCurrent().getLine());
+			defaultNode.setAttribute('is_implicit', true);
+		}
+
+		if (!checkConstantExpression(defaultNode)) {
+			throw new SyntaxError(
+				'A default value for an argument must be a constant (a boolean, a string, a number, a sequence, or a mapping).',
+				token.getLine(),
+				stream.getSourceContext(),
+			);
+		}
+		argumentsList.push([name, defaultNode]);
+	}
+	stream.expect(TokenType.PUNCTUATION, ')', 'A list of arguments must be closed by a parenthesis');
+	return [argumentsList, variadicName];
+}
+
+/**
+ * Whether a node is a constant expression.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+function checkConstantExpression(node) {
+	switch (node.type) {
+		case NodeType.Constant:
+		case NodeType.ArrayExpr:
+		case NodeType.Unary:
+			break;
+		default:
+			return false;
+	}
+	if (node.type === NodeType.Unary) {
+		const operator = node.getAttribute('operator');
+		if (operator !== '-' && operator !== '+') {
+			return false;
+		}
+	}
+	for (const child of node) {
+		if (!checkConstantExpression(child)) {
+			return false;
+		}
+	}
+	return true;
+}