csh
40a9885eb4
- flag weak candidates (no intent/heading/identifier/tag hit) and exit 2 when every candidate is weak: mis-hits used to be indistinguishable from real hits, so the retry-with-better-terms loop never fired - accept multiple ids per --section for batch fetch, failing atomically on any unknown id so a partial fetch cannot pass as complete - move query synonyms and page intent aliases to data/lexicon.json and enforce alias/page correspondence in --check; curation data no longer lives in the engine - document the weak-hit rule, batch fetch and prelude-once guidance in SKILL.md, with curation discipline in data/README.md - drop 11_pitfalls.md, renumber the trailing pages and spread retrieval tags across topics; lexicon keys are page filenames, so the renumbering and the new --check rule cannot land in separate commits
53 lines
3.8 KiB
Markdown
53 lines
3.8 KiB
Markdown
# TSL 快速落代码规则
|
|
|
|
本篇提供一份单点的语言核心事实速查，以及没有任何复用或模块需求时的默认起手骨架。
|
|
|
|
## 本篇职责
|
|
|
|
在落代码前一次性给出跨专题的语言硬规则（赋值、文件形态、声明位置、命名参数、下标起点、类与 `unit` 外形），并提供术语对照和默认可执行脚本骨架。
|
|
|
|
## 语言核心事实速查
|
|
|
|
<!-- tags: 语法速查, 硬规则, 核心规则一览, 先看哪些, 常见规则汇总 -->
|
|
|
|
这一节是本语法手册默认的语言硬规则收口点。涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。
|
|
|
|
- 赋值：普通赋值用 `:=`，不要把 `=` 当成普通赋值。
|
|
- 后缀：用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，入口流程、脚本任务或一次性执行逻辑对应 `.tsl`，可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`，只是脚本内部封装函数或类时仍按 `.tsl` 处理；仍不明确时向用户确认。
|
|
- `.tsl`：可执行脚本，语句区在前并按顺序执行；函数 / 类声明区在后，供前面的语句调用或运行时解析。不要在声明区后面继续追加脚本语句。
|
|
- `.tsf`：可复用模块 / 函数扩展文件；非 `unit` 顶层函数 / 过程部署到解释器 `funcext` 后，脚本可以直接调用；顶层类声明只按可复用声明理解；`unit` 按模块组织理解。
|
|
- `.tsf` 文件名：文件名（不含扩展名）必须与第一个顶层声明同名，`UserAccount.tsf` 的顶层声明必须是 `function UserAccount`、`type UserAccount = class` 或 `unit UserAccount`。
|
|
- `function` / `procedure`：用户只说“写一个函数”时默认用 `function`；只有用户明确要求 `procedure` / 过程时才用 `procedure Name(...); begin ... end;`。
|
|
- 类：顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`；创建对象有两种方式，`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。
|
|
- `unit`：涉及多文件组织时，先按 `unit Name; interface ... implementation ... end.` 骨架理解；不要把 `unit` 当默认最小起手。
|
|
- 命名参数：写法是 `Func(a:1, b:2)`，不要写成 `Func(a = 1, b = 2)`。
|
|
- 下标：`array(...)` 既可以写顺序数组，也可以写字符串键表；顺序数组和 `binary(...)` 二进制缓冲区下标从 `0` 开始，字符串下标从 `1` 开始。
|
|
|
|
## 术语对照
|
|
|
|
- “脚本语句区”：`.tsl` 文件开头会按顺序执行的语句。
|
|
- “声明区”：`.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。
|
|
- “顶层 `function / procedure`”：在 `.tsf` 中指模块暴露的顶层函数 / 过程，在 `.tsl` 中指脚本声明区里的函数 / 过程。
|
|
- “顶层函数骨架”“顶层函数定义体”：只指 `function` 骨架；不要因为任务没有返回值就自动改成 `procedure`。
|
|
- `class function` / “类方法”：同一件事；前者是代码关键字写法，后者是中文描述。
|
|
|
|
## 默认起手骨架
|
|
|
|
<!-- tags: 起手模板, 从哪开始写, 最小可跑, 第一个脚本, hello world -->
|
|
|
|
如果用户只要求写一段代码、脚本或示例，且没有明确 `.tsf`、`unit`、模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始：
|
|
|
|
代码块身份：可直接照写示例
|
|
|
|
```tsl
|
|
echo "hello";
|
|
```
|
|
|
|
代码块身份：输出片段
|
|
|
|
```text
|
|
hello
|
|
```
|
|
|
|
代码块说明：这是默认可执行脚本骨架；没有复用或模块需求时，不要主动改成 `.tsf`。需要在语句区之后接函数或类声明区时，骨架见 [02_core_model.md](02_core_model.md)。
|