231 lines
5.6 KiB
Markdown
231 lines
5.6 KiB
Markdown
---
|
||
name: tsl-guide
|
||
description: "TSL/TSF 语法与工程实践指南（基础语法/高级特性/函数库/最佳实践）。Triggers: TSL 语法, 写 TSL, 写 TSF, TSL 函数, TSL class, TSL unit, 矩阵操作, TS-SQL, TSL 函数库, tsl basics, tsl advanced, how to write tsl, tsf code, tsl api, 学习 TSL"
|
||
---
|
||
|
||
# TSL 完整指南
|
||
|
||
> **定位**：TSL 语言的一站式参考，从入门到进阶。本 skill 以语法为主，风格规范单独引用。
|
||
|
||
## 🚀 快速语法速查（仅语法）
|
||
|
||
> 代码风格与命名不是语法的一部分，见下方「代码风格与命名」。
|
||
|
||
### 变量与常量
|
||
|
||
```tsl
|
||
a := 1;
|
||
name := "test";
|
||
items := array(1, 2, 3);
|
||
table_data := array("Code": "0001", "Price": 12.3);
|
||
const kMaxRetries = 3;
|
||
```
|
||
|
||
### 函数
|
||
|
||
```tsl
|
||
function Add(a, b);
|
||
begin
|
||
return a + b;
|
||
end;
|
||
```
|
||
|
||
```tsl
|
||
function Parse(const s, var out_value);
|
||
begin
|
||
out_value := StrToInt(s);
|
||
return out_value;
|
||
end;
|
||
```
|
||
|
||
### 控制流
|
||
|
||
```tsl
|
||
if x > 0 then
|
||
y := 1;
|
||
else if x = 0 then
|
||
y := 0;
|
||
else
|
||
y := -1;
|
||
|
||
for i := 0 to 9 do
|
||
sum := sum + i;
|
||
|
||
for idx, v in items do
|
||
total := total + v;
|
||
```
|
||
|
||
### 异常处理
|
||
|
||
```tsl
|
||
try
|
||
v := StrToInt(s);
|
||
except
|
||
v := 0;
|
||
WriteLn(ExceptObject.ErrInfo);
|
||
end;
|
||
```
|
||
|
||
### 数组与索引
|
||
|
||
```tsl
|
||
arr := array(10, 20, 30);
|
||
value := arr[0];
|
||
|
||
matrix := array((1, 2), (3, 4));
|
||
col_0 := matrix[:, 0];
|
||
```
|
||
|
||
---
|
||
|
||
## 📌 代码风格与命名（非语法）
|
||
|
||
- 代码风格：`docs/tsl/code_style.md`
|
||
- 命名规范：`docs/tsl/naming.md`
|
||
- 本仓库硬约束：`.agents/tsl/index.md`
|
||
|
||
---
|
||
|
||
## 📚 详细文档索引（按需加载）
|
||
|
||
### 📖 基础语法（primer）
|
||
|
||
**文件**：`references/primer.md`
|
||
**内容**：
|
||
|
||
- 变量/常量、类型与字面量
|
||
- 数组与表数组表达
|
||
- 运算符与表达式
|
||
- 函数定义、参数修饰、默认值、命名参数、变参
|
||
- 控制流（if/case/for/while/repeat）
|
||
- 异常处理（try/except/finally/raise）
|
||
- 编译选项（`{$Explicit+}`/`{$VarByRef-}`）
|
||
|
||
**适用场景**：第一次写 TSL、查基础语法细节。
|
||
|
||
---
|
||
|
||
### 🚀 高级特性（advanced）
|
||
|
||
**文件**：`references/advanced.md`
|
||
**内容**：
|
||
|
||
- Unit/Namespace/函数文件与调用优先级
|
||
- Class/Object 模型（继承/override/Create/Destroy）
|
||
- 扩展语法：矩阵、集合运算、结果集过滤
|
||
- TS-SQL：select/insert/update/delete/sselect/vselect/mselect
|
||
- 运行时与性能语法要点（#网格计算等）
|
||
- 新一代语法概览（复数/WeakRef/算符重载）
|
||
|
||
**适用场景**：面向对象、模块化、矩阵与 TS-SQL、高级特性。
|
||
|
||
---
|
||
|
||
### 🔍 函数库速查（index）
|
||
|
||
**文件**：`references/functions_index.md`
|
||
**内容**：
|
||
|
||
- 函数库分类索引与检索策略
|
||
- 对应权威目录：`docs/tsl/syntax_book/function/tsl/index.md`
|
||
|
||
**重要说明**：
|
||
|
||
- 函数库已拆分为 `docs/tsl/syntax_book/function/` 多文件，**禁止整目录加载**
|
||
- 优先在 `docs/tsl/syntax_book/function/tsl/` 下分文件检索
|
||
|
||
---
|
||
|
||
### 💡 常见模式与最佳实践
|
||
|
||
**文件**：`references/common_patterns.md`
|
||
**内容**：参数校验、错误处理、I/O 分层、性能小贴士。
|
||
|
||
---
|
||
|
||
## ✅ 语法覆盖清单（对照 `docs/tsl/syntax_book/`）
|
||
|
||
- `01_language_basics.md` → `references/primer.md`
|
||
- `02_control_flow.md` → `references/primer.md`
|
||
- `03_functions.md` → `references/primer.md`
|
||
- `04_modules_and_namespace.md` → `references/advanced.md`
|
||
- `05_object_model.md` → `references/advanced.md`
|
||
- `06_extended_syntax.md` → `references/advanced.md`
|
||
- `07_debug_and_profiler.md` → `references/advanced.md`（语法要点）
|
||
- `08_new_generation.md` → `references/advanced.md`（概览）
|
||
|
||
---
|
||
|
||
## 🤖 Agent 使用指南
|
||
|
||
1. **分析需求**：判断需要基础语法还是高级特性
|
||
2. **按需加载**：只读取一个子文档（避免贪婪加载）
|
||
3. **必要时检索函数库**：先索引，再定位片段
|
||
|
||
### 典型场景与 Token 消耗
|
||
|
||
**场景 1：编写简单的 TSL 函数**
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 SKILL.md
|
||
3. 生成代码
|
||
|
||
Token 消耗：~6,000 tokens
|
||
```
|
||
|
||
**场景 2：编写 TSL 类**
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 SKILL.md + references/advanced.md
|
||
3. 生成代码
|
||
|
||
Token 消耗：~10,000 tokens
|
||
```
|
||
|
||
**场景 3：查询 TSL 函数库条目**
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 references/functions_index.md
|
||
3. 使用 rg 定位函数片段
|
||
4. 返回答案
|
||
|
||
Token 消耗：~8,000 tokens
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 函数库使用规则
|
||
|
||
- **禁止整目录加载**：`docs/tsl/syntax_book/function/` 体量巨大
|
||
- **推荐流程**：
|
||
1. 先看 `docs/tsl/syntax_book/function/tsl/index.md`
|
||
2. 再在 `docs/tsl/syntax_book/function/tsl/*.md` 中搜索
|
||
3. 只读取相关函数片段（≤100 行）
|
||
|
||
**检索示例**：
|
||
|
||
```bash
|
||
rg -n "\\bTrim\\b" docs/tsl/syntax_book/function/tsl/base.md
|
||
rg -n "^######\s+FileExists" docs/tsl/syntax_book/function/tsl/resource.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 权威文档路径
|
||
|
||
- 语法手册总览：`docs/tsl/syntax_book/index.md`
|
||
- 语言基础：`docs/tsl/syntax_book/01_language_basics.md`
|
||
- 控制流与异常：`docs/tsl/syntax_book/02_control_flow.md`
|
||
- 函数：`docs/tsl/syntax_book/03_functions.md`
|
||
- 模块与命名空间：`docs/tsl/syntax_book/04_modules_and_namespace.md`
|
||
- 对象模型：`docs/tsl/syntax_book/05_object_model.md`
|
||
- 扩展语法：`docs/tsl/syntax_book/06_extended_syntax.md`
|
||
- 运行时与性能工具：`docs/tsl/syntax_book/07_debug_and_profiler.md`
|
||
- 新一代语法：`docs/tsl/syntax_book/08_new_generation.md`
|
||
- 函数库：`docs/tsl/syntax_book/function/tsl/index.md`
|
||
- 代码风格：`docs/tsl/code_style.md`
|
||
- 命名规范：`docs/tsl/naming.md`
|