python-library-ralf-model 0.1.0__tar.gz

python_library_ralf_model-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+config.yaml
+logs/
+.cursor/

python_library_ralf_model-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: python-library-ralf-model
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Description-Content-Type: text/markdown
+
+# ralf_model
+
+在 **RALF（Register Abstraction Layer Format）源文本** 与 **`RalfDocument` / 抽象节点类型**（`BlockNode`、`RegisterNode`、`FieldNode`，并实现 `AbstractRalf*`）之间做解析与生成。
+
+## 用法
+
+```python
+from pathlib import Path
+
+from ralf_model import dump_ralf, load_ralf_file, parse_ralf
+
+doc = parse_ralf(Path("chip.ralf").read_text(encoding="utf-8"))
+text = dump_ralf(doc)
+```
+
+亦可使用 `loads_ralf` / `dumps_ralf`、`load_ralf_file` / `dump_ralf_file`（见 `ralf_model.io`）。加载时可传入 **`include_paths`**（类似 ``ralgen -I dir``），配合 **`source`** 行递归展开后再解析；相对路径先相对**当前文件目录**，再依次在各 include 目录检索。
+
+### source 与 include
+
+RALF 常作为 Tcl 脚本。单独成行的 ``source "f.ralf"``、``source {path}``、``source name.ralf``（可有行尾 ``;``、``#`` 注释）会在解析前被展开。不需要展开时：`loads_ralf(..., expand_source=False)` 或 `load_ralf_file(..., expand_source=False)`。
+
+```python
+from pathlib import Path
+from ralf_model import load_ralf_file
+
+doc = load_ralf_file(
+    "top.ralf",
+    include_paths=[Path("ralf_inc"), Path("../shared")],
+)
+```
+
+也可直接使用 ``expand_ralf_sources``、``resolve_source_path``（见 `ralf_model.source_expand`）。
+
+## 能力范围
+
+- **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
+- `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
+
+与 Synopsys `ralgen` 全语法并非字节级兼容；复杂构造若解析失败可再扩展解析器。

python_library_ralf_model-0.1.0/README.md

@@ -0,0 +1,40 @@
+# ralf_model
+
+在 **RALF（Register Abstraction Layer Format）源文本** 与 **`RalfDocument` / 抽象节点类型**（`BlockNode`、`RegisterNode`、`FieldNode`，并实现 `AbstractRalf*`）之间做解析与生成。
+
+## 用法
+
+```python
+from pathlib import Path
+
+from ralf_model import dump_ralf, load_ralf_file, parse_ralf
+
+doc = parse_ralf(Path("chip.ralf").read_text(encoding="utf-8"))
+text = dump_ralf(doc)
+```
+
+亦可使用 `loads_ralf` / `dumps_ralf`、`load_ralf_file` / `dump_ralf_file`（见 `ralf_model.io`）。加载时可传入 **`include_paths`**（类似 ``ralgen -I dir``），配合 **`source`** 行递归展开后再解析；相对路径先相对**当前文件目录**，再依次在各 include 目录检索。
+
+### source 与 include
+
+RALF 常作为 Tcl 脚本。单独成行的 ``source "f.ralf"``、``source {path}``、``source name.ralf``（可有行尾 ``;``、``#`` 注释）会在解析前被展开。不需要展开时：`loads_ralf(..., expand_source=False)` 或 `load_ralf_file(..., expand_source=False)`。
+
+```python
+from pathlib import Path
+from ralf_model import load_ralf_file
+
+doc = load_ralf_file(
+    "top.ralf",
+    include_paths=[Path("ralf_inc"), Path("../shared")],
+)
+```
+
+也可直接使用 ``expand_ralf_sources``、``resolve_source_path``（见 `ralf_model.source_expand`）。
+
+## 能力范围
+
+- **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
+- `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
+
+与 Synopsys `ralgen` 全语法并非字节级兼容；复杂构造若解析失败可再扩展解析器。

python_library_ralf_model-0.1.0/example/__main__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import sys
+
+from ralf_model import dump_ralf, parse_ralf
+
+_SAMPLE = """
+block b1 {
+  bytes 1;
+  register r {
+    bytes 1;
+    field WDT_EN @'h5 {
+      bits 1;
+      reset 'h0;
+      access rw;
+      enum { ENABLE = 1, DISABLE = 0 };
+    }
+  }
+}
+"""
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except OSError:
+            pass
+    doc = parse_ralf(_SAMPLE)
+    print(dump_ralf(doc))
+
+
+if __name__ == "__main__":
+    main()

python_library_ralf_model-0.1.0/example.bat

