csh
/
playbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl): align syntax annotations and examples

This commit is contained in:
csh 2026-01-11 12:53:30 +08:00
parent 37546fe4f7
commit e3ecd26a88
5 changed files with 219 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
codex/skills/tsl-guide/SKILL.md
View File

@ -14,56 +14,56 @@ description: "TSL/TSF 语法与工程实践指南（基础语法/高级特性/
### 变量与常量 ### 变量与常量
```tsl ```tsl
A := 1; a := 1;
Name := "test"; name := "test";
Items := array(1,2,3); items := array(1, 2, 3);
Table := array("Code":"0001","Price":12.3); table_data := array("Code": "0001", "Price": 12.3);
Const MaxRetries = 3; const kMaxRetries = 3;
``` ```
### 函数 ### 函数
```tsl ```tsl
Function Add(a,b); function Add(a, b);
Begin begin
Return a + b; return a + b;
End; end;
``` ```
```tsl ```tsl
Function Parse(const s, var out_value); function Parse(const s, var out_value);
Begin begin
out_value := StrToInt(s); out_value := StrToInt(s);
Return out_value; return out_value;
End; end;
``` ```
### 控制流 ### 控制流
```tsl ```tsl
If x>0 then if x > 0 then
y := 1 y := 1;
else if x = 0 then else if x = 0 then
y := 0 y := 0;
else else
y := -1; y := -1;
For i := 0 to 9 do for i := 0 to 9 do
sum := sum + i; sum := sum + i;
For idx,v in Items do for idx, v in items do
total := total + v; total := total + v;
``` ```
### 异常处理 ### 异常处理
```tsl ```tsl
Try try
v := StrToInt(s); v := StrToInt(s);
Except except
v := 0; v := 0;
Writeln(ExceptObject.ErrInfo); WriteLn(ExceptObject.ErrInfo);
End; end;
``` ```
### 数组与索引 ### 数组与索引
@ -72,8 +72,8 @@ End;
arr := array(10, 20, 30); arr := array(10, 20, 30);
value := arr[0]; value := arr[0];
m := array((1,2),(3,4)); matrix := array((1, 2), (3, 4));
col0 := m[:,0]; col_0 := matrix[:, 0];
``` ```
--- ---

202
codex/skills/tsl-guide/references/primer.md
View File

