# TSL 基础语法完整版

> 本文档是 `$tsl-guide` 的子文档，聚焦基础语法。代码风格与命名规范请见 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`。

## 目录

- [语言元素与注释](#语言元素与注释)
- [变量与常量](#变量与常量)
- [数据类型与字面量](#数据类型与字面量)
- [数组与表数组](#数组与表数组)
- [运算符与表达式](#运算符与表达式)
- [函数](#函数)
- [控制流](#控制流)
- [异常处理](#异常处理)
- [调试与性能相关语句](#调试与性能相关语句)

---

## 语言元素与注释

### 标识符与关键字

- 关键字为保留字（完整列表见 `docs/tsl/syntax_book/01_language_basics.md`）
- 标识符用于变量、函数、类、unit 等命名

### 注释

```tsl
// 行注释
{ 块注释 }
/* 另一种块注释 */
```

### 编译选项（语法级）

```tsl
{$Explicit+}  // 要求变量先声明再使用
{$Explicit-}  // 关闭显式声明
{$VarByRef-}  // 默认参数按值传递（可用 in/var/out 覆盖）
```

---

## 变量与常量

### 赋值

```tsl
a := 1;
b := 2.5;
s := "hello";
```

### 常量

```tsl
const kPi = 3.14159;
const kMaxRetry = 3;
```

### 显式变量声明（配合 `{$Explicit+}`）

```tsl
{$Explicit+}

var a, b;          // 多变量声明
var c := 10;       // 声明并初始化
var d: integer;    // 类型可写可省（类型信息不做强校验）
```

---

## 数据类型与字面量

常见类型（参考 `01_language_basics.md`）：

| 类型 | 说明 |
|------|------|
| Integer / Int64 | 整数 |
| Real | 浮点数 |
| Boolean | 布尔值（true/false） |
| TDateTime | 日期时间 |
| String | 字符串 |
| Binary | 二进制 |
| Array | 数组 |
| Matrix / TMatrix | 矩阵 |
| NIL | 空值 |

示例：

```tsl
i := 42;
r := 3.14;
b := true;
t := Date();
s := 'hello';
n := nil;
```

字符串支持单引号或双引号，索引访问从 0 开始：

```tsl
s := "ABC";
ch := s[0];
```

---

## 数组与表数组

### 一维数组（0-based）

```tsl
arr := array(2, 3, 5, 7, 11);
first := arr[0];
```

### 字符串下标（表数组）

```tsl
row := array("Code": "0001", "Price": 12.3);
code := row["Code"];
```

### 多维数组

```tsl
matrix := array((1, 2, 3), (4, 5, 6));
value := matrix[0][1];
```

---

## 运算符与表达式

### 常用运算符

- 赋值：`:=`, `+=`, `-=`, `*=`, `/=`
- 算术：`+ - * / div mod ^`
- 关系：`= <> < > <= >= like in`
- 逻辑：`and or not`
- 三目：`cond ? a : b`

示例：

```tsl
c := a + b;
ok := (a = b) or (a > 0);
x := (a > b) ? a : b;
```

矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。
完整运算符清单见 `01_language_basics.md`。

---

## 函数

### 基本结构

```tsl
function HelloTsl();
begin
    d := Date();
    return DateToStr(d);
end;
```

### 参数分隔与类型注解

类型注解仅用于说明与阅读，编译器不做类型检查。

- 无类型注解时用逗号分隔参数
- 带类型注解时用分号分隔参数
- 返回值类型写在 `)` 之后

```tsl
function F1(a, b);
function F2(a: string; b: array of real);
function F3(): void;
```

### 形参与实参（in/const/var/out）

```tsl
function Calc(in a, var b, out c);
begin
    b := b + a;
    c := b * 2;
    return c;
end;
```

### 缺省参数（新一代语法）

```tsl
function Foo(a, b = a + 1);
begin
    return b;
end;
```

### 命名参数（新一代语法）

```tsl
function FuncA(a, b, c);
begin
    return array(a, b, c);
end;

result := FuncA(1, c: 3); // b 默认为 nil
```

### 变参（`...`）与 Params

```tsl
function SumAll(...);
begin
    total := 0;
    for i, v in Params do
        total := total + v;
    return total;
end;
```

相关内置：`Params`, `ParamCount`, `RealParamCount`。

### 返回与退出

```tsl
return value; // 返回
exit;         // 退出函数
```

### 外部函数声明（external）

```tsl
function GetTickCount(): integer; stdcall; external "kernel32.dll" name "GetTickCount" keepresident;
```

更多外部接口与调用方式见 `03_functions.md`。

---

## 控制流

### if / else if

```tsl
if x > 0 then
    y := 1;
else if x = 0 then
    y := 0;
else
    y := -1;
```

### if 表达式（新一代语法）

```tsl
ret := if x > 0 then x * x else 0;
```

### case

```tsl
case age of
    0: WriteLn("Baby");
    1: WriteLn("Toddler");
else
    WriteLn("Other");
end;
```

### while / repeat

```tsl
while cond do
    DoSomething();

repeat
    DoSomething();
until cond;
```

### for（to / downto / step）

```tsl
for i := 1 to 10 do
    sum := sum + i;

for i := 10 downto 1 step 2 do
    sum := sum + i;
```

### for ... in（数组遍历）

```tsl
data := array('a': 1, 'b': 5, 'c': 3);
sum := 0;

for k, v in data do
    sum := sum + v;
```

### break / continue / goto

```tsl
while cond do
begin
    if stop then break;
    if skip then continue;
    // ...
end;

goto found;
label found;
    WriteLn("jumped");
```

---

## 异常处理

### Try / Except

```tsl
try
    v := StrToInt(s);
except
    v := 0;
    WriteLn(ExceptObject.ErrInfo);
end;
```

### Try / Finally

```tsl
try
    DoWork();
finally
    Cleanup();
end;
```

### Raise

```tsl
if a < 0 then raise "A 不能小于 0";
```

异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。

---

## 调试与性能相关语句

```tsl
debugreturn 1;
```

```tsl
t1 := mtic;
// ...
elapsed := mtoc(t1);
```

更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。