← 都来码 / Dolaima← 例程索引ladder/school/MANIFEST.md 原文

ladder/school/MANIFEST.md · 13513 字节 · 下载原文

# Ladder(梯形图 / PLC)外部语料 —— **改成 IEC ST**(2026-10-15 重收)

> **口径变更**:本前端是 IEC 61131-3 的**混合体**(文本梯级 `.ld` **加** ST 语句),
> 而它的 `BEGIN` 门在 2026-10-15 放开了 —— 之前**只有"程序体第一条是裸打印"才允许省略 `BEGIN`**,
> 把任何真实方言挡在第 1 行(见文末「历史」)。放开之后**真实的 IEC ST 程序编得动了**,
> 所以本门语料**从 LDmicro 换成 IEC ST**。

## 清单(5 个)

| 文件 | 类别 | 来源 | 许可 | 行数 | 编译 | 第一条错误(原样) |
|:--|:--|:--|:--|--:|:--:|:--|
| `conveyor.st` | 控制流(传送带启停 + 急停 + `ELSIF` 链) | https://github.com/vul-os/kerf/blob/main/packages/kerf-plc/tests/fixtures/conveyor.st | **MIT** | 32 | ✅ | — |
| `counter_program.st` | 数值(计数器 PROGRAM) | https://github.com/ironplc/ironplc/blob/main/examples/getting_started.st | **MIT** | 23 | ✅ | — |
| `blinker.st` | 定时器(1 Hz 脉冲,`TON` 实例调用) | https://github.com/vul-os/kerf/blob/main/packages/kerf-plc/tests/fixtures/blinker.st | **MIT** | 15 | ❌ | `期望 )`(具名实参 `t(IN := …, PT := T#1s)`) |
| `st_timing_utils.st` | 数组/数值(`ARRAY[*] OF TIME` + 提前返回) | https://github.com/Autonomy-Logic/smart-traffic-light/blob/main/src/Functions/TimingUtils.st | **MIT** | 67 | ❌ | `无法识别的语句(遇到 KeywordReturn 'RETURN')` |
| `st_traffic_types.st` | 类型(枚举 `TYPE … : (RED, GREEN, YELLOW)` + `STRUCT`) | https://github.com/Autonomy-Logic/smart-traffic-light/blob/main/src/DataTypes/TrafficTypes.st | **MIT** | 26 | ❌ | `期望 Identifier,实际得到 LeftParenthesis` |

三条硬口径(`scripts/compat-external-lint.py --dir .`):**5 个文件 0 违规**。
**合计:5 / 通过 2 / 失败 3。**

## 为什么只有 5 个(这次搜了、但**没收**的都记在这)

现实里的 IEC ST **是按"工程"组织的**,不是按"单文件程序"—— 搜到的绝大多数命中都**不满足
上级 README 那条"要自包含(单文件、不依赖外部)"**,所以**宁缺毋滥**,一个都没硬凑:

| 来源 | 为什么没收 |
|:--|:--|
| `ironplc/ironplc` 的 `compiler/plc2plc/resources/test/*_rendered.st`(107 个) | **解析器测试夹具**(round-trip 输入),**不是程序** —— `array_rendered.st` 里 `i` 都没声明就用了;收进来会把"未声明的变量"读成编译器缺口 |
| `wasome-plc/tutorials`(Apache-2.0,18 个) | **多文件工程片段**:`ch05-3/PROGRAM/func.st` 的注释自己写着"全局变量在 IDE 的全局变量列表中定义"、`main.st` 用 `VAR_EXTERNAL` 调另一个文件里的函数 ⇒ 单拿出来必报"未声明的变量" |
| `joyautomation/nautilus`(Apache-2.0,100 个) | 同上:`examples/batch-skid/lib/physics.st` 的注释自己写着「**a project library**」「`sim.st` is the only caller」⇒ 是库不是程序 |
| `Autonomy-Logic/smart-traffic-light` 的 `Programs/IntersectionController.st` | ⚠ 用 `AT %IX0.0 : BOOL` —— **IEC 直接 I/O 地址**,就是"直接操作硬件",**违反硬口径②** |
| `tkucic/plc_hello_mixing_tank`(MIT) | 它**没有 `.st` 文件**(ST 正文在 markdown 文档里),不是可直接编译的语料 |