@ -46,16 +46,16 @@
### 赋值 ### 赋值
```tsl ```tsl
A := 1; a := 1;
B := 2.5; b := 2.5;
S := "hello"; s := "hello";
``` ```
### 常量 ### 常量
```tsl ```tsl
Const PI = 3.14159; const kPi = 3.14159;
Const MaxRetry = 3; const kMaxRetry = 3;
``` ```
### 显式变量声明（配合 `{$Explicit+}`） ### 显式变量声明（配合 `{$Explicit+}`）
@ -63,9 +63,9 @@ Const MaxRetry = 3;
```tsl ```tsl
{$Explicit+} {$Explicit+}
Var A,B; // 多变量声明 var a, b; // 多变量声明
Var C := 10; // 声明并初始化 var c := 10; // 声明并初始化
Var D:Integer; // 类型可写可省（类型信息不做强校验） var d: integer; // 类型可写可省（类型信息不做强校验）
``` ```
--- ---
@ -89,19 +89,19 @@ Var D:Integer; // 类型可写可省（类型信息不做强校验）
示例： 示例：
```tsl ```tsl
I := 42; i := 42;
R := 3.14; r := 3.14;
B := true; b := true;
T := Date(); t := Date();
S := 'hello'; s := 'hello';
N := nil; n := nil;
``` ```
字符串支持单引号或双引号，索引访问从 0 开始： 字符串支持单引号或双引号，索引访问从 0 开始：
```tsl ```tsl
S := "ABC"; s := "ABC";
Ch := S[0]; ch := s[0];
``` ```
--- ---
@ -111,22 +111,22 @@ Ch := S[0];
### 一维数组（0-based） ### 一维数组（0-based）
```tsl ```tsl
Arr := array(2,3,5,7,11); arr := array(2, 3, 5, 7, 11);
First := Arr[0]; first := arr[0];
``` ```
### 字符串下标（表数组） ### 字符串下标（表数组）
```tsl ```tsl
Row := array("Code":"0001","Price":12.3); row := array("Code": "0001", "Price": 12.3);
Code := Row["Code"]; code := row["Code"];
``` ```
### 多维数组 ### 多维数组
```tsl ```tsl
Mat := array((1,2,3),(4,5,6)); matrix := array((1, 2, 3), (4, 5, 6));
Value := Mat[0][1]; value := matrix[0][1];
``` ```
--- ---
@ -144,9 +144,9 @@ Value := Mat[0][1];
示例： 示例：
```tsl ```tsl
C := A + B; c := a + b;
Ok := (A = B) or (A > 0); ok := (a = b) or (a > 0);
X := (A > B) ? A : B; x := (a > b) ? a : b;
``` ```
矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。 矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。
@ -159,54 +159,68 @@ X := (A > B) ? A : B;
### 基本结构 ### 基本结构
```tsl ```tsl
Function HelloTSL(); function HelloTsl();
Begin begin
D := Date(); d := Date();
Return DateToStr(D); return DateToStr(d);
End; end;
```
### 参数分隔与类型注解
类型注解仅用于说明与阅读，编译器不做类型检查。
- 无类型注解时用逗号分隔参数
- 带类型注解时用分号分隔参数
- 返回值类型写在 `)` 之后
```tsl
function F1(a, b);
function F2(a: string; b: array of real);
function F3(): void;
``` ```
### 形参与实参（in/const/var/out） ### 形参与实参（in/const/var/out）
```tsl ```tsl
Function Calc(in a, var b, out c); function Calc(in a, var b, out c);
Begin begin
b := b + a; b := b + a;
c := b * 2; c := b * 2;
Return c; return c;
End; end;
``` ```
### 缺省参数（新一代语法） ### 缺省参数（新一代语法）
```tsl ```tsl
Function Foo(a,b=a+1); function Foo(a, b = a + 1);
Begin begin
Return b; return b;
End; end;
``` ```
### 命名参数（新一代语法） ### 命名参数（新一代语法）
```tsl ```tsl
Function FuncA(a,b,c); function FuncA(a, b, c);
Begin begin
Return array(a,b,c); return array(a, b, c);
End; end;
Result := FuncA(1, c:3); // b 默认为 nil result := FuncA(1, c: 3); // b 默认为 nil
``` ```
### 变参（`...`）与 Params ### 变参（`...`）与 Params
```tsl ```tsl
Function SumAll(...); function SumAll(...);
Begin begin
Total := 0; total := 0;
For i,v in Params do for i, v in Params do
Total := Total + v; total := total + v;
Return Total; return total;
End; end;
``` ```
相关内置：`Params`, `ParamCount`, `RealParamCount`。 相关内置：`Params`, `ParamCount`, `RealParamCount`。
@ -214,14 +228,14 @@ End;
### 返回与退出 ### 返回与退出
```tsl ```tsl
Return X; // 返回 return value; // 返回
Exit; // 退出函数 exit; // 退出函数
``` ```
### 外部函数声明（external） ### 外部函数声明（external）
```tsl ```tsl
Function GetTickCount():Integer; stdcall; external "kernel32.dll" name "GetTickCount" KeepResident; function GetTickCount(): integer; stdcall; external "kernel32.dll" name "GetTickCount" keepresident;
``` ```
更多外部接口与调用方式见 `03_functions.md`。 更多外部接口与调用方式见 `03_functions.md`。
@ -233,10 +247,10 @@ Function GetTickCount():Integer; stdcall; external "kernel32.dll" name "GetTickC
### if / else if ### if / else if
```tsl ```tsl
If x>0 then if x > 0 then
y := 1 y := 1;
else if x = 0 then else if x = 0 then
y := 0 y := 0;
else else
y := -1; y := -1;
``` ```
@ -244,64 +258,64 @@ else
### if 表达式（新一代语法） ### if 表达式（新一代语法）
```tsl ```tsl
Ret := if x>0 then x*x else 0; ret := if x > 0 then x * x else 0;
``` ```
### case ### case
```tsl ```tsl
Case Age Of case age of
0: Writeln("Baby"); 0: WriteLn("Baby");
1: Writeln("Toddler"); 1: WriteLn("Toddler");
else else
Writeln("Other"); WriteLn("Other");
End; end;
``` ```
### while / repeat ### while / repeat
```tsl ```tsl
While cond do while cond do
DoSomething(); DoSomething();
Repeat repeat
DoSomething(); DoSomething();
Until cond; until cond;
``` ```
### for（to / downto / step） ### for（to / downto / step）
```tsl ```tsl
For i := 1 to 10 do for i := 1 to 10 do
Sum := Sum + i; sum := sum + i;
For i := 10 downto 1 step 2 do for i := 10 downto 1 step 2 do
Sum := Sum + i; sum := sum + i;
``` ```
### for ... in（数组遍历） ### for ... in（数组遍历）
```tsl ```tsl
Data := array('a':1,'b':5,'c':3); data := array('a': 1, 'b': 5, 'c': 3);
Sum := 0; sum := 0;
For k,v in Data do for k, v in data do
Sum := Sum + v; sum := sum + v;
``` ```
### break / continue / goto ### break / continue / goto
```tsl ```tsl
While cond do while cond do
Begin begin
If stop then Break; if stop then break;
If skip then Continue; if skip then continue;
// ... // ...
End; end;
Goto Finded; goto found;
label Finded; label found;
Writeln("jumped"); WriteLn("jumped");
``` ```
--- ---
@ -311,28 +325,28 @@ label Finded;
### Try / Except ### Try / Except
```tsl ```tsl
Try try
V := StrToInt(S); v := StrToInt(s);
Except except
V := 0; v := 0;
Writeln(ExceptObject.ErrInfo); WriteLn(ExceptObject.ErrInfo);
End; end;
``` ```
### Try / Finally ### Try / Finally
```tsl ```tsl
Try try
DoWork(); DoWork();
Finally finally
Cleanup(); Cleanup();
End; end;
``` ```
### Raise ### Raise
```tsl ```tsl
If A < 0 then Raise "A 不能小于 0"; if a < 0 then raise "A 不能小于 0";
``` ```
异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。 异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。
@ -342,13 +356,13 @@ If A < 0 then Raise "A 不能小于 0";
## 调试与性能相关语句 ## 调试与性能相关语句
```tsl ```tsl
DebugReturn 1; debugreturn 1;
``` ```
```tsl ```tsl
T1 := MTIC; t1 := mtic;
// ... // ...
Elapsed := MTOC(T1); elapsed := mtoc(t1);
``` ```
更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。 更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。

