python-library-ralf-model 0.1.2__tar.gz → 0.1.3__tar.gz

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-ralf-model
-Version: 0.1.2
+Version: 0.1.3
 Requires-Python: >=3.10
 Requires-Dist: pydantic<3,>=2.0
 Description-Content-Type: text/markdown

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-ralf-model"
-version = "0.1.2"
+version = "0.1.3"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/ralf_model/__init__.py

@@ -4,7 +4,7 @@ from ralf_model.abc import AbstractRalfBlock, AbstractRalfField, AbstractRalfReg
 from ralf_model.emit import dump_ralf
 from ralf_model.errors import RalfError, RalfParseError, RalfSourceError
 from ralf_model.io import dump_ralf_file, dumps_ralf, load_ralf_file, loads_ralf
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 from ralf_model.parse import normalize_ralf_whitespace, parse_ralf
 from ralf_model.source_expand import expand_ralf_sources, resolve_source_path
 
@@ -16,6 +16,7 @@ __all__ = [
     "FieldNode",
     "RalfDocument",
     "RegisterNode",
+    "SystemNode",
     "RalfError",
     "RalfParseError",
     "RalfSourceError",

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/ralf_model/emit.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 
 
 def _fmt_at_int(v: int) -> str:
@@ -58,6 +58,35 @@ def _emit_block_open_line(b: BlockNode, indent: str) -> str:
     return line
 
 
+def _emit_system_open_line(s: SystemNode, indent: str) -> str:
+    line = f"{indent}system {s.name}"
+    if s.rhs_head is not None:
+        line += f" = {s.rhs_head}"
+        if s.rhs_paren_path is not None:
+            line += f" ({s.rhs_paren_path})"
+        if s.base_address is not None:
+            line += f" @{_fmt_at_int(s.base_address)}"
+    elif s.base_address is not None:
+        line += f" @{_fmt_at_int(s.base_address)}"
+    return line
+
+
+def _emit_system(s: SystemNode, indent: str) -> list[str]:
+    head_line = _emit_system_open_line(s, indent)
+    if not s.has_body:
+        return [f"{head_line};"]
+    lines = [head_line + " {"]
+    inner = indent + "  "
+    if s.bytes_width is not None:
+        lines.append(f"{inner}bytes {s.bytes_width};")
+    for sub in s.systems:
+        lines.extend(_emit_system(sub, inner))
+    for sub in s.blocks:
+        lines.extend(_emit_block(sub, inner))
+    lines.append(indent + "}")
+    return lines
+
+
 def _emit_block(b: BlockNode, indent: str) -> list[str]:
     head_line = _emit_block_open_line(b, indent)
     if not b.has_body:
@@ -77,8 +106,15 @@ def _emit_block(b: BlockNode, indent: str) -> list[str]:
 def dump_ralf(doc: RalfDocument) -> str:
     """将 `RalfDocument` 序列化为 RALF 源文本（规范化排版）。"""
     out: list[str] = []
-    for i, b in enumerate(doc.blocks):
-        if i:
+    first = True
+    for s in doc.systems:
+        if not first:
+            out.append("")
+        first = False
+        out.extend(_emit_system(s, ""))
+    for b in doc.blocks:
+        if not first:
             out.append("")
+        first = False
         out.extend(_emit_block(b, ""))
     return "\n".join(out) + ("\n" if out else "")

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/ralf_model/nodes.py

@@ -69,9 +69,37 @@ class BlockNode(BaseModel):
     blocks: list[BlockNode] = Field(default_factory=list)
 
 
+class SystemNode(BaseModel):
+    """层次化 system；体内可嵌套 system 与 block，不含 register。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    rhs_head: str | None = Field(
+        default=None,
+        description="`=` 右侧起始的层级名（含可能的 `[..]` 后缀）",
+    )
+    rhs_paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 rhs_head 后的圆括号路径内容（不含括号）",
+    )
+    base_address: int | None = Field(
+        default=None,
+        description="`@` 后的地址；可出现于简单 `system 名 @addr` 或 `=` 形式末尾",
+    )
+    has_body: bool = Field(
+        default=True,
+        description="是否带有 `{ ... }`；仅分号结尾的声明为 False",
+    )
+    bytes_width: int | None = None
+    systems: list[SystemNode] = Field(default_factory=list)
+    blocks: list[BlockNode] = Field(default_factory=list)
+
+
 class RalfDocument(BaseModel):
-    """顶层 RALF 文件内容（当前实现要求顶层为若干 `block`）。"""
+    """顶层 RALF 文件内容（顶层为若干 `system`；亦兼容顶层 `block`）。"""
 
     model_config = ConfigDict(extra="forbid")
 
+    systems: list[SystemNode] = Field(default_factory=list)
     blocks: list[BlockNode] = Field(default_factory=list)

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/ralf_model/parse.py

@@ -5,7 +5,7 @@ from collections.abc import Sequence
 from pathlib import Path
 
 from ralf_model.errors import RalfParseError
-from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode, SystemNode
 
 
 class _Parser:
@@ -39,11 +39,22 @@ class _Parser:
         j = self._i + offset
         return self._s[j] if j < self._n else None
 
-    def _error(self, msg: str) -> None:
+    def _error_location(self) -> tuple[Path | None, int]:
         path = self._path
+        line = self.line
         if self._line_sources and 0 < self.line <= len(self._line_sources):
             path = self._line_sources[self.line - 1]
-        raise RalfParseError(msg, line=self.line, col=self.col, path=path)
+            local = 1
+            idx = self.line - 2
+            while idx >= 0 and self._line_sources[idx] == path:
+                local += 1
+                idx -= 1
+            line = local
+        return path, line
+
+    def _error(self, msg: str) -> None:
+        path, line = self._error_location()
+        raise RalfParseError(msg, line=line, col=self.col, path=path)
 
     def skip_ws_and_comments(self) -> None:
         while self._i < self._n:
@@ -168,16 +179,19 @@ class _Parser:
         self._error("期望 ;")
 
     def parse_document(self) -> RalfDocument:
+        systems: list[SystemNode] = []
         blocks: list[BlockNode] = []
         self.skip_ws_and_comments()
         while self._i < self._n:
             kw = self._peek_keyword()
-            if kw == "block":
+            if kw == "system":
+                systems.append(self.parse_system())
+            elif kw == "block":
                 blocks.append(self.parse_block())
             else:
-                self._error(f"顶层期望 block，得到 {kw!r}")
+                self._error(f"顶层期望 system 或 block，得到 {kw!r}")
             self.skip_ws_and_comments()
-        return RalfDocument(blocks=blocks)
+        return RalfDocument(systems=systems, blocks=blocks)
 
     def _peek_keyword(self) -> str:
         self.skip_ws_and_comments()
@@ -261,8 +275,8 @@ class _Parser:
             self.skip_ws_and_comments()
         return head, paren_inner, addr
 
-    def parse_block(self) -> BlockNode:
-        self.expect_keyword("block")
+    def parse_system(self) -> SystemNode:
+        self.expect_keyword("system")
         name = self.read_hierarchical_block_name()
         self.skip_ws_and_comments()
 
@@ -270,14 +284,128 @@ class _Parser:
             self._advance()
             addr = self.parse_integer_value()
             self.skip_ws_and_comments()
-            self.expect_char(";")
-            return BlockNode(
+            if self._peek() == ";":
+                self._advance()
+                return SystemNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=False,
+                    systems=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, subs_sys, subs_blk = self._parse_system_body()
+                self.expect_char("}")
+                return SystemNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=True,
+                    bytes_width=bw,
+                    systems=subs_sys,
+                    blocks=subs_blk,
+                )
+            self._error("system @地址 之后应为 ; 或 {")
+
+        if self._peek() == "=":
+            self._advance()
+            self.skip_ws_and_comments()
+            rhs_head, rhs_path, addr_rhs = self.parse_block_rhs_after_equals()
+            self.skip_ws_and_comments()
+            if self._peek() == ";":
+                self._advance()
+                return SystemNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=False,
+                    systems=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, subs_sys, subs_blk = self._parse_system_body()
+                self.expect_char("}")
+                return SystemNode(
+                    name=name,
+                    rhs_head=rhs_head,
+                    rhs_paren_path=rhs_path,
+                    base_address=addr_rhs,
+                    has_body=True,
+                    bytes_width=bw,
+                    systems=subs_sys,
+                    blocks=subs_blk,
+                )
+            self._error("system ... = ... 之后应为 ; 或 {")
+
+        if self._peek() == "{":
+            self._advance()
+            bw, subs_sys, subs_blk = self._parse_system_body()
+            self.expect_char("}")
+            return SystemNode(
                 name=name,
-                base_address=addr,
-                has_body=False,
-                registers=[],
-                blocks=[],
+                has_body=True,
+                bytes_width=bw,
+                systems=subs_sys,
+                blocks=subs_blk,
             )
+        self._error("system 名称之后应为 @、= 或 {")
+
+    def _parse_system_body(
+        self,
+    ) -> tuple[int | None, list[SystemNode], list[BlockNode]]:
+        bw: int | None = None
+        subs_sys: list[SystemNode] = []
+        subs_blk: list[BlockNode] = []
+        while True:
+            self.skip_ws_and_comments()
+            if self._peek() == "}":
+                break
+            kw = self._peek_keyword()
+            if kw == "bytes":
+                self.expect_keyword("bytes")
+                bw = self.parse_integer_value()
+                self.expect_char(";")
+            elif kw == "system":
+                subs_sys.append(self.parse_system())
+            elif kw == "block":
+                subs_blk.append(self.parse_block())
+            else:
+                self._error(f"system 内出现未识别的内容 {kw!r}")
+        return bw, subs_sys, subs_blk
+
+    def parse_block(self) -> BlockNode:
+        self.expect_keyword("block")
+        name = self.read_hierarchical_block_name()
+        self.skip_ws_and_comments()
+
+        if self._peek() == "@":
+            self._advance()
+            addr = self.parse_integer_value()
+            self.skip_ws_and_comments()
+            if self._peek() == ";":
+                self._advance()
+                return BlockNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=False,
+                    registers=[],
+                    blocks=[],
+                )
+            if self._peek() == "{":
+                self._advance()
+                bw, regs, subs = self._parse_block_body()
+                self.expect_char("}")
+                return BlockNode(
+                    name=name,
+                    base_address=addr,
+                    has_body=True,
+                    bytes_width=bw,
+                    registers=regs,
+                    blocks=subs,
+                )
+            self._error("block @地址 之后应为 ; 或 {")
 
         if self._peek() == "=":
             self._advance()

{python_library_ralf_model-0.1.2 → python_library_ralf_model-0.1.3}/tests/test_ralf_model.py

@@ -241,6 +241,41 @@ block a {
         self.assertNotIn("//", n)
 
 
+class SystemParseTests(unittest.TestCase):
+    def test_top_system_nests_system_and_block(self) -> None:
+        src = """
+system chip {
+  system cpu @0 {
+    block core {
+      register r @0 {
+        bytes 4;
+        field f {}
+      }
+    }
+  }
+  block peri @'h1000 {
+    register s @0 {
+      bytes 1;
+      field g {}
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        self.assertEqual(len(doc.systems), 1)
+        chip = doc.systems[0]
+        self.assertEqual(chip.name, "chip")
+        self.assertEqual(len(chip.systems), 1)
+        self.assertEqual(chip.systems[0].name, "cpu")
+        self.assertEqual(chip.systems[0].base_address, 0)
+        self.assertEqual(chip.blocks[0].name, "peri")
+        self.assertEqual(chip.blocks[0].base_address, 0x1000)
+        core = chip.systems[0].blocks[0]
+        self.assertEqual(core.registers[0].name, "r")
+        doc2 = parse_ralf(dump_ralf(doc))
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+
 class ParseErrorTests(unittest.TestCase):
     def test_parse_error_includes_file_path(self) -> None:
         with tempfile.TemporaryDirectory() as td:
@@ -263,6 +298,23 @@ class ParseErrorTests(unittest.TestCase):
                 load_ralf_file(top)
             self.assertIn(str(broken), str(ctx.exception))
             self.assertNotIn(str(top.resolve()), str(ctx.exception))
+            self.assertEqual(ctx.exception.line, 2)
+
+    def test_parse_error_line_in_included_file_after_filler(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            inc = root / "inc"
+            inc.mkdir()
+            (inc / "broken.ralf").write_text(
+                "// line1\n// line2\nblock y {\n  ???\n}\n",
+                encoding="utf-8",
+            )
+            top = root / "top.ralf"
+            filler = "\n".join(["// filler"] * 50)
+            top.write_text(filler + '\nsource "inc/broken.ralf"\n', encoding="utf-8")
+            with self.assertRaises(RalfParseError) as ctx:
+                load_ralf_file(top)
+            self.assertEqual(ctx.exception.line, 4)
 
 
 if __name__ == "__main__":