# 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` 应当**响亮报「未知指令」**，而不是把整个程序体咽下去、报"编译完成"。
