infinity-data 1.0.0__py3-none-any.whl

infinity_data/parser/__init__.py

@@ -0,0 +1,79 @@
+"""语法分析：RawAst 数据模型与解析器。
+
+- :class:`Parser`：LL(1) 递归下降解析器（parser.py）
+- RawAst 数据模型（models.py）：Document / 语句 / 值 / 约束 / 模板定义节点
+
+公共面从此包再导出，兼容 ``from infinity_data.parser import Document``；
+内部实现文件（models.py / parser.py / token_stream.py）不直接引用。
+
+注意：parser 包内部文件仍从 ``parser.models`` 模块级导入（避免经包根
+``__init__`` 触发自引用循环）——此约定与 semantic 子包一致。
+"""
+
+from infinity_data.parser.models import (
+    ArrayValue,
+    AstNode,
+    Constraint,
+    ConstraintCall,
+    ConstraintIdent,
+    ConstraintLiteral,
+    Constraints,
+    ConstraintStmt,
+    DictValue,
+    Document,
+    DollarValue,
+    EnvImportStmt,
+    ErrorConstraint,
+    ErrorStatement,
+    ErrorValue,
+    Field,
+    FileImportItem,
+    FileImportStmt,
+    JsonPathIndex,
+    JsonPathKey,
+    JsonPathSegment,
+    LiteralValue,
+    Statement,
+    TemplateCallValue,
+    TemplateConfig,
+    TemplateDef,
+    TemplateField,
+    TemplateImportItem,
+    TemplateImportStmt,
+    Value,
+)
+from infinity_data.parser.parser import Parser
+
+__all__ = [
+    'ArrayValue',
+    'AstNode',
+    'Constraint',
+    'ConstraintCall',
+    'ConstraintIdent',
+    'ConstraintLiteral',
+    'Constraints',
+    'ConstraintStmt',
+    'DictValue',
+    'Document',
+    'DollarValue',
+    'EnvImportStmt',
+    'ErrorConstraint',
+    'ErrorStatement',
+    'ErrorValue',
+    'Field',
+    'FileImportItem',
+    'FileImportStmt',
+    'JsonPathIndex',
+    'JsonPathKey',
+    'JsonPathSegment',
+    'LiteralValue',
+    'Parser',
+    'Statement',
+    'TemplateCallValue',
+    'TemplateConfig',
+    'TemplateDef',
+    'TemplateField',
+    'TemplateImportItem',
+    'TemplateImportStmt',
+    'Value',
+]

infinity_data/parser/diagnostics.py

@@ -0,0 +1,92 @@
+"""语法分析阶段诊断构造器与诊断定义。
+
+语法错误统一为 :class:`Diagnostic`（纯数据，从不抛异常）；
+:func:`diag` 便捷构造语法错误诊断，收集使用 :class:`DiagnosticCollector`。
+诊断定义（``parse.*``）导入时注册进全局注册表（:func:`register`）。
+"""
+
+from typing import Any
+
+from infinity_data.infra.diagnostics import Diagnostic, Severity, diagnostic_define, register_diagnostic_define
+from infinity_data.infra.location import SourceRange
+
+__all__ = ['diag']
+
+register_diagnostic_define(
+    diagnostic_define(
+        'parse.unrecognized_statement',
+        '[{location}] 无法识别的顶层 token: {name}',
+        en='[{location}] unrecognized top-level token: {name}',
+    ),
+    diagnostic_define(
+        'parse.unrecognized_import', '[{location}] 无法识别的导入语句', en='[{location}] unrecognized import statement'
+    ),
+    diagnostic_define(
+        'parse.unexpected_token',
+        '[{location}] 期望 {expected}，实际为 {actual}',
+        en='[{location}] expected {expected}, got {actual}',
+    ),
+    diagnostic_define(
+        'parse.template_arg_order',
+        '[{location}] 位置参数不能出现在命名参数之后',
+        en='[{location}] positional arguments cannot follow named arguments',
+    ),
+    diagnostic_define('parse.empty_token_list', 'Token 列表为空，无法解析', en='empty token list, nothing to parse'),
+    diagnostic_define(
+        'parse.invalid_json_path', '[{location}] 无效的 JSON 路径{detail}', en='[{location}] invalid JSON path{detail}'
+    ),
+    diagnostic_define(
+        'parse.unrecognized_value', '[{location}] 无法解析的值: {name}', en='[{location}] unrecognized value: {name}'
+    ),
+    diagnostic_define(
+        'parse.missing_separator',
+        '[{location}] 元素之间缺少分隔符（逗号或换行，空格不构成分隔）',
+        en='[{location}] missing separator between elements (comma or newline; space is not a separator)',
+    ),
+    diagnostic_define(
+        'parse.value_field',
+        '[{location}] 值位置出现字段定义 {name}（外层数组/对象未闭合）',
+        en='[{location}] field definition {name} in value position (enclosing array/object unclosed)',
+    ),
+    diagnostic_define(
+        'parse.field_requires_equals',
+        '[{location}] 字段 {name} 省略等号仅限复合值与模板调用，字面量/引用须用 = 赋值',
+        en='[{location}] field {name}: "=" required here (omit "=" only for dict/array/template call)',
+    ),
+    diagnostic_define(
+        'parse.template_field_no_constraint',
+        '[{location}] 模板字段 {field} 必须有类型标注（如 {field}: int）',
+        en='[{location}] template field {field} requires a type annotation (e.g. {field}: int)',
+    ),
+    diagnostic_define(
+        'parse.invalid_cast',
+        '[{location}] 未知的类型转换 {type}（合法: bool/int/float/str）',
+        en='[{location}] unknown cast type {type} (valid: bool/int/float/str)',
+    ),
+    diagnostic_define(
+        'parse.unrecognized_constraint',
+        '[{location}] 无法解析的约束: {name}',
+        en='[{location}] unrecognized constraint: {name}',
+    ),
+    diagnostic_define('parse.statement_error', '{path_prefix}{message}'),
+    diagnostic_define(
+        'parse.template_config_unknown',
+        '[{location}] 未知的模板配置项: {key}（合法项: {valid}）',
+        en='[{location}] unknown template config key: {key} (valid: {valid})',
+    ),
+    diagnostic_define(
+        'parse.template_config_type',
+        '[{location}] 模板配置 {key} 期望 {expected}，实际为 {actual}',
+        en='[{location}] template config {key} expects {expected}, got {actual}',
+    ),
+    diagnostic_define(
+        'parse.template_config_value',
+        '[{location}] 模板配置 {key} 必须是字面量（不支持 $ 引用 / 模板调用）',
+        en='[{location}] template config {key} must be a literal (no $ refs / template calls)',
+    ),
+)
+
+
+def diag(code: str, params: dict[str, Any], source: SourceRange | None) -> Diagnostic:
+    """构造语法阶段错误诊断（severity 恒为 ERROR）。"""
+    return Diagnostic(Severity.ERROR, code, params, source)

