104 lines
6.3 KiB
Markdown
104 lines
6.3 KiB
Markdown
# 4. 程序结构与导入
|
||
|
||
一个 namespace 的代码视图由导入和声明组成。声明描述类型、逻辑、agent 或界面；导入使代码能够引用其他 namespace 中允许使用的声明。基础内容也可作为资源归属到 namespace，但其登记方式不由代码视图文法定义。
|
||
|
||
## 4.1 正文结构
|
||
|
||
本文采用的程序结构为：
|
||
|
||
```text
|
||
零个或多个 use 声明
|
||
一个或多个 class、function 或 agent 声明
|
||
```
|
||
|
||
声明之间不使用逗号或分号。正文不含自身 namespace 声明，其归属来自外部 key 与索引。
|
||
|
||
“一个或多个”表示同一代码视图可以包含任意数量的这三类顶层声明，至少包含一个；不要求每类各出现一次，也不要求一个 namespace 只保存一个定义。
|
||
|
||
| 声明组合 | 表达的内容 |
|
||
| -------------- | --------------------- |
|
||
| 一个或多个 function | 一组可组合的逻辑入口或辅助计算 |
|
||
| 一个或多个 class | 一组共享数据结构及其成员定义 |
|
||
| 一个或多个 agent | 一组模型驱动的行为定义 |
|
||
| 三类声明混合 | 类型、普通逻辑和 agent 共同组成程序 |
|
||
|
||
顶层声明与内部成员是不同位置。class 内的成员函数仍是 function，但属于类的成员作用域；agent 内的变量、函数或类型也保留其共有语义，并与 agent 实例或运行职责关联。内部成员不会仅因使用相同关键字自动成为 namespace 的顶层成员。
|
||
|
||
这里描述代码视图中的声明结构，不表示查看视图就实例化全部 class、启动全部 agent 或执行全部函数。函数体里的 let 和 return 仍遵守函数体规则，图片、文本等非代码资源的登记也不靠增加占位 class 或 function 表达。
|
||
|
||
agent 是语言声明，内部复用共有成员结构并增加 agent 作用域及运行关联。声明骨架仍为提案；工具、记忆和控制关联的具体写法见[Agent](13-agents.md)。
|
||
|
||
这是一份逻辑代码视图的语法结构，不规定独立代码段的存储粒度或物理排列。代码段边界及视图组装规则见[代码存储与视图](../appendices/code-storage-and-views.md)。
|
||
|
||
## 4.2 use 声明
|
||
|
||
代码归属：`market:shop.checkout`。导入声明：
|
||
|
||
```endorphin
|
||
use atelier:shop.pricing
|
||
```
|
||
|
||
`use` 后跟一个完整 namespace key。workspace handle 与路径用冒号分隔，路径层级用点号分隔。每个 `use` 引用一个 namespace，不附加类名、函数名或选择性名称列表。
|
||
|
||
引用整个 namespace 表示指定依赖来源，不表示获得访问权限或自动执行其中的函数。
|
||
|
||
## 4.3 声明组合
|
||
|
||
代码归属：`atelier:shop.data`。
|
||
|
||
```endorphin
|
||
class Product {
|
||
name: String
|
||
price: Number
|
||
}
|
||
|
||
function listedPrice(product: Product): Number {
|
||
return product.price
|
||
}
|
||
```
|
||
|
||
同一视图可以同时包含类、函数和 agent。界面逻辑通过普通函数及其结果表达，与业务逻辑共用声明和表达式规则。
|
||
|
||
类与函数的内部结构分别在[类型与类](07-types-and-classes.md)和[函数与调用](09-functions-and-calls.md)中定义。查看资源和呈现界面结果见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||
|
||
以下是同一视图中的声明关系示意，不是完整源码。沿用 Product 与 listedPrice，agent 的工具关联形式尚未定义：
|
||
|
||
```text
|
||
namespace 代码视图
|
||
Product：class 定义
|
||
listedPrice：function 定义，使用 Product
|
||
定价 agent：agent 定义
|
||
内部变量与辅助函数
|
||
引用 listedPrice，或在内部实现其他工具逻辑
|
||
```
|
||
|
||
这三项可以共同存在，但拥有各自的声明身份。agent 引用 listedPrice 不改变函数归属，也不把该函数自动变为 agent 的内部成员。类、函数或 agent 的声明先进入 Preflight 准备，其调用或实例使用属于 inflight。
|
||
|
||
声明之间的依赖不要求按执行顺序将所有代码写在一个文件里；视图顺序、前向引用与名称冲突仍按各自的规则确定。独立代码段是否与一条顶层声明对应，也不由此示意规定。
|
||
|
||
## 4.4 名称引用
|
||
|
||
导入后的声明必须依据可见性和名称查找规则使用。跨 namespace 示例采用“导入的名称可直接查找且没有冲突”的简化条件，用于展示调用含义；这不是对全部声明自动进入作用域的承诺。
|
||
|
||
名称限定、别名、同名冲突与可见性规则列于[规范状态](../appendices/specification-status.md#引用与代码视图)。官方 UI 组件的来源单独说明，不属于示例用户库。
|
||
|
||
名称解析、代码可视域和平台权限分别承担三个判断：找到哪个声明、当前代码位置能否引用它、操作身份能否对它进行本次操作。use 完成依赖表达，不替代后两个判断。
|
||
|
||
按已确定的操作分工，阅读源码使用 `r`，编辑定义使用 `w`，调用程序入口使用 `x`。业务调用可以按入口契约产生数据写入，不需要因为这一效果给调用用户整个归属范围的编辑权。只具有 `x` 时所需签名与接口信息如何提供，仍待定义，不能据此承诺全部源码可见。
|
||
|
||
平台权限统一放在 workspace 层，内部声明仍可以具有自己的语言可视域。一个用户即使拥有整个 workspace 的 `r`，外部函数也不能绕过成员可见性；允许外部引用的声明也不会自动向无授权用户开放。主定义见[平台权限与代码可视域](02-user-identity.md#29-平台权限与代码可视域)。
|
||
|
||
本文的 atelier 与 market 都是 workspace handle。编写、修改或调用代码的用户可以不同；成员变化不改变 use 中引用的 workspace。
|
||
|
||
## 4.5 程序与局部片段
|
||
|
||
本书区分三类示例：
|
||
|
||
- 声明示例：展示可以出现在代码视图中的类、函数或 agent；未定关联形式采用结构示意。
|
||
- 函数体片段：展示 let、return 或局部表达式。
|
||
- 结构与访问示意：展示界面组成或资源访问行为，不表示源码。
|
||
|
||
局部片段用于查询语法，不自动成为程序顶层入口。入口选择、空视图与定位形式仍列于[规范状态](../appendices/specification-status.md#声明与类型)。
|
||
|
||
[上一章：namespace](03-namespaces.md) · [下一章：Preflight 与 inflight](05-preflight-and-inflight.md) · [目录](../README.md)
|