xr-syntax 0.1.0__py3-none-any.whl

xr_syntax/__init__.py

@@ -0,0 +1,59 @@
+"""定义 xr-syntax 顶层公共接口，集中导出语言无关语法核心以及 C++ 前端的常用类型。
+Public package surface for the language-neutral source model and C++ frontend.
+"""
+
+from .core import (
+    Diagnostic,
+    GreenChild,
+    GreenNode,
+    GreenToken,
+    GreenTrivia,
+    ParserKindInfo,
+    ParserSchema,
+    SourcePoint,
+    SourceSpan,
+    SyntaxElement,
+    SyntaxFragment,
+    SyntaxNode,
+    SyntaxToken,
+    SyntaxTree,
+    SyntaxTrivia,
+)
+from .cpp import (
+    CppBlockBuilder,
+    CppDocument,
+    CppFactory,
+    CppFileBuilder,
+    CppFunctionBuilder,
+    CppParser,
+    CppRegion,
+)
+
+# ---------------------------------------------------------------------------
+# 模块实现：定义 xr-syntax 顶层公共接口，集中导出语言无关语法核心以及 C++ 前端的常用类型。
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "CppBlockBuilder",
+    "CppDocument",
+    "CppFactory",
+    "CppFileBuilder",
+    "CppFunctionBuilder",
+    "CppParser",
+    "CppRegion",
+    "Diagnostic",
+    "GreenChild",
+    "GreenNode",
+    "GreenToken",
+    "GreenTrivia",
+    "ParserKindInfo",
+    "ParserSchema",
+    "SourcePoint",
+    "SourceSpan",
+    "SyntaxElement",
+    "SyntaxFragment",
+    "SyntaxNode",
+    "SyntaxToken",
+    "SyntaxTree",
+    "SyntaxTrivia",
+]

xr_syntax/cmake/__init__.py

@@ -0,0 +1,26 @@
+"""定义 CMake 前端公共接口；它与 C++ 前端共享同一套不可变语法树、重写和布局基础设施。
+CMake frontend built on the same syntax core and edit model as C++.
+"""
+
+from .builder import CMakeFileBuilder
+from .document import CMakeDocument
+from .factory import CMakeFactory
+from .grammar import CMAKE_GRAMMAR, GRAMMAR_REVISION, GRAMMAR_VERSION
+from .parser import CMakeParser
+from .view import CMakeArgumentView, CMakeCommandView
+
+# ---------------------------------------------------------------------------
+# 模块实现：定义 CMake 前端公共接口；它与 C++ 前端共享同一套不可变语法树、重写和布局基础设施。
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "CMAKE_GRAMMAR",
+    "CMakeArgumentView",
+    "CMakeCommandView",
+    "CMakeDocument",
+    "CMakeFactory",
+    "CMakeFileBuilder",
+    "CMakeParser",
+    "GRAMMAR_REVISION",
+    "GRAMMAR_VERSION",
+]

xr_syntax/cmake/builder.py

