📝 docs(tsl): rebuild canonical syntax and routing manual
This commit is contained in:
@@ -0,0 +1,235 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user