Merge branch 'master' into feat/better-issues

Author: alessiostalla

CHANGELOG.md

@@ -9,6 +9,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Issue`'s messages are capitalized.
 - Parsing `Issue`s' position uses the token's length.
 
+## [1.6.30] – 2024-09-30
+
+### Added
+- `Node.transformChildren` to run a function on all the children of a Node
+- `Node.replaceWith` to replace a Node with another
+
+### Changed
+- Aligned Token Categories with Kolasu
+- Increased code coverage
+
 ## [1.6.29] – 2024-07-09
 
 ### Fixed

package.json

@@ -3,7 +3,7 @@
 	"description": "AST building blocks for TypeScript/JavaScript, part of the *lasu family, with optional integrations with ANTLR4 and Ecore.",
 	"author": "Strumenta s.r.l.",
 	"publisher": "strumenta",
-	"version": "1.6.29",
+	"version": "1.6.30",
 	"license": "Apache-2.0",
 	"keywords": [
 		"antlr",

src/model/model.ts

@@ -340,6 +340,57 @@ export abstract class Node extends Origin implements Destination {
         return this;
     }
 
+    /**
+     * Replace the current Node with another Node
+     *
+     * @throws Error - if this.parent === undefined
+     */
+    replaceWith(other: Node): void {
+        if (!this.parent) {
+            throw new Error("Cannot replace a Node that has no parent")
+        }
+
+        this.parent.transformChildren(node => node === this ? other : node);
+    }
+
+    /**
+     * Apply the given `operation` function to
+     * all of the Node's children.
+     *
+     * It's possible to use both pure functions,
+     * to replace the nodes, and functions that mutate
+     * the nodes in-place.
+     */
+    transformChildren(operation: (node: Node) => Node): void {
+        const nodesNames = this.getChildNames();
+
+        nodesNames.forEach(nodeName => {
+            const propertyValue = this[nodeName];
+            if (propertyValue instanceof Node) {
+                const newNode = operation(propertyValue);
+                /*
+                 * Identity check;
+                 * If the variable is pointing to the same object,
+                 * the operation changed the Node in-place.
+                 */
+                if (newNode !== propertyValue) {
+                    this.setChild(nodeName, newNode);
+                }
+
+            } else if (Array.isArray(propertyValue)) {
+                propertyValue.forEach((element, index) => {
+                    if (element instanceof Node) {
+                        const newNode = operation(element);
+                        // Another identity check
+                        if (newNode !== element) {
+                            (propertyValue as Node[])[index] = newNode;
+                        }
+                    }
+                });
+            }
+        });
+    }
+
     withOrigin(origin?: Origin): this {
         this.origin = origin;
         return this;

src/parsing/parsing.ts

@@ -10,7 +10,12 @@ export enum TokenCategory {
     KEYWORD = "Keyword",
     NUMERIC_LITERAL = "Numeric literal",
     STRING_LITERAL = "String literal",
-    PLAIN_TEXT = "Plain text"
+    OTHER_LITERAL = "Other literal",
+    PLAIN_TEXT = "Plain text",
+    WHITESPACE = "Whitespace",
+    IDENTIFIER = "Identifier",
+    PUNCTUATION = "Punctuation",
+    OPERATOR = "Operator",
 }
 
 /**

tests/nodes/nodes.test.ts

@@ -0,0 +1,64 @@
+import { expect } from "chai";
+import { Box, SomeNode, SomeNodeInPackage } from "../nodes";
+
+describe('Node.transformChildren', () => {
+    let childNode1: SomeNode;
+    let childNode2: SomeNode;
+    let boxNode: Box;
+
+    beforeEach(() => {
+        childNode1 = new SomeNode("Child1");
+        childNode2 = new SomeNode("Child2");
+
+        boxNode = new Box("BoxNode", [childNode1, childNode2]);
+    })
+
+    it('should apply in-place transformation to each child node', () => {
+        const inPlaceTransformation = (node: SomeNode): SomeNode => {
+            node.a = node.a?.toUpperCase();
+            return node;
+        };
+
+        boxNode.transformChildren(inPlaceTransformation);
+
+        expect(boxNode.contents[0]["a"]).to.eq("CHILD1");
+        expect(boxNode.contents[0]).to.eq(childNode1);
+        expect(boxNode.contents[1]["a"]).to.eq("CHILD2");
+        expect(boxNode.contents[1]).to.eq(childNode2);
+    });
+
+    it('should replace children nodes when used with pure-functions', () => {
+        const replaceTransformation = (node: SomeNode): SomeNode => {
+            return new SomeNode(node.a?.toUpperCase())
+        };
+
+        boxNode.transformChildren(replaceTransformation);
+
+        expect(boxNode.contents[0]["a"]).to.eq("CHILD1");
+        expect(boxNode.contents[0]).to.not.eq(childNode1);
+        expect(boxNode.contents[1]["a"]).to.eq("CHILD2");
+        expect(boxNode.contents[1]).to.not.eq(childNode2);
+    });
+});
+
+describe('Node.replaceWith', () => {
+    it('should replace a child node with another node', () => {
+        const childNode1 = new SomeNode("Child1");
+        const childNode2 = new SomeNode("Child2");
+
+        const parentNode = new SomeNodeInPackage("ParentNode");
+
+        parentNode.setChild('someNode', childNode1);
+        expect(parentNode.getChildren('someNode')).to.eql([childNode1]);
+        childNode1.replaceWith(childNode2);
+        expect(parentNode.getChildren('someNode')).to.eql([childNode2]);
+    });
+
+    it('should throw error if parent is not set', () => {
+        const childNode1 = new SomeNode("Child1");
+
+        const nodeWithoutParent = new SomeNode("NodeWithoutParent");
+        expect(() => nodeWithoutParent.replaceWith(childNode1)).to.throw('Cannot replace a Node that has no parent');
+    });
+});
+