@mrhenry/twig-parser 0.1.0

package/src/index.js

@@ -0,0 +1,19 @@
+// @ts-check
+/**
+ * Public API of the `@mrhenry/twig-parser` package.
+ *
+ * @module twig-parser
+ */
+
+export { Node, NodeType, n } from './node.js';
+export { printNode } from './printer.js';
+export { ArrayExpression } from './array-expression.js';
+export { ExpressionParser, BINARY_INFORMATION, PREFIX_OPERATORS, POSTFIX_OPERATORS } from './expression-parser.js';
+export { Parser, TAG_PARSERS, BLOCK_TAGS, INLINE_TAGS, TAG_END_NAMES, isBlankText, decideTagEnd } from './parser.js';
+export {
+	CORE_FILTER_NAMES,
+	CORE_FUNCTION_NAMES,
+	CORE_TEST_NAMES,
+	PARSER_CALLABLE_FUNCTIONS,
+	ONE_MANDATORY_ARGUMENT_TESTS,
+} from './callables.js';

package/src/node.js

@@ -0,0 +1,474 @@
+// @ts-check
+/**
+ * The AST node model for the Twig parser.
+ *
+ * @module twig-parser
+ */
+
+import { printNode } from './printer.js';
+
+/**
+ * @typedef {import('@mrhenry/twig-tokenizer').Source} Source
+ */
+
+/**
+ * A single AST node.
+ *
+ * Nodes mirror the reference implementation's `Twig\Node\Node`: they carry
+ * child nodes (indexed by name) and a flat set of attributes. The {@link Node#type}
+ * property discriminates between node kinds (see `NodeType`).
+ *
+ * Children may be nodes, arrays of nodes, or other metadata values depending on
+ * the node kind; {@link Node#getNode} and {@link Node#getNodes} provide typed
+ * accessors for the node-valued children.
+ */
+export class Node {
+	/**
+	 * @param {string} type The node kind (one of {@link NodeType}).
+	 * @param {Record<string, unknown>} [children] Named children.
+	 * @param {Record<string, unknown>} [attributes] Node attributes.
+	 * @param {number} [lineNumber] The template line number.
+	 * @param {string|null} [tag] The originating tag name.
+	 */
+	constructor(type, children = {}, attributes = {}, lineNumber = 0, tag = null) {
+		/** @type {string} */
+		this.type = type;
+		/** @type {Record<string, unknown>} */
+		this.children = children;
+		/** @type {Record<string, unknown>} */
+		this.attributes = attributes;
+		/** @type {number} */
+		this.templateLine = lineNumber;
+		/** @type {string|null} */
+		this.tag = tag;
+		/** @type {Source|null} */
+		this.sourceContext = null;
+		/** @type {boolean} */
+		this.explicitParentheses = false;
+
+		/** Exact source text covered by this node (null when not tied to source). */
+		/** @type {string|null} */
+		this.raw = null;
+		/** Trivia preceding this node's source span. */
+		/** @type {string} */
+		this.leading = '';
+		/** Absolute source offset where the node's span starts. */
+		/** @type {number} */
+		this.rawStart = 0;
+		/** Absolute source offset just past the node's span. */
+		/** @type {number} */
+		this.rawEnd = 0;
+		/** Signature captured when the node was parsed, or null. */
+		/** @type {string|null} */
+		this.originalSignature = null;
+		/** Signature computed during the latest serialization pass. */
+		/** @type {string|null} */
+		this.currentSignature = null;
+	}
+
+	/**
+	 * @param {string} key
+	 * @returns {Node|null} The child node, or null when the child is absent or not a node.
+	 */
+	getNode(key) {
+		const child = this.children[key];
+		if (Array.isArray(child)) {
+			const first = child[0];
+			return first instanceof Node ? first : null;
+		}
+		return child instanceof Node ? child : null;
+	}
+
+	/**
+	 * @param {string} key
+	 * @returns {Node[]} The node-valued elements of a list child, or [].
+	 */
+	getNodes(key) {
+		const child = this.children[key];
+		if (Array.isArray(child)) {
+			return child.filter((item) => item instanceof Node);
+		}
+		return [];
+	}
+
+	/**
+	 * @param {string} key
+	 * @param {unknown} node
+	 */
+	setNode(key, node) {
+		this.children[key] = node;
+	}
+
+	/**
+	 * @param {string} key
+	 * @returns {boolean} Whether a node-valued child exists.
+	 */
+	hasNode(key) {
+		const child = this.children[key];
+		return child instanceof Node || (Array.isArray(child) && child.some((item) => item instanceof Node));
+	}
+
+	/**
+	 * @param {string} key
+	 */
+	removeNode(key) {
+		delete this.children[key];
+	}
+
+	/**
+	 * @template {unknown} [T=unknown]
+	 * @param {string} key
+	 * @returns {T|undefined} The attribute value.
+	 */
+	getAttribute(key) {
+		return /** @type {T|undefined} */ (this.attributes[key]);
+	}
+
+	/**
+	 * @template {unknown} [T=unknown]
+	 * @param {string} key
+	 * @param {T} [defaultValue]
+	 * @returns {T|undefined} The attribute value or the default.
+	 */
+	getAttributeOr(key, defaultValue) {
+		const value = this.attributes[key];
+		return value === undefined ? defaultValue : /** @type {T} */ (value);
+	}
+
+	/**
+	 * @param {string} key
+	 * @param {unknown} value
+	 */
+	setAttribute(key, value) {
+		this.attributes[key] = value;
+	}
+
+	/**
+	 * @returns {number} The template line number.
+	 */
+	getTemplateLine() {
+		return this.templateLine;
+	}
+
+	/**
+	 * @returns {string|null} The originating tag name.
+	 */
+	getNodeTag() {
+		return this.tag;
+	}
+
+	/**
+	 * @param {string} tag
+	 */
+	setNodeTag(tag) {
+		this.tag = tag;
+	}
+
+	/**
+	 * @returns {Source|null} The template source context.
+	 */
+	getSourceContext() {
+		return this.sourceContext;
+	}
+
+	/**
+	 * @param {Source|null} source
+	 */
+	setSourceContext(source) {
+		this.sourceContext = source;
+	}
+
+	/**
+	 * Marks the node as wrapped in explicit parentheses (affects precedence
+	 * deprecations in the reference implementation).
+	 */
+	setExplicitParentheses() {
+		this.explicitParentheses = true;
+		return this;
+	}
+
+	/**
+	 * @returns {boolean} Whether the node has explicit parentheses.
+	 */
+	hasExplicitParentheses() {
+		return this.explicitParentheses;
+	}
+
+	/**
+	 * Serializes this node (and its subtree) back to Twig source.
+	 *
+	 * When nothing in the subtree was mutated the exact source span captured at
+	 * parse time is returned (lossless). When the subtree was mutated, the node
+	 * is re-printed from its current contents, reusing the retained source of
+	 * any unchanged descendants.
+	 *
+	 * @returns {string} The serialized Twig source.
+	 */
+	serialize() {
+		refreshSignatures(this);
+		return this._serialize();
+	}
+
+	/**
+	 * Serializes using the signatures computed by the most recent
+	 * {@link refreshSignatures} pass.
+	 *
+	 * @returns {string} The serialized Twig source.
+	 */
+	_serialize() {
+		if (this.raw !== null && this.currentSignature === this.originalSignature) {
+			return this.leading + this.raw;
+		}
+		return printNode(this);
+	}
+
+	/**
+	 * @returns {string} The leading trivia of this node.
+	 */
+	getLeading() {
+		return this.leading;
+	}
+
+	/**
+	 * @returns {string|null} The retained source text of this node.
+	 */
+	getRaw() {
+		return this.raw;
+	}
+
+	/**
+	 * Iterates over all direct child nodes (flattening list children and
+	 * skipping non-node metadata values).
+	 *
+	 * @returns {Generator<Node>}
+	 */
+	*[Symbol.iterator]() {
+		for (const key of Object.keys(this.children)) {
+			const child = this.children[key];
+			if (child === null || child === undefined) {
+				continue;
+			}
+			if (Array.isArray(child)) {
+				for (const item of child) {
+					if (item instanceof Node) {
+						yield item;
+					}
+				}
+			} else if (child instanceof Node) {
+				yield child;
+			}
+		}
+	}
+
+	/**
+	 * Recursively visits this node and all descendants.
+	 *
+	 * @param {(node: Node) => void} callback Visitor callback.
+	 */
+	traverse(callback) {
+		callback(this);
+		for (const child of this) {
+			child.traverse(callback);
+		}
+	}
+}
+
+/**
+ * Node kinds produced by the parser.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const NodeType = {
+	// module / structure
+	Module: 'module',
+	Body: 'body',
+	Nodes: 'nodes',
+	Text: 'text',
+	Print: 'print',
+	Empty: 'empty',
+
+	// expressions
+	Constant: 'constant',
+	ContextVariable: 'context_variable',
+	AssignContextVariable: 'assign_context_variable',
+	LocalVariable: 'local_variable',
+	ArrayExpr: 'array',
+	ListExpr: 'list',
+	GetAttr: 'get_attr',
+	MacroReference: 'macro_reference',
+	Filter: 'filter',
+	FunctionCall: 'function',
+	Test: 'test',
+	ArrowFunction: 'arrow_function',
+	Binary: 'binary',
+	Unary: 'unary',
+	SetBinary: 'set',
+	SequenceDestructuringSet: 'sequence_destructuring_set',
+	ObjectDestructuringSet: 'object_destructuring_set',
+	Conditional: 'conditional',
+
+	// tags
+	Block: 'block',
+	BlockReference: 'block_reference',
+	For: 'for',
+	If: 'if',
+	Set: 'set',
+	Include: 'include',
+	Import: 'import',
+	Macro: 'macro',
+	MacroDeclaration: 'macro_declaration',
+	Macros: 'macros',
+	With: 'with',
+	Do: 'do',
+	Extends: 'extends',
+	Use: 'use',
+	Embed: 'embed',
+	AutoEscape: 'autoescape',
+	Apply: 'apply',
+	Sandbox: 'sandbox',
+	Deprecated: 'deprecated',
+	Flush: 'flush',
+	Guard: 'guard',
+	Types: 'types',
+	CheckSecurity: 'check_security',
+};
+
+/**
+ * Creates a node.
+ *
+ * @param {string} type The node kind.
+ * @param {Record<string, unknown>} [children] Named children.
+ * @param {Record<string, unknown>} [attributes] Attributes.
+ * @param {number} [lineNumber] Line number.
+ * @param {string|null} [tag] Tag name.
+ * @returns {Node} The created node.
+ */
+export function n(type, children = {}, attributes = {}, lineNumber = 0, tag = null) {
+	return new Node(type, children, attributes, lineNumber, tag);
+}
+
+/**
+ * A tiny FNV-1a hash, used to compare node subtrees cheaply.
+ *
+ * @param {string} text
+ * @returns {string} A base-36 digest.
+ */
+function fnv1a(text) {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < text.length; i += 1) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash.toString(36);
+}
+
+/**
+ * Computes a content signature for a value contained in a node (children or
+ * attributes). Nodes are folded in via their own content signature.
+ *
+ * @param {unknown} value
+ * @param {WeakMap<Node, string>} cache
+ * @returns {string}
+ */
+function valueSignature(value, cache) {
+	if (value instanceof Node) {
+		return `N${computeSignature(value, cache)}`;
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((item) => valueSignature(item, cache)).join(',')}]`;
+	}
+	if (value !== null && typeof value === 'object') {
+		const object = /** @type {Record<string, unknown>} */ (value);
+		return `{${Object.keys(object)
+			.sort()
+			.map((key) => `${key}:${valueSignature(object[key], cache)}`)
+			.join(',')}}`;
+	}
+	return String(value);
+}
+
+/**
+ * Computes the content signature of a node, memoised in `cache`.
+ *
+ * @param {Node} node
+ * @param {WeakMap<Node, string>} cache
+ * @returns {string}
+ */
+export function computeSignature(node, cache) {
+	const cached = cache.get(node);
+	if (cached !== undefined) {
+		return cached;
+	}
+	let material = `${node.type}\u0000${node.tag ?? ''}\u0000${node.explicitParentheses}`;
+	for (const key of Object.keys(node.attributes).sort()) {
+		material += `\u0001${key}=${valueSignature(node.attributes[key], cache)}`;
+	}
+	for (const key of Object.keys(node.children).sort()) {
+		material += `\u0002${key}=${valueSignature(node.children[key], cache)}`;
+	}
+	const signature = fnv1a(material);
+	cache.set(node, signature);
+	return signature;
+}
+
+/**
+ * Visits every node reachable from `node` through children and attributes.
+ *
+ * @param {Node} node
+ * @param {(node: Node) => void} callback
+ * @param {WeakSet<Node>} [seen]
+ */
+function walkNodes(node, callback, seen = new WeakSet()) {
+	if (seen.has(node)) {
+		return;
+	}
+	seen.add(node);
+	callback(node);
+	/** @param {unknown} value */
+	const visit = (value) => {
+		if (value instanceof Node) {
+			walkNodes(value, callback, seen);
+		} else if (Array.isArray(value)) {
+			for (const item of value) {
+				visit(item);
+			}
+		} else if (value !== null && typeof value === 'object') {
+			for (const item of Object.values(/** @type {Record<string, unknown>} */ (value))) {
+				visit(item);
+			}
+		}
+	};
+	for (const value of Object.values(node.children)) {
+		visit(value);
+	}
+	for (const value of Object.values(node.attributes)) {
+		visit(value);
+	}
+}
+
+/**
+ * Captures the original content signature of every node in a tree.
+ *
+ * @param {Node} root
+ */
+export function captureSignatures(root) {
+	const cache = new WeakMap();
+	computeSignature(root, cache);
+	walkNodes(root, (node) => {
+		node.originalSignature = cache.get(node) ?? null;
+	});
+}
+
+/**
+ * Recomputes the current content signature of every node in a tree.
+ *
+ * @param {Node} root
+ */
+export function refreshSignatures(root) {
+	const cache = new WeakMap();
+	computeSignature(root, cache);
+	walkNodes(root, (node) => {
+		node.currentSignature = cache.get(node) ?? null;
+	});
+}