docs: establish Endorphin language documentation baseline
This commit is contained in:
@@ -0,0 +1,30 @@
|
||||
# 应用领域
|
||||
|
||||
各应用领域共用身份、namespace、类型、表达式、调用以及 Preflight / inflight 阶段模型。领域划分用于说明用途，不为每个领域建立不同的语言基础。
|
||||
|
||||
| 领域 | 语言中的内容 | 参考章节 |
|
||||
| --- | --- | --- |
|
||||
| UI | 场景、渲染树、组件及展示效果 | [场景与渲染树](../guide/11-scenes-and-render-trees.md)、[UI 组件](../guide/12-ui-components.md) |
|
||||
| 业务逻辑 | 函数、结果、调用组合及业务效果 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| 数据结构与访问 | class、共享类型、读取与字段使用 | [类型与类](../guide/07-types-and-classes.md)、[数据读取](../guide/10-data-access.md) |
|
||||
| Agent | 后续的能力、上下文、任务及行为模型 | [规范状态](specification-status.md#agent) |
|
||||
|
||||
## 跨领域调用
|
||||
|
||||
普通调用是共有语义。UI、业务逻辑或后续 Agent 代码可以在允许访问的前提下使用相应逻辑，而不为跨领域调用建立独立的 RPC 协议声明。
|
||||
|
||||
类似 RPC 的体验指“调用逻辑并取得结果”。输入、输出、依赖和失败需要在语言中明确，传输客户端、连接方式和缓存由系统承担。
|
||||
|
||||
## 领域与 namespace
|
||||
|
||||
`alice:shop.ui`、`alice:shop.pricing`、`alice:shop.data` 和 `alice:shop.agents` 是组织示例，不是强制目录或具有特殊行为的保留路径。
|
||||
|
||||
namespace 的名称不自动决定逻辑在何处执行。一个 namespace 也不必只包含一种声明类别。
|
||||
|
||||
## Agent 范围
|
||||
|
||||
Agent 尚无具体源码语法。需要独立定义的内容包括能力、工具、上下文、任务、生命周期、权限，以及确定性代码和模型驱动行为的边界。
|
||||
|
||||
本书不为尚未定义的领域提供虚构关键字或 API；其扩展仍应共用语言已有的组织与调用模型。
|
||||
|
||||
[目录](../README.md)
|
||||
@@ -0,0 +1,38 @@
|
||||
# 代码存储与视图
|
||||
|
||||
本附录说明无源码文件模型中的代码组织约定。它补充 namespace 的逻辑视图，不定义业务数据的存储方式。
|
||||
|
||||
## 独立代码段
|
||||
|
||||
代码分别存储为独立代码段，每段关联一个唯一用户和至少一级 namespace。S3 承担代码内容的存储职责，索引维护 namespace key 与代码段的成员关系。
|
||||
|
||||
源码文件不作为代码身份或 module 边界。本书中的 Markdown 文件是文档章节，不对应语言中的源码组织单位。
|
||||
|
||||
代码段的具体语法粒度尚未定义，不能将一个场景、一条声明或一个 S3 对象直接规定为同一种单位。
|
||||
|
||||
## 索引与视图
|
||||
|
||||
```text
|
||||
完整 namespace key
|
||||
→ 索引中的成员关系
|
||||
→ S3 中的独立代码段
|
||||
→ namespace 的可见代码视图
|
||||
```
|
||||
|
||||
视图是逻辑上的代码集合。它的归属来自 key 与索引，不由对象名或物理目录确定。
|
||||
|
||||
S3 对象键不是语言中的 namespace key。bucket 名、对象键和存储接口不属于业务源码语法。
|
||||
|
||||
## 视图与程序结构
|
||||
|
||||
程序结构描述视图内导入与声明的语法关系，见[程序结构与导入](../guide/04-program-structure.md)。这一结构不要求将物理对象按文件顺序机械拼接。
|
||||
|
||||
视图成员范围、下级 namespace 是否纳入、导入作用范围、声明顺序、版本一致性与编辑映射尚未定义，统一记录在[规范状态](specification-status.md#引用与代码视图)。
|
||||
|
||||
## namespace 制
|
||||
|
||||
namespace 同时表达归属与查找位置，使业务函数、类型、场景和后续 Agent 代码遵循一致的组织模型。第一级与后续层级具有相同语义。
|
||||
|
||||
这一组织选择不自动决定构建边界、执行位置、权限继承或业务数据存储。相关语义需要由各自规则定义，而不是从 S3 物理布局推导。
|
||||
|
||||
[相关章节：namespace](../guide/03-namespaces.md) · [目录](../README.md)
|
||||
@@ -0,0 +1,124 @@
|
||||
# 形式文法
|
||||
|
||||
本附录集中列出正文采用的文法草案。文法说明可表达的源码结构；名称、类型、可见性与执行效果由相应章节定义。各主题的确定程度见[规范状态](specification-status.md)。
|
||||
|
||||
## EBNF 记法
|
||||
|
||||
| 记法 | 含义 |
|
||||
| --- | --- |
|
||||
| `=` | 定义产生式 |
|
||||
| `;` | 结束产生式 |
|
||||
| `|` | 选择 |
|
||||
| `,` | 顺序连接 |
|
||||
| `[ ... ]` | 可选项 |
|
||||
| `{ ... }` | 零次或多次重复 |
|
||||
| `( ... )` | 产生式分组 |
|
||||
| 引号中的文本 | 源码终结符 |
|
||||
|
||||
产生式中的逗号和分号属于 EBNF 记法，不要求源码在相同位置包含分隔符。任意词法单元之间可出现空白或行注释。EOF 表示输入结束。
|
||||
|
||||
## 程序与导入
|
||||
|
||||
```ebnf
|
||||
program = { use-decl }, declaration, { declaration }, EOF ;
|
||||
declaration = class-decl | function-decl | scene-decl ;
|
||||
|
||||
use-decl = "use", namespace-key ;
|
||||
namespace-key = user-handle, ":", namespace-path ;
|
||||
namespace-path = identifier, { ".", identifier } ;
|
||||
```
|
||||
|
||||
user-handle 是系统认可的唯一用户名，由身份规则提供，不等同于源码 identifier。代码自身的归属通过外部上下文提供，程序文法中没有自身 namespace 声明。
|
||||
|
||||
相关说明：[namespace](../guide/03-namespaces.md)、[程序结构与导入](../guide/04-program-structure.md)。
|
||||
|
||||
## 类与类型
|
||||
|
||||
```ebnf
|
||||
class-decl = "class", identifier, "{", { field-decl }, "}" ;
|
||||
field-decl = identifier, ":", type-name ;
|
||||
type-name = identifier ;
|
||||
```
|
||||
|
||||
相关说明：[类型与类](../guide/07-types-and-classes.md)。
|
||||
|
||||
## 函数与绑定
|
||||
|
||||
```ebnf
|
||||
function-decl = "function", identifier, "(", [ parameters ], ")",
|
||||
":", type-name, block ;
|
||||
parameters = parameter, { ",", parameter } ;
|
||||
parameter = identifier, ":", type-name ;
|
||||
|
||||
block = "{", { binding }, return-stmt, "}" ;
|
||||
binding = "let", identifier, "=", expression ;
|
||||
return-stmt = "return", expression ;
|
||||
```
|
||||
|
||||
本基本函数体文法只包含绑定和末尾返回，不覆盖完整控制流或独立表达式语句。
|
||||
|
||||
相关说明：[表达式与绑定](../guide/08-expressions-and-bindings.md)、[函数与调用](../guide/09-functions-and-calls.md)。
|
||||
|
||||
## 表达式
|
||||
|
||||
```ebnf
|
||||
expression = sum ;
|
||||
sum = product, { ("+" | "-"), product } ;
|
||||
product = unary, { ("*" | "/"), unary } ;
|
||||
unary = "-", unary | postfix ;
|
||||
postfix = primary, { member-access | call-arguments } ;
|
||||
|
||||
member-access = ".", identifier ;
|
||||
call-arguments = "(", [ expression-list ], ")" ;
|
||||
expression-list = expression, { ",", expression } ;
|
||||
|
||||
primary = identifier | string | number | symbol
|
||||
| "(", expression, ")" ;
|
||||
```
|
||||
|
||||
成员访问与调用先于一元负号，一元负号先于乘除，乘除先于加减。正文采用同级二元算术运算从左到右组合的规则。
|
||||
|
||||
此处能表达成员调用，不代表某个类型自动拥有相应成员。数据读取提案使用同一套表达式文法，没有单独的 get 关键字。
|
||||
|
||||
相关说明：[表达式与绑定](../guide/08-expressions-and-bindings.md)、[数据读取](../guide/10-data-access.md)。
|
||||
|
||||
## 场景与渲染节点
|
||||
|
||||
```ebnf
|
||||
scene-decl = "export", "scene", identifier, "{", render-decl, "}" ;
|
||||
render-decl = "render", "{", node, "}" ;
|
||||
|
||||
node = identifier, [ arguments ], [ children ] ;
|
||||
arguments = "(", [ argument, { ",", argument } ], ")" ;
|
||||
argument = [ identifier, ":" ], expression ;
|
||||
children = "{", { node }, "}" ;
|
||||
```
|
||||
|
||||
render 内单根结构由产生式表达。组件是否接受子节点、参数是否合法以及 render 内可使用哪些表达式效果，属于语义规则。
|
||||
|
||||
相关说明：[场景与渲染树](../guide/11-scenes-and-render-trees.md)、[UI 组件](../guide/12-ui-components.md)。
|
||||
|
||||
## 词法
|
||||
|
||||
```ebnf
|
||||
identifier = identifier-start, { identifier-continue } ;
|
||||
identifier-start = "_" | unicode-letter ;
|
||||
identifier-continue = "_" | unicode-letter | unicode-number ;
|
||||
|
||||
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
|
||||
number = digit, { digit }, [ ".", digit, { digit } ] ;
|
||||
symbol = ".", identifier ;
|
||||
|
||||
string = '"', { string-character | escape }, '"' ;
|
||||
escape = "\\n" | "\\t" | '\\"' | "\\\\" ;
|
||||
|
||||
line-comment = "//", { character-except-line-feed }, [ line-feed ] ;
|
||||
```
|
||||
|
||||
unicode-letter、unicode-number、string-character、character-except-line-feed 和 line-feed 为词法字符类别。string-character 不包括未转义的双引号、反斜杠和换行；负号不属于 number。
|
||||
|
||||
Unicode 分类边界及源码中的换行字符规则列于[规范状态](specification-status.md#词法与表达式)。
|
||||
|
||||
相关说明：[词法结构](../guide/06-lexical-structure.md)。
|
||||
|
||||
[目录](../README.md)
|
||||
@@ -0,0 +1,27 @@
|
||||
# 术语表
|
||||
|
||||
| 术语 | 定义 | 详见 |
|
||||
| --- | --- | --- |
|
||||
| Endorphin | 用统一声明与调用模型描述前后端应用的云原生编程语言 | [语言概览](../guide/01-overview.md) |
|
||||
| 用户名 / handle | 在系统内唯一标识用户并参与代码定位的名称 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 显示名 | 用于界面展示、可重复的姓名或昵称 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 归属用户 | namespace key 指定的代码所属用户 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 操作用户 | 发起本次读取、修改或执行的身份 | [用户身份](../guide/02-user-identity.md) |
|
||||
| namespace | 代码归属、组织与检索的单位 | [namespace](../guide/03-namespaces.md) |
|
||||
| namespace key | 用户名与非空 namespace 路径组成的定位标识 | [namespace](../guide/03-namespaces.md) |
|
||||
| 代码段 | 独立存储、具有明确归属的代码内容单位 | [代码存储与视图](code-storage-and-views.md) |
|
||||
| 可见代码视图 | 由索引成员关系获得的 namespace 逻辑代码集合 | [代码存储与视图](code-storage-and-views.md) |
|
||||
| use | 引用完整 namespace key 的声明 | [程序结构与导入](../guide/04-program-structure.md) |
|
||||
| Preflight | 理解、检查和准备程序的构建阶段 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| inflight | 使用实际输入执行逻辑并产生可观察结果的运行阶段 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| 类型 | 描述值的结构及其允许用法的定义 | [类型与类](../guide/07-types-and-classes.md) |
|
||||
| class | 数据结构声明 | [类型与类](../guide/07-types-and-classes.md) |
|
||||
| 表达式 | 描述计算并产生值的源码形式 | [表达式与绑定](../guide/08-expressions-and-bindings.md) |
|
||||
| 绑定 | 将表达式结果关联到局部名称 | [表达式与绑定](../guide/08-expressions-and-bindings.md) |
|
||||
| 函数 | 定义输入、结果和执行逻辑的可调用声明 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| 数据依赖 | 后续计算需要前一计算结果的关系 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| 场景 / scene | 描述一个 UI 视图的声明 | [场景与渲染树](../guide/11-scenes-and-render-trees.md) |
|
||||
| 渲染树 | render 块内由组件节点组成的树 | [场景与渲染树](../guide/11-scenes-and-render-trees.md) |
|
||||
| 符号字面量 | 以点号和标识符表达的命名值，如 `.title` | [词法结构](../guide/06-lexical-structure.md) |
|
||||
|
||||
[目录](../README.md)
|
||||
@@ -0,0 +1,111 @@
|
||||
# 规范状态
|
||||
|
||||
本附录记录语言设计的确定程度与尚未定义的边界。它用于理解设计稿，不代表软件实现进度或可执行性保证。
|
||||
|
||||
## 已确定约定
|
||||
|
||||
| 主题 | 已确定内容 |
|
||||
| --- | --- |
|
||||
| 语言定位 | 前后端共用的云原生编程语言，UI 是应用领域之一 |
|
||||
| 代码归属 | 每段代码属于唯一用户名和至少一级 namespace |
|
||||
| 用户身份 | 使用唯一 handle 定位，不用显示名替代 |
|
||||
| namespace | 各层语义一致；以外部 key 检索，不在正文声明自身归属 |
|
||||
| key 形式 | `用户名:namespace路径`，冒号分隔用户与路径，点号分隔层级 |
|
||||
| use | 引用完整 namespace，不附加选择性名称列表 |
|
||||
| 代码组织 | 独立代码段存储在 S3，由索引组装可见代码视图，不采用源码文件 module 制 |
|
||||
| 数据结构目标 | 用 class 表达共享结构，通过类取得数据的具体形式另行定义 |
|
||||
| 调用目标 | 普通逻辑调用表达输入、结果与依赖，系统组织执行 |
|
||||
| 官方组件 | 官方 UI 组件与用户库内容分别定义 |
|
||||
| 阶段命名 | 构建阶段为 Preflight，运行阶段为 inflight；名称本身不增加源码关键字 |
|
||||
|
||||
## 收录的语法提案
|
||||
|
||||
| 提案 | 正文位置 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 词法与字面量 | [第 6 章](../guide/06-lexical-structure.md) | 本书统一采用的标识符、字符串、数字和符号形式 |
|
||||
| 类字段与类型标注 | [第 7 章](../guide/07-types-and-classes.md) | class 目标已确定，字段和类型体系仍为具体写法提案 |
|
||||
| 表达式与 let | [第 8 章](../guide/08-expressions-and-bindings.md) | 基础运算、成员访问与局部绑定 |
|
||||
| function 与 return | [第 9 章](../guide/09-functions-and-calls.md) | 函数签名、基本函数体与调用组合 |
|
||||
| Product.get | [第 10 章](../guide/10-data-access.md) | 读取体验提案，不是 class 自动附带的 API |
|
||||
| 场景与组件 | [第 11、12 章](../guide/11-scenes-and-render-trees.md) | scene、render、参数、布局与默认值 |
|
||||
|
||||
程序声明组合与[形式文法](formal-grammar.md)同样属于设计稿。正文中的陈述定义这些提案内部的用法，不将其确定程度提升为最终规范。
|
||||
|
||||
## 身份与权限
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 用户名的字符、长度、大小写、Unicode 归一化及身份范围扩展。
|
||||
- handle 改名、旧名称复用、历史引用稳定性及账号生命周期。
|
||||
- 代码的默认公开性、读取与执行权限，以及 namespace 权限继承。
|
||||
- 协作、Agent 委托、操作身份记录与归属转移。
|
||||
|
||||
定位信息不构成授权，是这些规则必须保留的边界。
|
||||
|
||||
## 引用与代码视图
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 代码段的语法边界、视图成员范围和下级 namespace 的纳入方式。
|
||||
- use 的作用范围、声明可见性、限定名、别名与同名冲突。
|
||||
- 视图顺序、版本选择、成员一致性及编辑操作映射。
|
||||
- key 的传递编码和索引关联机制。
|
||||
|
||||
正文跨 namespace 示例采用目标声明可见、名称可直接解析且无冲突的条件；该条件不代替正式名称查找规则。
|
||||
|
||||
## 声明与类型
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 程序入口、空代码视图、多个场景的选择与顶层绑定。
|
||||
- 完整基础类型、数值范围、可选值、泛型及类型转换。
|
||||
- 类构造、方法、默认值、继承和字段可见性。
|
||||
- 重复声明、完整控制流、可变性、赋值和作用域细节。
|
||||
|
||||
本文简单函数体仅收录 let 与末尾 return，不意味着整门语言只允许这两种语句。
|
||||
|
||||
## 词法与表达式
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 完整保留字集合、Unicode 版本与字符类别边界。
|
||||
- 换行字符、字符串扩展转义、更多字面量和运算符。
|
||||
- 数值溢出、除法、隐式转换与所有调用参数的求值顺序。
|
||||
|
||||
正文中同级二元算术运算的组合顺序属于表达式提案，不规定所有调用的执行顺序。
|
||||
|
||||
## 调用与数据
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 显式等待、失败处理、缺失值、取消和超时的源码形式。
|
||||
- 数据读取成员的声明、参数与结果类型。
|
||||
- 一次结果、持续结果及其更新语义。
|
||||
- 带业务修改的调用顺序、重复执行限制与失败行为。
|
||||
- 更新代码时已有调用使用哪个版本。
|
||||
|
||||
正常结果必须符合声明，未就绪或失败不能伪造为成功结果。Product.get 示例只展示成功路径。
|
||||
|
||||
## UI
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 官方组件库的 key、显式引用形式与名称可见性。
|
||||
- 命名参数和位置参数的完整绑定规则及重复传参处理。
|
||||
- 渲染中的调用、状态、数据绑定、事件与更新。
|
||||
- 布局单位、参数范围、负数、显式尺寸、约束与溢出。
|
||||
- 主题、样式、文字测量和其他组件。
|
||||
|
||||
正文的官方组件示例省略未定义的依赖部分，不承诺免导入使用。
|
||||
|
||||
## Agent
|
||||
|
||||
Agent 是规划应用领域。声明、能力、工具、上下文、任务、生命周期、权限及模型驱动行为的边界尚未定义。
|
||||
|
||||
## 规范范围
|
||||
|
||||
本文定义源码及应有的语言效果。云端实体、持久化类、自动建表、通信、缓存、部署和编排实现不在本阶段规范中。
|
||||
|
||||
S3 约定仅用于代码存储，不规定业务数据后端。Preflight 与 inflight 的职责不要求特定机器码、执行图或部署产物。
|
||||
|
||||
[目录](../README.md)
|
||||
Reference in New Issue
Block a user