📝 docs(tsl): align syntax annotations and examples
This commit is contained in:
parent
37546fe4f7
commit
e3ecd26a88
|
|
@ -14,56 +14,56 @@ description: "TSL/TSF 语法与工程实践指南（基础语法/高级特性/
|
|||
### 变量与常量
|
||||
|
||||
```tsl
|
||||
A := 1;
|
||||
Name := "test";
|
||||
Items := array(1,2,3);
|
||||
Table := array("Code":"0001","Price":12.3);
|
||||
Const MaxRetries = 3;
|
||||
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;
|
||||
function Add(a, b);
|
||||
begin
|
||||
return a + b;
|
||||
end;
|
||||
```
|
||||
|
||||
```tsl
|
||||
Function Parse(const s, var out_value);
|
||||
Begin
|
||||
function Parse(const s, var out_value);
|
||||
begin
|
||||
out_value := StrToInt(s);
|
||||
Return out_value;
|
||||
End;
|
||||
return out_value;
|
||||
end;
|
||||
```
|
||||
|
||||
### 控制流
|
||||
|
||||
```tsl
|
||||
If x>0 then
|
||||
y := 1
|
||||
if x > 0 then
|
||||
y := 1;
|
||||
else if x = 0 then
|
||||
y := 0
|
||||
y := 0;
|
||||
else
|
||||
y := -1;
|
||||
|
||||
For i := 0 to 9 do
|
||||
for i := 0 to 9 do
|
||||
sum := sum + i;
|
||||
|
||||
For idx,v in Items do
|
||||
for idx, v in items do
|
||||
total := total + v;
|
||||
```
|
||||
|
||||
### 异常处理
|
||||
|
||||
```tsl
|
||||
Try
|
||||
try
|
||||
v := StrToInt(s);
|
||||
Except
|
||||
except
|
||||
v := 0;
|
||||
Writeln(ExceptObject.ErrInfo);
|
||||
End;
|
||||
WriteLn(ExceptObject.ErrInfo);
|
||||
end;
|
||||
```
|
||||
|
||||
### 数组与索引
|
||||
|
|
@ -72,8 +72,8 @@ End;
|
|||
arr := array(10, 20, 30);
|
||||
value := arr[0];
|
||||
|
||||
m := array((1,2),(3,4));
|
||||
col0 := m[:,0];
|
||||
matrix := array((1, 2), (3, 4));
|
||||
col_0 := matrix[:, 0];
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -46,16 +46,16 @@
|
|||
### 赋值
|
||||
|
||||
```tsl
|
||||
A := 1;
|
||||
B := 2.5;
|
||||
S := "hello";
|
||||
a := 1;
|
||||
b := 2.5;
|
||||
s := "hello";
|
||||
```
|
||||
|
||||
### 常量
|
||||
|
||||
```tsl
|
||||
Const PI = 3.14159;
|
||||
Const MaxRetry = 3;
|
||||
const kPi = 3.14159;
|
||||
const kMaxRetry = 3;
|
||||
```
|
||||
|
||||
### 显式变量声明（配合 `{$Explicit+}`）
|
||||
|
|
@ -63,9 +63,9 @@ Const MaxRetry = 3;
|
|||
```tsl
|
||||
{$Explicit+}
|
||||
|
||||
Var A,B; // 多变量声明
|
||||
Var C := 10; // 声明并初始化
|
||||
Var D:Integer; // 类型可写可省（类型信息不做强校验）
|
||||
var a, b; // 多变量声明
|
||||
var c := 10; // 声明并初始化
|
||||
var d: integer; // 类型可写可省（类型信息不做强校验）
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -89,19 +89,19 @@ Var D:Integer; // 类型可写可省（类型信息不做强校验）
|
|||
示例：
|
||||
|
||||
```tsl
|
||||
I := 42;
|
||||
R := 3.14;
|
||||
B := true;
|
||||
T := Date();
|
||||
S := 'hello';
|
||||
N := nil;
|
||||
i := 42;
|
||||
r := 3.14;
|
||||
b := true;
|
||||
t := Date();
|
||||
s := 'hello';
|
||||
n := nil;
|
||||
```
|
||||
|
||||
字符串支持单引号或双引号，索引访问从 0 开始：
|
||||
|
||||
```tsl
|
||||
S := "ABC";
|
||||
Ch := S[0];
|
||||
s := "ABC";
|
||||
ch := s[0];
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -111,22 +111,22 @@ Ch := S[0];
|
|||
### 一维数组（0-based）
|
||||
|
||||
```tsl
|
||||
Arr := array(2,3,5,7,11);
|
||||
First := Arr[0];
|
||||
arr := array(2, 3, 5, 7, 11);
|
||||
first := arr[0];
|
||||
```
|
||||
|
||||
### 字符串下标（表数组）
|
||||
|
||||
```tsl
|
||||
Row := array("Code":"0001","Price":12.3);
|
||||
Code := Row["Code"];
|
||||
row := array("Code": "0001", "Price": 12.3);
|
||||
code := row["Code"];
|
||||
```
|
||||
|
||||
### 多维数组
|
||||
|
||||
```tsl
|
||||
Mat := array((1,2,3),(4,5,6));
|
||||
Value := Mat[0][1];
|
||||
matrix := array((1, 2, 3), (4, 5, 6));
|
||||
value := matrix[0][1];
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -144,9 +144,9 @@ Value := Mat[0][1];
|
|||
示例：
|
||||
|
||||
```tsl
|
||||
C := A + B;
|
||||
Ok := (A = B) or (A > 0);
|
||||
X := (A > B) ? A : B;
|
||||
c := a + b;
|
||||
ok := (a = b) or (a > 0);
|
||||
x := (a > b) ? a : b;
|
||||
```
|
||||
|
||||
矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。
|
||||
|
|
@ -159,54 +159,68 @@ X := (A > B) ? A : B;
|
|||
### 基本结构
|
||||
|
||||
```tsl
|
||||
Function HelloTSL();
|
||||
Begin
|
||||
D := Date();
|
||||
Return DateToStr(D);
|
||||
End;
|
||||
function HelloTsl();
|
||||
begin
|
||||
d := Date();
|
||||
return DateToStr(d);
|
||||
end;
|
||||
```
|
||||
|
||||
### 参数分隔与类型注解
|
||||
|
||||
类型注解仅用于说明与阅读，编译器不做类型检查。
|
||||
|
||||
- 无类型注解时用逗号分隔参数
|
||||
- 带类型注解时用分号分隔参数
|
||||
- 返回值类型写在 `)` 之后
|
||||
|
||||
```tsl
|
||||
function F1(a, b);
|
||||
function F2(a: string; b: array of real);
|
||||
function F3(): void;
|
||||
```
|
||||
|
||||
### 形参与实参（in/const/var/out）
|
||||
|
||||
```tsl
|
||||
Function Calc(in a, var b, out c);
|
||||
Begin
|
||||
function Calc(in a, var b, out c);
|
||||
begin
|
||||
b := b + a;
|
||||
c := b * 2;
|
||||
Return c;
|
||||
End;
|
||||
return c;
|
||||
end;
|
||||
```
|
||||
|
||||
### 缺省参数（新一代语法）
|
||||
|
||||
```tsl
|
||||
Function Foo(a,b=a+1);
|
||||
Begin
|
||||
Return b;
|
||||
End;
|
||||
function Foo(a, b = a + 1);
|
||||
begin
|
||||
return b;
|
||||
end;
|
||||
```
|
||||
|
||||
### 命名参数（新一代语法）
|
||||
|
||||
```tsl
|
||||
Function FuncA(a,b,c);
|
||||
Begin
|
||||
Return array(a,b,c);
|
||||
End;
|
||||
function FuncA(a, b, c);
|
||||
begin
|
||||
return array(a, b, c);
|
||||
end;
|
||||
|
||||
Result := FuncA(1, c:3); // b 默认为 nil
|
||||
result := FuncA(1, c: 3); // b 默认为 nil
|
||||
```
|
||||
|
||||
### 变参（`...`）与 Params
|
||||
|
||||
```tsl
|
||||
Function SumAll(...);
|
||||
Begin
|
||||
Total := 0;
|
||||
For i,v in Params do
|
||||
Total := Total + v;
|
||||
Return Total;
|
||||
End;
|
||||
function SumAll(...);
|
||||
begin
|
||||
total := 0;
|
||||
for i, v in Params do
|
||||
total := total + v;
|
||||
return total;
|
||||
end;
|
||||
```
|
||||
|
||||
相关内置：`Params`, `ParamCount`, `RealParamCount`。
|
||||
|
|
@ -214,14 +228,14 @@ End;
|
|||
### 返回与退出
|
||||
|
||||
```tsl
|
||||
Return X; // 返回
|
||||
Exit; // 退出函数
|
||||
return value; // 返回
|
||||
exit; // 退出函数
|
||||
```
|
||||
|
||||
### 外部函数声明（external）
|
||||
|
||||
```tsl
|
||||
Function GetTickCount():Integer; stdcall; external "kernel32.dll" name "GetTickCount" KeepResident;
|
||||
function GetTickCount(): integer; stdcall; external "kernel32.dll" name "GetTickCount" keepresident;
|
||||
```
|
||||
|
||||
更多外部接口与调用方式见 `03_functions.md`。
|
||||
|
|
@ -233,10 +247,10 @@ Function GetTickCount():Integer; stdcall; external "kernel32.dll" name "GetTickC
|
|||
### if / else if
|
||||
|
||||
```tsl
|
||||
If x>0 then
|
||||
y := 1
|
||||
if x > 0 then
|
||||
y := 1;
|
||||
else if x = 0 then
|
||||
y := 0
|
||||
y := 0;
|
||||
else
|
||||
y := -1;
|
||||
```
|
||||
|
|
@ -244,64 +258,64 @@ else
|
|||
### if 表达式（新一代语法）
|
||||
|
||||
```tsl
|
||||
Ret := if x>0 then x*x else 0;
|
||||
ret := if x > 0 then x * x else 0;
|
||||
```
|
||||
|
||||
### case
|
||||
|
||||
```tsl
|
||||
Case Age Of
|
||||
0: Writeln("Baby");
|
||||
1: Writeln("Toddler");
|
||||
case age of
|
||||
0: WriteLn("Baby");
|
||||
1: WriteLn("Toddler");
|
||||
else
|
||||
Writeln("Other");
|
||||
End;
|
||||
WriteLn("Other");
|
||||
end;
|
||||
```
|
||||
|
||||
### while / repeat
|
||||
|
||||
```tsl
|
||||
While cond do
|
||||
while cond do
|
||||
DoSomething();
|
||||
|
||||
Repeat
|
||||
repeat
|
||||
DoSomething();
|
||||
Until cond;
|
||||
until cond;
|
||||
```
|
||||
|
||||
### for（to / downto / step）
|
||||
|
||||
```tsl
|
||||
For i := 1 to 10 do
|
||||
Sum := Sum + i;
|
||||
for i := 1 to 10 do
|
||||
sum := sum + i;
|
||||
|
||||
For i := 10 downto 1 step 2 do
|
||||
Sum := Sum + i;
|
||||
for i := 10 downto 1 step 2 do
|
||||
sum := sum + i;
|
||||
```
|
||||
|
||||
### for ... in（数组遍历）
|
||||
|
||||
```tsl
|
||||
Data := array('a':1,'b':5,'c':3);
|
||||
Sum := 0;
|
||||
data := array('a': 1, 'b': 5, 'c': 3);
|
||||
sum := 0;
|
||||
|
||||
For k,v in Data do
|
||||
Sum := Sum + v;
|
||||
for k, v in data do
|
||||
sum := sum + v;
|
||||
```
|
||||
|
||||
### break / continue / goto
|
||||
|
||||
```tsl
|
||||
While cond do
|
||||
Begin
|
||||
If stop then Break;
|
||||
If skip then Continue;
|
||||
while cond do
|
||||
begin
|
||||
if stop then break;
|
||||
if skip then continue;
|
||||
// ...
|
||||
End;
|
||||
end;
|
||||
|
||||
Goto Finded;
|
||||
label Finded;
|
||||
Writeln("jumped");
|
||||
goto found;
|
||||
label found;
|
||||
WriteLn("jumped");
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -311,28 +325,28 @@ label Finded;
|
|||
### Try / Except
|
||||
|
||||
```tsl
|
||||
Try
|
||||
V := StrToInt(S);
|
||||
Except
|
||||
V := 0;
|
||||
Writeln(ExceptObject.ErrInfo);
|
||||
End;
|
||||
try
|
||||
v := StrToInt(s);
|
||||
except
|
||||
v := 0;
|
||||
WriteLn(ExceptObject.ErrInfo);
|
||||
end;
|
||||
```
|
||||
|
||||
### Try / Finally
|
||||
|
||||
```tsl
|
||||
Try
|
||||
try
|
||||
DoWork();
|
||||
Finally
|
||||
finally
|
||||
Cleanup();
|
||||
End;
|
||||
end;
|
||||
```
|
||||
|
||||
### Raise
|
||||
|
||||
```tsl
|
||||
If A < 0 then Raise "A 不能小于 0";
|
||||
if a < 0 then raise "A 不能小于 0";
|
||||
```
|
||||
|
||||
异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。
|
||||
|
|
@ -342,13 +356,13 @@ If A < 0 then Raise "A 不能小于 0";
|
|||
## 调试与性能相关语句
|
||||
|
||||
```tsl
|
||||
DebugReturn 1;
|
||||
debugreturn 1;
|
||||
```
|
||||
|
||||
```tsl
|
||||
T1 := MTIC;
|
||||
t1 := mtic;
|
||||
// ...
|
||||
Elapsed := MTOC(T1);
|
||||
elapsed := mtoc(t1);
|
||||
```
|
||||
|
||||
更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。
|
||||
|
|
|
|||
|
|
@ -144,6 +144,7 @@
|
|||
- [多维数组的理解](#多维数组的理解)
|
||||
- [字符串也可以作为数组的下标](#字符串也可以作为数组的下标)
|
||||
- [数组的表达方式](#数组的表达方式)
|
||||
- [Array of 类型注解（可选）](#array-of-类型注解可选)
|
||||
- [TSL 语言的数组和其他语言相比的特性](#tsl-语言的数组和其他语言相比的特性)
|
||||
- [TMatrix](#tmatrix)
|
||||
- [Matrix](#matrix)
|
||||
|
|
@ -157,6 +158,7 @@
|
|||
- [COM 方法的调用例子](#com-方法的调用例子)
|
||||
- [TSLObj](#tslobj)
|
||||
- [常量与变量](#常量与变量)
|
||||
- [类型注解](#类型注解)
|
||||
- [全局变量](#全局变量)
|
||||
- [常量](#常量)
|
||||
- [常量及常量成员的定义与初始化](#常量及常量成员的定义与初始化)
|
||||
|
|
@ -1831,6 +1833,17 @@ d := array(1 + 3, 2 + 5);
|
|||
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 语言的数组和其他语言相比的特性
|
||||
|
||||
- 支持字符串下标，便于按名称访问。
|
||||
|
|
@ -2034,6 +2047,19 @@ today := Date();
|
|||
|
||||
变量 dToday 通过 Date()函数的返回，被赋值为一个 TDateTime 类型的数据。
|
||||
|
||||
#### 类型注解
|
||||
|
||||
类型注解使用 `:` 指定标识符类型，常见于函数参数/返回值、类字段和属性声明。
|
||||
|
||||
注解名称不参与编译检查，可任意命名，仅用于说明与阅读。
|
||||
|
||||
```tsl
|
||||
function Open(path: string; flags: options = 0): result;
|
||||
begin
|
||||
return array("path": path, "flags": flags);
|
||||
end;
|
||||
```
|
||||
|
||||
常量即同 C 语言中的常量，它是一个固定值，在程序执行期间不会改变。
|
||||
|
||||
截止到 2023-07 月份前的 TSL 版中，TSL 中没有特定的常量标识符，即不支持通过 const 来定义一个常量标识符。
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@
|
|||
- [目录](#目录)
|
||||
- [函数定义体和函数](#函数定义体和函数)
|
||||
- [概念](#概念)
|
||||
- [参数类型与返回类型](#参数类型与返回类型)
|
||||
- [主函数与子函数](#主函数与子函数)
|
||||
- [形式参数与实际参数](#形式参数与实际参数)
|
||||
- [值参数](#值参数)
|
||||
|
|
@ -71,6 +72,29 @@ TSL 仅允许 `return` 一个值，如果需要返回多个内容，建议用数
|
|||
```tsl
|
||||
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 语言中，根据函数的可使用范围，将函数分成主函数和子函数两种。
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@
|
|||
- [作用域](#作用域)
|
||||
- [字段](#字段)
|
||||
- [字段简介](#字段简介)
|
||||
- [字段类型与弱引用](#字段类型与弱引用)
|
||||
- [static 静态字段](#static-静态字段)
|
||||
- [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 前缀，就表明为静态字段也称静态成员变量，静态字段就是全部类实例共用的字段，亦可以不用实例化来进行调用。
|
||||
|
|
@ -1279,6 +1293,12 @@ class(ClassName).FuncName();
|
|||
|
||||
语法：`Property PropertyName[(ParamList)] [read fieldOrMethod][write fieldOrMethod][Index IndexValue]`
|
||||
|
||||
属性名后可指定类型，语法：`property Name: Type read fieldOrMethod [write fieldOrMethod]`。类型注解不参与编译检查，可任意命名。
|
||||
|
||||
```tsl
|
||||
property Components: DocxComponentsFacade read components_;
|
||||
```
|
||||
|
||||
其中，
|
||||
|
||||
1、关键字 Property 关键字表示开始声明了一个属性；
|
||||
|
|
|
|||
Loading…
Reference in New Issue