simaticml-decoder 0.1.0__py3-none-any.whl

simaticml_decoder/instructions.py

@@ -0,0 +1,105 @@
+"""The instruction catalog — deliberately *data, not logic*.
+
+fold.py reasons about pin *categories* (power-flow in/out, comparison pre/out,
+box en/eno, flip-flop, OR-junction), never about specific instruction names.
+This table maps Part Name -> category + pin vocabulary + a render hint. Adding a
+new instruction (TOF, CTU, NContact, ...) is a row here, not a change to the
+traversal. That is what lets v0's "parse-but-flag everything else" degrade
+gracefully: a name absent from this table folds to an ir.Unhandled node.
+
+Pin names per the Part Pin Vocabulary in SIMATICML_READING_GUIDE.md. Entries are
+the confirmed instructions from the six sample blocks plus their clearly-symmetric
+siblings (TOF/TP, Sr, NBox/NContact, the comparison family).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Category(str, Enum):
+    POWER_FLOW = "power_flow"      # in/out, contact-like: passes or blocks power
+    COIL = "coil"                 # in/out, writes its operand
+    OR_JUNCTION = "or_junction"   # merges parallel branches (Part Name="O")
+    COMPARISON = "comparison"     # pre/out, contact-like compare
+    EDGE = "edge"                 # pre/out or in/out, rising/falling detection
+    FLIPFLOP = "flipflop"         # named set/reset inputs -> q
+    BOX = "box"                   # en/eno operation box (Move/Add/Inc/timers/system FC)
+
+
+@dataclass
+class Spec:
+    name: str
+    category: Category
+    power_in: str | None = None         # name of the power-in pin, if any
+    power_out: str | None = None        # name of the power-out pin, if any
+    render: str | None = None           # operator/keyword hint for emit (":=", "<", ...)
+    pins: tuple[str, ...] = field(default_factory=tuple)  # informative pin list
+    note: str = ""
+
+
+# Helper constructors keep the table compact and readable.
+def _pf(name, render=None):
+    return Spec(name, Category.POWER_FLOW, "in", "out", render, ("in", "operand", "out"))
+
+
+def _coil(name, render):
+    return Spec(name, Category.COIL, "in", "out", render, ("in", "operand", "out"))
+
+
+def _cmp(name, op):
+    return Spec(name, Category.COMPARISON, "pre", "out", op, ("pre", "in1", "in2", "out"))
+
+
+def _box(name, pins, render=None):
+    return Spec(name, Category.BOX, "en", "eno", render, pins)
+
+
+CATALOG: dict[str, Spec] = {
+    # --- power flow -------------------------------------------------------- #
+    "Contact": _pf("Contact"),
+    "Coil": _coil("Coil", ":="),
+    "SCoil": _coil("SCoil", "S"),       # set coil  ( S )
+    "RCoil": _coil("RCoil", "R"),       # reset coil ( R )
+    "O": Spec("O", Category.OR_JUNCTION, None, "out", "OR", ("in1", "in2", "out")),
+    # --- comparisons (pre/out, contact-like) ------------------------------ #
+    "Lt": _cmp("Lt", "<"),
+    "Le": _cmp("Le", "<="),
+    "Eq": _cmp("Eq", "="),
+    "Ne": _cmp("Ne", "<>"),
+    "Ge": _cmp("Ge", ">="),
+    "Gt": _cmp("Gt", ">"),
+    # --- edge detection ---------------------------------------------------- #
+    "PContact": Spec("PContact", Category.EDGE, "pre", "out", "rising",
+                     ("pre", "operand", "bit", "out")),
+    "NContact": Spec("NContact", Category.EDGE, "pre", "out", "falling",
+                     ("pre", "operand", "bit", "out")),
+    "PBox": Spec("PBox", Category.EDGE, "in", "out", "rising", ("in", "bit", "out")),
+    "NBox": Spec("NBox", Category.EDGE, "in", "out", "falling", ("in", "bit", "out")),
+    # --- flip-flops -------------------------------------------------------- #
+    "Rs": Spec("Rs", Category.FLIPFLOP, None, "q", "reset_priority",
+               ("s1", "r", "operand", "q")),
+    "Sr": Spec("Sr", Category.FLIPFLOP, None, "q", "set_priority",
+               ("s", "r1", "operand", "q")),
+    # --- boxes (en/eno) ---------------------------------------------------- #
+    "Move": _box("Move", ("en", "in", "out1", "eno"), ":="),
+    "Add": _box("Add", ("en", "in1", "in2", "out", "eno"), "+"),
+    "Sub": _box("Sub", ("en", "in1", "in2", "out", "eno"), "-"),
+    "Mul": _box("Mul", ("en", "in1", "in2", "out", "eno"), "*"),
+    "Div": _box("Div", ("en", "in1", "in2", "out", "eno"), "/"),
+    "Inc": _box("Inc", ("en", "operand", "eno"), "+1"),
+    "Dec": _box("Dec", ("en", "operand", "eno"), "-1"),
+    "Calculate": _box("Calculate", ("en", "eno"), "equation"),
+    # --- IEC timers (system FBs; UPPERCASE pins; need Instance) ------------ #
+    "TON": _box("TON", ("IN", "PT", "Q", "ET")),
+    "TOF": _box("TOF", ("IN", "PT", "Q", "ET")),
+    "TP": _box("TP", ("IN", "PT", "Q", "ET")),
+    # --- system FC example ------------------------------------------------- #
+    "RD_LOC_T": _box("RD_LOC_T", ("en", "RET_VAL", "OUT", "eno")),
+}
+
+
+def lookup(name: str) -> Spec | None:
+    """Return the Spec for a Part name, or None (caller folds to ir.Unhandled)."""
+    return CATALOG.get(name)

simaticml_decoder/ir.py

@@ -0,0 +1,182 @@
+"""Phase 2 output: the folded *semantics*, with no memory of the XML.
+
+A network becomes an ordered list of statements. Rung conditions become a boolean
+expression tree. Two cross-cutting commitments live here from the start:
+
+* Traceability — every node carries the source ``uid``(s) it came from, so emit
+  can map any rendered claim back to the net it was derived from.
+* Loud failure — anything the folder could not interpret becomes an ``Unhandled``
+  node carrying its part name + uid, so emit can surface it visibly instead of a
+  silent omission (the worst possible failure in authoritative-looking SCL).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+# --------------------------------------------------------------------------- #
+# Boolean / value expressions (rung conditions, comparison operands)          #
+# --------------------------------------------------------------------------- #
+@dataclass
+class VarRef:
+    """A resolved operand, already rendered to its display form by operand.py."""
+
+    name: str                           # e.g. "#FI_Forward", '"DB".field', "%MW100"
+    uid: str | None = None
+
+
+@dataclass
+class Literal:
+    value: str                          # rendered constant, e.g. "0", "TRUE", "T#3s"
+    uid: str | None = None
+
+
+@dataclass
+class Not:
+    operand: Expr
+
+
+@dataclass
+class And:
+    operands: list[Expr] = field(default_factory=list)
+
+
+@dataclass
+class Or:
+    operands: list[Expr] = field(default_factory=list)      # n-ary, matches O cardinality
+
+
+@dataclass
+class Compare:
+    op: str                             # "<" | "<=" | "=" | ">=" | ">" | "<>"
+    left: Expr
+    right: Expr
+    uid: str | None = None
+
+
+class EdgeKind(str, Enum):
+    RISING = "rising"                   # P_TRIG / PContact / PBox
+    FALLING = "falling"                 # N_TRIG / NContact / NBox
+
+
+@dataclass
+class Edge:
+    kind: EdgeKind
+    signal: Expr                        # monitored signal / incoming power flow
+    mem_bit: VarRef | None = None       # edge-memory operand
+    uid: str | None = None
+
+
+@dataclass
+class RawExpr:
+    """Free-form expression text taken verbatim (e.g. a Calculate-box Equation)."""
+
+    text: str
+    uid: str | None = None
+
+
+@dataclass
+class Unhandled:
+    """A construct parsed but not folded. Rendered loudly by emit, never dropped."""
+
+    part_name: str
+    uid: str | None = None
+    note: str = ""
+
+
+Expr = (
+    VarRef | Literal | Not | And | Or | Compare | Edge | RawExpr | Unhandled
+)
+
+
+# --------------------------------------------------------------------------- #
+# Statements (one rung's effect)                                              #
+# --------------------------------------------------------------------------- #
+class AssignKind(str, Enum):
+    NORMAL = "normal"                   # Coil           ->  target := <cond>;
+    NEGATED = "negated"                 # negated Coil   ->  target := NOT <cond>;
+    SET = "set"                         # SCoil          ->  IF <cond> THEN target := TRUE;
+    RESET = "reset"                     # RCoil          ->  IF <cond> THEN target := FALSE;
+
+
+@dataclass
+class Assign:
+    target: VarRef
+    value: Expr
+    kind: AssignKind = AssignKind.NORMAL
+    is_latch: bool = False              # set when a structural seal-in was detected
+    note: str | None = None             # surfaced by emit when load-bearing
+    uid: str | None = None
+
+
+@dataclass
+class FlipFlop:
+    """Rs / Sr — reset- or set-priority bistable on a stored operand."""
+
+    target: VarRef
+    set_expr: Expr
+    reset_expr: Expr
+    reset_priority: bool = True         # Rs == reset-dominant; Sr == set-dominant
+    uid: str | None = None
+
+
+@dataclass
+class BoxCall:
+    """A system FB/FC box: TON/TOF/TP, Move/Add/Inc, RD_LOC_T, ..."""
+
+    instruction: str                    # "TON", "Move", ...
+    inputs: dict[str, Expr] = field(default_factory=dict)    # pin -> expression
+    outputs: dict[str, VarRef] = field(default_factory=dict) # pin -> destination
+    instance: str | None = None         # rendered instance name, for system FBs
+    enable: Expr | None = None          # the en / IN power-flow condition
+    uid: str | None = None
+
+
+@dataclass
+class UserCall:
+    """A Call/CallInfo to a user FC/FB — parameters self-documented in the XML."""
+
+    name: str
+    block_type: str                     # FC | FB
+    instance: str | None = None
+    params: dict[str, Expr | VarRef] = field(default_factory=dict)
+    enable: Expr | None = None
+    uid: str | None = None
+
+
+Statement = Assign | FlipFlop | BoxCall | UserCall | Unhandled
+
+
+# --------------------------------------------------------------------------- #
+# Network + block level                                                        #
+# --------------------------------------------------------------------------- #
+@dataclass
+class NetworkLogic:
+    index: int
+    language: str
+    title: str | None = None
+    comment: str | None = None
+    statements: list[Statement] = field(default_factory=list)  # folded LAD/FBD
+    scl_text: str | None = None         # set for reconstructed SCL networks
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TagRef:
+    """One side of the cross-reference table: where a tag is written / read."""
+
+    network_index: int
+    uid: str | None = None
+    role: str = ""                      # "write" | "read" + context (pin/operand)
+
+
+@dataclass
+class DecodedBlock:
+    name: str
+    kind: str
+    interface: object                   # model.Interface, carried through for the sidecar
+    networks: list[NetworkLogic] = field(default_factory=list)
+    xref: dict[str, list[TagRef]] = field(default_factory=dict)   # tag -> uses
+    instruction_inventory: dict[str, int] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)

