Cable support: what exists, what it would take, and the one decision that unblocks it

[ispyisail]

Cable support has been asked for four times and stalled four times, always on the same thing: nobody has decided what "cable support" should mean. This is an attempt to make that decision small, by writing down exactly what exists today and what each possible level would cost.

It supersedes nothing — it gathers #405, #609 and #601 into one place so there is a single thread to answer.

Everything below was checked against master 2da5166.

---

1. Why

Cable support has been asked for repeatedly, and every request has stalled on
the same thing — nobody has decided what "cable support" means.

Where	Ask	State
#405 Cables nomenclature (Sairus1)	"It would be great to incorporate the list of cables, it's very necessary"	open; a direction was proposed in June and not answered
discussion #609	cable management: bulk edit, select-by-cable, cable reporting	0 replies since 1 Aug
discussion #601	structured conductor data for external wire-length tools	0 replies since 1 Aug
forum topic 2930	the thread #405 was pointed at	—

That is the honest starting position: the blocker is a decision, not code.
This document exists to make the decision small.

---

2. What exists today, exactly

The field

• ConductorProperties::m_cable and m_bus — plain QString
  (sources/conductorproperties.h:97-98).
• Edited per conductor, as free text, in the conductor properties dialog
  (conductorpropertieswidget.cpp:88 and :134).
• Round-tripped to the project file as the cable and bus attributes on
  <conductor> (conductorproperties.cpp:286-287), and to QSettings.

Nothing reads either of them

No export, no report, no drawing, no query. Verified by searching every use of
the members and of the XML attribute names: the only hits are the struct, the
dialog, and the serialisation.

The near misses

Three places look like cable support and are not:

Looks like	Reality
--export-cables	the from-to wiring list: one row per conductor — Page, Component 1, Terminal 1, Component 2, Terminal 2, Tension/Protocol, Wire colour, Wire section, Function (wiringlistexport.cpp:369-388). No cable column, no grouping
Terminal strip Cable and CableWire columns	present in the model (terminalstripmodel.h:59-60) but RealTerminal::cable() and cableWire() return an empty string unconditionally (realterminal.cpp:162, :170). An empty UI surface already wired up
Search & Replace	covers m_function, m_tension_protocol, colour, style and others (searchandreplaceworker.cpp:414-435); m_cable and m_bus are simply absent, so the one field you would most want to bulk-edit cannot be

Correcting my own earlier answer. On #405 in June I wrote that the
terminal strip "already shows Cable and CableWire columns, pulling from the
same metadata". That was wrong. The columns exist; both accessors are stubs
returning an empty string, so the columns are always blank and nothing
connects them to the conductor field. Anyone who went looking for them on my
say-so found nothing, and I am sorry for that.

No cable object

There is no Cable class, no cable table in the project database, and no
grouping anywhere. The database's conductor table
(projectdatabase.cpp:667) stores uuid, diagram_uuid, the two terminal
references and text — none of the documentation fields exist in it, which
is why --export-wiring (database-backed) cannot emit the columns
--export-cables (document-backed) can.

---

3. What "cable support" could mean

Three levels, increasing in cost and in commitment. They are cumulative.

Level	The cable is…	Adds persisted data?
1. A tag that works	still a string on each conductor, but searchable, selectable, queryable and exportable	no
2. A schedule	still a string, but reported: grouped rows, core counts, from/to	no
3. An object	a thing in the project with its own identity, type, section, core count and endpoints; conductors reference it	yes

Level 3 is what other ECAD tools mean by cable management. Levels 1 and 2 are
what most of the requests above actually describe.

---

4. Hard constraints

These come from CLAUDE.md and QET-DATA-DIRECTION-PLAN.md and they decide
the design more than taste does.

1. Persisted data must reach the database schema too — never add state only
   the XML knows.
2. Do not add a 38th scene-walker. 37 call sites already walk live
   Element/Conductor objects; each one blocks lazy folio loading. A cable
   report must query the project database, not the scenes.
3. Populate the database from the document, not from constructed scenes —
   the circular dependency that makes lazy loading impossible.
4. The project database is derived and rebuilt on every load, never written
   to disk. Adding columns to it is therefore free: no migration, no
   versioning, and a bad row costs nothing.
5. The .qet format must stay readable by older versions: unknown attributes
   and unknown child elements are ignored on load, so additive changes are
   safe and removals are not.

Constraint 4 is the useful one: levels 1 and 2 add no persisted state at
all, so they carry none of the format risk that has stalled this before.

---

5. Proposal

Phase 1 — make the existing field first-class (recommended first)

