Coverage for src/renaissance/syntax_tree/ast_node.py: 94%
155 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
1# Copyright (C) 2024-2026 TNO
2#
3# Licensed under the terms specified in the LICENSE file in the root directory
4# of this repository, also available at:
5# https://github.com/TNO/Renaissance.Py/blob/main/LICENSE
7"""AI: Abstract base class for AST node implementations, with the shared traversal and rewrite protocol."""
9from __future__ import annotations
11import re
12import sys
13from abc import ABC, abstractmethod
14from collections.abc import Callable, Sequence
15from enum import Enum
16from pathlib import Path
17from typing import Any, Self
19from renaissance.syntax_tree.node_protocol import NodeProtocol
20from renaissance.syntax_tree.semantic_kind import SemanticKind
21from renaissance.utils.ast_utils import format_node, next_sibling, preceding_sibling, process_node
22from renaissance.utils.text_utils import TextUtils
25# enum with ABORT, CONTINUE and SKIP
26class VisitorResult(Enum):
27 """AI: Signal how an AST traversal should continue after visiting a node."""
29 ABORT = 0
30 CONTINUE = 1
31 SKIP = 2
34class ASTReference[NodeProtocolT: NodeProtocol]:
35 """Reference between two AST nodes, with its kind and additional properties."""
37 def __init__(self, ast_node: NodeProtocolT, ref_kind: str, properties: dict[str, Any]) -> None:
38 """Initialise the reference.
40 Args:
41 ast_node: Node at the other end of the reference.
42 ref_kind: Kind of the reference.
43 properties: Additional properties of the reference.
45 """
46 self._node = ast_node
47 self._ref_kind = ref_kind
48 self._properties = properties
50 @property
51 def node(self) -> NodeProtocolT:
52 """Return the node at the other end of the reference."""
53 return self._node
55 @property
56 def ref_kind(self) -> str:
57 """AI: Return the kind of this reference."""
58 return self._ref_kind
60 @property
61 def properties(self) -> dict[str, Any]:
62 """AI: Return this reference's additional properties."""
63 return self._properties
66# To make usage of the concrete class methods easier, ASTNode MUST NOT have ABSTRACT public classes!!
67class ASTNode[NodeT, TranslationUnitT](ABC):
68 """The base class to represent an AST node.
70 It is an abstract class that should be inherited by concrete classes that represent specific AST nodes.
71 """
73 cache: dict[str, bytes] = {}
74 parser_kind: str
75 semantic_kind: SemanticKind
77 def __init__(self, root: Self) -> None:
78 """AI: Initialize a new AST node rooted at the given translation-unit-level node."""
79 super().__init__()
80 self._parent = None
81 self._children: list[Self] = []
82 self.show_props: bool = False
83 self.translation_unit: TranslationUnitT | None = None
84 self._kind: str = ""
85 self._length: int = 0
86 self._offset: int = 0
87 self._filename: str = ""
88 self.root: Self = root
89 self._properties = {}
90 self._name = ""
91 self.node: NodeT | None = None
92 self.indent = ""
94 def __repr__(self) -> str:
95 """AI: Return the formatted node representation."""
96 return format_node(self)
98 def is_part_of_translation_unit(self) -> bool:
99 """AI: Return whether this node's filename matches its root node's filename."""
100 return self.filename == self.root.filename
102 @property
103 def signature(self) -> str:
104 """AI: Return this node's source code text, or an empty string if it has no filename or span."""
105 start = self.offset
106 end = self.extended_end_offset
107 if start == end:
108 return ""
109 file = self.filename
110 if not file:
111 return ""
112 return self.content(start, end)
114 @property
115 def text(self) -> str:
116 """AI: Return this node's signature text shifted left to remove its leading indent."""
117 return TextUtils.shift_left(self.signature, len(self.indent), start_line=1)
119 def content(self, start: int, end: int) -> str:
120 """AI: Return the decoded source text between start and end offsets in the root's file content."""
121 content = self.root.binary_file_content()
122 # TODO: see docs/developer/architecture/position-consistency.md - decodes with the host encoding, not the adapter's.
123 return str(content[start:end], sys.getfilesystemencoding())
125 def binary_file_content(self, file_path: str | None = None) -> bytes:
126 """AI: Return the raw bytes of file_path (or the root's filename), reading and caching it on first access."""
127 if not file_path:
128 file_path = self.root.filename
129 try:
130 return ASTNode.cache[file_path]
131 except KeyError:
132 with Path(file_path).open("rb") as f:
133 content = f.read()
134 ASTNode.cache[file_path] = content
135 return content
137 @property
138 def preceding_sibling(self) -> Self | None:
139 """AI: Return the sibling node immediately preceding this one, or None."""
140 return preceding_sibling(self)
142 @property
143 def next_sibling(self) -> Self | None:
144 """AI: Return the sibling node immediately following this one, or None."""
145 return next_sibling(self)
147 @property
148 @abstractmethod
149 def references(self) -> Sequence[ASTReference[ASTNode[NodeT, TranslationUnitT]]]:
150 """AI: Return the references that this node points to."""
152 @property
153 @abstractmethod
154 def referenced_by(self) -> Sequence[ASTReference[ASTNode[NodeT, TranslationUnitT]]]:
155 """AI: Return the references that point to this node."""
157 def get_ancestor(self, kind: str | re.Pattern[str]) -> Self | None:
158 """AI: Return the nearest ancestor node whose kind matches the given kind pattern, or None."""
159 pattern = re.compile(kind, re.IGNORECASE) if isinstance(kind, str) else kind
160 parent = self.parent
161 if not parent:
162 return None
163 if pattern.match(parent.kind):
164 return parent
165 return parent.get_ancestor(pattern)
167 def is_descendant_of(self, node: Self) -> bool:
168 """AI: Return whether this node is a descendant of node."""
169 return node.is_ancestor_of(self)
171 def is_ancestor_of(self, descendant: Self) -> bool:
172 """AI: Return whether this node is an ancestor of descendant."""
173 parent: Self | None = descendant.parent
174 if parent == self:
175 return True
176 if not parent:
177 return False
178 return self.is_ancestor_of(parent)
180 @staticmethod
181 @abstractmethod
182 def load(file_path: Path, extra_args: Sequence[str], working_dir: Path) -> ASTNode[NodeT, TranslationUnitT]:
183 """AI: Parse the source file at file_path into an AST node."""
185 @staticmethod
186 @abstractmethod
187 def load_from_text(text: str, file_name: str, extra_args: Sequence[str], working_dir: Path) -> ASTNode[NodeT, TranslationUnitT]:
188 """AI: Parse source text (attributed to file_name) into an AST node."""
190 @property
191 def name(self) -> str:
192 """AI: Return this node's name."""
193 return self._name
195 @property
196 def filename(self) -> str:
197 """AI: Return this node's source file name."""
198 return self._filename
200 # TODO: Is this the best name: offset, start_offset, begin_offset, ...?
201 # TODO: Should offset return a slice object, https://docs.python.org/3/library/functions.html#slice, instead of an int?
202 # That would make it easier to get the text segment.
203 @property
204 def offset(self) -> int:
205 """AI: Return the character offset where this node begins in the source text."""
206 return self._offset
208 @property
209 def end_offset(self) -> int:
210 """AI: Return the character offset where this node ends in the source text."""
211 return self.offset + self.length
213 # TODO: Is this the really best solution to ensure that the modified code has the proper layout?
214 @property
215 @abstractmethod
216 def extended_end_offset(self) -> int:
217 """AI: Return the character offset where this node's extended span (including trailing layout) ends."""
219 @property
220 def length(self) -> int:
221 """AI: Return the length in characters of this node's source text."""
222 return self._length
224 @property
225 def kind(self) -> str:
226 """AI: Return this node's parser kind."""
227 return self._kind
229 @abstractmethod
230 def matches_kind(self, node: Self) -> bool:
231 """AI: Return whether node has the same kind as this node."""
233 # TODO: What is the best name: properties, attributes, syntax_attributes, ...?
234 @property
235 def properties(self) -> dict[str, int | str]: # TODO: Is int | str really sufficient? Shouldn't it be Any?
236 """AI: Return this node's syntax properties."""
237 return self._properties
239 @property
240 def parent(self) -> Self | None:
241 """AI: Return this node's parent node, or None if it has none."""
242 return self._parent
244 @property
245 @abstractmethod
246 def is_statement(self) -> bool:
247 """AI: Return whether this node represents a statement."""
249 @property
250 def children(self) -> list[Self]:
251 """AI: Return this node's child nodes."""
252 return self._children
254 def process(self, function: Callable[[Self], None]) -> None:
255 """AI: Apply function to this node and recursively to all of its descendants."""
256 process_node(self, function)
258 def accept(self, function: Callable[[Self], VisitorResult]) -> None:
259 """Accept a visitor function and apply it to the current node and its children.
261 Args:
262 function (Callable[[Self], VisitorResult]): A function that takes an ASTNode as an argument and returns a VisitorResult.
264 """
265 if function(self) == VisitorResult.CONTINUE:
266 for child in self.children:
267 child.accept(function)