jmri_core.persistence.loco_cv_xml

  1"""``rosters/<id>.xml`` — per-locomotive CV state file.
  2
  3The locomotive-config file at ``roster/<id>.xml`` carries identity and
  4function labels; the *programmed CV state* of a specific decoder is
  5either embedded there as a ``<values>`` block (JMRI 5.x default) or
  6kept in a separate ``rosters/<id>.xml``. This module models the
  7separate-file form because that's the layout the alpha tester
  8explicitly asked for in their feedback:
  9
 10> there is a rosters subdirectory that should *not* be read by default.
 11> It contains all the decoder cv settings for the locomotives listed in
 12> the roster. These should be loaded as needed by the programmer panel
 13
 14The format we read/write:
 15
 16    <?xml version="1.0" encoding="UTF-8"?>
 17    <locomotive-cv-values id="459">
 18      <CV name="1" value="3" />
 19      <CV name="7" value="151" />
 20      <CV name="29" value="38" />
 21    </locomotive-cv-values>
 22
 23When the file doesn't exist yet, an empty :class:`LocoCvState` is
 24returned. The programmer page accumulates reads + writes into it and
 25flushes back to disk on every mutation.
 26"""
 27from __future__ import annotations
 28
 29import pathlib
 30
 31from lxml import etree
 32
 33from jmri_core.beans.loco_cv_state import LocoCvState
 34
 35
 36def load_loco_cv_bytes(data: bytes) -> LocoCvState:
 37    """Parse a ``rosters/<id>.xml`` from bytes."""
 38    parser = etree.XMLParser(
 39        remove_blank_text=False,
 40        resolve_entities=False,
 41        load_dtd=False,
 42        no_network=True,
 43    )
 44    root = etree.fromstring(data, parser=parser)
 45    if root.tag != "locomotive-cv-values":
 46        raise ValueError(
 47            f"expected <locomotive-cv-values> root, got <{root.tag}>"
 48        )
 49    loco_id = root.get("id") or ""
 50    cv_values: dict[str, int] = {}
 51    for cv in root.findall("CV"):
 52        name = cv.get("name")
 53        val = cv.get("value")
 54        if not name or val is None:
 55            continue
 56        try:
 57            cv_values[name] = int(val)
 58        except ValueError:
 59            # Skip malformed entries; don't blow up the rest of the file.
 60            continue
 61    return LocoCvState(loco_id=loco_id, cv_values=cv_values)
 62
 63
 64def load_loco_cv(path: str | pathlib.Path) -> LocoCvState:
 65    """Load a per-loco CV file. Returns an empty state if missing."""
 66    p = pathlib.Path(path)
 67    if not p.exists():
 68        # The id is the file stem (e.g. ``459.xml`` → ``"459"``).
 69        return LocoCvState(loco_id=p.stem)
 70    return load_loco_cv_bytes(p.read_bytes())
 71
 72
 73def save_loco_cv_bytes(state: LocoCvState) -> bytes:
 74    """Serialize a :class:`LocoCvState` to XML."""
 75    root = etree.Element("locomotive-cv-values", attrib={"id": state.loco_id})
 76    # Sort by numeric CV when possible, fall back to lexicographic.
 77    def _key(name: str) -> tuple[int, str]:
 78        try:
 79            return (0, f"{int(name):05d}")
 80        except ValueError:
 81            return (1, name)
 82    for name in sorted(state.cv_values, key=_key):
 83        etree.SubElement(root, "CV", attrib={
 84            "name": name,
 85            "value": str(state.cv_values[name]),
 86        })
 87    return etree.tostring(
 88        root,
 89        xml_declaration=True,
 90        encoding="utf-8",
 91        pretty_print=True,
 92        standalone=False,
 93    )
 94
 95
 96def save_loco_cv(path: str | pathlib.Path, state: LocoCvState) -> None:
 97    target = pathlib.Path(path)
 98    target.parent.mkdir(parents=True, exist_ok=True)
 99    # Atomic write: tmp + rename so a crash mid-write can't corrupt the file.
