csh
736d1a8ad7
Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement. BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
106 lines
4.8 KiB
Markdown
106 lines
4.8 KiB
Markdown
# TSL 快速落代码规则
|
||
|
||
本篇提供一份由专题页逐条派生的语言核心事实速查，以及没有任何复用或模块需求时的默认起手骨架。
|
||
|
||
## 本篇职责
|
||
|
||
<!-- section-id: syntax-01-001 -->
|
||
|
||
在落代码前一次性汇总跨专题的语言硬规则（赋值、文件形态、声明位置、命名参数、下标起点、类与 `unit` 外形），并提供术语对照和默认脚本骨架。本页是强制读取的派生摘要，不独立拥有完整事实；每条规则的完整上下文仍由对应专题页拥有。
|
||
|
||
## 语言核心事实速查
|
||
|
||
<!-- section-id: syntax-01-002 -->
|
||
|
||
<!-- tags: 语法速查, 硬规则, 核心规则一览, 先看哪些, 常见规则汇总 -->
|
||
|
||
这一节是专题事实的强制派生速查，不是第二份事实源。写代码时先核对这里，再按当前任务的语法要素取回对应专题 Section；`--check` 会逐条比较下面的摘要与专题页 canonical 规则。
|
||
|
||
<!-- quickstart-rule: assignment -->
|
||
|
||
- 普通变量赋值使用 `:=`；`=` 在普通表达式里用于比较，不用于赋值。
|
||
|
||
<!-- quickstart-rule: file-choice -->
|
||
|
||
- 未给后缀时，入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`；只是脚本内部封装函数或类时，仍按 `.tsl` 处理；仍不明确时向用户确认，不要把脚本入口和可复用模块合并成一个猜测文件。
|
||
|
||
<!-- quickstart-rule: tsl-layout -->
|
||
|
||
- `.tsl` 脚本按两段理解：语句区在前并按顺序执行；声明区在后，可放 `function / procedure` 或 `type Name = class`。写 `.tsl` 时先写语句区，需要函数、过程或类时把声明区放在语句区之后。
|
||
|
||
<!-- quickstart-rule: tsf-layout -->
|
||
|
||
- 写 `.tsf` 时只写顶层函数 / 过程 / 类声明，或 `unit`；不要写成会直接顺序执行的脚本入口。
|
||
|
||
<!-- quickstart-rule: tsf-filename -->
|
||
|
||
- `.tsf` 文件名（不含扩展名）必须与第一个顶层声明同名；第一个声明可以是同名 `function`、`type Name = class` 或 `unit`。
|
||
|
||
<!-- quickstart-rule: function-default -->
|
||
|
||
- 用户提示词里的“函数”默认对应 `function`，不要自动改写成 `procedure`。
|
||
|
||
<!-- quickstart-rule: procedure-explicit -->
|
||
|
||
- `procedure Name(...); begin ... end;` 只在用户明确要求 `procedure` / 过程时生成；不要因为没有返回值就自动改用 `procedure`。
|
||
|
||
<!-- quickstart-rule: class-shape -->
|
||
|
||
- 类定义统一按 `type Name = class ... end;` 写。
|
||
|
||
<!-- quickstart-rule: object-creation -->
|
||
|
||
- 普通本地类实例化默认生成 `new ClassName()`；`createObject("ClassName")`、`createObject(ClassType)` 只在字符串类名、类类型变量或跨 `unit` 路径场景生成。
|
||
|
||
<!-- quickstart-rule: unit-shape -->
|
||
|
||
- `unit` 是完整的顶层主体；常见完整形态是 `unit Name; interface ... implementation ... end.`。
|
||
|
||
<!-- quickstart-rule: unit-default -->
|
||
|
||
- 如果没有特殊需求，默认优先用完整形态；简写形态只在不需要显式区分 `interface` / `implementation` 时再用。
|
||
|
||
<!-- quickstart-rule: named-arguments -->
|
||
|
||
- 调用时支持命名参数，写法是 `name: value`。
|
||
|
||
<!-- quickstart-rule: named-argument-order -->
|
||
|
||
- 一旦某次调用里开始使用命名参数，后面的参数就不能再退回位置参数。
|
||
|
||
<!-- quickstart-rule: index-origins -->
|
||
|
||
- `array(...)` 既可以写顺序数组，也可以写字符串键表；顺序数组和 `binary(...)` 二进制缓冲区下标从 `0` 开始，字符串下标从 `1` 开始。
|
||
|
||
## 术语对照
|
||
|
||
<!-- section-id: syntax-01-003 -->
|
||
|
||
- “脚本语句区”：`.tsl` 文件开头会按顺序执行的语句。
|
||
- “声明区”：`.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。
|
||
- “顶层 `function / procedure`”：在 `.tsf` 中指模块暴露的顶层函数 / 过程，在 `.tsl` 中指脚本声明区里的函数 / 过程。
|
||
- “顶层函数骨架”“顶层函数定义体”：只指 `function` 骨架；不要因为任务没有返回值就自动改成 `procedure`。
|
||
- `class function` / “类方法”：同一件事；前者是代码关键字写法，后者是中文描述。
|
||
|
||
## 默认起手骨架
|
||
|
||
<!-- section-id: syntax-01-004 -->
|
||
|
||
<!-- tags: 起手模板, 从哪开始写, 最小可跑, 第一个脚本, hello world -->
|
||
|
||
如果用户只要求写一段代码、脚本或示例，且没有明确 `.tsf`、`unit`、模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始：
|
||
|
||
代码块身份：可直接照写示例
|
||
|
||
```tsl
|
||
echo "hello";
|
||
```
|
||
|
||
代码块身份：输出片段
|
||
|
||
```text
|
||
hello
|
||
```
|
||
|
||
代码块说明：这是默认可执行脚本骨架；没有复用或模块需求时，不要主动改成 `.tsf`。需要在语句区之后接函数或类声明区时，骨架见 [02_core_model.md](02_core_model.md)。
|