feat: IEC 61131-3 structure and array initialization (forum report), plus six initialization fixes

[thiagoralves]

Closes the forum report "Initialization variable with user defined structure type". The user's syntax was correct IEC 61131-3 — the production simply wasn't implemented. Investigating it surfaced five more initialization defects, three of them silent wrong-value bugs.

Structure initialization (Annex B.1.4.3)

test_ai_var : analog_input := (min_ai_scale := 4.0, max_ai_scale := 22.0);

Previously error: Expected RParen, found :=. Now supported in every declaration position: file-level and CONFIGURATION VAR_GLOBAL, PROGRAM / FUNCTION_BLOCK / FUNCTION / METHOD variables, STRUCT element defaults, inside array literals, and for function block instances (t : TON := (PT := T#1s) — the same production the standard uses for fb_name_decl).

Lowering lives in one place, backend/struct-init-codegen.ts, shared by codegen.ts and type-codegen.ts:

strucpp::iec_struct_init<POINT>([](auto& v0) { v0.Y = 2.0; v0.X = 1.0; })

Not a braced aggregate initializer: elements may be written in any order and may be omitted, with an omitted element keeping the default from its own declaration — which C++17 cannot express (no designated initializers). The runtime helper default-constructs the value, applying each element's own default, and the lambda overwrites only what is named. Nested levels take their type from decltype(v0.MEMBER), so library types and inline array members need no metadata lookup.

Also implements the type-level default forms of Annex B.1.3.3 (Setpoint : REAL := 25.0;, Origin : Point := (x := 0.0);), previously a parse error even for elementary types. A single post-build pass copies the default onto declarations without their own initializer, so every downstream consumer sees an ordinary initializer; it re-runs on the merged unit so a TYPE and its uses can live in different files.

Array repetition (Annex B.1.4.3 array_initial_elements)

[10(0)], [3(1), 2(5)], [7, 4(2), 9], and the bracket-less := 2(3), 2(4). The repeated value is a full expression, so it may be a structure initializer or a nested array literal. Gated on an integer immediately followed by (, which is never an expression in ST, so a function call as an array element is unaffected. Counts above 65536 throw rather than truncating — expansion is linear in the count.

Nested array initializers, and 3D arrays

[[1, 2, 3], [4, 5, 6]] for a multi-dimensional array. Implemented in the runtime rather than by teaching codegen to detect ranks, so overload resolution handles it and the notation works in every scope automatically. Each level fills from its own lower bound, so a short inner list leaves the rest of that row at its default instead of shifting the next row up — the semantic difference from writing the values flat. Array1D also gained an element-typed list, so an array whose element is itself composite works (ARRAY[0..1] OF Row), and so does the nested-Array1D chain a 4+-dimensional array lowers to.

3D arrays were entirely unusable, not merely uninitialisable: IEC_ARRAY_3D had neither an initializer list nor at(), and codegen emits the bounds-checked at() for every subscript in a body. It is now at parity with 1D/2D.

Function block array invocation

units[0](step := 2.0) did not parse — the statement was taken as an assignment target, which then demanded :=. A new instanceCallStatement, gated on ( following the closing ] directly, claims exactly the element invocation and leaves arr[0].m(…) to the existing rules. FunctionCallExpression gains an optional instance; the FB type resolves through the array's element type, and input assignment, the call, VAR_IN_OUT copy-back and => capture all work against that expression unchanged, including variable and multi-dimensional indices.

Bugs found and fixed along the way

Each was pre-existing; the first three were silent.

• PROGRAM variable composite initializers were dropped. arr : ARRAY[0..2] OF INT := [1,2,3] compiled clean and ran with a zero-filled array — the project model flattened initializers to a string via expressionToString, which had no case for array literals. It now carries the AST expression, which also removed the parallel string-lowering pass in getDefaultValue (based literals, digit separators, typed prefixes, time and calendar literals, strings), so declaration initializers and statement bodies can no longer disagree.
• Array-literal defaults on a STRUCT element were dropped to {} with no diagnostic.
• STRING/WSTRING literals in the type generator were emitted unescaped, so an embedded " closed the C++ string early. Latent until array defaults started emitting; OSCAT's HTML-entity tables hit it immediately. translateIECString moved to codegen-utils so a STRING literal lowers identically everywhere.
• The debug pointer table indexed multi-dimensional arrays with chained [i][j], which Array2D/Array3D have no operator for — so any project with a multi-dimensional array and debug enabled failed to build (reported from an AVR build). A shared formatArrayElementAccess now owns the per-rank rule alongside formatArrayType.
• File-level VAR_GLOBAL was invisible to VAR_EXTERNAL. Such a reference now validates, including the type check, and is dropped from the pointer-plumbing list — file-level globals are plain file-scope storage the body already reaches by name, and a GlobalVar<V>* member would shadow the very global being referenced. The CONFIGURATION path is unchanged.
• A TYPE naming a function block (AccumGrid : ARRAY[…] OF Accum) emitted its alias before the POU forward declarations, so the element type was undeclared.

Two initializer forms change shape

Both still valid C++ with the same value, and now identical to what the statement path emits: INT#5 emits static_cast<IEC_INT>(5) instead of 5, and 1.5E3 emits 1500.0. The two assertions in codegen-var-initializers.test.ts that were pinned to the old string-lowering output are updated.

Verification

2132 tests passing (86 files), up from 2006 — ~126 new across parser/AST, the shared lowering, codegen, semantics, and g++ integration. Coverage thresholds pass; type-defaults.ts at 100%.

The integration tests run the binaries and assert values, not just compilation — the only way to catch out-of-order elements landing on the wrong member, omitted elements losing their defaults, or a repetition group filling the wrong slots.

Also validated end-to-end through the OpenPLC Editor on a real project (44 assertions covering every form, plus the AVR generated_debug.cpp compiled for atmega2560), since the program and debug-table paths fail independently.

Documented, not implemented

• := [10()] — repetition with no value. No positional lowering in C++17, and neither matiec nor CODESYS accepts it.
• A method call on an array element, units[0].M() — needs the expression grammar's method-call lookahead to accept a subscripted object.
• No validation that an array initializer's shape or element count matches the declared dimensions, and none that a subscript count matches the rank. Ordinary mistakes there surface as C++ errors or silent truncation rather than ST diagnostics. Worth a follow-up.

🤖 Generated with Claude Code

[thiagoralves]

Added a seventh commit: feat(semantic): validate array initializer shape and subscript count.

This closes the follow-up flagged in the description — the three mistakes that previously escaped to g++ or truncated silently now produce ST diagnostics with line and column:

ARRAY[0..2] OF INT := [1,2,3,4,5,6]              -> compiled, silently kept 1,2,3
ARRAY[0..1,0..1] OF INT := [[1,2,3],[4,5,6]]     -> compiled, silently dropped 3 and 6
ARRAY[0..1,0..1,0..2] OF INT := [[1,2,3],[4,5,6]] -> g++: no matching constructor
p[0,0] on a 3-dimensional array                   -> g++: no matching call to 'at'

Now:

fmt.st:3:29: error: Initializer for 'A' has 6 values but the array holds 3. The extra values would be discarded.
fmt.st:7:8: error: 'M' has 2 dimensions but is indexed with 1 index.

The subscript check walks the ordered access chain rather than the flat subscripts list, because only the chain distinguishes a[0][1] (two steps into an array of arrays) from a[0,1] (one two-index step into a 2D array) — the flat list reports 2 for both.

Every check is skipped rather than guessed at when the shape isn't statically known (ARRAY[*], non-constant bounds, unresolved types, a dereference in the chain), so it can only add diagnostics for definite mistakes. 31 new tests, deliberately split between rejected and accepted cases — the accepted half is the point, since a false positive here would block valid code.

Suite: 2163 passing, no net new lint warnings.

[marconetsf]

Dropping the string path loses precision on 64-bit integer initializers. projectVarInitializer now routes PROGRAM/VAR_GLOBAL initializers through generateInitializer → generateExpression → formatIntegerLiteral, whose plain-decimal branch is return String(value) where value is a JS number (parseIECInteger uses parseInt). The removed lowerNumericInitializer passed the raw digits through iecBaseToCppLiteral (which returns raw.replace(/_/g, "") for decimals), so it was exact.

PROGRAM Main VAR x : LINT := 9007199254740993; END_VAR

used to emit X(9007199254740993) and now emits X(9007199254740992) — a silently wrong constant. Either keep rawValue for plain decimals in formatIntegerLiteral (return raw.replace(/_/g, "")) or store integer literal values as bigint.

[marconetsf]

case "StructInitializerExpression": … return "{}" is a silent-wrong-value fallback, and it is reachable from real ST, not just from impossible positions. generateExpression's ArrayLiteralExpression case maps elements through generateExpression, so arr := [(x := 1.0), (x := 2.0)]; in a PROGRAM body emits ARR = {{}, {}}; — every element zeroed, no diagnostic. The same happens for a structure initializer passed as a named FB argument and for SETUP vars in test-main-gen.ts (emitExpression(decl.initialValue)). Since a structure initializer in a non-declaration position is not legal IEC anyway, emit a CompileError (or a codegen warning) here instead of silently value-initialising.