@@ -0,0 +1,10 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+python -m example

python_library_ralf_model-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-ralf-model"
+version = "0.1.0"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0,<3",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ralf_model"]

python_library_ralf_model-0.1.0/ralf_model/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ralf_model.abc import AbstractRalfBlock, AbstractRalfField, AbstractRalfRegister
+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.parse import normalize_ralf_whitespace, parse_ralf
+from ralf_model.source_expand import expand_ralf_sources, resolve_source_path
+
+__all__ = [
+    "AbstractRalfBlock",
+    "AbstractRalfField",
+    "AbstractRalfRegister",
+    "BlockNode",
+    "FieldNode",
+    "RalfDocument",
+    "RegisterNode",
+    "RalfError",
+    "RalfParseError",
+    "RalfSourceError",
+    "dump_ralf",
+    "dumps_ralf",
+    "dump_ralf_file",
+    "expand_ralf_sources",
+    "load_ralf_file",
+    "loads_ralf",
+    "parse_ralf",
+    "normalize_ralf_whitespace",
+    "resolve_source_path",
+]

python_library_ralf_model-0.1.0/ralf_model/abc.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AbstractRalfField(Protocol):
+    """RALF `field` 对应的对象应至少具备 `name`。"""
+
+    name: str
+
+
+@runtime_checkable
+class AbstractRalfRegister(Protocol):
+    """RALF `register` 对应的对象应至少具备 `name`。"""
+
+    name: str
+
+
+@runtime_checkable
+class AbstractRalfBlock(Protocol):
+    """RALF `block` 对应的对象应至少具备 `name`。"""
+
+    name: str

python_library_ralf_model-0.1.0/ralf_model/emit.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
+
+
+def _fmt_at_int(v: int) -> str:
+    """`@` 后的偏移（字节或位），采用 Verilog 无尺寸十六进制字面量。"""
+    if v < 0:
+        return str(v)
+    return f"'h{v:x}"
+
+
+def _emit_field(f: FieldNode, indent: str) -> list[str]:
+    head = f"{indent}field {f.name}"
+    if f.offset_bits is not None:
+        head += f" @{_fmt_at_int(f.offset_bits)}"
+    head += " {"
+    lines = [head]
+    inner = indent + "  "
+    for stmt in f.inner_statements:
+        for line in stmt.splitlines():
+            lines.append(f"{inner}{line.strip()}")
+    lines.append(indent + "}")
+    return lines
+
+
+def _emit_register(r: RegisterNode, indent: str) -> list[str]:
+    head = f"{indent}register {r.name}"
+    if r.offset_bytes is not None:
+        head += f" @{_fmt_at_int(r.offset_bytes)}"
+    if r.declaration_only:
+        return [f"{head};"]
+    lines = [head + " {"]
+    inner = indent + "  "
+    if r.bytes_width is not None:
+        lines.append(f"{inner}bytes {r.bytes_width};")
+    for f in r.fields:
+        lines.extend(_emit_field(f, inner))
+    lines.append(indent + "}")
+    return lines
+
+
+def _emit_block_open_line(b: BlockNode, indent: str) -> str:
+    """``block ...`` 行中 `{` 之前的部分（含 `@` / `=` 等）。"""
+    line = f"{indent}block {b.name}"
+    if b.rhs_head is not None:
+        line += f" = {b.rhs_head}"
+        if b.rhs_paren_path is not None:
+            line += f" ({b.rhs_paren_path})"
+        if b.base_address is not None:
+            line += f" @{_fmt_at_int(b.base_address)}"
+    elif b.base_address is not None:
+        line += f" @{_fmt_at_int(b.base_address)}"
+    return line
+
+
+def _emit_block(b: BlockNode, indent: str) -> list[str]:
+    head_line = _emit_block_open_line(b, indent)
+    if not b.has_body:
+        return [f"{head_line};"]
+    lines = [head_line + " {"]
+    inner = indent + "  "
+    if b.bytes_width is not None:
+        lines.append(f"{inner}bytes {b.bytes_width};")
+    for r in b.registers:
+        lines.extend(_emit_register(r, inner))
+    for sub in b.blocks:
+        lines.extend(_emit_block(sub, inner))
+    lines.append(indent + "}")
+    return lines
+
+
+def dump_ralf(doc: RalfDocument) -> str:
+    """将 `RalfDocument` 序列化为 RALF 源文本（规范化排版）。"""
+    out: list[str] = []
+    for i, b in enumerate(doc.blocks):
+        if i:
+            out.append("")
+        out.extend(_emit_block(b, ""))
+    return "\n".join(out) + ("\n" if out else "")

