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/20_object_runtime_and_introspection.md
+53 -23
View File
@@ -18,7 +18,7 @@
2. 普通对象创建、普通方法调用、类声明和继承都回到 [08_objects_and_classes.md](08_objects_and_classes.md)，不要把 `findClass(...)` / `createObject(...)` 当默认写法。
3. 确实命中反射时，入口优先照 `findClass`、`findFunction`、`thisFunction`、`findOverLoad` 等文档明确示例写。
4. 访问弱引用前先做 `checkWeakRef(...)` 判定，不要假设失效弱引用安全返回 `nil`。
5. 类内 `weakRef;` / `autoRef;` 段落式写法属于反例，不要照写。
5. 类内段落式 `weakRef` / `autoRef`（不带分号）是合法的成员弱引用开关；只有带分号的 `weakRef;` / `autoRef;` 才报 `invalid class definition`。
6. 函数值调用边界回看函数页，避免把函数指针直接当普通函数调用。
7. 没有对应代码块时不要发明对象运行时/反射/弱引用写法。
@@ -48,7 +48,7 @@
- 对已经失效的弱引用直接调用 `weakref_get(w)` 会运行报错，不要把它当成“安全返回 nil”的接口。
- 类成员上的 `[weakRef] field;` 和 `[autoRef] field;` 可以通过。
- `[weakRef]` 成员不会阻止对象析构；强引用释放后，对象会正常销毁。
- 类内段落式 `weakRef;` / `autoRef;` 不作为可写事实，错误信息包含 `invalid class definition`。
- 类内段落式 `weakRef` / `autoRef`（不带分号）像 `public` / `private` 一样切换后续成员的弱引用属性，可写；只有带分号的 `weakRef;` / `autoRef;` 才报 `invalid class definition`。
## 可直接照写示例
@@ -84,12 +84,12 @@ end;
```tsl
classA := findClass("A");
obj := new A();
writeLn(classA.FucA());
writeLn(classA.FuncA());
writeLn(obj is classA);
type A = class
public
class function FucA();
class function FuncA();
begin
return "ClassA";
end;
@@ -110,18 +110,18 @@ end;
```tsl
objb := new ClassB();
obj := findClass("ClassA", objb);
writeLn(obj.Fuc());
writeLn(obj.Func());
type ClassA = class
public
function Fuc(); virtual;
function Func(); virtual;
begin
return "ClassA";
end;
end;
type ClassB = class(ClassA)
public
function Fuc(); override;
function Func(); override;
begin
return "ClassB";
end;
@@ -183,10 +183,10 @@ end;
代码块身份：可直接照写示例
```tsl
oa := new ca("abc");
oa := new Ca("abc");
writeLn(objectstate(oa));
type ca = class
type Ca = class
public
static sca;
function create(n);
@@ -208,20 +208,20 @@ end;
代码块身份：可直接照写示例
```tsl
o := new ca();
o := new Ca();
o.c := 3;
writeLn(o.c);
type ca = class
type Ca = class
public
value;
property c read getc write setc;
function setc(v);
property c read Getc write Setc;
function Setc(v);
begin
writeLn(tslassigning);
value := v;
end;
function getc();
function Getc();
begin
writeLn(tslassigning);
return value;
@@ -302,16 +302,16 @@ end;
代码块身份：可直接照写示例
```tsl
t := findOverLoad(2, "fun", new TestClass());
t := findOverLoad(2, "Fun", new TestClass());
writeLn(t.do(1, 2));
type TestClass = class
public
function fun(p1, p2); overload;
function Fun(p1, p2); overload;
begin
return p1 + p2;
end;
function fun(p1); overload;
function Fun(p1); overload;
begin
return p1 + 10;
end;
@@ -321,7 +321,7 @@ end;
结果说明：
- 输出 `3`
- 说明 `findOverLoad(2, "fun", obj)` 可以按参数个数拿到对应重载方法
- 说明 `findOverLoad(2, "Fun", obj)` 可以按参数个数拿到对应重载方法
### 函数信息、对象枚举与生命周期
@@ -356,14 +356,15 @@ end;
代码块身份：可直接照写示例
```tsl
objA := new TestClass01(100);
objB := new TestClass01(101);
objsInfo := tslObjects(1);
writeLn(length(objsInfo["TestClass01"]));
newObjA := objsInfo["TestClass01"][0, "obj"];
writeLn(newObjA is class(TestClass01));
writeLn(newObjA.add(1, 2));
objA := new TestClass01(100);
objB := new TestClass01(101);
type TestClass01 = class
public
value;
@@ -371,7 +372,7 @@ public
begin
value := _value;
end;
class function add(x, y);
class function Add(x, y);
begin
return x + y;
end;
@@ -556,7 +557,7 @@ end;
- 不要把 `objectstate(self)` 里的 `self` 泛化成普通成员访问都要加 `self` 前缀。
- 不要把弱引用能力的条件编译宏写成 `weakRef`。
- 不要以为 `weakref_get(deadWeakRef)` 会像普通可空访问那样安全返回 `nil`。
- 不要以为类内段落式 `weakRef;` / `autoRef;` 也能直接通过。
- 不要给段落切换关键字加分号；`weakRef;` / `autoRef;`（带分号）会报 `invalid class definition`，段落式要写成不带分号的 `weakRef` / `autoRef`。
- 不要以为 `[weakRef]` 成员会继续强持有对象。
代码块身份：反例 / 不可照写
@@ -573,4 +574,33 @@ public
end;
```
上面这种把 `weakRef;` / `autoRef;` 当作类内段落切换的写法不作为可写事实，会编译失败，错误信息包含 `invalid class definition`。
上面这种给段落切换关键字**加分号**（`weakRef;` / `autoRef;`）的写法会编译失败，错误信息包含 `invalid class definition`。关键在分号：段落切换关键字要像 `public` / `private` 那样**不带分号**独占一行，带分号后被当成独立语句才报错。正确的段落式写法见下一段。
段落式 `weakRef` / `autoRef`（不带分号）像 `public` / `private` 一样切换后续成员的弱引用属性：
代码块身份：可直接照写示例
```tsl
o := new AutoWeakTest();
o.fa := 1;
o.fb := 2;
writeLn(o.fa, ',', o.fb);
type AutoWeakTest = class
public
fa;
weakRef
fOnClick;
fOnDblClick;
autoRef
fb;
end;
```
结果说明：
- 输出 `1,2`
- `weakRef`（不带分号）打开后续成员的自动弱引用开关，`fOnClick` / `fOnDblClick` 成为弱引用成员
- `autoRef`（不带分号）关闭开关，`fb` 恢复为强引用成员
- 段落切换只影响其后、下一个切换关键字之前的成员；`fa` 在初始（强引用）段
- 这与行内 `[weakRef] field;` 是两种可用写法：行内只作用于单个成员，段落式作用于整段