infinity_data/parser/models.py

@@ -0,0 +1,295 @@
+"""语法分析阶段 AST 节点（RawAst）。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from infinity_data.tokenizer.models.raw_tokens import SourceRange
+from infinity_data.tokenizer.models.tokens import (
+    BoolToken,
+    FloatToken,
+    IntegerToken,
+    NoexistToken,
+    NullToken,
+    StringToken,
+)
+
+
+# ═══════════════════════════════════════════════════════════
+# 节点
+# ═══════════════════════════════════════════════════════════
+@dataclass
+class AstNode:
+    """AST 节点基类。"""
+
+    source: SourceRange
+
+
+# ═══════════════════════════════════════════════════════════
+# 文档
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class Document(AstNode):
+    """顶层文档，包含一组语句。
+
+    顶层是隐式 dict；``: <constraint, ...>`` 以 :class:`ConstraintStmt`
+    形式出现在 statements 中，语义分析阶段作用于编译产物 root。
+    """
+
+    statements: list[Statement] = field(default_factory=lambda: [])
+
+
+# ═══════════════════════════════════════════════════════════
+# 语句
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class TemplateImportItem(AstNode):
+    """模板导入项: Name [as Alias]。"""
+
+    name: str  # 被导入文件中的模板名
+    alias: str | None = None  # 本地别名（可选）
+
+
+@dataclass
+class TemplateImportStmt(AstNode):
+    """模板导入: !from "path" import Name1, Name2 as N2"""
+
+    from_path: str  # 文件路径（unix 风格）
+    items: list[TemplateImportItem]  # 导入项列表
+
+
+@dataclass
+class EnvImportStmt(AstNode):
+    """环境变量导入: !env import NAME [as NEW_NAME]"""
+
+    name: str  # 环境变量名
+    alias: str | None  # 别名（可选）
+
+
+@dataclass
+class JsonPathKey(AstNode):
+    """JSON 路径中的键访问: .key 或 .\"key\""""
+
+    key: str
+
+
+@dataclass
+class JsonPathIndex(AstNode):
+    """JSON 路径中的索引访问: [N]"""
+
+    index: int
+
+
+type JsonPathSegment = JsonPathKey | JsonPathIndex
+
+
+@dataclass
+class FileImportItem(AstNode):
+    """配置文件导入项。"""
+
+    json_path: list[JsonPathSegment]  # 路径段列表；空列表 = 导入整个文件
+    alias: str  # 别名（必须）
+
+
+@dataclass
+class FileImportStmt(AstNode):
+    """配置文件导入: !file "path" as <format> import .path.to.key as alias, ..."""
+
+    file_path: str  # 文件路径
+    format: str | None  # 文件格式: "yaml", "json", "toml" 或 None（自动检测后缀）
+    imports: list[FileImportItem]
+
+
+@dataclass
+class TemplateField(AstNode):
+    """模板内部字段定义。与普通 Field 不同之处：
+    - 必须带有类型约束
+    - 默认值可选（省略表示必填字段）
+    - 必填字段必须在非必填字段之前
+    """
+
+    name: str
+    constraints: Constraints  # 模板字段必须有类型标注
+    default_value: Value | None  # None = 必填字段
+
+
+@dataclass
+class TemplateConfig:
+    """模板头部配置（``~X(key=value)``），语法层解析为类型化字段。
+
+    - ``allow_extra``：校验时是否放行额外字段（模板即约束 / schema）
+    - ``positional``：是否允许位置参数（false = 只接受命名参数）
+    - ``description``：模板文档（元数据，暂不消费，供 LSP/文档）
+
+    未来新增配置项：在此加字段，parser 侧在对应键集合补一行（字段即白名单）。
+    """
+
+    allow_extra: bool = False
+    positional: bool = True
+    description: str | None = None
+
+
+@dataclass
+class TemplateDef(AstNode):
+    """模板定义: ~Name { ... } 或 ~Name(config=value) { ... }"""
+
+    name: str
+    fields: list[TemplateField]
+    config: TemplateConfig = field(default_factory=TemplateConfig)
+    constraints: list[Constraint] = field(default_factory=lambda: [])
+
+
+@dataclass
+class Field(AstNode):
+    """普通字段定义：name[: type] [= value]。
+
+    值缺失（裸 key）不是合法语法：语义分析阶段报错。
+    noexist 需显式书写 ``= noexist`` 字面量。
+    """
+
+    name: str
+    constraints: Constraints | None = None
+    value: Value | None = None
+
+
+@dataclass
+class ConstraintStmt(AstNode):
+    """顶层结构级约束: ``: <constraint, ...>``（作用于编译产物 root）。
+
+    顶层是隐式 dict，``:`` 起始的语句约束整个 root，而非某个字段。
+    约束函数与字段级约束共用同一注册表。
+    """
+
+    constraints: list[Constraint]
+
+
+# ═══════════════════════════════════════════════════════════
+# 约束
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class ConstraintIdent(AstNode):
+    """简单约束标识符，如 int, str, ?"""
+
+    name: str
+
+
+@dataclass
+class ConstraintCall(AstNode):
+    """约束函数调用，如 each(str)、range(1, 10)、not(?)、any(int, str)。"""
+
+    name: str
+    arguments: list[Constraint] = field(default_factory=lambda: [])
+
+
+@dataclass
+class ConstraintLiteral(AstNode):
+    """约束中的字面量参数，如 range(1, 10) 中的 1、10。"""
+
+    value: LiteralValue
+
+
+type Constraint = ConstraintIdent | ConstraintCall | ConstraintLiteral | ErrorConstraint
+
+
+@dataclass
+class Constraints(AstNode):
+    """约束列表，如 int, str?, <int, range(1,10)>, <int, each(str)>。
+
+    语义说明：
+    - constraints 列表，若 len > 1，隐含 all(constraint1, constraint2, ...)
+    """
+
+    constraints: list[Constraint] = field(default_factory=lambda: [])
+
+
+# ═══════════════════════════════════════════════════════════
+# 值
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class LiteralValue(AstNode):
+    """字面量值"""
+
+    value: FloatToken | IntegerToken | BoolToken | NullToken | NoexistToken | StringToken
+
+
+@dataclass
+class DollarValue(AstNode):
+    """$ 导入空间引用: $NAME [as type]。
+
+    用于引用 !env import 导入的变量。
+    """
+
+    name: str  # 变量名
+    type_cast: Literal['int', 'float', 'bool', 'str', None]  # 可选类型转换
+
+
+@dataclass
+class DictValue(AstNode):
+    """对象值: { ... }
+
+    ``: <constraint, ...>`` 结构级约束作用于该字面量 dict 的整体。
+    """
+
+    fields: list[Field]
+    constraints: list[Constraint] = field(default_factory=lambda: [])
+
+
+@dataclass
+class ArrayValue(AstNode):
+    """数组值: [ ... ]"""
+
+    elements: list[Value]
+
+
+@dataclass
+class TemplateCallValue(AstNode):
+    """模板调用: Name(args...)"""
+
+    template_name: str
+    positional_args: list[Value]
+    named_args: dict[str, Value]
+
+
+# ═══════════════════════════════════════════════════════════
+# 错误节点
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class ErrorStatement(AstNode):
+    """解析失败的语句。用于错误恢复。"""
+
+    message: str
+
+
+@dataclass
+class ErrorValue(AstNode):
+    """解析失败的值。用于错误恢复。"""
+
+    message: str
+
+
+@dataclass
+class ErrorConstraint(AstNode):
+    """解析失败的约束。用于错误恢复。"""
+
+    message: str
+
+
+# ═══════════════════════════════════════════════════════════
+# 联合类型
+# ═══════════════════════════════════════════════════════════
+
+type Statement = (
+    TemplateImportStmt | EnvImportStmt | FileImportStmt | TemplateDef | Field | ConstraintStmt | ErrorStatement
+)
+type Value = LiteralValue | DollarValue | DictValue | ArrayValue | TemplateCallValue | ErrorValue