roald87 / tcblack

Opnionated code formatter for TwinCAT.

TcBlack: TwinCAT code formatter

Opinionated code formatter for TwinCAT. Currently in the alpha state. Use at your own risk and only with files which are under source control.

TcBlack is available as a command line tool (TcBlackCLI) as well as a visual studio extension (TcBlackExtension).

Current state

FB_Child from ShowcaseProject formatted using the TcBlackExtension for Visual Studio.

TcBlackCLI usage

1. Download the latest release.

2. Open the windows command prompt and navigate to the folder containing TcBlack.exe.

3. Reformat one or more file by giving their full path names:

   > TcBlack --safe --file C:\Full\Path\To\Filename.TcPOU C:\Full\Path\To\AnotherFilename.TcPOU
   

   or using the short version and format a single file:

   > TcBlack --safe -f C:\Full\Path\To\Filename.TcPOU
   

   or format a whole project at once and replace all indentation by a two spaces:

   > TcBlack --safe -f C:\Full\Path\To\Project.plcproj --indentation "  "
   

For more info enter > TcBlack --help in the command prompt or check the manual.

Installing the extension

To install the VSIX extension in Visual Studio or TcXaeShell please see the installation guide.

Idea

Change

FUNCTION_BLOCK  FB_Child EXTENDS FB_Base  IMPLEMENTS I_Interface,I_Interface2

VAR_INPUT
END_VAR
VAR

SomeText: STRING;
	Counter		: DINT:= 1 ;
  Result		: DINT :=2;


      Base:FB_Base;
END_VAR
===================================
SomeText:= 'Current counts';

IF Conditions[1] AND Conditions[2]  AND Conditions[3] AND Conditions[4] AND Conditions[5]AND Conditions[6] THEN
	Counter :=Counter+ 1;

	IF Counter > 2 THEN
	Counter := Counter + 5 ;
	END_IF
END_IF

Base(Variable1:=2, Variable2:=3 , Variable3:= 5,Sentence:='Entropy is a real bitch.', Conditions :=Conditions);


AddTwoInts(    Variable1 :=4,
    Variable2:=4);

Into

FUNCTION_BLOCK FB_Child
EXTENDS FB_Base
IMPLEMENTS I_Interface, I_Interface2
VAR
    SomeText : STRING;
    Counter : DINT := 1;
    Result : DINT := 2;

    Base : FB_Base;
END_VAR

===================================
SomeText := 'Current counts';

IF
    Conditions[1]
    AND Conditions[2]
    AND Conditions[3]
    AND Conditions[4]
    AND Conditions[5]
    AND Conditions[6]
THEN
    Counter := Counter + 1;

    IF Counter > 2 THEN
        Counter := Counter + 5 ;
    END_IF
END_IF

Base(
    Variable1:=2,
    Variable2:=3 ,
    Variable3:=5,
    Sentence:='Entropy is a real bitch.',
    Conditions:=Conditions
);

AddTwoInts(Variable1:=4, Variable2:=4);

Why

Get a consistent style across your project, without having to go through all the code. Focus on the logic and structure of the code, not the formatting.

How

By making a command line tool which can be either used manually on individual files, a whole project or added as a pre-hook commit which automatically reformats before making a commit.

Style

Follow the same style rules as Black for Python (where applicable). Why try to reinvent the wheel, when Black offers a popular rule base which has been tested and tried? For more info see the style guide.

TcBlackCLI implementation

There are two modes for the TcBlackCLI. A safe mode which checks if the code did not undergo unwanted changes after reformatting. The non-safe mode is faster, but it could be that there were unwanted changes to the code. TcBlackExtension always operates in the non-safe mode.

The safe mode builds the project before and after formatting. It then compares the generated number (a sort of checksum?) which is used as the name of the *.compileinfo file. This file is generated in the _CompileInfo folder of a project each time it is build.

The number doesn't change when you alter whitespaces, add/change comments or add brackets around a long if statement. Only if the actual code changes then the number also changes. For example, if you add a variable, add a line of code or change the order of variables.

Contributing

You're more then welcome to help if you'd like! See the contributing guidelines for more info.

tcblack's Issues

Regex for variable definition fails on string which includes semi colon or closing bracket

Losing the initialization portion if there's a semicolon inside the string

My initial idea was negative lookahead in the Tokenize method.

TcBlack/src/TcBlack/VariableDeclaration.cs

Line 77 in 8440ab0

+ $@"{unit_pattern}{possible_space}{initialization}(?:;){comment}";

(?:;(?!.*;))
This negative lookahead would fail if there's a semi colon in the comment portion of the line also.

