Beckhoff TwinCAT IEC 61131-3 基于Lark的Structured Text工具

或者简称为blark。B(eckhoff)-lark。在我的脑海中，至少听起来不错。

语法

该语法使用Lark的Earley解析器算法。

该语法本身并不完美。它可能无法可靠地解析您的源代码或生成有用的Python实例。

有关更多信息，请参阅问题。

作为一个有趣的边项目，blark不是我的首要任务。有关项目的未来方向，请参阅问题列表。

需求

• lark（用于基于语法的解析）
• lxml（用于解析TwinCAT项目）

功能

• TwinCAT源代码文件解析（*.TcPOU等）
• 加载TwinCAT项目和解决方案
• 生成任何支持的源代码的lark.Tree
• 支持源代码的Python数据类，具有内省和代码重构

正在进行中

• Sphinx API文档生成（一个新的Sphinx域）
• 代码重排
• “依赖存储”-递归解析和检查项目依赖关系
• 摘要生成 - 在数据类之上提供一个层，以总结源代码细节
• 直接在TwinCAT源代码文件中重写源代码

安装

使用Pip安装快捷方便。

pip install --upgrade blark

快速入门（pip / virtualenv与venv）

1. 使用venv设置环境

$ python -m venv blark_venv
$ source blark_venv/bin/activate

2. 使用pip安装库

$ python -m pip install blark

快速入门（Conda）

1. 使用conda设置环境

$ conda create -n blark-env -c conda-forge python=3.10 pip blark
$ conda activate blark-env

2. 从conda安装库

$ conda install blark

开发安装

如果您遇到问题或希望运行blark的未发布版本，您可以像这样直接从本存储库安装

$ python -m pip install git+https://github.com/klauer/blark

示例运行

运行解析器或实验性的格式化工具。当前支持的文件类型包括来自TwinCAT3项目的文件（.tsproj、.sln、.TcPOU、.TcGVL）和平文.st文件。

$ blark parse --print-tree blark/tests/POUs/F_SetStateParams.TcPOU
function_declaration
  None
  F_SetStateParams
  indirect_simple_specification
    None
    simple_specification        BOOL
  input_declarations
    None
    var1_init_decl
      var1_list
... (clipped) ...

要直接与Python数据类交互，请确保首先安装了IPython，然后尝试

$ blark parse --interactive blark/tests/POUs/F_SetStateParams.TcPOU
# Assuming IPython is installed, the following prompt will come up:

In [1]: results[0].identifier
Out[1]: 'F_SetStateParams/declaration'

In [2]: results[1].identifier
Out[2]: 'F_SetStateParams/implementation'

输出解析并重新格式化的源代码集

$ blark format blark/tests/source/array_of_objects.st
{attribute 'hide'}
METHOD prv_Detection : BOOL
    VAR_IN_OUT
        currentChannel : ARRAY [APhase..CPhase] OF class_baseVector(SIZEOF(vector_t), 0);
    END_VAR
END_METHOD

blark也支持直接重写TwinCAT源代码文件

$ blark format blark/tests/POUs/F_SetStateParams.TcPOU

<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
  <POU Name="F_SetStateParams" Id="{f9611d23-4bb5-422d-9f11-2cc94e61fc9e}" SpecialFunc="None">
    <Declaration><![CDATA[FUNCTION F_SetStateParams : BOOL
    VAR_INPUT
        nStateRef : UDINT;
        rPosition : REAL;
        rTolerance : REAL;
        stBeamParams : ST_BeamParams;

... (clipped) ...

还可以将源代码解析为支持代码内省和重写的标记化SourceCode树

In [1]: import blark

In [2]: parsed = blark.parse_source_code(
   ...:     """
   ...: PROGRAM ProgramName
   ...:     VAR_INPUT
   ...:         iValue : INT;
   ...:     END_VAR
   ...:     VAR_ACCESS
   ...:         AccessName : SymbolicVariable : TypeName READ_WRITE;
   ...:     END_VAR
   ...:     iValue := iValue + 1;
   ...: END_PROGRAM
   ...: """
   ...: )

# Access the lark Tree here:
In [3]: parsed.tree.data
Out[3]: Token('RULE', 'iec_source')

# Or the transformed information:
In [3]: transformed = parsed.transform()

In [4]: program = transformed.items[0]

In [5]: program.declarations[0].items[0].variables[0].name
Out[5]: Token('IDENTIFIER', 'iValue')

可重用解析器的支持起始语法规则包括

"iec_source"
"action"
"data_type_declaration"
"function_block_method_declaration"
"function_block_property_declaration"
"function_block_type_declaration"
"function_declaration"
"global_var_declarations"
"program_declaration"
"statement_list"

对于高级用户，其他起始规则仍然可能，但在那种情况下必须创建新的解析器，并且不支持转换。

此外，请注意，您应该避免即时创建解析器，因为重新解析语法的启动成本很高。尽可能使用从blark.get_parser()提供的解析器。

In [1]: import blark

In [2]: parser = blark.new_parser(start=["any_integer"])

In [3]: Tree('hex_integer', [Token('HEX_STRING', '1010')])

添加测试用例

目前，测试用例以两种形式提供。在blark/tests/目录中，有POUs/和source/目录。

TwinCAT源代码文件属于blark/tests/POUs。纯文本源代码文件（例如，.st文件）属于blark/tests/source。

请随时贡献您的测试用例，我们将尽力确保blark可以无误地解析它们（并且继续解析它们）。

致谢

最初基于Volker Birk的IEC 61131-3语法iec2xml（GitHub分叉在此）以及Flor Narciso等人的IEC 61131-3标准编程语言的句法规范。语法中的许多方面都得到了增加、修改，并且在某些情况下完全重写，以更好地支持lark语法和转换器。

特别感谢blark的贡献者

• @engineerjoe440

相关、类似或替代项目

有多个类似或相关的项目可供选择。

• "MATIEC" - 另一个支持IEC 61131-3第二版结构化文本的解析器，不包含类、命名空间和其他华丽的功能。更新版本也可在GitHub上找到
• OpenPLC运行时版本3 - 如项目所述

  OpenPLC是一个开源的可编程逻辑控制器，基于易于使用的软件。我们的重点是提供低成本工业自动化解决方案。OpenPLC已被用于许多研究论文中，作为工业网络安全研究的框架，因为它是有源代码的唯一控制器。

• RuSTy 文档 - 使用Rust编写的结构化文本编译器。如项目所述

  RuSTy是一个结构化文本（ST）编译器，使用Rust编写。RuSTy使用LLVM框架最终编译成本地代码。

• IEC Checker - IEC 61131-3逻辑的静态分析工具。如维护者所述

  iec-checker能够解析ST源代码并将其AST和CFG转换为JSON格式，因此您可以使用您选择的任何语言进行处理。

• TcBlack - TwinCAT代码的类似于Python black的代码格式化器