# Lexical Structure And Compile Options

文档类型：语法主线
是否可直接用于生成代码：是
是否含已验证可执行示例：是
是否含已验证反例：是
遇到不确定时跳转到：[19_types_and_conversions.md](19_types_and_conversions.md)、[12_pitfalls.md](12_pitfalls.md)、[01_introduction.md](01_introduction.md)

手册位置：第 18 篇，共 32 篇。上一篇：[16_debug_and_profiler.md](16_debug_and_profiler.md)。下一篇：[19_types_and_conversions.md](19_types_and_conversions.md)。

这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：保留字、标识符、注释、条件编译、文件包含、依赖编译选项。

## 这一篇解决什么问题

回答“TSL 的词法层规则和编译期开关应该去哪里查，而不是把这些边界混进值、函数、类的正文里”。

## 必须记住的规则

- 标识符大小写无关；当前最小运行验证里，下划线也可以出现在标识符中。
- 当前解释器接受 `//` 行注释、首行 `#!` CGI 风格注释、`{ ... }` 块注释，以及 `(* ... *)` 块注释。
- 当前解释器接受 `{$DEFINE}`、`{$UNDEF}`、`{$IFDEF}`、`{$IFNDEF}`、`{$ELSE}`、`{$ENDIF}` 这组条件编译指令。
- 条件编译当前已验证只会编译命中的分支；未命中的分支里即使放坏代码，也不会阻止脚本通过。
- 当前解释器接受 `{$Explicit+}`；一旦开启，后续变量必须先用 `var` 声明，否则会报 `variable not defined`。
- 当前解释器也接受 `{$Explicit-}`；它可以在同一源文件里把“先声明后使用”的要求重新关掉。
- 当前解释器接受 `{$VarByRef-}` 与 `{$VarByRef+}`；它们会切换“未修饰形参”的默认传递方式，细节见 [06_functions_and_calls.md](06_functions_and_calls.md)。
- 当前命令行解释器里，`{$I}` / `{$INCLUDE}` 的最小相对路径和绝对路径样例都没有跑通；错误信息是 `include file ... not found or include feature not implemented`。
- `{$dependency ...}` 这类编辑器辅助编译选项，本轮还没有拿到正向最小验证，不先写成正文事实。

## 已验证语法

大小写无关与下划线标识符：

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

```tsl
program test;
begin
    My_Var := 7;
    WriteLn(my_var);
    WriteLn(MY_VAR);
end.
```

已验证运行结果：

- 依次输出 `7`、`7`
- 说明当前解释器下标识符大小写无关
- 也说明下划线可以出现在标识符中

注释与条件编译：

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

```tsl
#! shebang style comment
program test;
begin
    a := 1; // line comment
    {
        (* nested comment marker *)
    }
    WriteLn(a);
{$DEFINE FLAG}
{$IFDEF FLAG}
    WriteLn(10);
{$ELSE}
    WriteLn(20);
{$ENDIF}
{$UNDEF FLAG}
{$IFNDEF FLAG}
    WriteLn(30);
{$ELSE}
    WriteLn(40);
{$ENDIF}
end.
```

已验证运行结果：

- 依次输出 `1`、`10`、`30`
- 说明首行 `#!`、`//`、`{ ... }`、`(* ... *)` 在当前解释器里都能通过
- 也说明 `DEFINE` / `UNDEF` / `IFDEF` / `IFNDEF` / `ELSE` / `ENDIF` 这一组条件编译指令在当前解释器里可以正常生效

`{$Explicit+}` 的正向最小例子：

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

```tsl
program test;
begin
{$Explicit+}
    var a;
    a := 1;
    WriteLn(a);
end.
```

已验证运行结果：

- 输出 `1`
- 说明 `{$Explicit+}` 开启后，配合 `var` 声明可以正常通过

`{$Explicit-}` 可以在同一源文件里关掉显式声明要求：

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

```tsl
program test;
begin
{$Explicit+}
    var a;
    a := 1;
{$Explicit-}
    b := 2;
    WriteLn(a + b);
end.
```

已验证运行结果：

- 输出 `3`
- 说明 `{$Explicit-}` 会从出现位置开始取消“变量必须先声明”的限制

条件编译不会去编译未命中的坏代码分支：

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

```tsl
program test;
begin
{$UNDEF NEVER}
{$IFDEF NEVER}
    { 未命中分支里的坏代码示意见下方反例块 }
{$ELSE}
    WriteLn(1);
{$ENDIF}
end.
```

已验证运行结果：

- 输出 `1`
- 说明未命中的条件编译分支不会参与当前脚本编译

未命中分支里拿来做验证的坏代码外形：

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

```text
this is bad code
```

上面这类内容只用于说明“坏代码”长什么样，不要直接写进正向示例块。

`{$VarByRef-}` 与 `{$VarByRef+}`：

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

```tsl
program test;
function TouchDefault(a);
begin
    a := 9;
end;
{$VarByRef-}
function TouchValue(a);
begin
    a := 8;
end;
function TouchForcedVar(var a);
begin
    a := 7;
end;
{$VarByRef+}
function TouchRestored(a);
begin
    a := 6;
end;
begin
    x := 1;
    TouchDefault(x);
    WriteLn(x);
    y := 1;
    TouchValue(y);
    WriteLn(y);
    z := 1;
    TouchForcedVar(z);
    WriteLn(z);
    r := 1;
    TouchRestored(r);
    WriteLn(r);
end.
```

已验证运行结果：

- 依次输出 `9`、`1`、`7`、`6`
- 说明默认模式下，未修饰参数仍会写回调用方
- 说明 `{$VarByRef-}` 下，未修饰参数会改成按值传递
- 说明 `var` 形参在 `{$VarByRef-}` 下仍保持引用语义
- 也说明 `{$VarByRef+}` 可以把默认语义重新切回可写回模式

## 当前已验证的反向边界

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

```text
program test;
begin
{$Explicit+}
    a := 1;
end.
```

上面这段最小样例已实测编译失败，报错主因是 `variable not defined`。

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

```text
program test;
{$I "common.inc"}
begin
    WriteLn(1);
end.
```

无论把 `common.inc` 写成相对路径还是绝对路径，当前命令行解释器都没有跑通，错误信息都是 `include file ... not found or include feature not implemented`。

## 跳转指引

- 回看文件模型与顶层主体：见 [03_core_model.md](03_core_model.md)
- 回看值、字面量与字符串：见 [04_values_and_literals.md](04_values_and_literals.md)
- 回看变量、常量与显式声明：见 [05_variables_and_constants.md](05_variables_and_constants.md)
- 看类型与转换：见 [19_types_and_conversions.md](19_types_and_conversions.md)
- 看字符串与编码：见 [20_strings_and_text.md](20_strings_and_text.md)