tsl-devkit/docs/tsl/syntax/02_quickstart.md

# Syntax Quickstart

文档类型：语法主线
是否可直接用于生成代码：是
是否含已验证可执行示例：是
是否含已验证反例：是
遇到不确定时跳转到：[03_core_model.md](03_core_model.md)、[06_functions_and_calls.md](06_functions_and_calls.md)、[10_units_and_scope.md](10_units_and_scope.md)

手册位置：第 2 篇，共 32 篇。上一篇：[01_introduction.md](01_introduction.md)。下一篇：[03_core_model.md](03_core_model.md)。

这一篇集中回答两个紧邻问题：现在要写 TSL 时，应该从哪一种最短骨架起手；以及落代码前必须先核对哪些语言硬规则。

## 这一篇解决什么问题

快速回答“当前任务应该从松散语句、函数、类还是 unit 开始”，并提供一份单点的语言核心事实速查。

## 语言核心事实速查

这一节是当前语法手册默认的语言硬规则收口点。涉及赋值、顶层外形、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。

- 普通赋值用 `:=`，不要把 `=` 当成普通赋值。
- 顶层主体先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
- 如果当前文件采用顶层 `function / procedure` 模型，就不要再混入松散语句。
- 无返回值时用 `procedure Name(...); begin ... end;`，不要勉强用 `function`。
- 顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`。
- 多文件组织默认先按 `unit Name; interface ... implementation ... end.` 理解。
- 命名参数写法是 `Func(a:1, b:2)`。
- `array(...)` 既可以写顺序数组，也可以写字符串键表；数组下标从 `0` 开始，字符串下标从 `1` 开始。

## 术语对照

- 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，指的是同一类顶层模型：文件以顶层 `function` / `procedure` 为主体。
- 文档里出现的 `class function` 和“类方法”，指的是同一件事：前者是代码关键字写法，后者是中文描述。

## 先选哪一种骨架

| 当前任务                       | 起手骨架            |
| ------------------------------ | ------------------- |
| 只写一段一次性脚本逻辑         | 顶层松散语句        |
| 先沉淀一个可复用逻辑块         | 顶层 `function`     |
| 需要对象状态、字段、方法       | `type Name = class` |
| 需要把接口和实现组织进一个模块 | `unit`              |

默认建议：

- 如果你只是要让新 session 先写出一段最稳、最容易续写的基础语法，优先从顶层 `function` 开始。
- `uses` 往往天然进入多文件查找路径问题，所以不放进这篇的最小起手骨架里。

## 已验证最小骨架

顶层松散语句骨架：

代码块身份：已验证可执行示例

```tsl
a := 1;
```

顶层函数骨架：

代码块身份：已验证可执行示例

```tsl
function Demo();
begin
    return 1;
end;
```

顶层类骨架：

代码块身份：已验证可执行示例

```tsl
type DemoType = class
end;
```

顶层 `unit` 骨架：

代码块身份：已验证可执行示例

```tsl
unit DemoUnit;
interface
    function Ping();

implementation
    function Ping();
    begin
        return 1;
    end;
end.
```

## 最常用起手版本

如果你现在没有明确的多文件或对象建模需求，直接从函数版本开始：

代码块身份：已验证可执行示例

```tsl
function Hello();
begin
    return 1;
end;
```

## 最容易写错的一件事

- 不要把“顶层函数定义”和“顶层松散语句”混写在同一个最小文件里。

代码块身份：反例 / 不可照写

```text
function Add(a, b);
begin
    return a + b;
end;

value := Add(1, 2);
```

上面这种“先定义顶层函数，再接松散语句”的混合写法会编译失败。

## 跳转指引

- 先建立整体读法：见 [01_introduction.md](01_introduction.md)
- 继续判断顶层模型：见 [03_core_model.md](03_core_model.md)
- 继续写函数：见 [06_functions_and_calls.md](06_functions_and_calls.md)
- 继续写 `unit` / `uses`：见 [10_units_and_scope.md](10_units_and_scope.md)
- 继续写类：见 [09_objects_and_classes.md](09_objects_and_classes.md)