But that gives me even weirder results with the assignment operator now showing up.

Remove assembly signing

Github secrets are not available to forked repos. That's why the piplines of the PR's failed from others than mine.

Singing would only be necessary in case of publishing a release. So, it should be possible to remove the required signature when it goes into the pipeline for only builds and tests.

Build TwinCAT project using DevEnv

See TcUnit project here and here. Or Beckhoff documentation API and an example.

Add command to turn off/on formatting

Use // fmt: off and end with // fmt: on to turn off formatting of a certain code section.

Prevent exception in non-safe mode without build.log

If you run TcBlack for the first time and in non-safe mode it will raise an exception because the build.log file is not there. If you first run it in safe mode the file gets created.

Prevent insert of := in array limits

Turns

Buffer: ARRAY[0..TcUnit.GVL_Param_TcUnit.xUnitBufferSize - 1] OF BYTE;

into

Buffer: ARRAY[0..TcUnit.GVL_Param_TcUnit.xUnitBufferSize := - 1] OF BYTE;

but should not change

VSIX support for VS2019

Would you consider adding support to the vs extension for VS2019?
Thanks.

Only find files with .sln extension

Currently if there is a file which is called .slnbak then it can't find a single .sln file and thus it will return an empty sln path.

Recognize empty lines

Do not remove spaces from strings in FB_init of a function block

Currently it removes spaces from

// In
fbInst : FB_WithName(Name:='Text with spaces');

// Out
fbInst : FB_WithName(Name:='Textwithspaces');

Visual Studio Development Tools Environment (DTE) build method is slower than devenv solution

The new build method implemented with #47 is much slower than the previous solution. Is there a way to speed things up?

Seperate pipeline into a build and test part

Then it is clearer where it failed.

Do not put spaces around negative array indices

Currently it does this:

-aLINT : ARRAY[-1..1] OF LINT;
+aLINT : ARRAY[ - 1..1] OF LINT;

This should not happen.

Remove any empty lines after VAR and before END_VAR

No message in console that it is building the project after formatting in safe mode

Add support for IMPLEMENTS and EXTENDS

Get line ending and indentation from TcPOU file

Search for the line ending and indentation type (spaces vs tabs) in the file and use the same type when calling Format().

Investigate making lineending and indentation global variables

Would save a lot of code, since these are used everywhere. Question is does it work with the unit tests?

Add support for access modifiers

Recognize PUBLIC, PRIVATE, PROTECTED, INTERNAL in functions and function blocks.

File shouldn't have to be saved before doing a format

If you add a few extra lines of code and do not save the file and then format, TcBlack will remove the code you just added. Only if you save the file it will correctly format it.

TcBlackExtension v0.1.0

Removes FB name from declaration when using FINAL

Removed the FB name. My initial guess is due to the FINAL descriptor.

With a FINAL method also weird behavior with an extra colon added.

If you point me in the right direction I can take a look at it.

Detect with which TwinCAT version the original project was build

And build it than using the same one.

Make TcBlackCLI work from every directory and with relative paths

Currently TcBlack.exe only works under the following conditions:

1. build.log needs to be present when executed in non-safe mode.
2. TcBlack.exe is executed directly from its own folder
3. All files which should be reformatted are entered with their full paths.

Add undo functionality to TcBlackExtension

After formatting a text with the TcBlackExtension, there is no way to undo it. you can't undo it with Ctrl + Z. Not sure how to implement this yet.

Empty line should have equal number of tabs as surrouding code

Or else there will be unnecessary diffs, since the VS TwinCAT editor automatically adds these indents.

This is to prevent diffs like these (double empty lines are automatically removed):

VAR
    var1 : REAL;
-    
-    
+
    var2 : REAL;
END_VAR 

How to insert a tab in windows command prompt when you want to use tabs for indentation

I could not figure out how to format using the tab as an indentation in the windows command prompt. I tried:

• pasting it and turning on/off the option where special characters are converted in the command prompt properties
• using --indentation "\t"

The work around I found was to make a bat file with the following content and run that one.

> TcBlack.exe --indentation "	" -p C:\Some\Project\PLC.plcproj 

Replace hardcoded devenv path with method to find devenv path on local system

Currently the devenvPath is hard coded in TcProjectBuilder to the default path "C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/Common7/IDE/devenv.exe" for VS2017. Would be nice to make it independent of the system and VS version.

Adds extra white space on empty line

Adds extra white space on empty line between variable declarations.

Also include TcBlackExtension in build pipeline

