51 lines
4.3 KiB
Markdown
51 lines
4.3 KiB
Markdown
# 语言核对地图
|
||
|
||
本页帮助作者定位当前语言规则。每次新增或改动语言断言，读取相关主定义及规范状态；此表不是另一份语言规范。下面的文件位置以文档仓库根目录为基准，直接按主题查阅。
|
||
|
||
## 断言从哪里来
|
||
|
||
| 证据 | 可以据此写什么 | 需要注意 |
|
||
| --- | --- | --- |
|
||
| 用户本次明确确认的语言决定 | 将决定落实为主定义、例子、文法与状态 | 只落实明确决定的范围，相关未定项仍保持未定 |
|
||
| 当前规范状态与主要定义 | 重述已确定约定，解释已收录提案 | 两者冲突时先定位，不选择更方便写例子的版本 |
|
||
| 一个源码示例 | 说明该例在明确条件下的预期效果 | 示例本身不证明全语言默认值或完整规则 |
|
||
| 软件实现行为 | 在用户要求的范围报告观测事实 | 本阶段文档不据此自动确定语言语义 |
|
||
| 外部语言或文档 | 研究解释方法，或说明显式提出的候选设计 | 相似语言的能力不自动属于本语言 |
|
||
|
||
用户授权改文与用户确认语言设计是两件事。可以直接改善清晰度、目录和例子解释；新增名称规则、API、权限或结果状态需要具体依据。
|
||
|
||
## 主题、主定义与易错推断
|
||
|
||
| 主题 | 应读取的文件 | 特别核对 |
|
||
| --- | --- | --- |
|
||
| 定位 | guide/01-overview.md；appendices/application-domains.md | 前后端与 Agent 的统一语言定位；不要写成只服务界面的 DSL |
|
||
| 身份 | guide/02-user-identity.md | handle 唯一、显示名可重复；归属、操作身份与作者有区别；唯一不等于永久不变 |
|
||
| namespace | guide/03-namespaces.md；appendices/code-storage-and-views.md | 用户名加至少一级路径；层级语义一致；归属来自外部索引，不从源码文件目录推导 |
|
||
| 导入 | guide/04-program-structure.md | use 后是完整 key；导入不改变归属，不授予权限，不自动执行 |
|
||
| 阶段 | guide/05-preflight-and-inflight.md | Preflight 与 inflight 大小写；阶段不等于前后端位置，也不是新增关键字 |
|
||
| 词法 | guide/06-lexical-structure.md；appendices/formal-grammar.md | 草案中的标识符与字面量，不外推完整 Unicode、关键字或转义规则 |
|
||
| 类型 | guide/07-types-and-classes.md | class 结构不等于持久化实体、自动建表或自动具有 get |
|
||
| 表达式 | guide/08-expressions-and-bindings.md | 结合与优先级不自动决定所有调用的求值顺序 |
|
||
| 调用 | guide/09-functions-and-calls.md | 普通调用保留值、类型、依赖和业务效果；不能擅自并行、重试或假定纯函数 |
|
||
| 数据 | guide/10-data-access.md | Product.get 是提案；业务 id 与 namespace key 不同；成功、缺失、失败、未就绪不能混写 |
|
||
| UI | guide/11-scenes-and-render-trees.md；guide/12-ui-components.md | 单根限制针对 render；官方组件来源未定；用户库不默认提供官方组件 |
|
||
| Agent | appendices/application-domains.md；appendices/specification-status.md | 应用方向不代表声明、工具、委托或权限语法已确定 |
|
||
|
||
所有主题同时核对 appendices/specification-status.md。涉及词形、产生式或组合约束时再核对 appendices/formal-grammar.md；纯措辞修改不必重读全书。
|
||
|
||
## 三种状态如何落笔
|
||
|
||
**已确定约定**直接陈述事实，例如“use 引用一个完整 namespace key”。精确链接指向主定义，其他页按需要作短说明。
|
||
|
||
**已收录提案**可以清楚说明提案内部的规则。在章节入口或第一次关键例子旁标明状态，不把每句都改成“可能”“也许”。
|
||
|
||
**未定义边界**写明缺少的维度，例如“别名和同名冲突的名称查找形式尚未定义”，并链接状态位置。不要用含糊的“待完善”遮住会影响例子合法性的缺口。
|
||
|
||
## 处理冲突
|
||
|
||
先抄出两处冲突的具体断言，分别找到状态或用户决定依据。若只是旧写法残留，按明确决定修正并搜索同类残留；若实际需要新语义，完成不依赖该选择的部分，向用户提出最小必要决定。
|
||
|
||
例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定用户名是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。
|
||
|
||
[语义契约](semantic-contracts.md) · [语义变更任务](../tasks/TASK-06.md)
|