python_library_ralf_model-0.1.0/ralf_model/errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class RalfError(Exception):
+    """RALF 解析或生成错误基类。"""
+
+
+class RalfParseError(RalfError):
+    """文本不符合预期语法或词法。"""
+
+    def __init__(self, message: str, *, line: int, col: int) -> None:
+        super().__init__(f"{message} (行 {line}, 列 {col})")
+        self.line = line
+        self.col = col
+
+
+class RalfSourceError(RalfError):
+    """source 展开或路径解析失败（含循环引用、找不到文件）。"""
+
+    def __init__(self, message: str, *, path: Path | None = None) -> None:
+        super().__init__(message)
+        self.path = path

python_library_ralf_model-0.1.0/ralf_model/io.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ralf_model.emit import dump_ralf
+from ralf_model.nodes import RalfDocument
+from ralf_model.parse import parse_ralf
+from ralf_model.source_expand import expand_ralf_sources
+
+
+def load_ralf_file(
+    path: str | Path,
+    *,
+    encoding: str = "utf-8",
+    include_paths: Sequence[str | Path] | None = None,
+    expand_source: bool = True,
+) -> RalfDocument:
+    """从文件加载；若 ``expand_source`` 为真，先按 Tcl ``source`` 语义展开（含 ``include_paths`` 检索）。"""
+    p = Path(path).resolve()
+    text = p.read_text(encoding=encoding)
+    inc = tuple(Path(x).resolve() for x in (include_paths or ()))
+    if expand_source:
+        text = expand_ralf_sources(text, current_file=p, include_paths=inc, encoding=encoding)
+    return parse_ralf(text)
+
+
+def loads_ralf(
+    text: str,
+    *,
+    encoding: str = "utf-8",
+    base_dir: str | Path | None = None,
+    include_paths: Sequence[str | Path] | None = None,
+    expand_source: bool = True,
+) -> RalfDocument:
+    """自字符串解析。展开 ``source`` 时相对路径相对 ``base_dir``（默认当前工作目录）。"""
+    bd = Path(base_dir).resolve() if base_dir is not None else Path.cwd()
+    virtual = bd / "__inline__.ralf"
+    inc = tuple(Path(x).resolve() for x in (include_paths or ()))
+    if expand_source:
+        text = expand_ralf_sources(
+            text,
+            current_file=virtual,
+            include_paths=inc,
+            encoding=encoding,
+        )
+    return parse_ralf(text)
+
+
+def dump_ralf_file(doc: RalfDocument, path: str | Path, *, encoding: str = "utf-8") -> None:
+    Path(path).write_text(dump_ralf(doc), encoding=encoding)
+
+
+def dumps_ralf(doc: RalfDocument) -> str:
+    """序列化为字符串，等价于 `dump_ralf`。"""
+    return dump_ralf(doc)

python_library_ralf_model-0.1.0/ralf_model/nodes.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FieldNode(BaseModel):
+    """单个 field：`inner_statements` 按源顺序保存每条完整语句（含分号）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    offset_bits: int | None = Field(default=None, description="field 内 `@` 后的位偏移")
+    inner_statements: list[str] = Field(
+        default_factory=list,
+        description='field 花括号内语句，如 bits 1;、reset \'h0;、enum { ... };',
+    )
+
+
+class RegisterNode(BaseModel):
+    """寄存器：可为完整 `{ ... }` 定义，或仅 `register name;` 的前向引用。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    offset_bytes: int | None = Field(default=None, description="register 后的 `@` 字节偏移")
+    bytes_width: int | None = None
+    fields: list[FieldNode] = Field(default_factory=list)
+    declaration_only: bool = False
+
+
+class BlockNode(BaseModel):
+    """层次化 block。
+
+    典型形态：
+    - 定义体：``block 名 { ... }``
+    - 简单映射：``block 名 @地址;``
+    - 实例化：``block 左名 = 右名 [ (路径) ] [ @地址 ] ;`` 或带 ``{ ... }``
+    """
+
+    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="`@` 后的地址；可出现于简单 `block 名 @addr` 或 `=` 形式末尾",
+    )
+    has_body: bool = Field(
+        default=True,
+        description="是否带有 `{ ... }`；仅分号结尾的声明为 False",
+    )
+    bytes_width: int | None = None
+    registers: list[RegisterNode] = Field(default_factory=list)
+    blocks: list[BlockNode] = Field(default_factory=list)
+
+
+class RalfDocument(BaseModel):
+    """顶层 RALF 文件内容（当前实现要求顶层为若干 `block`）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    blocks: list[BlockNode] = Field(default_factory=list)