I couldn't build TcBlackExtension when I added TCatSysManager.dll to the project, but it should be possible to do it like that according to Gerhard Barteling.

Remove empty variable type declarations

// in

METHOD Something
VAR_INPUT
END_VAR
VAR
END_VAR

// out

METHOD Something

Format a whole project at once

If you give a .plcproj file instead of a .TcPOU file, it should reformat all the files in the project.

Make class for unrecognized lines

Calling Format() on these will return the original string.

GUI/Integration into Visual Studio for TcBlack

Is it possible to add an GUI/Integration to Visual Studio for TcBlack, the same way that StWeep is integrated into Visual Studio? Would be nice to have an open-source alternative to StWeep.

Format implementation of files

Currently only looks like the Declaration part of files are formatted. I'd like to look at getting the Implementation part of files included. Did you have any specific ideas/ways you were thinking of doing this?

Rename TcProgrammingEntity to TcObject

Better name which is also used in the docs.

Replace complex regex in Tokenize

Currently the VariableDeclaration.Tokenize() method in TcBlackCore has quite a complex regular expression to separate all the different components. For example to close #35 a two step regex was needed. It might be a better idea to replace the regex with a a finite state machine as also discussed here. Example of finite state machine.

Raise exception when no plcproj or sln file is found

If you format in safe mode and it either fails to find a . plcproj file and/or a .sln file it will still do the formatting.

Make it such that the user receives an error message and it aborts the formatting.

• Program should handle the file not found exception
• Add test for plcproj not found
• Add test for sln file not found

Add support for multiline comments

Add trailing commas to expressions that are split by comma where each element is on its own line

Pipeline should notify in case of static code analyses warnings

Currently the static code analyses is run, but there is no clear indication when a warning was raised due to this. For example this one:

Not sure how to indicate failure. Somehow need to return a number other than 0 to make the pipeline fail.

Only run pipeline when there are changes in src folder

Other folders do not contain files which should be build.

Use: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths

Add support for PUBLIC FINAL/ABSTRACT

The following combinations are possible:

FUNCTION_BLOCK PUBLIC FINAL SomeFB
FUNCTION_BLOCK INTERNAL FINAL SomeFB

FUNCTION_BLOCK PUBLIC ABSTRACT SomeFB
FUNCTION_BLOCK INTERNAL ABSTRACT SomeFB

METHOD PUBLIC ABSTRACT METH : BOOL
METHOD PRIVATE ABSTRACT METH : BOOL
METHOD PROTECTED ABSTRACT METH : BOOL
METHOD INTERNAL ABSTRACT METH : BOOL

Add option to change line length

Add --line-length option for CLI to change the line length.

Override automatic type detection of line ending and indentation

Currently if TcBlack will detects a single \r\n in a .TcPOU file it will use \r\n as a line ending. Similarly for the indentation: if it finds a single \t in a file it will use that one for the entire file.

It would be nice to override this behavior. For example in case there is a single \t in the file, but everywhere else four spaces are used.

Also this would allow for more indentation types then the current options of tabs or four spaces. Finally this would allow for an easy way to standardize the indentation across an entire project.

Format declarations of methods and properties

Make command line interface to run TcBlack

• Implement safe mode
  • Get hash before and after compile
• When selecting a single file, find plcproj and sln file automatically
• Read TcPou file(s)
• Reformat files
• Make a .bak copy of the original file
• Write reformatted code in in original file

Recognize pragma fields

E.g. nVar : INT; {info 'TODO: should get another name'}

TcBlackCore can not be build

When trying to build the TcBlackCore project I get the following error:

Unable to get MD5 checksum for the key file "TcBlackCoreSign.pfx". Could not find file 'C:\Users_username_\source\repos_username_\TcBlack\src\TcBlackCore\TcBlackCoreSign.pfx'.

This file is mentioned in the solution explorer, but is not included in the repo.

After removing the file in the solution explorer the solution could be build.

Show how many files were reformatted

Maybe non-verbose mode shows the number of reformatted files:

> TcBlack.exe --filenames C:\SomeFile.TcPOU C:\SecondFile.TcPOU
...
All done! Formatted 1 of total 2 files.

And the verbose mode (-v --verbose) also shows which files were reformatted

> TcBlack.exe --verbose --filenames C:\SomeFile.TcPOU C:\SecondFile.TcPOU
...
All done! Formatted 1 of total 2 files:
 - C:\SomeFile.TcPOU

And if none were formatted:

> TcBlack.exe --filenames C:\SecondFile.TcPOU
...
All done! No files were formatted.

Add support to format interfaces