https://github.com/klauer/blark
Beckhoff TwinCAT ST (IEC 61131-3) code parsing in Python using Lark (Earley)
https://github.com/klauer/blark
iec61131-3 sphinx-domain structured-text twincat
Last synced: about 2 months ago
JSON representation
Beckhoff TwinCAT ST (IEC 61131-3) code parsing in Python using Lark (Earley)
- Host: GitHub
- URL: https://github.com/klauer/blark
- Owner: klauer
- License: gpl-2.0
- Created: 2020-02-09T00:35:54.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-01-31T16:54:22.000Z (4 months ago)
- Last Synced: 2025-03-30T13:08:00.426Z (about 2 months ago)
- Topics: iec61131-3, sphinx-domain, structured-text, twincat
- Language: Python
- Homepage: https://klauer.github.io/blark/
- Size: 6.57 MB
- Stars: 49
- Watchers: 5
- Forks: 5
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Beckhoff TwinCAT IEC 61131-3 Lark-based Structured Text Tools
Or for short, blark. B(eckhoff)-lark. It sounded good in my head, at least.
## The Grammar
The [grammar](blark/iec.lark) uses Lark's Earley parser algorithm.
The grammar itself is not perfect. It may not reliably parse your source code
or produce useful Python instances just yet.
See [issues](https://github.com/klauer/blark/issues) for further details.
As a fun side project, blark isn't at the top of my priority list. For
an idea of where the project is going, see the issues list.
## Requirements
* [lark](https://github.com/lark-parser/lark) (for grammar-based parsing)
* [lxml](https://github.com/lxml/lxml) (for parsing TwinCAT projects)
## Capabilities
* TwinCAT source code file parsing (``*.TcPOU`` and others)
* TwinCAT project and solution loading
* ``lark.Tree`` generation of any supported source code
* Python dataclasses of supported source code, with introspection and code refactoring
### Works-in-progress
* Sphinx API documentation generation (a new Sphinx domain)
* Code reformatting
* "Dependency store" - recursively parse and inspect project dependencies
* Summary generation - a layer on top of dataclasses to summarize source code details
* Rewriting source code directly in TwinCAT source code files
## Installation
Installation is quick with Pip.
```bash
pip install --upgrade blark
```
### Quickstart (pip / virtualenv with venv)
1. Set up an environment using venv:
```bash
$ python -m venv blark_venv
$ source blark_venv/bin/activate
```
2. Install the library with pip:
```bash
$ python -m pip install blark
```
### Quickstart (Conda)
1. Set up an environment using conda:
```bash
$ conda create -n blark-env -c conda-forge python=3.10 pip blark
$ conda activate blark-env
```
2. Install the library from conda:
```bash
$ conda install blark
```
### Development install
If you run into issues or wish to run an unreleased version of blark, you may
install directly from this repository like so:
```bash
$ python -m pip install git+https://github.com/klauer/blark
```
## Sample runs
Run the parser or experimental formatter utility. Current supported file types
include those from TwinCAT3 projects ( ``.tsproj``, ``.sln``, ``.TcPOU``,
``.TcGVL``) and plain-text ``.st`` files.
```bash
$ 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) ...
```
To interact with the Python dataclasses directly, make sure IPython is
installed first and then try:
```
$ 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'
```
Dump out a parsed and reformatted set of source code:
```bash
$ 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 supports rewriting TwinCAT source code files directly as well:
```bash
$ blark format blark/tests/POUs/F_SetStateParams.TcPOU
OpenPLC is an open-source Programmable Logic Controller that is based on easy to use software. Our focus is to provide a low cost industrial solution for automation and research. OpenPLC has been used in many research papers as a framework for industrial cyber security research, given that it is the only controller to provide the entire source code.
- [RuSTy](https://github.com/PLC-lang/rusty)
[documentation](https://plc-lang.github.io/rusty/intro_1.html) - Structured text
compiler written in Rust. As stated by the project:
> RuSTy is a structured text (ST) compiler written in Rust. RuSTy utilizes the LLVM framework to compile eventually to native code.
- [IEC Checker](https://github.com/jubnzv/iec-checker) - Static analysis tool
for IEC 61131-3 logic. As described by the maintainer:
> iec-checker has the ability to parse ST source code and dump AST and CFG to JSON format, so you can process it with your language of choice.
- [TcBlack](https://github.com/Roald87/TcBlack) - Python black-like code formatter for TwinCAT code.