playbook/skills/tsl-syntax-reference/references/04_variables_and_constants.md

TSL 变量与常量

这一篇收拢变量与常量初始化规则。

本篇职责

回答“普通变量怎样直接使用、var 在什么位置出现、常量必须怎样初始化、global 怎样跨函数共享，以及运行时常量怎样冻结一次调用中的表达式结果”。

核心规则

• 默认变量模型是“直接赋值即得到变量”，不要求先写 var。
• 例如：a := 1; b := array(1, 2, 3); 这种写法可直接编译。
• 这条只覆盖整体赋值；对还没建立的变量直接写单元格赋值（q[0][0] := 1;）会在运行时报 变量类型不是Array，要先用 q := array(); 建立容器再写下标。
• var name; 只作为显式声明写法，不能当成默认必需步骤。
• const name = value; 是常量初始化的默认生成写法；const 不能只声明名字而不初始化。
• 文档规则：
  • const name = value; 适合顶层脚本常量、函数内部 const 段、unit 接口常量、类成员常量。
  • 顶层脚本里的 const name = value; 可以放在后续脚本语句之前；单独只写一行 const name = value; 不作为可运行脚本骨架。
• 函数内部 const = expr、以及松散脚本顶层的 const = expr，都可以把右侧写成常量表达式。
• 用 const = 初始化的这些常量不能再次赋值。
• 多参数赋值文档明确写法是 [a, b] := array(...)。
• 左侧只有一个变量时，末尾逗号不能省略，必须写成 [a, ] := array(...)。
• 当左侧变量数大于右侧数组长度时，多出的变量会得到 nil。
• 右侧数组元素也可以是数组；拆出来的变量会直接得到对应子数组。
• 多参数赋值也可以出现在函数调用参数里。
• {$explicit+} 开启后，后续变量必须先用 var 声明；未声明变量会报 variable not defined。
• global x, y; 声明当前任务中的全局变量；每个需要访问它的函数都要再次写 global 声明。
• const name := expression; 是运行时常量：进入所属函数时计算，当前调用内不可再次赋值；不要与编译时常量 const name = expression; 混写。

可直接照写示例

使用这些示例时遵守：

• 默认生成普通变量时直接用 :=；只有用户明确要求或 {$explicit+} 场景才复制 var。
• 普通示例默认按 .tsl 脚本语句区书写；需要函数或类型时，放在后置声明区。
• 复制常量示例时只使用 const name = value;。

普通变量与显式声明

默认变量模型：

代码块身份：可直接照写示例

a := 1;
b := array(1, 2, 3);
writeLn(a);
writeLn(b[1]);

代码块身份：输出片段

1
2

显式 var 写法：

代码块身份：可直接照写示例

var a;
a := 1;

整体赋值免声明，但单元格赋值不免——容器要先建立：

代码块身份：可直接照写示例

whole := rand(3, 3);
writeLn(mRows(whole));
cell := array();
cell[0][0] := 1;
writeLn(cell[0][0]);

结果说明：

• 依次输出 3、1
• whole := rand(3, 3) 说明整体接一个数组不需要先声明
• cell := array(); 这一行不能省；省掉后 cell[0][0] := 1; 会在运行时报 变量类型不是Array，因为下标赋值需要一个已经是数组的容器

代码块身份：输出片段

3
1

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

q[0][0] := 1;

对还没建立的变量直接写单元格赋值会运行时报 变量类型不是Array；先写 q := array();。

{$explicit+} 下的显式声明：

代码块身份：可直接照写示例

{$explicit+}
var a;
a := 1;
writeLn(a);

代码块身份：输出片段

1

常量初始化

顶层最稳的常量写法：

代码块身份：可直接照写示例

const kValue = 1;
echo kValue;

代码块身份：输出片段

1

顶层 const = 也可以写常量表达式：

代码块身份：可直接照写示例

const kValue = 1 + 2 * 3;
writeLn(kValue);

代码块身份：输出片段

7

函数内部 const 段：

代码块身份：可直接照写示例

function Demo();
const max_retries = 1 + 2 * 3;
begin
    return max_retries;
end;

unit 接口常量：

代码块身份：可直接照写示例

unit DemoUnit;

interface

const kValue = 1;
function GetValue();

implementation

function GetValue();
begin
    return kValue;
end;

end.

类成员常量：

代码块身份：可直接照写示例

type DemoType = class
public
    const kValue = 1;
end;

顶层 const = 只有在“后面继续接可执行语句”的脚本模型里才成立：