@@ -0,0 +1,91 @@
+"""提供只在 build() 边界解析一次的 CMake 文件构建器。
+CMake file builder that parses once at the build() boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from xr_syntax.core import SourceDraft, SyntaxFragment
+
+from .document import CMakeDocument
+from .factory import CMakeFactory
+
+# ---------------------------------------------------------------------------
+# 模块实现：提供只在 build() 边界解析一次的 CMake 文件构建器。
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CMakeFileBuilder:
+    """累积 CMake source draft，并在 build() 时统一解析。
+    Accumulate CMake source drafts and parse the complete file once in build().
+    """
+
+    factory: CMakeFactory = field(default_factory=CMakeFactory)
+    items: list[SourceDraft | SyntaxFragment] = field(default_factory=list)
+
+    def add(self, item: SourceDraft | SyntaxFragment) -> SourceDraft | SyntaxFragment:
+        """追加同语言 draft 或已验证 fragment。
+        Append a same-language draft or validated fragment.
+        """
+        self.factory._source_of(item)
+        self.items.append(item)
+        return item
+
+    def raw(self, source: str) -> SourceDraft:
+        """追加原始 CMake source draft。
+        Append raw CMake source for validation by the final parse.
+        """
+        draft = SourceDraft(self.factory.language, source)
+        self.add(draft)
+        return draft
+
+    def comment(self, text: str) -> SourceDraft:
+        """追加 CMake 注释 draft。
+        Append one CMake comment draft.
+        """
+        draft = self.factory._comment_draft(text)
+        self.add(draft)
+        return draft
+
+    def command(
+        self,
+        name: str,
+        arguments: Iterable[str] = (),
+    ) -> SourceDraft:
+        """追加 CMake 命令 draft。
+        Append one CMake command draft.
+        """
+        draft = self.factory._command_draft(name, arguments)
+        self.add(draft)
+        return draft
+
+    def if_block(
+        self,
+        condition: Iterable[str],
+        body: Iterable[SourceDraft | SyntaxFragment],
+    ) -> SourceDraft:
+        """追加完整的 if()/endif() 条件块 draft。
+        Append one complete if()/endif() block draft.
+        """
+        draft = self.factory._if_block_draft(condition, body)
+        self.add(draft)
+        return draft
+
+    def build(self, *, require_clean: bool = False) -> CMakeDocument:
+        """渲染全部源码并只 parse 一次；可要求生成结果没有 diagnostics。
+        Parse the complete generated file once and optionally require a clean result.
+        """
+        rendered = [
+            self.factory._source_of(item).rstrip("\r\n")
+            for item in self.items
+        ]
+        source = "\n".join(rendered)
+        if source and not source.endswith("\n"):
+            source += "\n"
+        document = CMakeDocument.parse(source, parser=self.factory.parser)
+        if require_clean and document.diagnostics:
+            messages = "; ".join(item.message for item in document.diagnostics)
+            raise ValueError(f"generated CMake source has parser diagnostics: {messages}")
+        return document

xr_syntax/cmake/document.py

@@ -0,0 +1,90 @@
+"""提供面向 CMake 的高层文档查询接口，底层仍使用语言无关的不可变语法模型。
+High-level CMake document queries over the generic syntax model.
+"""
+
+from __future__ import annotations
+
+from xr_syntax.core import SyntaxDocument, SyntaxElement, SyntaxNode
+
+from .grammar import CMAKE_GRAMMAR
+from .parser import CMakeParser
+from .view import CMakeCommandView
+
+# ---------------------------------------------------------------------------
+# 基于共享语法核心实现的 CMake 文档查询
+# CMake document queries using the shared syntax core
+# ---------------------------------------------------------------------------
+
+class CMakeDocument(SyntaxDocument):
+    """在通用不可变语法树之上提供 CMake 专用查询和编辑接口。
+    CMake-specific query facade over the same immutable syntax core used by C++.
+    """
+    __slots__ = ()
+
+    language = "cmake"
+    grammar = CMAKE_GRAMMAR
+
+    @classmethod
+    def parse(
+        cls,
+        source: str | bytes,
+        *,
+        source_name: str | None = None,
+        parser: CMakeParser | None = None,
+    ) -> CMakeDocument:
+        """使用可选的固定版本 CMake grammar 解析文本或字节并创建文档快照。
+        Parse CMake source using the optional pinned language-pack grammar.
+        """
+        selected = parser or CMakeParser()
+        return cls(
+            selected.parse(source, source_name=source_name),
+            selected,
+        )
+
+    def comments(self) -> tuple[SyntaxElement, ...]:
+        """按源码顺序返回全部 CMake 注释节点。
+        Return CMake comments in source order.
+        """
+        return self.elements("comment")
+
+    def commands(self, name: str | None = None) -> tuple[SyntaxNode, ...]:
+        """返回 CMake 命令节点，并可按命令名进行大小写不敏感过滤。
+        Return command nodes, optionally filtered case-insensitively by command name.
+        """
+        nodes = tuple(
+            node
+            for node in self.root.descendants(include_self=True)
+            if isinstance(node, SyntaxNode)
+            and (node.kind == "normal_command" or node.kind.endswith("_command"))
+        )
+        if name is None:
+            return nodes
+        normalized = name.casefold()
+        return tuple(
+            node
+            for node in nodes
+            if CMakeCommandView(node).name.casefold() == normalized
+        )
+
+    def command_views(self, name: str | None = None) -> tuple[CMakeCommandView, ...]:
+        """返回类型化命令视图，并可按命令名过滤。
+        Return typed command views, optionally filtered by command name.
+        """
+        return tuple(CMakeCommandView(node) for node in self.commands(name))
+
+    def blocks(self) -> tuple[SyntaxNode, ...]:
+        """返回 if、foreach、while、function、macro 等结构化块节点。
+        Return structured block nodes such as if/foreach/while/function/macro constructs.
+        """
+        kinds = {
+            "if_condition",
+            "foreach_loop",
+            "while_loop",
+            "function_def",
+            "macro_def",
+        }
+        return tuple(
+            node
+            for node in self.root.descendants(include_self=True)
+            if isinstance(node, SyntaxNode) and node.kind in kinds
+        )

xr_syntax/cmake/factory.py

@@ -0,0 +1,158 @@
+"""提供 CMake 命令、注释和条件块的 parser-backed 片段工厂。
+Factories for parser-backed CMake source fragments.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from xr_syntax.core import GreenToken, SourceDraft, SyntaxElement, SyntaxFragment, SyntaxNode
+from xr_syntax.format import Group, Indent, concat, join, line, render, softline
+
+from .document import CMakeDocument
+from .parser import CMakeParser
+
+# ---------------------------------------------------------------------------
+# 模块实现：提供 CMake 命令、注释和条件块的 parser-backed 片段工厂。
+# ---------------------------------------------------------------------------
+
+class CMakeFactory:
+    """创建带 CMake 语言归属的 parser-backed 片段。
+    Create parser-backed fragments carrying explicit CMake language provenance.
+    """
+
+    language = "cmake"
+
+    def __init__(
+        self,
+        parser: CMakeParser | None = None,
+        *,
+        width: int = 100,
+    ) -> None:
+        """初始化 CMake 片段工厂并保存布局宽度。
+        Initialize the CMake fragment factory and store its layout width.
+        """
+        self.parser = parser or CMakeParser()
+        self.width = width
+
+    def raw(self, source: str) -> SyntaxFragment:
+        """创建显式 opaque 的原始 CMake 片段。
+        Create an explicit opaque CMake source fragment.
+        """
+        return SyntaxFragment(
+            self.language,
+            GreenToken("raw", source, named=True),
+            opaque=True,
+        )
+
+    def comment(self, text: str) -> SyntaxFragment:
+        """创建一条 CMake 行注释片段。
+        Create one CMake line-comment fragment.
+        """
+        draft = self._comment_draft(text)
+        return self._fragment(self._first_element(draft.source, "comment"))
+
+    def command(
+        self,
+        name: str,
+        arguments: Iterable[str] = (),
+    ) -> SyntaxFragment:
+        """按给定宽度创建一个 CMake 命令片段。
+        Create one CMake command fragment with width-aware argument layout.
+        """
+        draft = self._command_draft(name, arguments)
+        return self._fragment(self._first_node(draft.source, "normal_command"))
+
+    def if_block(
+        self,
+        condition: Iterable[str],
+        body: Iterable[SyntaxFragment],
+    ) -> SyntaxFragment:
+        """由条件和 body 片段创建 if()/endif() 块。
+        Create a complete if()/endif() block from condition and body fragments.
+        """
+        draft = self._if_block_draft(condition, body)
+        return self._fragment(self._first_node(draft.source, "if_condition"))
+
+    def _comment_draft(self, text: str) -> SourceDraft:
+        """生成尚未解析的 CMake 注释源码。
+        Build unparsed source for one CMake comment.
+        """
+        return SourceDraft(self.language, f"# {text}")
+
+    def _command_draft(
+        self,
+        name: str,
+        arguments: Iterable[str] = (),
+    ) -> SourceDraft:
+        """通过布局 IR 生成尚未解析的 CMake 命令源码。
+        Render one unparsed CMake command through the layout IR.
+        """
+        document = Group(
+            concat(
+                name,
+                "(",
+                Indent(
+                    concat(
+                        softline,
+                        join(line, tuple(arguments)),
+                    )
+                ),
+                softline,
+                ")",
+            )
+        )
+        return SourceDraft(self.language, render(document, width=self.width))
+
+    def _if_block_draft(
+        self,
+        condition: Iterable[str],
+        body: Iterable[SourceDraft | SyntaxFragment],
+    ) -> SourceDraft:
+        """生成尚未解析的 if()/endif() 块源码。
+        Build unparsed source for one if()/endif() block.
+        """
+        opening = self._command_draft("if", condition).source
+        body_text = "\n".join(
+            self._source_of(item).rstrip("\r\n") for item in body
+        )
+        rendered = [opening]
+        if body_text:
+            rendered.append(body_text)
+        rendered.append("endif()")
+        return SourceDraft(self.language, "\n".join(rendered))
+
+    def _source_of(self, item: SourceDraft | SyntaxFragment) -> str:
+        """返回同语言 draft/fragment 的源码文本。
+        Return source text from a same-language draft or syntax fragment.
+        """
+        if isinstance(item, SourceDraft):
+            return item.source_for(self.language)
+        item.green_for(self.language)
+        return item.render()
+
+    def _fragment(self, element: SyntaxElement) -> SyntaxFragment:
+        """把解析元素包装成 CMake fragment。
+        Wrap one parsed syntax element as a CMake fragment.
+        """
+        return SyntaxFragment(self.language, element.green)
+
+    def _first_element(self, source: str, kind: str) -> SyntaxElement:
+        """返回临时解析结果中指定 kind 的第一个元素。
+        Return the first parsed syntax element of the requested kind.
+        """
+        document = CMakeDocument.parse(source, parser=self.parser)
+        elements = document.elements(kind)
+        if not elements:
+            raise ValueError(f"generated CMake fragment did not contain {kind}")
+        return elements[0]
+
+    def _first_node(self, source: str, kind: str) -> SyntaxNode:
+        """返回临时解析结果中指定 kind 的第一个节点。
+        Return the first parsed node of the requested kind.
+        """
+        document = CMakeDocument.parse(source, parser=self.parser)
+        nodes = document.nodes(kind)
+        if not nodes:
+            raise ValueError(f"generated CMake fragment did not contain {kind}")
+        return nodes[0]