No file-format change. Uses data users can already enter today.

• Add cable and bus to SearchAndReplaceWorker — both the batch-apply path
  (applyChange()) and the advanced regex path (replaceAdvanced()), matching
  how function and tension/protocol are handled. This alone turns the field
  from write-only into something maintainable across a project.
• Add the documentation fields — cable, bus, function, tension_protocol,
  conductor_color, conductor_section — as columns on the database's
  conductor table, populated from the document during the existing conductor
  pass.
• Add a cable column to --export-cables, so a spreadsheet can group by it
  immediately. This is the "quick win" offered on Cables nomenclature #405.
• Select all conductors of a cable — a context-menu entry on a conductor,
  driven by a database query rather than a scene walk.

Phase 2 — a cable schedule

Still no file-format change; a report over Phase 1's data.

• A cable schedule: one row per distinct cable value — cable ID, from/to
  (device and folio, derived from the endpoints), core count (how many
  conductors carry that cable), section and colour where consistent, flagged
  where they disagree.
• Delivered the same two ways the nomenclature already is: a CSV export
  (--export-cable-schedule) and an on-diagram table built on the existing
  QetGraphicsTableItem machinery, so it prints with the project.
• Fill the terminal strip's stubbed Cable/CableWire columns from the same
  query, which is a few lines once the data is in the database.

Phase 3 — a cable as an object (needs a decision before any code)

This is the level that adds persisted state, so it is the one that needs
@scorpio810's agreement first.

• A project-level cable list — one entry per cable: designation, type,
  section, core count, optional manufacturer reference.
• Conductors reference a cable by uuid, keeping the free-text field as a
  fallback for projects that never migrate.
• Cores become nameable, which is what makes CableWire meaningful and lets a
  cable carry spare cores — a cable of 7 cores with 4 used, which no
  conductor-derived count can ever represent.
• Stored as its own block in the project XML, mirrored into the database, in
  that order. Old versions ignore the block and keep the per-conductor text.

---

6. Why a cable is not simply "conductors with the same label"

Worth stating because it decides whether Phase 3 is ever needed:

• Spare cores exist in reality and have no conductor to hang on.
• A cable has one type, section and length; conductors within it can
  disagree today, and nothing notices.
• Cable designations are assigned and reserved before the wires are drawn.
• A cable runs between two places, which is not always the same as the
  endpoints of its member conductors — a cable can pass through a junction box.

Phases 1 and 2 are still worth doing without Phase 3: they make the common case
work. But they cannot express any of the four points above, and pretending
otherwise is how a half-feature ships.

---

7. Decisions needed

1. Is Phase 1 acceptable as an immediate, self-contained change? It adds no
   persisted state and no format change.
2. Should the Phase 2 schedule be a CSV export, an on-diagram table, or
   both?
3. Is Phase 3 wanted at all, or is a conductor tag plus reporting the right
   ceiling for QElectroTech?
4. If Phase 3 is wanted: does a cable belong to the project (one list,
   folios reference it) or to a folio? Project-level is assumed above.
5. Should bus follow cable through all of this, or be left alone? It has
   the same shape and the same emptiness.

---

8. Implementation checklist (Phase 1)

• searchandreplaceworker.cpp — add m_cable/m_bus to applyChange()
  and a what == "cable" / "bus" branch in replaceAdvanced()
• the Search & Replace UI — two more fields, same pattern as function
• projectdatabase.cpp — add the six documentation columns to the
  conductor table and populate them from the document
• wiringlistexport.cpp — add the cable column to the CSV
• context menu — "Select all conductors of this cable", via a database query
• cli_reference wiki page — document the new column
• conductors wiki page — replace the "read by nothing" paragraph

9. Test plan

• A project with three cables across two folios: bulk-rename one cable and
  assert only its conductors changed.
• Round-trip: set cable and bus, save, reload, resave — byte-identical.
• Database: assert the conductor rows carry the documentation fields, and that
  the count of conductors per cable matches the drawing.
• --export-cables before and after: same rows, one more column.
• Corpus check: all 24 example projects resave byte-identically, since none of
  them set a cable value.

10. Explicit non-goals

• No cable routing or physical length calculation. Discussion Feature idea: structured conductor data (DB table + folio cross-reference links) to support FreeCAD/3D wire-length tools #601 wants
  lengths from a 3D tool; that is a different feature and is not assumed here.
• No cable library of manufacturer part numbers in phases 1 and 2.
• No automatic cable assignment. A conductor joins a cable because someone said
  so.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01CaKympWT3owLotCpEN2CFj