⇒ ⚠ **顺带补了 lint 的一条漏网**:`%IX0.0` / `%QW1` / `%MB10` 这类 **IEC 直接 I/O 地址**
从前**没有任何规则管**(那几条只管 DOS 的 `inportb`/`MK_FP`),于是上面那份用了 `%IX0.0` 的
ST 文件**静默通过**了三条硬口径。现在加了这条(判据要 `%` 紧跟 I/Q/M 再跟数字 ——
别的语言里 `%` 是取模,不会长这样),并**正反两向自校**过。
⚠ 同一次还修了 lint 把 **`MANIFEST.md` 当语料判**的误报(文档会**举例**提到被禁的写法,
"前端不认 `%IX0.0`" 这种句子被当成了违规)。

## 这批照出来的 ST 缺口(按文件数)

1. **`RETURN` 语句**(`st_timing_utils.st`)—— 提前返回,ST 里到处是它。
2. **枚举类型 `TYPE X : (A, B, C);`**(`st_traffic_types.st`)—— 现在报 `期望 Identifier,得到 LeftParenthesis`。
3. **功能块实例 + 具名实参**(`blinker.st` 的 `t : TON; t(IN := clock_in, PT := T#1s); t.Q`)
   —— 需要**实例**这一层语义,不是纯语法。

## 先摸清本仓 `.ld` 是什么方言(动手找之前必读)

`Examples/ladder/` + `docs/老程序兼容性.md` 读完,结论是 ——
本仓的「Ladder」**不是任何一个厂商的梯形图方言**,而是一套自研的
**IEC 61131-3 混合体**(`LadderCompiler/Lexer.cs` 的关键字表是唯一真源):

- **骨架**:`PROGRAM <名> / VAR … END_VAR / BEGIN … END_PROGRAM`,语句带 `;`,注释只认 `(* … *)`;
- **IL 助记符**:`LD / LDI / ST / OUT / SET / RST / ANDN / ORN`(三菱 / Mitsubishi 味);
- **功能块**:`TON / TOF / TP / CTU / CTD / CTUD`(IEC 味);
- **ST 语句**:`IF/ELSIF/ELSE/END_IF`、`WHILE`、`FOR`、`CASE`、`:=`、`AND/OR/NOT/MOD`;
- **图形化梯级**:`--| |--`(常开触点)/ `--|/|--`(常闭)/ `--( )--`(线圈)/
  `--(S)--` / `--(R)--` / `--[TON]--` / `--[CTU]--`(**文本画的梯形图**,`Lexer.cs:GetLadderElementTokenType`);
- 还有裸打印 `PRINT_STR/PRINT_INT/PRINT_FLOAT/PRINT_CHAR`。

⇒ 「同样形态」的判据就是上面这一套。**网上没有任何厂商的文本梯形图长这样**(见下)。

## 清单