simaticml_decoder/model.py

@@ -0,0 +1,264 @@
+"""Phase 1 output: a faithful, behaviour-free mirror of the SimaticML XML.
+
+This layer mirrors the *syntax* of the export (blocks, sections, parts, wires)
+exactly as it appears — it does not interpret logic. Interpretation happens in
+fold.py against ir.py. Keeping the two apart is the front-end/middle-end split:
+adding FBD (same FlgNet) or a new output target touches one phase, not all three.
+
+Field coverage follows the "Stable Parser Model" in SIMATICML_READING_GUIDE.md.
+Large open enumerations (the 20 Access scopes, 13 address areas) are kept as
+plain ``str`` plus a ``raw`` escape hatch rather than exhaustive enums, so an
+unfamiliar value round-trips instead of raising.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class BlockKind(str, Enum):
+    FC = "FC"
+    FB = "FB"
+    OB = "OB"
+    DB = "DB"
+    UNKNOWN = "UNKNOWN"
+
+
+class Language(str, Enum):
+    """Per-compile-unit programming language. Subset we render in v0 + passthrough."""
+
+    LAD = "LAD"
+    FBD = "FBD"
+    SCL = "SCL"
+    STL = "STL"
+    GRAPH = "GRAPH"
+    OTHER = "OTHER"  # DB / SDB / IEC variants etc. — parsed, not rendered in v0
+
+
+# ----------------------------------------------------------------------------- #
+# Interface (block signature + local declarations)                              #
+# ----------------------------------------------------------------------------- #
+@dataclass
+class Member:
+    name: str
+    datatype: str                       # may be a quoted UDT ref, e.g. '"PLC_System"'
+    is_udt: bool = False                # True when datatype was quoted in the XML
+    version: str | None = None          # system/complex types (e.g. TON_TIME "1.0")
+    start_value: str | None = None      # TIA literal, e.g. "T#3s", "16#0"
+    remanence: str | None = None        # e.g. "Retain"
+    comment: str | None = None
+    children: list[Member] = field(default_factory=list)  # nested struct members
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass
+class Section:
+    name: str                           # Input | Output | InOut | Static | Temp | Constant | Return
+    members: list[Member] = field(default_factory=list)
+
+
+@dataclass
+class Interface:
+    sections: list[Section] = field(default_factory=list)
+
+
+# ----------------------------------------------------------------------------- #
+# Operands referenced by Access nodes                                           #
+# ----------------------------------------------------------------------------- #
+@dataclass
+class Component:
+    """One level of a (possibly dotted) symbol path, e.g. System.CLK100ms."""
+
+    name: str
+    slice_access: str | None = None     # SliceAccessModifier, e.g. "x0" / "b1"
+    access_modifier: str = "None"       # None | Array | Reference | ReferenceToArray
+    simple_access_modifier: str = "None"  # None | Periphery | QualityInformation | combos
+    indices: list[Access] = field(default_factory=list)  # array subscripts (Access children)
+
+
+@dataclass
+class Symbol:
+    components: list[Component] = field(default_factory=list)
+
+
+@dataclass
+class Constant:
+    type: str | None = None             # ConstantType (may be Informative)
+    value: str | None = None            # ConstantValue (may be Informative)
+    name: str | None = None
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass
+class Address:
+    area: str                           # Input | Output | Memory | DB | Timer | Counter | ...
+    type: str | None = None
+    bit_offset: int | None = None       # Byte*8 + Bit
+    block_number: int | None = None     # DB number, for DB access
+
+
+# Operand = Symbol | Constant | Address (other scope children parsed into ``raw``)
+Operand = Symbol | Constant | Address | None
+
+
+@dataclass
+class Access:
+    """A data reference. Per-use (never deduplicated): each occurrence is its own node."""
+
+    uid: str
+    scope: str                          # 20 possible values — kept as str (see guide)
+    operand: Operand = None
+    raw: dict = field(default_factory=dict)
+
+
+# ----------------------------------------------------------------------------- #
+# Instructions (Part) and user/system calls (Call)                              #
+# ----------------------------------------------------------------------------- #
+@dataclass
+class TemplateValue:
+    name: str                           # e.g. "Card", "SrcType", "time_type"
+    kind: str                           # Cardinality | Type | Operation
+    value: str | None = None
+
+
+@dataclass
+class Instance:
+    """Backing static member for a system FB (TON/CTU/...) — same shape as Symbol."""
+
+    scope: str
+    components: list[Component] = field(default_factory=list)
+
+
+@dataclass
+class Part:
+    uid: str
+    name: str                           # Contact | Coil | O | Move | TON | Lt | Rs | ...
+    disabled_eno: bool = False
+    version: str | None = None          # system FB/FC type version
+    template_values: list[TemplateValue] = field(default_factory=list)
+    negated_pins: list[str] = field(default_factory=list)   # from <Negated Name="..."/>
+    invisible_pins: list[str] = field(default_factory=list)
+    instance: Instance | None = None    # system FB instance ref
+    equation: str | None = None         # Calculate box only
+    comment: str | None = None
+    raw: dict = field(default_factory=dict)
+
+
+@dataclass
+class Parameter:
+    name: str
+    section: str                        # Input | Output | InOut | Return
+    type: str | None = None
+    informative: bool = False
+
+
+@dataclass
+class Call:
+    uid: str
+    name: str                           # called block name
+    block_type: str                     # FC | FB | OB | DB | UDT | FBT | FCT
+    instance: Instance | None = None    # for FB calls
+    parameters: list[Parameter] = field(default_factory=list)
+    comment: str | None = None
+
+
+# ----------------------------------------------------------------------------- #
+# Wires (the graph edges)                                                        #
+# ----------------------------------------------------------------------------- #
+class EndpointKind(str, Enum):
+    POWERRAIL = "Powerrail"
+    IDENT_CON = "IdentCon"              # -> Access node (data), by uid
+    NAME_CON = "NameCon"               # -> Part/Call pin, by (uid, name)
+    OPEN_CON = "OpenCon"               # explicitly unused output
+    OPEN_BRANCH = "Openbranch"         # unterminated branch
+
+
+@dataclass
+class Endpoint:
+    kind: EndpointKind
+    uid: str | None = None              # for IdentCon / NameCon / OpenCon
+    pin: str | None = None              # for NameCon
+
+
+@dataclass
+class Wire:
+    """First endpoint is the source; the rest are sinks (fan-out)."""
+
+    uid: str
+    endpoints: list[Endpoint] = field(default_factory=list)
+
+
+@dataclass
+class Label:
+    uid: str
+    name: str
+    comment: str | None = None
+
+
+# ----------------------------------------------------------------------------- #
+# Network sources (one per programming language)                                 #
+# ----------------------------------------------------------------------------- #
+@dataclass
+class FlgNet:
+    """LAD/FBD network: indexed parts/calls/accesses + the wire list. UIds are
+    scoped to *this* compile unit only (reused across networks)."""
+
+    accesses: dict[str, Access] = field(default_factory=dict)
+    parts: dict[str, Part] = field(default_factory=dict)
+    calls: dict[str, Call] = field(default_factory=dict)
+    wires: list[Wire] = field(default_factory=list)
+    labels: list[Label] = field(default_factory=list)
+
+
+@dataclass
+class StructuredText:
+    """SCL network: an ordered, interleaved token/access stream (a tokenised AST).
+    Reconstructed to text by scl_reconstruct.py — not folded."""
+
+    items: list[object] = field(default_factory=list)  # Access | Token | comment nodes (raw)
+
+
+# StatementList (STL) and Graph (SFC) are parsed-but-not-rendered in v0; kept as
+# raw element trees so nothing is lost.
+@dataclass
+class RawSource:
+    language: Language
+    element: object = None              # retained xml.etree element for later phases
+
+
+NetworkSource = FlgNet | StructuredText | RawSource | None
+
+
+@dataclass
+class Network:
+    index: int                          # 1-based, in document order
+    language: Language
+    title: str | None = None
+    comment: str | None = None
+    source: NetworkSource = None        # None == empty network
+
+
+# ----------------------------------------------------------------------------- #
+# Top level                                                                      #
+# ----------------------------------------------------------------------------- #
+@dataclass
+class Block:
+    kind: BlockKind
+    id: str
+    name: str
+    number: int | None = None
+    language: Language = Language.LAD   # block-level default; networks may differ
+    memory_layout: str | None = None
+    memory_reserve: int | None = None   # FB only
+    set_eno_automatically: bool = False
+    title: str | None = None
+    comment: str | None = None
+    interface: Interface = field(default_factory=Interface)
+    networks: list[Network] = field(default_factory=list)
+
+
+@dataclass
+class Document:
+    engineering_version: str | None     # e.g. "V21"
+    block: Block

simaticml_decoder/operand.py

@@ -0,0 +1,141 @@
+"""Render a model.Access into its TIA display string.
+
+Split out because it is needed in two phases (fold labels its nodes; emit prints
+them) and is a self-contained pile of display conventions. Conventions applied
+(SIMATICML_READING_GUIDE.md "Display Conventions"):
+
+    LocalVariable scope        -> "#name"
+    GlobalVariable scope       -> '"DB".field'
+    Address scope              -> "%MW100" (area letter + offset)
+    SliceAccessModifier "x0"   -> ".%X0"
+    multi-component symbol     -> dotted path "System.CLK100ms"
+    array AccessModifier       -> "name[<index>]"
+    LiteralConstant            -> the value verbatim ("0", "TRUE", "T#3s")
+
+Phase 1 (parse) is implemented first; this is filled alongside it so folded
+networks have readable names.
+"""
+
+from __future__ import annotations
+
+from . import model
+
+# Address Area -> TIA display prefix (SIMATICML_READING_GUIDE.md "Area values").
+_AREA_PREFIX: dict[str, str] = {
+    "Input": "%I",
+    "Output": "%Q",
+    "Memory": "%M",
+    "PeripheryInput": "%PI",
+    "PeripheryOutput": "%PQ",
+    "Timer": "%T",
+    "Counter": "%C",
+    "Local": "%L",
+    "DB": "%DB",
+    "DI": "%DI",
+}
+
+# Address Type -> width letter used in the absolute display (%MW, %MB, ...).
+# Bool is special-cased to the byte.bit form and is not in this table.
+_TYPE_WIDTH: dict[str, str] = {
+    "byte": "B",
+    "sint": "B",
+    "usint": "B",
+    "char": "B",
+    "word": "W",
+    "int": "W",
+    "uint": "W",
+    "s5time": "W",
+    "dword": "D",
+    "dint": "D",
+    "udint": "D",
+    "real": "D",
+    "time": "D",
+    "lword": "L",
+    "lint": "L",
+    "ulint": "L",
+    "lreal": "L",
+}
+
+
+def render(access: model.Access) -> str:
+    """model.Access -> display string (TIA conventions; see module docstring)."""
+    operand = access.operand
+    if isinstance(operand, model.Symbol):
+        return _render_symbol(operand, access.scope)
+    if isinstance(operand, model.Constant):
+        return _render_constant(operand)
+    if isinstance(operand, model.Address):
+        return _render_address(operand)
+    # Undef / Unnamed / scopes whose child landed in raw (Expression, CallInfo,
+    # ...): no readable operand. Fail visibly rather than silently — a wrong name
+    # is worse than an obvious placeholder.
+    return f"<{access.scope or 'Undef'}#{access.uid}>"
+
+
+# --------------------------------------------------------------------------- #
+# Symbols                                                                      #
+# --------------------------------------------------------------------------- #
+def _render_symbol(symbol: model.Symbol, scope: str | None) -> str:
+    if not symbol.components:
+        return f"<{scope or 'Symbol'}>"
+    is_global = scope == "GlobalVariable"
+    parts = [
+        _render_component(comp, quote=(is_global and i == 0))
+        for i, comp in enumerate(symbol.components)
+    ]
+    path = ".".join(parts)
+    # Local/interface variables get the '#' prefix; global access is already
+    # quoted at its root ('"DB".field') and takes no prefix.
+    if scope == "LocalVariable":
+        return "#" + path
+    return path
+
+
+def _render_component(comp: model.Component, quote: bool = False) -> str:
+    text = f'"{comp.name}"' if quote else comp.name
+    # Array subscripts: one or more Access children rendered recursively.
+    if comp.access_modifier in ("Array", "ReferenceToArray") and comp.indices:
+        subs = ", ".join(render(idx) for idx in comp.indices)
+        text += f"[{subs}]"
+    # Bit/byte/word/dword slice: "x0" -> ".%X0", "b1" -> ".%B1".
+    if comp.slice_access:
+        letter = comp.slice_access[0].upper()
+        number = comp.slice_access[1:]
+        text += f".%{letter}{number}"
+    return text
+
+
+# --------------------------------------------------------------------------- #
+# Constants                                                                    #
+# --------------------------------------------------------------------------- #
+def _render_constant(const: model.Constant) -> str:
+    if const.value is not None:
+        return const.value
+    if const.name is not None:
+        return const.name
+    return "<const>"
+
+
+# --------------------------------------------------------------------------- #
+# Absolute addresses                                                           #
+# --------------------------------------------------------------------------- #
+def _render_address(addr: model.Address) -> str:
+    prefix = _AREA_PREFIX.get(addr.area, "%" + (addr.area or "?"))
+    # DB-qualified access carries a block number: DB10.DBW0-style.
+    db_qualifier = ""
+    if addr.block_number is not None and addr.area in ("DB", "DI"):
+        prefix = f"%DB{addr.block_number}" if addr.area == "DB" else f"%DI{addr.block_number}"
+        db_qualifier = ".DB" if addr.area == "DB" else ".DI"
+
+    if addr.bit_offset is None:
+        return prefix + db_qualifier
+
+    byte, bit = divmod(addr.bit_offset, 8)
+    type_lc = (addr.type or "").lower()
+    if type_lc in ("bool", "bit", ""):
+        return f"{prefix}{db_qualifier}{'X' if db_qualifier else ''}{byte}.{bit}"
+    width = _TYPE_WIDTH.get(type_lc)
+    if width:
+        return f"{prefix}{db_qualifier}{width}{byte}"
+    # Unknown width: fall back to the bit-addressed form so nothing is lost.
+    return f"{prefix}{db_qualifier}{byte}.{bit}"