26
docs/tsl/syntax_book/01_language_basics.md
View File

@ -144,6 +144,7 @@
- [多维数组的理解](#多维数组的理解) - [多维数组的理解](#多维数组的理解)
- [字符串也可以作为数组的下标](#字符串也可以作为数组的下标) - [字符串也可以作为数组的下标](#字符串也可以作为数组的下标)
- [数组的表达方式](#数组的表达方式) - [数组的表达方式](#数组的表达方式)
- [Array of 类型注解（可选）](#array-of-类型注解可选)
- [TSL 语言的数组和其他语言相比的特性](#tsl-语言的数组和其他语言相比的特性) - [TSL 语言的数组和其他语言相比的特性](#tsl-语言的数组和其他语言相比的特性)
- [TMatrix](#tmatrix) - [TMatrix](#tmatrix)
- [Matrix](#matrix) - [Matrix](#matrix)
@ -157,6 +158,7 @@
- [COM 方法的调用例子](#com-方法的调用例子) - [COM 方法的调用例子](#com-方法的调用例子)
- [TSLObj](#tslobj) - [TSLObj](#tslobj)
- [常量与变量](#常量与变量) - [常量与变量](#常量与变量)
- [类型注解](#类型注解)
- [全局变量](#全局变量) - [全局变量](#全局变量)
- [常量](#常量) - [常量](#常量)
- [常量及常量成员的定义与初始化](#常量及常量成员的定义与初始化) - [常量及常量成员的定义与初始化](#常量及常量成员的定义与初始化)
@ -1831,6 +1833,17 @@ d := array(1 + 3, 2 + 5);
empty := array(); empty := array();
``` ```
##### Array of 类型注解（可选）
类型注解可用 `array of <label>` 标注元素含义，支持嵌套（如 `array of array of real`）。注解仅用于说明，编译器不做类型检查。
```tsl
function Clone(items: array of string): array of string;
begin
return items;
end;
```
##### TSL 语言的数组和其他语言相比的特性 ##### TSL 语言的数组和其他语言相比的特性
- 支持字符串下标，便于按名称访问。 - 支持字符串下标，便于按名称访问。
@ -2034,6 +2047,19 @@ today := Date();
变量 dToday 通过 Date()函数的返回，被赋值为一个 TDateTime 类型的数据。 变量 dToday 通过 Date()函数的返回，被赋值为一个 TDateTime 类型的数据。
#### 类型注解
类型注解使用 `:` 指定标识符类型，常见于函数参数/返回值、类字段和属性声明。
注解名称不参与编译检查，可任意命名，仅用于说明与阅读。
```tsl
function Open(path: string; flags: options = 0): result;
begin
return array("path": path, "flags": flags);
end;
```
常量即同 C 语言中的常量，它是一个固定值，在程序执行期间不会改变。 常量即同 C 语言中的常量，它是一个固定值，在程序执行期间不会改变。
截止到 2023-07 月份前的 TSL 版中，TSL 中没有特定的常量标识符，即不支持通过 const 来定义一个常量标识符。 截止到 2023-07 月份前的 TSL 版中，TSL 中没有特定的常量标识符，即不支持通过 const 来定义一个常量标识符。

24
docs/tsl/syntax_book/03_functions.md
View File

@ -8,6 +8,7 @@
- [目录](#目录) - [目录](#目录)
- [函数定义体和函数](#函数定义体和函数) - [函数定义体和函数](#函数定义体和函数)
- [概念](#概念) - [概念](#概念)
- [参数类型与返回类型](#参数类型与返回类型)
- [主函数与子函数](#主函数与子函数) - [主函数与子函数](#主函数与子函数)
- [形式参数与实际参数](#形式参数与实际参数) - [形式参数与实际参数](#形式参数与实际参数)
- [值参数](#值参数) - [值参数](#值参数)
@ -71,6 +72,29 @@ TSL 仅允许 `return` 一个值，如果需要返回多个内容，建议用数
```tsl ```tsl
return array(x, y); return array(x, y);
``` ```
### 参数类型与返回类型
函数参数与返回值可以在名称后使用 `:` 指定类型，类型注解可选。注解名称不参与编译检查，可任意命名，仅用于说明与阅读。
参数分隔规则：
- 不带类型注解时，用逗号分隔参数，例如 `function f1(a, b);`
- 带类型注解时，用分号分隔参数，例如 `function f2(a: string; b: array of real);`
- 返回值类型在 `)` 之后定义，例如 `function f3(): void;`
```tsl
function SafeConvert(value: input_value; convert_func: handler): real;
begin
return ##convert_func(value);
end;
function Open(path: string; flags: options = 0): result;
begin
return array("path": path, "flags": flags);
end;
```
### 主函数与子函数 ### 主函数与子函数
在 TSL 语言中，根据函数的可使用范围，将函数分成主函数和子函数两种。 在 TSL 语言中，根据函数的可使用范围，将函数分成主函数和子函数两种。

20
docs/tsl/syntax_book/05_object_model.md
View File

@ -16,6 +16,7 @@
- [作用域](#作用域) - [作用域](#作用域)
- [字段](#字段) - [字段](#字段)
- [字段简介](#字段简介) - [字段简介](#字段简介)
- [字段类型与弱引用](#字段类型与弱引用)
- [static 静态字段](#static-静态字段) - [static 静态字段](#static-静态字段)
- [const 常量成员](#const-常量成员) - [const 常量成员](#const-常量成员)
- [方法](#方法) - [方法](#方法)
@ -529,6 +530,19 @@ myObj.Field1 := "This is a Field";
可以为字段指定作用域 可以为字段指定作用域
#### 字段类型与弱引用
字段可以使用 `:` 指定类型。类型注解不参与编译检查，可任意命名，仅用于说明与阅读。对于对象字段，可用 `[weakref]` 标记为弱引用，用于避免循环引用。
```tsl
type Node = class
protected
[weakref]parent_: Node;
children_: array of Node;
meta_: meta_info;
end;
```
#### static 静态字段 #### static 静态字段
在字段的前边加入 static 前缀，就表明为静态字段也称静态成员变量，静态字段就是全部类实例共用的字段，亦可以不用实例化来进行调用。 在字段的前边加入 static 前缀，就表明为静态字段也称静态成员变量，静态字段就是全部类实例共用的字段，亦可以不用实例化来进行调用。
@ -1279,6 +1293,12 @@ class(ClassName).FuncName();
语法：`Property PropertyName[(ParamList)] [read fieldOrMethod][write fieldOrMethod][Index IndexValue]` 语法：`Property PropertyName[(ParamList)] [read fieldOrMethod][write fieldOrMethod][Index IndexValue]`
属性名后可指定类型，语法：`property Name: Type read fieldOrMethod [write fieldOrMethod]`。类型注解不参与编译检查，可任意命名。
```tsl
property Components: DocxComponentsFacade read components_;
```
其中， 其中，
1、关键字 Property 关键字表示开始声明了一个属性； 1、关键字 Property 关键字表示开始声明了一个属性；