| 文件名 | 类别 | 方言 | 来源 URL | 许可 | 行数 | 编译 | 第一条错误 |
|:--|:--|:--|:--|:--|--:|:--:|:--|
| `traffic.ld` | 经典模拟(交通灯) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/traffic.ld | GPL-3.0 | 73 | ❌ | `traffic.ld:1:1: error: 期望 BEGIN 关键字` |
| `blink.ld` | 定时器(闪烁灯) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/blink.ld | GPL-3.0 | 61 | ❌ | `blink.ld:1:1: error: 期望 BEGIN 关键字` |
| `coil_s_r_n.ld` | 触点/线圈(S/R/N 线圈) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/coil_s_r_n.ld | GPL-3.0 | 39 | ❌ | `coil_s_r_n.ld:1:1: error: 期望 BEGIN 关键字` |
| `ctu_ctd_ctc.ld` | 计数器(CTU/CTD/CTC) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/ctu_ctd_ctc.ld | GPL-3.0 | 58 | ❌ | `ctu_ctd_ctc.ld:1:1: error: 期望 BEGIN 关键字` |
| `var-timer.ld` | 定时器(可变延时 TOF) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/var-timer.ld | GPL-3.0 | 63 | ❌ | `var-timer.ld:1:1: error: 期望 BEGIN 关键字` |
| `7seg-display.ld` | 数组/查表(数码管) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/7seg-display.ld | GPL-3.0 | 123 | ❌ | `7seg-display.ld:1:1: error: 期望 BEGIN 关键字` |
| `hello.ld` | 字符串/文本(串口 Hello) | LDmicro | https://github.com/LDmicro/LDmicro/blob/master/ldmicro/sample/hello.ld | GPL-3.0 | 31 | ❌ | `hello.ld:1:1: error: 期望 BEGIN 关键字` |
| `conveyor.st` | 控制流(传送带启停/急停) | IEC ST | https://github.com/vul-os/kerf/blob/main/packages/kerf-plc/tests/fixtures/conveyor.st | MIT | 32 | ❌ | `conveyor.st:2:1: error: 期望 BEGIN 关键字` |
| `blinker.st` | 定时器(1Hz 脉冲) | IEC ST | https://github.com/vul-os/kerf/blob/main/packages/kerf-plc/tests/fixtures/blinker.st | MIT | 15 | ❌ | `blinker.st:2:1: error: 期望 BEGIN 关键字` |
| `counter_program.st` | 数值(计数器 PROGRAM) | IEC ST | https://github.com/ironplc/ironplc/blob/main/examples/getting_started.st | MIT | 23 | ❌ | `counter_program.st:16:5: error: 期望 BEGIN 关键字` |
| `motor_onoff.iecst` | 模拟(电机启停 + 互锁) | IEC ST | https://github.com/fernanda-salinas/Structured-Text-PLC/blob/main/MotorONOFF.iecst | 未标注 | 24 | ❌ | `motor_onoff.iecst:1:1: error: 期望 BEGIN 关键字` |
| `send_message_timers.iecst` | 控制流(定时器状态机) | IEC ST | https://github.com/fernanda-salinas/Structured-Text-PLC/blob/main/SendMessageTIMERS.iecst | 未标注 | 57 | ❌ | `send_message_timers.iecst:1:1: error: 期望 BEGIN 关键字` |

> 许可:LDmicro 为 **GPL-3.0**(`LICENSE.txt`)、kerf 与 ironplc 为 **MIT**;
> fernanda-salinas/Structured-Text-PLC **仓库里没有 LICENSE 文件**,按「未标注」记。
> 收进仓库前按上级 README「许可」一节由人来定。

## 当年这 12 个文件**全军覆没**(12/12 同一条错误)

**根因一句话**:本前端**要求程序体以 `BEGIN` 开头**,而**没有任何一个真实世界的 PLC 文本方言会写 `BEGIN`**。

`Parser.cs:156` 那段:`BEGIN` 可有可无,**仅当**程序体第一条是裸打印语句(`PRINT_*`)时才允许省略;
否则 `Expect(KeywordBegin)` 当场报错。而两类语料都不满足:

| 方言 | 程序体开头是 | 结果 |
|:--|:--|:--|
| **LDmicro**(`.ld`,7 个) | 第 1 行是文件头 `LDmicro0.1` | 报在 `1:1` |
| **IEC 61131-3 ST**(`.st/.iecst`,5 个) | `END_VAR` 之后直接进语句(标准里**根本没有 `BEGIN`**) | 报在程序体第一条(`2:1` / `16:5` / `1:1`) |

**这条错误是"响的"(好)**,但也说明:**本前端读不了任何现实方言** ——
`LDmicro` 用的 `RUNG / CONTACTS / COIL / TON / CTC` 与本仓的 `NETWORK / LD / OUT / --( )--` 是**两套词**;
IEC ST 的 `//` 注释、`T#1s` 时间字面量、`%IX0.0` 地址、`tonX(IN := …, PT := …)` 功能块调用形态
本前端也一概不认(`test_error.ld` 明写「本前端**不认** COM / `//` / `'`」)。

### 附带发现(⚠ 供编译器开发参考):补上 `BEGIN` 之后,程序体会被**静默吞掉**

在副本里**手工插一个 `BEGIN`**(只为定位,不改语料)后复测:

- **7 个 LDmicro 文件全部"编过"**(`✔ 编译完成`)—— 但**是空的**:
  `RUNG` 被当成标识符读进去,撞上 `CONTACTS`(既不是 `(`、`[`,也不是 `:=`)⇒
  落进 `ParseStStatement` 末尾那句「**跳过无法识别的语句**」(`while (… != Semicolon && … != EOF)`),
  而 LDmicro 文件**一个 `;` 都没有** ⇒ 一口气吞到 EOF ⇒ 产出一个**空程序**、退出码 0、不报错。
  最小复现(现写的,两行之差):

  ```
  BEGIN
  RUNG
    CONTACTS X 1
    COIL Y 0 0 0
  END
  ```
  ⇒ `✔ 编译完成`,**运行无任何输出**。

  ⚠ 这正是本仓 **E222 / BUG-03** 的同一个形态(「整条梯级连后面第一条语句一起消失」):
  **"编译绿 ≠ 程序跑对"**。这类"静默吞掉"对老程序最危险 —— 用户看到"编译通过"就以为能跑了。

- **5 个 ST 文件补 `BEGIN` 后仍报 `期望 BEGIN`**(它们的 `PROGRAM`/`FUNCTION_BLOCK` 头、
  或没有 `VAR` 段,落点各不相同)—— 说明这道门**不止一道**。

## 找不到更多 —— 如实说明(重要)

**这门语言"网上的文本形态经典梯形图"基本不存在**,试过的来源与结论:

| 来源 | 结果 |
|:--|:--|
| Rosetta Code | **没有 ladder / PLC 任务**(该站不覆盖 IEC 61131-3) |
| GitHub 搜 `structured text plc examples` 一族的仓库(fernanda-salinas / LeandroDQuevedo / PacktPublishing/PLCs-for-Beginners / Krishnaelectrovoltz / CONTROLLINO-PLC / tkucic / corgiolu-labs …) | 命中的**几乎全是 IDE 工程文件**(CODESYS `.project` / PLCopen `plc.xml` / `.ecp`,含 LD 图形或二进制),**不是纯文本源码**;纯 `.st` 只有零星片段(`fernanda` 那份**无 LICENSE**、且是博文片段不是完整程序) |
| Beremiz / OpenPLC Editor 的 `exemples/` | 经典「First Steps」等例题**全在 `plc.xml`(XML 工程)里**,ST 正文是 `<ST><![CDATA[…]]></ST>` 片段,**不是独立 `.st` 文件** |
| ironplc / nautilus | 有完整 `.st`,但**是给编译器/测试用的资源**(`first_steps_*`)、或是 **2024-2026 的新工程**(`examples/*`),**不算"经典老程序"** ⇒ 只挑了其中 1 个最接近例题形态的 `getting_started.st` |
| LDmicro `sample/` | ✅ **唯一成规模、真·经典、纯文本**的梯形图语料(交通灯 / 闪烁 / 线圈 / 计数器 / 定时器 / 数码管 / 串口 Hello),但仍属**另一套方言** |
| 中文 PLC 教材 / 各厂商手册(S7-300 AWL、S7-200 STL、三菱/欧姆龙助记符、AB `.L5X`) | **全是 PDF / 扫描件**;文本部分是**厂商专属方言**(`A I0.0` / `XIC` / `LD…OUT…TIM`),与本前端不同源,且不成独立文件形态 |

⇒ **能凑到 10 个"单文件、纯文本、经典"的只有靠 LDmicro(7 个)为骨架,
再补 5 个真实世界的 IEC ST 例题**。**没有硬凑、没有现编** —— 12 个文件全部是网上原样下载的真实程序。
若只认「同一个方言」,则**这门语言在互联网上找不到 10 个可用的**(LDmicro 之外基本为零)。

## 给编译器开发的两句话

1. **要收现实方言,先放开 `BEGIN` 这道门**(IEC ST 标准里没有 `BEGIN`)——
   否则任何真实的英 ST/IL/LDmicro 程序都会在第 1 行就被挡掉,**一整门语言的语料测不出别的东西**。
2. **补上 `BEGIN` 之后的"静默吞掉整段"要优先修**(E222 同族):
   一条 `RUNG`/`CONTACTS`/`COIL` 应当**响亮报「未知指令」**,而不是把整个程序体咽下去、报"编译完成"。