xr_syntax/cmake/grammar/LICENSE.tree-sitter-cmake

@@ -0,0 +1,21 @@
+ The MIT License (MIT)
+
+Copyright (c) 2025 Uy Ha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xr_syntax/cmake/grammar/__init__.py

@@ -0,0 +1,61 @@
+"""加载并校验固定版本的 CMake grammar 元数据。
+Load and validate pinned CMake grammar metadata.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import pkgutil
+from typing import Any
+
+from xr_syntax.core import LanguageGrammar
+
+GRAMMAR_VERSION = "0.7.4"
+GRAMMAR_REVISION = "ca627bb5828616b6246aafdc3c3222789e728e37"
+NODE_TYPES_SHA256 = "e696c1156c9916d1d26f2e4643b6d32794dd079b0c8640aa1dabf2f33a3f5cdf"
+
+
+def _load() -> LanguageGrammar:
+    """读取、校验 CMake grammar 元数据并构造 LanguageGrammar。
+    Load and validate CMake grammar metadata and build a LanguageGrammar.
+    """
+    payload = pkgutil.get_data(__package__, "node-types.json")
+    if payload is None:
+        raise RuntimeError("packaged CMake grammar schema is missing")
+
+    # Windows checkout 可能使用 CRLF，校验前统一为 LF。
+    # Windows checkouts may use CRLF, so normalize to LF before hashing.
+    text = payload.decode("utf-8").replace("\r\n", "\n").replace("\r", "\n")
+    normalized = text.encode("utf-8")
+    digest = hashlib.sha256(normalized).hexdigest()
+    if digest != NODE_TYPES_SHA256:
+        raise RuntimeError(
+            "packaged CMake grammar schema checksum mismatch: "
+            f"{digest} != {NODE_TYPES_SHA256}"
+        )
+
+    decoded: Any = json.loads(text)
+    if not isinstance(decoded, list) or not all(
+        isinstance(item, dict) for item in decoded
+    ):
+        raise RuntimeError("packaged CMake node-types schema has an invalid root")
+
+    return LanguageGrammar.from_node_types(
+        language="cmake",
+        version=GRAMMAR_VERSION,
+        source_revision=GRAMMAR_REVISION,
+        source_sha256=NODE_TYPES_SHA256,
+        data=decoded,
+    )
+
+
+CMAKE_GRAMMAR = _load()
+
+
+__all__ = [
+    "CMAKE_GRAMMAR",
+    "GRAMMAR_REVISION",
+    "GRAMMAR_VERSION",
+    "NODE_TYPES_SHA256",
+]