Rewriter API (#1396)

~(Sending it again with the new master, so there's no noise about the
API.)~

~I added two examples to the user guides to check their usage, but still
the documentation in general is lacking, or the code ugly. The idea is
to have a quick look and see if this is the kind of API we want to have
for these scenarios.~

~It's expected to fail in CI for lack of documentation.~

EDIT: this PR includes both the Rust and the NPM API.

Supersedes #1395

Author: beta-ziliani

.changeset/green-poets-bow.md

@@ -0,0 +1,5 @@
+---
+"@nomicfoundation/slang": minor
+---
+
+Add a rewriter API, allowing the transformation of CSTs by extending the `BaseRewriter` type, overriding the appropriate methods ([User Guide](https://nomicfoundation.github.io/slang/1.3.0/user-guide/08-examples/06-inject-logging/)).

.cspell.json

@@ -33,6 +33,7 @@
     "structs",
     "tera",
     "ufixed",
+    "unshift",
     "unparse",
     "usize"
   ]

crates/codegen/runtime/cargo/crate/src/runtime/cst/generated/rewriter.rs

@@ -8,6 +8,8 @@ mod edge_label;
 mod lexical_context;
 #[path = "generated/nonterminal_kind.rs"]
 mod nonterminal_kind;
+#[path = "generated/rewriter.rs"]
+mod rewriter;
 #[path = "generated/terminal_kind.rs"]
 mod terminal_kind;
 
@@ -16,6 +18,7 @@ pub(crate) use lexical_context::{IsLexicalContext, LexicalContext, LexicalContex
 pub use metaslang_cst::kinds::TerminalKindExtensions;
 pub(crate) use metaslang_cst::kinds::{EdgeLabelExtensions, NonterminalKindExtensions};
 pub use nonterminal_kind::NonterminalKind;
+pub use rewriter::BaseRewriter;
 pub use terminal_kind::TerminalKind;
 
 // These derives are because default #[derive(...)] on a generic type implements only the trait

crates/codegen/runtime/cargo/crate/src/runtime/cst/mod.rs

@@ -0,0 +1,110 @@
+{%- if rendering_in_stubs -%}
+  /// This is a stub.
+  pub trait BaseRewriter { }
+{%- else -%}
+  use std::rc::Rc;
+  use crate::cst::{Edge, Node, NonterminalKind, NonterminalNode, TerminalKind, TerminalNode};
+
+  /// Trait to rewrite a CST.
+  pub trait BaseRewriter {
+      /// Replaces the `node` with a new node. If the result is `None`, the node is removed from the tree.
+      /// This function is typically the entry point of the rewrite operation.
+      fn rewrite_node(&mut self, node: &Node) -> Option<Node> {
+          match node {
+              Node::Terminal(node) => self.rewrite_terminal_node(node),
+              Node::Nonterminal(node) => self.rewrite_nonterminal_node(node),
+          }
+      }
+
+      /// Rewrites a non-terminal node. Typically called from `rewrite_node`.
+      #[allow(clippy::too_many_lines)]
+      fn rewrite_nonterminal_node(&mut self, node: &Rc<NonterminalNode>) -> Option<Node> {
+        match node.kind {
+          {% for nonterminal in model.kinds.nonterminal_kinds %}
+          NonterminalKind::{{ nonterminal.id }} =>
+            self.rewrite_{{- nonterminal.id | snake_case -}}(node),
+          {% endfor %}
+        }
+      }
+
+      /// Rewrites a terminal node. Typically called from `rewrite_node`.
+      #[allow(clippy::too_many_lines)]
+      fn rewrite_terminal_node(&mut self, node: &Rc<TerminalNode>) -> Option<Node> {
+        match node.kind {
+          {% for terminal in model.kinds.terminal_kinds %}
+          TerminalKind::{{ terminal.id }} =>
+            self.rewrite_{{- terminal.id | snake_case -}}(node),
+          {% endfor %}
+          TerminalKind::UNRECOGNIZED =>
+            self.rewrite_unrecognized(node),
+
+          TerminalKind::MISSING =>
+            self.rewrite_missing(node),
+        }
+      }
+
+      {% for nonterminal in model.kinds.nonterminal_kinds %}     
+      /// Rewrites a `{{- nonterminal.id -}}` node, recursively traversing the children (unless overriden).
+      fn rewrite_{{- nonterminal.id | snake_case -}}(&mut self, node: &Rc<NonterminalNode>) -> Option<Node> {
+        Some(self.rewrite_children(node))
+      }
+      {% endfor %}
+
+      {% for terminal in model.kinds.terminal_kinds %}     
+        /// Rewrites a `{{- terminal.id -}}` node.
+        fn rewrite_{{- terminal.id | snake_case -}}(&mut self, node: &Rc<TerminalNode>) -> Option<Node> {
+          Some(Node::Terminal(Rc::clone(node)))
+        }
+      {% endfor %}
+      
+      /// Rewrites an `Unrecognized` node.
+      fn rewrite_unrecognized(&mut self, node: &Rc<TerminalNode>) -> Option<Node> {
+        Some(Node::Terminal(Rc::clone(node)))
+      }
+    
+      /// Rewrites a `Missing` node.
+      fn rewrite_missing(&mut self, node: &Rc<TerminalNode>) -> Option<Node> {
+        Some(Node::Terminal(Rc::clone(node)))
+      }
+  
+      /// Rewrites all the children of a given non-terminal node.
+      fn rewrite_children(&mut self, node: &Rc<NonterminalNode>) -> Node {
+          let mut new_children: Option<Vec<Edge>> = None;
+
+          for (index, child) in node.children.iter().enumerate() {
+              if let Some(new_child_node) = self.rewrite_node(&child.node) {
+                  if new_child_node.id() == child.node.id() {
+                      if let Some(ref mut new_children) = new_children {
+                          new_children.push(Edge {
+                              label: child.label,
+                              node: new_child_node,
+                          });
+                      }
+                  } else {
+                      // node has changed, produce new edge
+                      let edge = Edge {
+                          label: child.label,
+                          node: new_child_node,
+                      };
+                      if new_children.is_none() {
+                          new_children = Some(node.children[..index].to_vec());
+                      }
+                      new_children.as_mut().unwrap().push(edge);
+                  }
+              } else {
+                  // node was removed. if `new_children` is set, just skip this one
+                  // otherwise, copy the first ones from `children` (but not the last)
+                  if new_children.is_none() {
+                      new_children = Some(node.children[..index].to_vec());
+                  }
+              }
+          }
+
+          if let Some(nc) = new_children {
+              Node::nonterminal(node.kind, nc)
+          } else {
+              Node::Nonterminal(Rc::clone(node))
+          }
+      }
+  }
+{%- endif -%}

crates/codegen/runtime/cargo/crate/src/runtime/cst/rewriter.rs.jinja2

@@ -2,6 +2,7 @@ import * as wasm from "../../../wasm/index.mjs";
 
 export * from "./assertions.mjs";
 export * from "./extensions.mjs";
+export * from "./generated/rewriter.mjs";
 
 /** {@inheritDoc wasm.cst.NonterminalKind} */
 export const NonterminalKind = wasm.cst.NonterminalKind;

crates/codegen/runtime/npm/package/src/runtime/cst/generated/rewriter.mts

@@ -0,0 +1,109 @@
+{%- if rendering_in_stubs -%}
+  /** This is a stub. */
+  export abstract class BaseRewriter { }
+{%- else -%} 
+  import { NonterminalKind, NonterminalNode, Node, NodeType, TerminalNode, TerminalKind, Edge } from "../index.mjs";
+
+  /** Abstract class to rewrite a CST. */
+  export abstract class BaseRewriter {
+    
+    /** Replaces the `node` with a new node. If the result is `undefined`, the node is removed from the tree.
+        This function typically the entry point of the rewrite operation. */
+    public rewriteNode(node: Node): Node | undefined {
+      switch (node.type) {
+        case NodeType.TerminalNode:
+          return this.rewriteTerminalNode(node);
+        case NodeType.NonterminalNode:
+          return this.rewriteNonterminalNode(node);
+      }
+    }
+
+    /** Rewrites a non-terminal node. Typically called from `rewriteNode`. */
+    public rewriteNonterminalNode(node: NonterminalNode): Node | undefined {
+      switch (node.kind) {
+        {% for nonterminal in model.kinds.nonterminal_kinds %}
+        case NonterminalKind.{{ nonterminal.id }}:
+          return this.rewrite{{- nonterminal.id -}}(node);
+        {% endfor %}
+      }
+    }
+
+    /** Rewrites a terminal node. Typically called from `rewriteNode`. */
+    public rewriteTerminalNode(node: TerminalNode): Node | undefined {
+      switch (node.kind) {
+        {% for terminal in model.kinds.terminal_kinds %}
+        case TerminalKind.{{ terminal.id }}:
+          return this.rewrite{{- terminal.id -}}(node);
+        {% endfor %}
+        case TerminalKind.Unrecognized:
+          return this.rewriteUnrecognized(node);
+        case TerminalKind.Missing:
+          return this.rewriteMissing(node);
+      }
+    }
+
+    {% for nonterminal in model.kinds.nonterminal_kinds %}     
+      /** @virtual Rewrites a `{{- nonterminal.id -}}` node, recursively traversing the children (unless overriden). */
+      public rewrite{{- nonterminal.id -}}(node: NonterminalNode): Node | undefined {
+        return this.rewriteChildren(node);
+      }
+    {% endfor %}
+    
+    {% for terminal in model.kinds.terminal_kinds %}     
+      /** @virtual Rewrites a `{{- terminal.id -}}` node. */
+      public rewrite{{- terminal.id -}}(node: TerminalNode): Node | undefined {
+        return node;
+      }
+    {% endfor %}
+    
+    /** @virtual Rewrites an `Unrecognized` node. */
+    public rewriteUnrecognized(node: TerminalNode): Node | undefined {
+      return node;
+    }
+  
+    /** @virtual Rewrites a `Missing` node. */
+    public rewriteMissing(node: TerminalNode): Node | undefined {
+      return node;
+    }
+  
+    /** Rewrites all the children of a given non-terminal node. */
+    protected rewriteChildren(node: NonterminalNode): NonterminalNode {
+      let newChildren: Array<Edge> | undefined = undefined;
+      const children = node.children();
+
+      children.forEach((child, index) => {
+        const newChild = this.rewriteNode(child.node);
+        if (newChild == undefined) {
+          // node was removed. if `newChildren` is set, just skip this one
+          // otherwise, copy the first ones from `children` (but the last)
+          if (newChildren == undefined) {
+            newChildren = children.slice(0, index);
+          }
+        } else if (newChild.id != child.node.id) {
+          // node has changed, produce new edge
+          let edge;
+          switch (newChild.type) {
+            case NodeType.TerminalNode:
+              edge = Edge.createWithTerminal(child.label, newChild);
+              break;
+            case NodeType.NonterminalNode:
+              edge = Edge.createWithNonterminal(child.label, newChild);
+              break;
+          }
+
+          if (newChildren == undefined) {
+            newChildren = children.slice(0, index);
+          }
+          newChildren.push(edge);
+        } else if (newChildren != undefined) {
+          newChildren.push(child);
+        }
+      });
+      if (newChildren != undefined) {
+        return NonterminalNode.create(node.kind, newChildren);
+      } else {
+        return node;
+      }
+    }
+  }
+{%- endif -%}