Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d
25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
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