代码块身份：可直接照写示例

const kMaxRetries = 3 + 4;
value := kMaxRetries;

全局变量 global

global 让同一运行任务中的不同函数访问同一变量。每个需要读写该变量的函数都要声明它；漏写时，同名标识符会按局部变量处理。

代码块身份：可直接照写示例

global shared_value;
shared_value := 37;
writeLn(ReadShared());

function ReadShared();
begin
    global shared_value;
    return shared_value;
end;

代码块身份：输出片段

37

本节只拥有“当前任务内跨函数共享”和“每个引用函数都要声明”的规则；不要从中推断跨任务持久化、线程隔离或进程级生命周期。

运行时常量 const name := expression

运行时常量使用 := 初始化，可以依赖参数、变量或函数调用。它在每次进入所属函数时重新计算一次，随后在本次调用内不可修改。

代码块身份：可直接照写示例

writeLn(FreezeValue(2));
writeLn(FreezeValue(5));

function FreezeValue(value);
begin
    const fixed := value + 1;
    return fixed;
end;

代码块身份：输出片段

3
6

边界：

• 编译时常量写 const name = expression;；运行时常量写 const name := expression;
• 运行时常量声明放在函数 begin ... end 语句体中，不放在函数头后的 const 声明段
• 运行时常量不作为类成员写法
• 初始化后再次赋值会破坏常量约束，不要生成

多参数赋值

多参数赋值：

代码块身份：可直接照写示例

[r1, r2] := array(1, 3, 5, 7, 9);
writeLn(r1);
writeLn(r2);

代码块身份：输出片段

1
3

单变量拆包时，末尾逗号不能省略：

代码块身份：可直接照写示例

[re, ] := array(1, 2, 3, 4);
writeLn(re);

代码块身份：输出片段

1

左侧变量比右侧数组更长时，多出的变量为 nil：

代码块身份：可直接照写示例

[r1, r2] := array(1);
writeLn(r1);
writeLn(r2 = nil);

代码块身份：输出片段

1
1

右侧元素也可以是数组：

代码块身份：可直接照写示例

[r1, r2] := array((1, 2), (3, 4));
writeLn(r1[0]);
writeLn(r1[1]);
writeLn(r2[0]);
writeLn(r2[1]);

结果说明：

• 依次输出 1、2、3、4

代码块身份：输出片段

1
2
3
4

函数返回数组后也可以直接拆包：

代码块身份：可直接照写示例

[error, re] := PairAdd(3, 4);
writeLn(error);
writeLn(re);

function PairAdd(a, b);
begin
    return array(0, a + b);
end;

结果说明：

• 依次输出 0、7

代码块身份：输出片段

0
7

函数参数里也可以使用多参数赋值：

代码块身份：可直接照写示例

writeLn(Test(e := 3, [f, g] := array(1, 2), g));

function Test(a, b, c);
begin
    return a + b + c;
end;

结果说明：

• 输出 6

代码块身份：输出片段

6

默认生成模板

普通变量和顶层常量的默认骨架如下：

代码块身份：可直接照写示例

const kMaxRetries = 3;
counter := kMaxRetries;
items := array(1, 2, 3);

禁止项

• 以为普通变量必须先写 var 才能使用。
• 把“整体赋值免声明”推广到单元格赋值，直接对未建立的变量写 q[0][0] := 1;。
• 把常量初始化写成普通变量赋值风格。
• 以为 const = 顶层单独写一行就一定成立。
• 以为 const 可以只声明名字，不写初始化表达式。
• 以为单变量拆包可以写成 [a] := array(...)。
• 以为 {$explicit+} 开启后仍然可以继续直接写未声明变量。
• 只在脚本顶层声明一次 global，却忘记在读取它的函数里再次声明。
• 把运行时常量 const name := expression; 写进函数头后的编译时 const 声明段。
• 把运行时常量当成可重新赋值的普通变量或类成员。

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

const value = 1;
value := 2;

上面这类写法会编译失败，报错点在重新赋值这一行。

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

const value = 1;

上面这类“顶层单独一行”的 const = 也会编译失败。

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

const value;

上面这类没有初始化表达式的 const 会编译失败；const 必须写初始化值。

错误原因是常量语句缺少初始化表达式。

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

[re] := array(1, 2, 3);

上面这种单变量拆包写法会报 left side can not be assign to。单变量时必须写成 [re, ] := ...。

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

{$explicit+}
a := 1;

上面这类写法会编译失败，主因是 variable not defined。

代码块身份：输出片段

variable not defined