v0.8.3

Grammar changes

• IDENTIFIER will no longer match certain reserved keywords.

• Fixed a variety of scenarios where additional semicolons are acceptable in TwinCAT.

• EXTENDS now supports a list of bases (function blocks, interfaces, structures, unions)

• Function block variable declarations now also support VAR_INST

• END_INTERFACE is now optional.

• Dual access specifiers are now supported for PROPERTY:

   PROPERTY PRIVATE p_fActValue : LREAL PROTECTED
   END_PROPERTY
  

  Here, PROTECTED is the access_override which overrides the default PRIVATE.

Fixes

• Boolean literals were parsed as IDENTIFIER terminals rather than boolean_literal instances.
• End positions of comments and pragmas as retrieved from tokens in ParseResult.comments were off by one. Fixed both Token.end_pos and Token.end_column.
• blark.summary: Case insensitive access of variable names
• blark.summary: Consolidates getters/setters into a single summary
• blark.summary: Added implementation_source to more classes
• blark.summary: Fixes for handling multiple base extends
• Better handling for determining POU types from XML and plain code
• Outdated GitHub Actions workflows are now running again

Pull Requests

• CI/FIX: deprecated actions by @klauer in #112
• Fix end position of comments and pragmas by @klauer in #113
• Fix end positions of comments and pragmas by @alajovic in #110
• Increase priority of constant rule in grammar (#108) by @alajovic in #114
• Adding on to #111 by @klauer in #116
• Some fixes by @DenSinH in #111

New Contributors

• @alajovic made their first contribution in #110
• @DenSinH made their first contribution in #111

Thank you, @alajovic and @DenSinH!

Full Changelog: v0.8.2...v0.8.3

v0.8.2

What's Changed

• Extended unions (#102 by @engineerjoe440) should now parse correctly:

  TYPE THING EXTENDS THING_BASE:
  UNION
      {attribute 'hide' := 'true'}
      As_THING_BASE : THING_BASE;
  END_UNION
  

• Enumerated default values defined by function calls (#104 by @engineerjoe440) should now parse:

  {attribute 'qualified_only'}
  {attribute 'to_string'}
  TYPE color :
  (
     off := ANY_TO_DINT(someColor.off),
     red := ANY_TO_DINT(someColor.red),
     green := ANY_TO_DINT(someColor.green)
  ) DINT;
  

• Fixed support for multiple structure member variable declarations in the same line (#105), for example:

  TYPE someStruct :
  STRUCT
          AlertTimer, SignalBadTimer, QualityBadTimer : library.TPUDO;
  END_STRUCT
  END_TYPE
  

  The dataclasses and relevant summary versions have been updated to accommodate this.

• Fixed a class of issues related to blark's lax whitespace handling, where things such as variable names could be unintentionally interpreted as reserved keywords (#107)

Full Changelog: v0.8.1...v0.8.2

v0.8.1

This is a packaging bugfix release.

For details about v0.8.0, see here.

Full Changelog: v0.8.0...v0.8.1

v0.8.0

What's Changed

• Fixed support for function call chaining in general expressions beyond just statements (#93 / #94)
• Fixed support for indirect specifications with initialization parameters (e.g., POINTER TO FB_Something(1, 2)) (#85, #95)
• Some initial API documentation is now available on GitHub Pages
  • All transformer (lark grammar -> AST-like) dataclasses now have docstrings and examples (#89)
  • Dataclass documentation shows the associated Lark grammar rule(s)
• Fixed incorrect escape character for double quotes in double-byte strings ($" #86)
• The prototype Sphinx domain is returns to being functional post-solution-loading refactor (#87)
• Comment pre-parsing will now include positional metadata (#89)
• Preliminary supporting for annotating source code with HTML/XML tags (stylesheets not included) (#88)
  • Example: blark format --output-format html FB_ProjectA.TcPOU
• More test coverage of the grammar and related tools

Grammar

• Added chained_function_call grammar rule (ChainedFunctionCall dataclass)
• Some unused rules and terminals - vestiges of old blark functionality - were removed
  • structured_var_declaration, function_var_decl, step_*
• Added chained_function_call
  • chained_function_call_statement now uses chained_function_call

Pull Requests

• Unused grammar rule clean-up and grammar coverage tests by @klauer in #86
• FIX: make sphinx domain work again by @klauer in #87
• ENH/DOC: docstrings + start of API docs by @klauer in #89
• ENH: first pass at html output by @klauer in #88
• CI: documentation deployment GitHub Action by @klauer in #92
• FIX: function call chaining in expressions by @klauer in #94
• FIX: init arguments for pointer type specifications by @klauer in #95

Full Changelog: v0.7.1...v0.8.0

v0.7.1

What's Changed

• FIX: format failure of #83 by @klauer in #84

Full Changelog: v0.7.0...v0.7.1

v0.7.0

What's Changed

This release includes a major rework of TwinCAT solution file loading, the blark CLI tool, and a number of grammar-related fixes.

• INTERFACE definitions are now supported. (#73) The solution loader can load these .TcIO files directly.
• Add support for the JMP statement (#79)
• Grammar fixes for the following:
  • Arrays of arrays in type declarations and initialization (e.g., fValue : ARRAY [1..10] OF ARRAY [1..10] OF INT;) (#66)
  • Code with identifiers starting with Return or Continue will no longer be mistaken for statements of the same name (#68)
  • String lengths may now be expressions (e.g., STRING(g_Constant + 1) := 'abc') (#72)
  • Expressions in initial array elements are no longer limited to constants (e.g., currentChannel : ARRAY[1..g_c_someConstant] OF POINTER TO struct_groupData := [ ADR(_object[1].someValue) ];) (#74)
  • Removed support for power expression (**) which is invalid in TwinCAT-flavor ST (#76)
• A new TwinCAT solution loader (.sln, .tsproj, .TcPOU, etc.) was added to blark with a goal of making file loading more easily customizable, with the option to load/save arbitrary file formats. (#64)
  • The implementation is preliminary and subject to change (as is everything in blark).
  • blark continues to support the current input formats (plain text .st files, and TwinCAT source code files)
  • Removed the dependency on pytmc (for code loading, the dependency store, and everything else).
  • New requirement, lxml, for project parsing.
  • Allow for mapping of blark input line numbers back to source code files. Input files may now correspond to one or more different grammar rules (e.g., a TcPOU FUNCTION_BLOCK that contains declaration, an implementation, and any number of METHOD / ACTION / PROPERTY sub-items).
  • Allow for in-place code rewriting of source code files (blark format --write my_pou.TcPOU)
• Rework of user-facing parsing API to use a consistent dataclass. (#64)
  • This groups together the source code, a map of line numbers, the raw lark.Tree, and an option to easily transform it into blark.transform dataclasses to allow for code rewriting, reformatting, summarization, and so on.
• Rework of the blark parse CLI. See blark parse --help for more details.
• Rework of the blark format CLI to support the new input/output file handling. See blark format --help for more details.

Pull Requests

• Support arrays of arrays by @engineerjoe440 in #66
• Resolve RETURN and CONTINUE Overly-Greedy Matching by @engineerjoe440 in #68
• FIX: string length expression by @klauer in #72
• REF/ENH: standalone solution parser and rewrite of input/output format support by @klauer in #64
• FIX/CLN: remove unsupported power_expression by @klauer in #76
• FIX: Bugfix for expressions in initial array elements by @klauer in #74
• ENH: interface support by @klauer in #73
• ENH: first pass at JMP and labeled statements by @klauer in #79
• FIX: ignore global text list project files by @klauer in #81

Full Changelog: v0.6.0...v0.7.0

v0.6.0

What's Changed

This release includes a number of small-but-important grammar fixes.

• Fixed support for explicit base 10 integer literals (e.g., 10#12345)
• Added an explicit CONTINUE statement. This erroneously parsed as a no-op statement previously.
• Added support of chained function-call/method-call statements with new function_call_statement_list grammar.
• Added optional dereference (^) character to function and method calls (e.g., uut.call1()^.call2())
• Removed method_statement to reduce ambiguity, since method_statement is a subset of functional_call_statement
• Add support for array initializer for function_block objects. (Example)
• Enhanced function_block declaration to support setting structured attributes (VAR_INPUT and VAR_IN_OUT).

Pull Requests

• FIX: further annotation-related fixes by @klauer in #46
• CI: updates to GitHub Actions and pre-commit fixes by @klauer in #49
• Feature/add continue statement to grammar by @engineerjoe440 in #48
• updated README by @engineerjoe440 in #51
• Add Support of Chained Method/Function Calls by @engineerjoe440 in #55
• Array Initializer by @engineerjoe440 in #56
• Support Dereferenced Function/Method Returns in Grammar by @engineerjoe440 in #59
• Support for Explicit Base 10 Integers by @engineerjoe440 in #62
• Address Issue with Array-Initialization -- Other General Cleanup by @engineerjoe440 in #63

Full Changelog: v0.5.0...v0.6.0

v0.5.0

What's Changed

• Enhancement/support recursive pointer to by @engineerjoe440 in #33
• Bugfix/Enhancement: Add Support of bit_string_literal in CASE Statements by @engineerjoe440 in #35
• Enhancements and Fixes Found While Testing Code Base by @engineerjoe440 in #36
  • Add Support of VAR_EXTERNAL in Functions
  • Allow DateTimes to exclude seconds/fractional-seconds
  • Support Arrays of FunctionBlocks that use an FB_init inline
  • Allow "Stray" semicolons that would otherwise have no effect
  • Allow Namespaced (dotted) access to structures in declarations when setting a default.
  • Separate Global Variable Attributes to allow inclusion of "INTERNAL"
  • Fix function call handling of empty arguments
• Refactor/enhancement: better CLI handling of non-TwinCAT files by @klauer in #37
• Bugfix: small regression after IndirectionType adjustments of #33 by @klauer in #38
• Maintenance: test coverage and dropping support for lark < 1.0 by @klauer in #39
• CI: code coverage via pytest-cov and codecov by @klauer in #40
• Maintenance/tests: Move existing example to test suite + remove invalid one by @klauer in #41
• Bugfix: miscellaneous transformer fixes to get JSON serialization working by @klauer in #42
• Test suite: fix source file naming in test suite by @klauer in #45

Full Changelog: v0.4.0...v0.5.0

v0.4.0

What's Changed

Grammar enhancements

• Support access specifiers for function block declarations by @engineerjoe440 in #22
• Add Support of Indirection in Unions by @engineerjoe440 in #26
• Function and Data Type Access Specifier, and Structures using FB_Init args by @engineerjoe440 and @klauer in #30
• LTIME (and related) support by @engineerjoe440 in #31
• AND_THEN and OR_ELSE operators by @engineerjoe440 in #25

Development updates

Continuous integration additions:

• Add Github Action to Run Pytest for push/pull-request Actions by @engineerjoe440 in #23
• Add flake8 Github Action by @engineerjoe440 in #24

New Contributors

• @engineerjoe440 became the first blark collaborator.

Thanks for the excellent feedback, contributions and help, @engineerjoe440!

Full Changelog: v0.3.0...v0.4.0

v0.3.0

Changes / fixes / etc

A big release with an overhaul of most aspects of blark.

• Add round-trippable Python dataclasses for structured text grammar
  • Source code -> dataclasses you can interact with -> source code
  • Comments and pragmas can be retained
  • Formatting is not retained (blark has an abstract - not full - syntax tree)
• Added start of sphinx domain for code documentation generation
• Added UNION, PROPERTY support and many other grammar fixes
• Nested comments are handled fully
• Added dependency store
  • Parse project + all dependencies that have source code available
  • Using the summary classes, relatively easily poke around with source code objects
• Removed unused dataclasses + grammar rules
  • Closes #18
  • Up for discussion if I'm missing something
  • Task config, instruction lists, SFC networks, ...
• Grammar fixes
  • Functions can return indirect types
  • Added variable attribute flags to blocks where accepted, according to infosys docs
• Improved code summary utilities
  • Easier to use to find declarations and such
  • Add ProgramSummary, GlobalVariableSummary
  • Base type EXTENDS declarations are wrapped into the derived type
• Added program and global variables to documentation generation (sphinx domain)
• Added apischema-based serialization in the test suite
  • This helped improve the type annotations in places as round-tripping validation was failing
  • However, Python 3.9+ with apischema 0.17.5 (did not test other versions) is hitting an infinite loop when attempting to serialize most of the data structures. Serialization testing for those Python versions is disabled for now until I get a chance to dig in / report the issue if it's not on my end
  • Python 3.7 and Python 3.8 are testing serialization with the transformed dataclasses just fine though

PRs

• REF/ENH: round-trippable Python dataclasses for structured text grammar by @klauer in #9
• ENH: initial attempts at code summary layer, sphinx domain by @klauer in #12
• ENH: dependencies, first pass at serialization, and more by @klauer in #19

Full Changelog: v0.1.7...v0.3.0