100    tmp = target.with_suffix(target.suffix + ".tmp")
101    tmp.write_bytes(save_loco_cv_bytes(state))
102    tmp.replace(target)
103
104
105# ----- reading CV state from a JMRI locomotive-config -------------------
106#
107# JMRI's real-world layout embeds CV state inside the roster entry file
108# itself (``roster/<id>.xml``) under a ``<values>`` block. Our proprietary
109# ``rosters/<id>.xml`` was a design choice that diverges from JMRI. When
110# opening a real JMRI profile we must fall back to reading CV values
111# from the roster entry, or the programmer view can't display CVs the
112# user has already programmed.
113
114
115def load_cv_values_from_locomotive_config(
116    path: str | pathlib.Path, *, loco_id: str | None = None,
117) -> LocoCvState | None:
118    """Extract CV state from a ``locomotive-config`` file's ``<values>`` block.
119
120    The JMRI-canonical location for per-loco CV state. Returns ``None`` if
121    the file doesn't exist or has no ``<values>`` block; returns an
122    (empty) :class:`LocoCvState` when the block is present but has no
123    ``<CV>`` rows yet.
124
125    *loco_id* narrows the search when the file lists multiple
126    ``<locomotive>`` entries (rare — JMRI writes one per file). When
127    omitted, the first ``<locomotive>`` wins.
128    """
129    p = pathlib.Path(path)
130    if not p.exists():
131        return None
132    return load_cv_values_from_locomotive_config_bytes(
133        p.read_bytes(), loco_id=loco_id,
134    )
135
136
137def save_cv_values_into_locomotive_config(
138    path: str | pathlib.Path,
139    cv_values: dict[str, int],
140    *,
141    loco_id: str | None = None,
142) -> None:
143    """Update or insert a ``<values>`` block inside a ``locomotive-config``
144    file, preserving every other element.
145
146    * If *path* doesn't exist, does nothing (caller is expected to have
147      created the roster entry first via the roster service).
148    * If *cv_values* is empty, an existing ``<values>`` block is removed
149      entirely — the file still round-trips through the roster loader.
150    * When the file lists multiple locomotives (rare), *loco_id* picks
151      which one gets the update; otherwise the first is used.
152
153    Writes are atomic (tmp + rename) so a crash mid-write can't corrupt
154    the roster entry.
155    """
156    p = pathlib.Path(path)
157    if not p.exists():
158        return
159    parser = etree.XMLParser(
160        remove_blank_text=False,
161        resolve_entities=False,
162        load_dtd=False,
163        no_network=True,
164    )
165    tree = etree.parse(str(p), parser=parser)
166    root = tree.getroot()
167    if root.tag != "locomotive-config":
168        return
169    target_loco = None
170    for loco in root.iter("locomotive"):
171        if loco_id is None or loco.get("id", "") == loco_id:
172            target_loco = loco
173            break
174    if target_loco is None:
175        return
176
177    # Update in place: preserve any existing ``<values>`` sub-elements
178    # that AREN'T our per-CV entries. In particular JMRI Java writes a
179    # sibling ``<decoderDef>`` block inside ``<values>`` that tracks
180    # per-variable human values; wiping the whole ``<values>`` block
181    # (as an earlier revision did) destroys that data. Same story for
182    # any other unrecognised child element we don't own.
183    values_el = target_loco.find("values")
184    if values_el is None:
185        if not cv_values:
186            return
187        values_el = etree.SubElement(target_loco, "values")
188    else:
189        # Remove existing per-CV entries so we don't stack duplicates.
190        # Accept both element shapes we've written across versions.
191        for entry in list(values_el):
192            if isinstance(entry.tag, str) and entry.tag in ("CVvalue", "CV"):
193                values_el.remove(entry)
194
195    def _key(name: str) -> tuple[int, str]:
196        try:
197            return (0, f"{int(name):05d}")
198        except ValueError:
199            return (1, name)
200
201    if cv_values:
202        # Emit ``<CVvalue>`` — that's the tag name JMRI Java writes and
203        # reads. Interop-safe: a file we write will round-trip through
204        # JMRI Java, and a file JMRI Java wrote (with ``<CVvalue>``)
205        # gets picked up by our reader too.
206        #
207        # lxml's ``pretty_print`` only formats truly-new subtrees; when
208        # we append into an already-parsed element with existing
209        # whitespace nodes it silently packs siblings onto one line.
210        # Explicitly set ``.tail`` on each new entry to a newline +
211        # indent so the file stays hand-editable and diff-friendly.
212        # The last entry gets the closing-tag indent so ``</values>``
213        # lines up under its parent.
214        parent_depth = 0
215        node = values_el
216        while node is not None and node.tag != "locomotive-config":
217            parent_depth += 1
218            node = node.getparent()
219        indent_unit = "  "
220        entry_indent = "\n" + indent_unit * (parent_depth + 1)
221        close_indent = "\n" + indent_unit * parent_depth
222        sorted_names = sorted(cv_values, key=_key)
223        # Make sure the last-existing child's tail (if any) leads into
224        # the first new entry cleanly.
225        if len(values_el) > 0:
226            values_el[-1].tail = entry_indent
227        for i, name in enumerate(sorted_names):
228            el = etree.SubElement(values_el, "CVvalue", attrib={
229                "name": name,
230                "value": str(cv_values[name]),
231            })
232            el.tail = (
233                close_indent if i == len(sorted_names) - 1 else entry_indent
234            )
235    elif len(values_el) == 0:
236        # No per-CV entries left and no other children (decoderDef etc.)
237        # → drop the empty ``<values>`` element rather than leaving
238        # dead XML behind.
239        target_loco.remove(values_el)
240
241    tmp = p.with_suffix(p.suffix + ".tmp")
242    tree.write(
243        str(tmp),
244        xml_declaration=True,
245        encoding="utf-8",
246        pretty_print=True,
247        standalone=False,
248    )
249    tmp.replace(p)
250
251
252def load_cv_values_from_locomotive_config_bytes(
253    data: bytes, *, loco_id: str | None = None,
254) -> LocoCvState | None:
255    """Bytes-in variant of :func:`load_cv_values_from_locomotive_config`."""
256    parser = etree.XMLParser(
257        remove_blank_text=False,
258        resolve_entities=False,
259        load_dtd=False,
260        no_network=True,
261    )
262    try:
263        root = etree.fromstring(data, parser=parser)
264    except etree.XMLSyntaxError:
265        return None
266    if root.tag != "locomotive-config":
267        return None
268    for loco in root.iter("locomotive"):
269        this_id = loco.get("id", "")
270        if loco_id is not None and this_id != loco_id:
271            continue
272        values = loco.find("values")
273        if values is None:
274            return None
275        cv_values: dict[str, int] = {}
276        # Accept both element shapes:
277        # * ``<CVvalue name=... value=.../>`` — what real JMRI Java
278        #   writes inside ``<values>``. This is the JMRI-canonical form.
279        # * ``<CV name=... value=.../>`` — what earlier versions of our
280        #   own code wrote. Kept for backwards compat on files we've
281        #   already touched.
282        for tag in ("CVvalue", "CV"):
283            for cv in values.iter(tag):
284                name = cv.get("name")
285                val = cv.get("value")
286                if not name or val is None:
287                    continue
288                try:
289                    cv_values[name] = int(val)
290                except ValueError:
291                    continue
292        return LocoCvState(loco_id=this_id or (loco_id or ""), cv_values=cv_values)
293    return None