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

🎨 style(syntax): normalize naming conventions

Browse Source 
Align all TSL syntax documentation examples with docs/tsl/naming.md:

- Classes/types: PascalCase, drop Hungarian prefix (THuman→Human)
- Parameters/locals: snake_case with meaningful names (isLeft→is_left, maxb→max_b)
- Private members: snake_case_ with trailing underscore (real_part_, imaginary_part_)
- Public members: PascalCase (value→Value)
- Top-level functions: PascalCase (test→Test)
- Module constants: kPascalCase (kernel_dll→kKernelDll)

Affected: 01-24 syntax docs (23 files)
Verified: 150+ code blocks locally tested, output unchanged
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
csh
2026-07-07 16:34:19 +08:00
co-authored by Claude Fable 5
parent 23c35fdfda
commit 014c23d386
23 changed files with 2009 additions and 352 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tsl/syntax/08_objects_and_classes.md
+165 -97
View File
@@ -192,29 +192,29 @@ writeLn(a);
代码块身份：可直接照写示例
```tsl
class(THuman).mCount := 100;
writeLn(class(THuman).mCount);
h := new THuman();
writeLn(class(THuman).mCount);
writeLn(h.mCount);
class(Human).count := 100;
writeLn(class(Human).count);
h := new Human();
writeLn(class(Human).count);
writeLn(h.count);
type THuman = class
type Human = class
public
static mCount;
static count;
function create();
begin
mCount := (mCount ?: 0) + 1;
count := (count ?: 0) + 1;
end;
end;
```
输出说明：
- `class(THuman).mCount := 100` 可以直接写静态字段
- `class(THuman).mCount` 先输出 `100`
- 创建对象后，`class(THuman).mCount` 输出 `101`
- 通过实例读取 `h.mCount` 也输出 `101`
- 单个静态字段默认写成 `static mCount;`
- `class(Human).count := 100` 可以直接写静态字段
- `class(Human).count` 先输出 `100`
- 创建对象后，`class(Human).count` 输出 `101`
- 通过实例读取 `h.count` 也输出 `101`
- 单个静态字段默认写成 `static count;`
`const` 成员：
@@ -224,20 +224,20 @@ end;
o := new C();
writeLn(o.TestConst());
writeLn(o.TestConstInParam());
writeLn(o.mA);
writeLn(class(C).mB);
writeLn(o.a);
writeLn(class(C).b);
type C = class
public
const mA = 1;
static const mB = mA + 10;
const a = 1;
static const b = a + 10;
function TestConst();
begin
return mA + mB;
return a + b;
end;
function TestConstInParam(b = mB);
function TestConstInParam(param_b = b);
begin
return b;
return param_b;
end;
end;
```
@@ -431,53 +431,53 @@ end;
代码块身份：可直接照写示例
```tsl
b := new MyBox();
b.Value := 7;
writeLn(b.Value);
b.Value := -1;
writeLn(b.Value);
box := new Box();
box.Value := 7;
writeLn(box.Value);
box.Value := -1;
writeLn(box.Value);
type MyBox = class
type Box = class
public
_value;
value_;
function SetValue(v);
begin
if v > 0 then
_value := v;
value_ := v;
end;
property Value read _value write SetValue;
property Value read value_ write SetValue;
end;
```
输出说明：
- `b.Value := 7` 后，`b.Value` 输出 `7`
- `b.Value := -1` 后，`b.Value` 仍输出 `7`
- `box.Value := 7` 后，`box.Value` 输出 `7`
- `box.Value := -1` 后，`box.Value` 仍输出 `7`
带类型注解的 `property`：
代码块身份：可直接照写示例
```tsl
b := new MyBox();
b.Value := 9;
writeLn(b.Value);
box := new Box();
box.Value := 9;
writeLn(box.Value);
type MyBox = class
type Box = class
public
_value;
value_;
function SetValue(v);
begin
_value := v;
value_ := v;
end;
property Value: integer read _value write SetValue;
property Value: integer read value_ write SetValue;
end;
```
输出说明：
- `property Value: integer ...` 这种类型注解写法可以通过
- 上述例子中的 `b.Value` 输出 `9`
- 上述例子中的 `box.Value` 输出 `9`
字段和类方法类型注解：
@@ -491,10 +491,10 @@ writeLn(box.ReadName());
type TypedBox = class
public
function create(_name: string; _value: any);
function create(name: string; value: any);
begin
name_ := _name;
value_ := _value;
name_ := name;
value_ := value;
end;
function ReadName(): string;
begin
@@ -511,7 +511,7 @@ end;
输出说明：
- `name_: string;` 和 `value_: any;` 可以作为类字段类型注解。
- `function create(_name: string; _value: any);` 可以作为类方法参数类型注解。
- `function create(name: string; value: any);` 可以作为类方法参数类型注解。
- `function ReadName(): string;` 可以作为类方法返回值类型注解。
- 上述例子依次输出 `abc`、`7`、`abc`。
@@ -538,8 +538,8 @@ writeLn(b.ReadLeft());
type PairBox = class
public
function create(_left: string); overload;
function create(_left: string; _right: any); overload;
function create(left: string); overload;
function create(left: string; right: any); overload;
function ReadLeft(): string;
property Left: string read left_ write left_;
property Right: any read right_ write right_;
@@ -548,15 +548,15 @@ private
right_: any;
end;
function PairBox.create(_left: string); overload;
function PairBox.create(left: string); overload;
begin
create(_left, nil);
create(left, nil);
end;
function PairBox.create(_left: string; _right: any); overload;
function PairBox.create(left: string; right: any); overload;
begin
left_ := _left;
right_ := _right;
left_ := left;
right_ := right;
end;
function PairBox.ReadLeft(): string;
@@ -570,7 +570,7 @@ end;
- 类内可以只声明带类型的重载方法签名。
- 类外实现写成 `function PairBox.create(...); overload;`，并保持同样的参数类型和 `overload` 标记。
- 类外实现属于声明区；写完后不要再追加脚本语句。
- 从一个构造函数转调另一个构造函数时，直接写 `create(_left, nil);`，不要加 `self` 前缀。
- 从一个构造函数转调另一个构造函数时，直接写 `create(left, nil);`，不要加 `self` 前缀。
- 上述例子依次输出 `left`、`<NIL>`、`left`、`2`、`left`。
代码块身份：输出片段
@@ -588,9 +588,9 @@ left
代码块身份：可直接照写示例
```tsl
aa := new A();
aa.idx(0) := "abc";
writeLn(aa.idx(0));
obj := new A();
obj.idx(0) := "abc";
writeLn(obj.idx(0));
type A = class
public
@@ -613,18 +613,18 @@ end;
输出说明：
- `aa.idx(0) := "abc"` 可以写入索引 property
- `aa.idx(0)` 输出 `abc`
- `obj.idx(0) := "abc"` 可以写入索引 property
- `obj.idx(0)` 输出 `abc`
固定 `index` property：
代码块身份：可直接照写示例
```tsl
aa := new A();
aa.idx0 := "abc";
writeLn(aa.idx0);
writeLn(aa.idx(0));
obj := new A();
obj.idx0 := "abc";
writeLn(obj.idx0);
writeLn(obj.idx(0));
type A = class
public
@@ -648,19 +648,19 @@ end;
输出说明：
- `aa.idx0 := "abc"` 可以写入固定整数索引 property
- `aa.idx0` 输出 `abc`
- `aa.idx(0)` 也输出 `abc`
- `obj.idx0 := "abc"` 可以写入固定整数索引 property
- `obj.idx0` 输出 `abc`
- `obj.idx(0)` 也输出 `abc`
固定字符串索引：
代码块身份：可直接照写示例
```tsl
aa := new A();
aa.school := "math";
writeLn(aa.school);
writeLn(aa.idx("High school"));
obj := new A();
obj.school := "math";
writeLn(obj.school);
writeLn(obj.idx("High school"));
type A = class
public
@@ -685,8 +685,8 @@ end;
输出说明：
- `property school index "High school"` 这种固定字符串索引写法可以通过
- `aa.school` 输出 `math`
- `aa.idx("High school")` 也输出 `math`
- `obj.school` 输出 `math`
- `obj.idx("High school")` 也输出 `math`
参数化 `property`：
@@ -699,18 +699,18 @@ writeLn(d.DateV());
type MyDate = class
public
_year;
_month;
_day;
year_;
month_;
day_;
function getDateV();
begin
return _year * 10000 + _month * 100 + _day;
return year_ * 10000 + month_ * 100 + day_;
end;
function setDateV(y, m, d);
begin
_year := y;
_month := m;
_day := d;
year_ := y;
month_ := m;
day_ := d;
end;
property DateV(y, m) read getDateV write setDateV;
end;
@@ -726,9 +726,9 @@ end;
代码块身份：可直接照写示例
```tsl
aa := new A();
aa.Item(2) := "x";
writeLn(aa.Item(2));
obj := new A();
obj.Item(2) := "x";
writeLn(obj.Item(2));
type A = class
public
@@ -751,9 +751,9 @@ end;
输出说明：
- `read getItem` 这种“读方法接同参数个数”的写法可以通过
- `write setItem` 这种“写方法接参数个数 + 赋值值”的写法可以通过
- 上述例子中的 `aa.Item(2)` 输出 `x`
- `read getItem` 这种”读方法接同参数个数”的写法可以通过
- `write setItem` 这种”写方法接参数个数 + 赋值值”的写法可以通过
- 上述例子中的 `obj.Item(2)` 输出 `x`
### 对象创建与类类型
@@ -922,9 +922,9 @@ public
begin
return p1 + p2;
end;
function fun(p1); overload;
function fun(param): integer; overload;
begin
return p1 + 10;
return param + 10;
end;
end;
```
@@ -1050,6 +1050,74 @@ end;
- 父类 `virtual` + 子类 `override` 组合可以通过
- 上述例子中的 `d.Speak()` 输出 `2`
子类同名方法不加 `override` 时是「隐藏（hide）」而不是「覆盖（override）」：
代码块身份：可直接照写示例
```tsl
c := new Child();
writeLn(c.Who());
writeLn(c.Ask());
type Parent = class
public
function Who();
begin
return "parent";
end;
function Ask();
begin
return Who();
end;
end;
type Child = class(Parent)
public
function Who();
begin
return "child";
end;
end;
```
输出说明：
- `c.Who()` 输出 `child`：直接调用命中子类自己的同名方法
- `c.Ask()` 输出 `parent`：父类方法内部的 `Who()` 仍解析到父类版本，说明不加 `override` 只是「隐藏」父类方法，没有改变父类内部的调用目标
- 要让父类方法内部也定向到子类实现，父类方法须声明 `virtual`、子类方法须声明 `override`
对照：父类 `virtual` + 子类 `override` 时，父类方法内部调用会定向到子类：
代码块身份：可直接照写示例
```tsl
c := new Child();
writeLn(c.Ask());
type Parent = class
public
function Who(); virtual;
begin
return "parent";
end;
function Ask();
begin
return Who();
end;
end;
type Child = class(Parent)
public
function Who(); override;
begin
return "child";
end;
end;
```
输出说明：
- `c.Ask()` 输出 `child`：`virtual` + `override` 后，父类方法内部的 `Who()` 定向到子类实现
- 这就是 hide 与 override 的关键区别：hide 只影响直接调用，override 改变了所有经由基类的间接调用
`class(BaseClass, ObjectName).MethodName()`：
代码块身份：可直接照写示例
@@ -1179,35 +1247,35 @@ end;
代码块身份：可直接照写示例
```tsl
h := new THuman();
writeLn(class(THuman).GetCount());
h := new Human();
writeLn(class(Human).GetCount());
h := nil;
writeLn(class(THuman).GetCount());
writeLn(class(Human).GetCount());
type THuman = class
type Human = class
public
static mCount;
static count;
function create();
begin
mCount := (mCount ?: 0) + 1;
count := (count ?: 0) + 1;
end;
function destroy();
begin
mCount--;
writeLn(mCount);
count--;
writeLn(count);
end;
class function GetCount();
begin
return mCount;
return count;
end;
end;
```
输出说明：
- 创建对象后，`class(THuman).GetCount()` 输出 `1`
- 创建对象后，`class(Human).GetCount()` 输出 `1`
- `h := nil` 时会触发 `destroy()`，中途输出 `0`
- 释放后再次读取 `class(THuman).GetCount()` 也输出 `0`
- 释放后再次读取 `class(Human).GetCount()` 也输出 `0`
`self(0)` / `self(1)`：
@@ -1373,10 +1441,10 @@ cls := class(Unit1.Class1.Class2);
```text
MathBox.Add(1, 2);
THuman.mCount := 7;
Human.count := 7;
```
上面这种裸类名成员访问不作为可写事实；类方法可用 `class(MathBox).Add(...)` 或 `findClass("MathBox").Add(...)` 调用，静态字段可用 `class(THuman).mCount` 访问。
上面这种裸类名成员访问不作为可写事实；类方法可用 `class(MathBox).Add(...)` 或 `findClass("MathBox").Add(...)` 调用，静态字段可用 `class(Human).count` 访问。
代码块身份：反例 / 不可照写