Files
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

1011 lines
36 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* The Project Rescue Helper — `eeschema/project_rescue.cpp`.
*
* What it is for: a schematic remembers which symbols it was drawn with, and a
* library is free to change underneath it. Rescue is the offer to keep the copy
* the schematic was drawn with, under a new name in a `<schematic>-rescue`
* library, rather than silently taking whatever the library says today.
*
* There are two rescuers upstream and they are not interchangeable:
*
* if( schematic.HasNoFullyDefinedLibIds() )
* RescueLegacyProject( true );
* else
* RescueSymbolLibTableProject( true );
* (`sch_editor_control.cpp:533-541`)
*
* `LEGACY_RESCUER` is for a schematic whose symbols have no library nickname at
* all — a KiCad 4 file, before symbol library tables. Anything we can open has
* fully defined ids, so the one that applies here is always
* `SYMBOL_LIB_TABLE_RESCUER`, and this module ports its candidate finder,
* `RESCUE_SYMBOL_LIB_TABLE_CANDIDATE::FindRescues` (`project_rescue.cpp:344-436`).
*
* ## The two places it looks
*
* The finder consults the project's legacy `<project>-cache.lib`, through
* `PROJECT_SCH::LegacySchLibs`, and the symbol library table. The cache is
* taken as an argument here rather than reached for, because who supplies it is
* the caller's business — `sch_io/legacy/read-lib.ts` reads that format, and a
* project without one hands over an empty map.
*
* With no cache exactly one arm stays live, and it is a real one: an id whose
* item name contains characters `LIB_ID` forbids. Both cache-dependent skips
* sit *inside* the legal-name test —
*
* if( LIB_ID::HasIllegalChars( symbol_id.GetLibItemName() ) == -1 )
* {
* if( cache_match && lib_match && !cache_match->PinsConflictWith( … ) )
* continue;
* if( !cache_match && lib_match )
* continue;
* }
*
* — so `Device:Conn<1>`, which an importer or a hand-edited file leaves behind,
* is a candidate on the strength of its name alone.
*
* This is deliberately NOT the same question as ERC's `lib_symbol_mismatch`,
* which compares a sheet's `lib_symbols` entry against the library. That is the
* modern cache; this is the KiCad 4/5 one. Upstream keeps both, and so do we.
*/
import type { LibSymbol, LibPin, SchSymbol, Schematic } from './types.js';
import type { EditCommand } from './tools/command.js';
import { flattenLibSymbol } from './lib_symbol.js';
import { schSymbolLibraryName } from './lib_symbol.js';
import {
libItemName,
libNickname,
libItemNameIllegalCharOffset,
} from './tools/edit_symbol_libid.js';
import { escapeLibId, unescapeString } from '@ziroeda/common';
import type { InputPrefs } from '@ziroeda/common/view/wx_view_controls.js';
import { DisplayErrorMessage } from '@ziroeda/common/confirm.js';
import { IO_ERROR } from '@ziroeda/common/exceptions.js';
import { LIB_ID } from '@ziroeda/common/lib_id.js';
import {
LIBRARY_TABLE_SCOPE,
LIBRARY_TABLE_TYPE,
} from '@ziroeda/common/libraries/library_table.js';
import { Pgm } from '@ziroeda/common/pgm_base.js';
import type { PROJECT } from '@ziroeda/common/project.js';
import { ESCAPE_CONTEXT, EscapeString } from '@ziroeda/common/string_utils.js';
import {
KiCadSymbolLibFileExtension,
LegacySymbolLibFileExtension,
} from '@ziroeda/common/wildcards_and_files_ext.js';
import { wxOK } from '@ziroeda/wx/defs.js';
import { wxID_OK } from '@ziroeda/wx/menu.js';
import { KICAD_T } from '@ziroeda/core/typeinfo.js';
import { LIB_SYMBOL } from './lib_symbol.js';
import { SymbolLibAdapter } from './project_sch.js';
import type { SCH_EDIT_FRAME } from './sch_edit_frame.js';
import { SCH_FILE_T, SCH_IO_MGR } from './sch_io/sch_io_mgr.js';
import { SCH_IO_KICAD_SEXPR } from './sch_io/kicad_sexpr/sch_io_kicad_sexpr.js';
import { SCH_SCREENS } from './sch_screen.js';
import type { SCH_SHEET_PATH } from './sch_sheet_path.js';
import type { SCH_SYMBOL } from './sch_symbol.js';
import type { SCHEMATIC } from './schematic.js';
/**
* One row of the rescue dialog — `RESCUE_SYMBOL_LIB_TABLE_CANDIDATE`.
*
* `cache` and `lib` are the two symbols being compared: the copy in the
* project's cache library and the copy in the library the id names. At least
* one is always present (`if( !cache_match && !lib_match ) continue`), and
* which of them is missing is what the action description reports.
*/
export interface RescueCandidate {
/** `m_requested_id.Format()`, the library id the schematic asks for. */
readonly requestedId: string;
/** `m_new_id.Format()`, where the rescued copy will live. */
readonly newId: string;
readonly cache: LibSymbol | null;
readonly lib: LibSymbol | null;
/** The unit and body style of the first placement found, for the preview. */
readonly unit: number;
readonly bodyStyle: number;
}
/**
* The rescue library's nickname — `GetRescueLibraryFileName`
* (`project_rescue.cpp:107-113`), which is the SCHEMATIC's filename with
* `-rescue` appended, not the project's name. They are usually the same, and
* on a project whose root sheet was renamed they are not.
*/
export function rescueLibraryNickname(schematicFileName: string): string {
const base = schematicFileName.replace(/^.*[\\/]/, '').replace(/\.[^.]*$/, '');
return `${base}-rescue`;
}
/** The file the rescued symbols are written to. Upstream sets the extension to
* `.kicad_sym` in `WriteRescueLibrary` even though the row it looks up may be
* a legacy one (`project_rescue.cpp:806`). */
export function rescueLibraryFileName(schematicFileName: string): string {
return `${rescueLibraryNickname(schematicFileName)}.kicad_sym`;
}
/** Every pin of a symbol, tagged with the unit and body style it is drawn in. */
interface TaggedPin {
readonly pin: LibPin;
readonly unit: number;
readonly bodyStyle: number;
}
/**
* `LIB_SYMBOL::GetGraphicalPins()` with no arguments: no unit filtering, no
* body-style filtering, so every pin of every unit. A derived symbol answers
* from its root, which is what flattening does here.
*/
function graphicalPins(sym: LibSymbol): TaggedPin[] {
const flat = flattenLibSymbol(sym);
return flat.units.flatMap((u) =>
u.pins.map((pin) => ({ pin, unit: u.unit, bodyStyle: u.bodyStyle })),
);
}
/** Which properties `pinsConflictWith` compares beyond unit, body style and position. */
export interface PinConflictTests {
readonly numbers: boolean;
readonly names: boolean;
readonly type: boolean;
readonly orientation: boolean;
readonly length: boolean;
}
/**
* `LIB_SYMBOL::PinsConflictWith` (`lib_symbol.cpp`).
*
* For every pin of `a`, look for a pin of `b` in the same unit and body style,
* at the same position, agreeing on whichever of the five properties were asked
* for. One pin with no such partner is a conflict.
*
* Note the asymmetry, which is upstream's: it walks `a`'s pins only, so a `b`
* with extra pins at positions `a` does not use is not a conflict. The rescue
* call passes `a` = the cache copy, so a library that has GAINED pins is not by
* itself a reason to rescue; one that moved or renamed them is.
*/
export function pinsConflictWith(a: LibSymbol, b: LibSymbol, tests: PinConflictTests): boolean {
const others = graphicalPins(b);
for (const mine of graphicalPins(a)) {
const found = others.some(
(other) =>
mine.unit === other.unit &&
mine.bodyStyle === other.bodyStyle &&
mine.pin.at.x === other.pin.at.x &&
mine.pin.at.y === other.pin.at.y &&
(!tests.numbers || mine.pin.number === other.pin.number) &&
(!tests.names || mine.pin.name === other.pin.name) &&
(!tests.type || mine.pin.electricalType === other.pin.electricalType) &&
(!tests.orientation || mine.pin.angle === other.pin.angle) &&
(!tests.length || mine.pin.length === other.pin.length),
);
if (!found) return true;
}
return false;
}
/** The tests the rescuer asks for: everything but the pin length
* (`project_rescue.cpp:409`, `PinsConflictWith( *lib_match, true, true, true, true, false )`). */
export const RESCUE_PIN_TESTS: PinConflictTests = {
numbers: true,
names: true,
type: true,
orientation: true,
length: false,
};
/** How {@link findRescues} reaches the two libraries it compares. */
export interface RescueSources {
/**
* The project's legacy `<project>-cache.lib`, by the name the cache files a
* symbol under. Empty when the project has no cache library, which is every
* project written by KiCad 6 or later.
*/
readonly cache: ReadonlyMap<string, LibSymbol>;
/** `SchGetLibSymbol( symbol_id, … )` — the library the id names, or null. */
readonly lib: (libId: string) => LibSymbol | null;
/** The root schematic's file name, which names the rescue library. */
readonly schematicFileName: string;
}
/**
* `findSymbol( aName, LegacySchLibs, aCached = true )`, and its second attempt.
*
* A V5-era cache library wrote the LIB_ID delimiter as something other than
* ':', so the name is looked up twice — once as the id formats it, once with
* the nickname and item name joined by '-'. (The comment upstream says the
* delimiter became '_'; the format string it then uses is '-'. Mirrored as
* written, because what matters is which names actually match a file on disk.)
*/
function findCached(cache: ReadonlyMap<string, LibSymbol>, libId: string): LibSymbol | null {
const direct = cache.get(libId);
if (direct) return direct;
const nickname = libNickname(libId);
const item = libItemName(libId);
return cache.get(`${nickname}-${item}`) ?? null;
}
/**
* `RESCUE_SYMBOL_LIB_TABLE_CANDIDATE::FindRescues` (`project_rescue.cpp:344-436`).
*
* `aRescuer.GetSymbols()` is every symbol on every screen of the hierarchy,
* sorted by library id so that each id is looked up once
* (`getSymbols`/`sort_by_libid`, `project_rescue.cpp:41-77`). The candidates
* accumulate in a `std::map<LIB_ID, …>` and are emitted in that map's order, so
* the dialog lists them sorted by id rather than by where they appear on the
* sheet — reproduced here by sorting the ids.
*/
export function findRescues(
symbols: readonly SchSymbol[],
sources: RescueSources,
): RescueCandidate[] {
const rescueNickname = rescueLibraryNickname(sources.schematicFileName);
const byId = new Map<string, RescueCandidate>();
for (const symbol of symbols) {
const symbolId = symbol.libId;
// One lookup per id: the C++ gets this from the sort, we get it from the map.
if (byId.has(symbolId)) continue;
const cacheMatch = findCached(sources.cache, symbolId);
let libMatch = sources.lib(symbolId);
// "If it's a derived symbol, use the parent symbol to perform the pin test."
// A derived symbol with no reachable root is treated as no match at all.
if (libMatch?.extends) {
const root = libMatch.parent ? rootOf(libMatch) : null;
libMatch = root;
}
if (!cacheMatch && !libMatch) continue;
if (libItemNameIllegalCharOffset(libItemName(symbolId)) === -1) {
if (cacheMatch && libMatch && !pinsConflictWith(cacheMatch, libMatch, RESCUE_PIN_TESTS))
continue;
if (!cacheMatch && libMatch) continue;
}
// "Differentiate symbol name in the rescue library by appending the original
// symbol library table nickname to the symbol name to prevent name clashes."
const newName = escapeLibId(libItemName(symbolId));
byId.set(symbolId, {
requestedId: symbolId,
newId: `${rescueNickname}:${newName}-${libNickname(symbolId)}`,
cache: cacheMatch,
lib: libMatch,
unit: symbol.unit,
bodyStyle: symbol.bodyStyle,
});
}
return [...byId.keys()].sort(compareLibId).map((id) => byId.get(id)!);
}
/** `LIB_SYMBOL::GetRootSymbol`, walking `m_parent` to the symbol that defines
* the body. Null when the chain is broken, which upstream treats as no match. */
function rootOf(sym: LibSymbol): LibSymbol | null {
let cur: LibSymbol | undefined = sym;
const seen = new Set<LibSymbol>();
while (cur?.extends) {
if (seen.has(cur)) return null;
seen.add(cur);
cur = cur.parent;
}
return cur ?? null;
}
/** `LIB_ID::compare`: the nickname, then the item name, both by code unit. */
function compareLibId(a: string, b: string): number {
const an = libNickname(a);
const bn = libNickname(b);
if (an !== bn) return an < bn ? -1 : 1;
const ai = libItemName(a);
const bi = libItemName(b);
return ai === bi ? 0 : ai < bi ? -1 : 1;
}
/**
* `RESCUE_SYMBOL_LIB_TABLE_CANDIDATE::GetActionDescription`
* (`project_rescue.cpp:442-465`) — the "Action Taken" column.
*
* Three sentences for three situations, and they are not interchangeable: the
* first is a refusal, the second is a symbol the library has lost, the third is
* a symbol the library still has but has changed.
*/
export function rescueActionDescription(c: RescueCandidate): string {
const u = unescapeString;
if (!c.cache && !c.lib)
return `Cannot rescue symbol ${u(libItemName(c.requestedId))} which is not available in any library or the cache.`;
if (c.cache && !c.lib)
return `Rescue symbol ${u(c.requestedId)} found only in cache library to ${u(c.newId)}.`;
return `Rescue modified symbol ${u(c.requestedId)} to ${u(c.newId)}`;
}
/**
* The definition a rescue writes — `PerformAction`'s first half
* (`project_rescue.cpp:468-479`).
*
* The CACHE copy wins when there is one: the whole point is to keep the symbol
* the schematic was drawn with. It falls back to the library copy only for the
* illegal-name case, where the two are the same symbol and only the id is
* being repaired. `Flatten()` first, because the rescue library has to stand on
* its own — a derived symbol whose parent stayed behind would draw as nothing.
*/
export function rescuedDefinition(c: RescueCandidate): LibSymbol | null {
const source = c.cache ?? c.lib;
if (!source) return null;
const flat = flattenLibSymbol(source);
const name = libItemName(c.newId);
return {
...flat,
libId: c.newId,
// Flatten() resolves the inheritance; the copy must not claim a parent that
// is not going into the rescue library with it.
extends: undefined,
parent: undefined,
units: flat.units.map((u) => ({ ...u, name: `${name}_${u.unit}_${u.bodyStyle}` })),
} as LibSymbol;
}
/** One `RESCUE_LOG` row: which placement was repointed, and from what. */
export interface RescueLogEntry {
readonly reference: string;
readonly oldId: string;
readonly newId: string;
}
/**
* `PerformAction`'s second half: every placement asking for the old id is
* repointed at the new one.
*
* Ours also has to move the placement's cached definition, which upstream does
* not because its cache is a separate file. `lib_symbols` is keyed by the name
* the placement resolves through, so a symbol repointed at `foo-rescue:R-Device`
* with no such entry would draw as nothing at all.
*/
export function repointSymbols(
symbols: readonly SchSymbol[],
chosen: readonly RescueCandidate[],
): { symbols: SchSymbol[]; log: RescueLogEntry[] } {
const byOldId = new Map(chosen.map((c) => [c.requestedId, c]));
const log: RescueLogEntry[] = [];
let changed = false;
const next = symbols.map((s) => {
const c = byOldId.get(s.libId);
if (!c) return s;
log.push({
reference: s.fields.find((f) => f.key === 'Reference')?.value ?? '',
oldId: c.requestedId,
newId: c.newId,
});
// `SetLibId` alone upstream. Here the placement's private-copy pointer has
// to go too: it named an entry under the OLD id, and the rescued definition
// is filed under the new one.
const { libName: _dropped, ...rest } = s;
changed = true;
return { ...rest, libId: c.newId };
});
// The identity matters: `rescueDocumentCommand` reads it to leave a sheet
// that places none of the rescued ids untouched, rather than replacing it
// with an equal copy.
return { symbols: changed ? next : [...symbols], log };
}
/**
* The rescue applied to one document, as an `EditCommand`.
*
* Upstream this is two separate things: `PerformAction` repoints the placements
* in memory, and `WriteRescueLibrary` writes the rescued definitions to a new
* `.kicad_sym` file. Ours does both of those AND a third thing upstream has no
* need of — filing the definitions in the sheet's own `lib_symbols`. That block
* is what a placement actually draws from, so a symbol repointed at a library
* we have only just written, and not yet indexed, would otherwise come up
* empty-bodied until the project was reopened.
*
* The old entries are dropped in the same step, because `SCH_SCREEN` keeps
* `lib_symbols` to what the sheet still uses; leaving them would put a
* definition in the file that nothing on the sheet resolves through.
*
* The command is undoable in the ordinary way, but nothing undoes it: upstream
* calls `m_frame->ClearUndoRedoList()` once the rescues are done
* (`sch_editor_control.cpp:582`), because the library on disk has changed and
* putting the schematic back would leave it pointing at a rescue library it no
* longer matches.
*/
export function rescueDocumentCommand(chosen: readonly RescueCandidate[]): EditCommand {
const label = 'Rescue Symbols';
return {
label,
apply(doc: Schematic): Schematic {
if (!doc.symbols.some((s) => chosen.some((c) => c.requestedId === s.libId))) return doc;
const { symbols } = repointSymbols(doc.symbols, chosen);
const rescued = chosen
.filter((c) => doc.symbols.some((s) => s.libId === c.requestedId))
.map(rescuedDefinition)
.filter((d): d is LibSymbol => d !== null);
if (rescued.length === 0) return { ...doc, symbols };
// What the sheet still resolves through, after the repointing.
const used = new Set(symbols.map(schSymbolLibraryName));
const kept = doc.libSymbols.filter((l) => used.has(l.libId));
const already = new Set(kept.map((l) => l.libId));
return {
...doc,
symbols,
libSymbols: [...kept, ...rescued.filter((d) => !already.has(d.libId))],
};
},
invert(before: Schematic): EditCommand {
return {
label,
apply: () => before,
invert: (b: Schematic) => ({
label,
apply: () => b,
invert: () => rescueDocumentCommand(chosen),
}),
};
},
};
}
// ---- DIALOG_RESCUE_EACH's contract (the dialog is designer's, reached through
// EESCHEMA_APP.DialogRescueEach) ----
/** One row of "Instances of this symbol" — `PopulateInstanceList`. */
export interface RescueInstance {
readonly reference: string;
readonly value: string;
}
export interface DialogRescueEachProps {
candidates: readonly RescueCandidate[];
/** The placements of one library id, in hierarchy order. */
instancesOf: (requestedId: string) => readonly RescueInstance[];
/**
* Whether the "Never Show Again" button is shown — `aAskShowAgain`, which is
* `!aRunningOnDemand`. Running it yourself from the Tools menu offers no way
* to stop it being offered, because you asked for it.
*/
askShowAgain: boolean;
inputPrefs?: InputPrefs;
/** OK: the candidates still ticked, in list order. */
onOk: (chosen: readonly RescueCandidate[]) => void;
/** Cancel, and the Never Show Again answer, which also rescues nothing. */
onCancel: () => void;
onNeverShowAgain: () => void;
}
// ---------------------------------------------------------------------------
// The KiCad classes (project_rescue.h / project_rescue.cpp) on the live model. Of the two
// rescuers only SYMBOL_LIB_TABLE_RESCUER is ported: LEGACY_RESCUER is for a schematic with no
// library nicknames (a KiCad 4 file), whose LEGACY_SYMBOL_LIBS the live model does not load yet,
// and RescueSymbols only reaches it for such a file. PROJECT_SCH::LegacySchLibs - the project's
// `<project>-cache.lib` - is not a PROJECT element here, so `findSymbol` over it finds nothing:
// with no cache, the live arm is a symbol id with characters LIB_ID forbids.
// ---------------------------------------------------------------------------
/** `sort_by_libid`: symbols in LIB_ID order, so a library symbol is searched once per group. */
function getSymbols(aSchematic: SCHEMATIC, aSymbols: SCH_SYMBOL[]): void {
const screens = new SCH_SCREENS(aSchematic.Root());
// Get the full list
for (let screen = screens.GetFirst(); screen; screen = screens.GetNext()) {
for (const aItem of screen.Items().OfType(KICAD_T.SCH_SYMBOL_T))
aSymbols.push(aItem as SCH_SYMBOL);
}
if (aSymbols.length === 0) return;
// sort aSymbols by lib symbol. symbols will be grouped by same lib symbol.
aSymbols.sort((a, b) => a.GetLibId().compare(b.GetLibId()));
}
/** `findSymbol( aName, aLibs, aCached )`: the legacy libraries are not loaded (see above). */
function findSymbol(_aName: string, _aLibs: null, _aCached: boolean): LIB_SYMBOL | null {
return null;
}
/** `GetRescueLibraryFileName( aSchematic )`: `<schematic>-rescue.lib` beside the schematic. */
function GetRescueLibraryFileName(aSchematic: SCHEMATIC): {
path: string;
name: string;
ext: string;
} {
const fn = aSchematic.GetFileName();
const slash = fn.lastIndexOf('/');
const full = fn.slice(slash + 1);
const dot = full.lastIndexOf('.');
return {
path: slash < 0 ? '' : fn.slice(0, slash),
name: `${dot <= 0 ? full : full.slice(0, dot)}-rescue`,
ext: LegacySymbolLibFileExtension,
};
}
const fullPathOf = (aFn: { path: string; name: string; ext: string }) =>
`${aFn.path === '' ? '' : `${aFn.path}/`}${aFn.name}.${aFn.ext}`;
/** `SchGetLibSymbol( aLibId, aLibMgr )` (sch_base_frame.cpp:83) without a cache library. */
function SchGetLibSymbol(
aLibId: LIB_ID,
aLibMgr: ReturnType<typeof SymbolLibAdapter>,
): LIB_SYMBOL | null {
try {
return aLibMgr.LoadSymbol(aLibId);
} catch (ioe) {
if (!(ioe instanceof IO_ERROR)) throw ioe;
return null;
}
}
export abstract class RESCUE_CANDIDATE {
protected m_requested_name: string;
protected m_new_name: string;
protected m_lib_candidate: LIB_SYMBOL | null;
protected m_unit: number;
protected m_bodyStyle: number;
constructor(
aRequestedName: string,
aNewName: string,
aLibCandidate: LIB_SYMBOL | null,
aUnit: number,
aBodyStyle: number,
) {
this.m_requested_name = aRequestedName;
this.m_new_name = aNewName;
this.m_lib_candidate = aLibCandidate;
this.m_unit = aUnit;
this.m_bodyStyle = aBodyStyle;
}
/** Get the name that was originally requested in the schematic. */
GetRequestedName(): string {
return this.m_requested_name;
}
/** Get the name we're proposing changing it to. */
GetNewName(): string {
return this.m_new_name;
}
/** Get the part that can be loaded from the project cache, if possible, or else NULL. */
GetCacheCandidate(): LIB_SYMBOL | null {
return null;
}
/** Get the part the would be loaded from the libraries, if possible, or else NULL. */
GetLibCandidate(): LIB_SYMBOL | null {
return this.m_lib_candidate;
}
GetUnit(): number {
return this.m_unit;
}
GetBodyStyle(): number {
return this.m_bodyStyle;
}
/** Get a description of the action proposed, for displaying in the UI. */
abstract GetActionDescription(): string;
/** Perform the actual rescue action. @return true for success. */
abstract PerformAction(aRescuer: RESCUER): boolean;
}
export class RESCUE_SYMBOL_LIB_TABLE_CANDIDATE extends RESCUE_CANDIDATE {
private readonly m_requested_id: LIB_ID;
private readonly m_new_id: LIB_ID;
private readonly m_cache_candidate: LIB_SYMBOL | null;
constructor(
aRequestedId: LIB_ID = new LIB_ID(),
aNewId: LIB_ID = new LIB_ID(),
aCacheCandidate: LIB_SYMBOL | null = null,
aLibCandidate: LIB_SYMBOL | null = null,
aUnit = 0,
aBodyStyle = 0,
) {
super(aRequestedId.Format(), '', aLibCandidate, aUnit, aBodyStyle);
this.m_requested_id = aRequestedId;
this.m_new_id = aNewId;
this.m_cache_candidate = aCacheCandidate;
}
override GetCacheCandidate(): LIB_SYMBOL | null {
return this.m_cache_candidate;
}
/**
* `FindRescues( aRescuer, aCandidates )` (project_rescue.cpp:344): one candidate per symbol id
* that is only in the cache, conflicts with its library symbol, or has an illegal name.
*/
static FindRescues(aRescuer: RESCUER, aCandidates: RESCUE_CANDIDATE[]): void {
const candidate_map = new Map<
string,
{ id: LIB_ID; candidate: RESCUE_SYMBOL_LIB_TABLE_CANDIDATE }
>();
// Remember the list of symbols is sorted by LIB_ID.
// So a search in libraries is made only once by group
let cache_match: LIB_SYMBOL | null = null;
let lib_match: LIB_SYMBOL | null = null;
let old_symbol_id = new LIB_ID();
let symbolName: string;
for (const eachSymbol of aRescuer.GetSymbols()) {
const symbol_id = eachSymbol.GetLibId();
if (!old_symbol_id.equals(symbol_id)) {
// A new symbol name is found (a new group starts here).
// Search the symbol names candidates only once for this group:
old_symbol_id = symbol_id;
symbolName = symbol_id.Format();
// Get the library symbol from the cache library. It will be a flattened
// symbol by default (no inheritance).
cache_match = findSymbol(symbolName, null, true);
// At some point during V5 development, the LIB_ID delimiter character ':' was
// replaced by '_' when writing the symbol cache library so we have to test for
// the LIB_NICKNAME_LIB_SYMBOL_NAME case.
if (!cache_match) {
symbolName = `${symbol_id.GetLibNickname()}-${symbol_id.GetLibItemName()}`;
cache_match = findSymbol(symbolName, null, true);
}
// Get the library symbol from the symbol library table.
lib_match = SchGetLibSymbol(symbol_id, SymbolLibAdapter(aRescuer.GetPrj()));
if (!cache_match && !lib_match) continue;
// If it's a derived symbol, use the parent symbol to perform the pin test.
if (lib_match?.IsDerived()) lib_match = lib_match.GetRootSymbol() ?? null;
// Test whether there is a conflict or if the symbol can only be found in the cache.
if (LIB_ID.HasIllegalChars(symbol_id.GetLibItemName()) === -1) {
if (
cache_match &&
lib_match &&
!cache_match.PinsConflictWith(lib_match, true, true, true, true, false)
)
continue;
if (!cache_match && lib_match) continue;
}
// Fix illegal LIB_ID name characters.
const new_name = EscapeString(symbol_id.GetLibItemName(), ESCAPE_CONTEXT.CTX_LIBID);
// Differentiate symbol name in the rescue library by appending the original symbol
// library table nickname to the symbol name to prevent name clashes in the rescue
// library.
const libNickname = GetRescueLibraryFileName(aRescuer.Schematic()).name;
const new_id = new LIB_ID(libNickname, `${new_name}-${symbol_id.GetLibNickname()}`);
const candidate = new RESCUE_SYMBOL_LIB_TABLE_CANDIDATE(
symbol_id,
new_id,
cache_match,
lib_match,
eachSymbol.GetUnit(),
eachSymbol.GetBodyStyle(),
);
candidate_map.set(symbol_id.Format(), { id: symbol_id, candidate });
}
}
// Now, dump the map into aCandidates (std::map<LIB_ID, …>: LIB_ID order)
for (const { candidate } of [...candidate_map.values()].sort((a, b) => a.id.compare(b.id)))
aCandidates.push(candidate);
}
GetActionDescription(): string {
if (!this.m_cache_candidate && !this.m_lib_candidate) {
return `Cannot rescue symbol ${unescapeString(this.m_requested_id.GetLibItemName())} which is not available in any library or the cache.`;
} else if (this.m_cache_candidate && !this.m_lib_candidate) {
return `Rescue symbol ${unescapeString(this.m_requested_id.Format())} found only in cache library to ${unescapeString(this.m_new_id.Format())}.`;
}
return `Rescue modified symbol ${unescapeString(this.m_requested_id.Format())} to ${unescapeString(this.m_new_id.Format())}`;
}
PerformAction(aRescuer: RESCUER): boolean {
const tmp = this.m_cache_candidate ?? this.m_lib_candidate;
if (!tmp) return false; // wxCHECK_MSG: "Both cache and library symbols undefined."
const new_symbol = tmp.Flatten();
new_symbol.SetLibId(this.m_new_id);
new_symbol.SetName(this.m_new_id.GetLibItemName());
aRescuer.AddSymbol(new_symbol);
for (const eachSymbol of aRescuer.GetSymbols()) {
if (!eachSymbol.GetLibId().equals(this.m_requested_id)) continue;
eachSymbol.SetLibId(this.m_new_id);
eachSymbol.ClearFlags();
aRescuer.LogRescue(eachSymbol, this.m_requested_id.Format(), this.m_new_id.Format());
}
return true;
}
}
/** `RESCUE_LOG`. */
export interface RESCUE_LOG {
symbol: SCH_SYMBOL;
old_name: string;
new_name: string;
}
/**
* `DIALOG_RESCUE_EACH` as InvokeDialogRescueEach sets it up: the window shows the candidates and
* writes `chosen` (one flag per candidate, the list's check boxes), ending with wxID_OK; Cancel
* and "Never Show Again" leave nothing chosen.
*/
export interface DIALOG_RESCUE_EACH_ARG {
candidates: readonly RESCUE_CANDIDATE[];
symbols: readonly SCH_SYMBOL[];
currentSheet: SCH_SHEET_PATH;
askShowAgain: boolean;
chosen: boolean[];
}
export abstract class RESCUER {
protected m_symbols: SCH_SYMBOL[] = [];
protected m_prj: PROJECT;
protected m_schematic: SCHEMATIC;
protected m_currentSheet: SCH_SHEET_PATH;
protected m_all_candidates: RESCUE_CANDIDATE[] = [];
protected m_chosen_candidates: RESCUE_CANDIDATE[] = [];
protected m_rescue_log: RESCUE_LOG[] = [];
constructor(aProject: PROJECT, aSchematic: SCHEMATIC | null, aCurrentSheet: SCH_SHEET_PATH) {
this.m_schematic = aSchematic ?? (aCurrentSheet.LastScreen()!.Schematic() as SCHEMATIC);
if (this.m_schematic) getSymbols(this.m_schematic, this.m_symbols);
this.m_prj = aProject;
this.m_currentSheet = aCurrentSheet;
}
abstract WriteRescueLibrary(aParent: SCH_EDIT_FRAME): boolean;
abstract OpenRescueLibrary(): void;
abstract FindCandidates(): void;
abstract AddSymbol(aNewSymbol: LIB_SYMBOL): void;
abstract InvokeDialog(aParent: SCH_EDIT_FRAME, aAskShowAgain: boolean): Promise<void>;
/** `RemoveDuplicates()`: the first candidate of each requested name. */
RemoveDuplicates(): void {
const names_seen: string[] = [];
this.m_all_candidates = this.m_all_candidates.filter((it) => {
if (names_seen.includes(it.GetRequestedName())) return false;
names_seen.push(it.GetRequestedName());
return true;
});
}
GetCandidateCount(): number {
return this.m_all_candidates.length;
}
GetChosenCandidateCount(): number {
return this.m_chosen_candidates.length;
}
GetSymbols(): SCH_SYMBOL[] {
return this.m_symbols;
}
GetPrj(): PROJECT {
return this.m_prj;
}
Schematic(): SCHEMATIC {
return this.m_schematic;
}
LogRescue(aSymbol: SCH_SYMBOL, aOldName: string, aNewName: string): void {
this.m_rescue_log.push({ symbol: aSymbol, old_name: aOldName, new_name: aNewName });
}
DoRescues(): boolean {
for (const each_candidate of this.m_chosen_candidates) {
if (!each_candidate.PerformAction(this)) return false;
}
return true;
}
UndoRescues(): void {
for (const each_logitem of this.m_rescue_log) {
const libId = new LIB_ID();
libId.SetLibItemName(each_logitem.old_name);
each_logitem.symbol.SetLibId(libId);
each_logitem.symbol.ClearFlags();
}
}
/** `RescueProject( aParent, aRescuer, aRunningOnDemand )` (project_rescue.cpp:544). */
static async RescueProject(
aParent: SCH_EDIT_FRAME,
aRescuer: RESCUER,
aRunningOnDemand: boolean,
): Promise<boolean> {
aRescuer.FindCandidates();
if (!aRescuer.GetCandidateCount()) {
if (aRunningOnDemand) {
await aParent.ShowModalDialog('KICAD_MESSAGE_DIALOG', [], {
message: 'This project has nothing to rescue.',
caption: 'Project Rescue Helper',
style: wxOK,
});
}
return true;
}
aRescuer.RemoveDuplicates();
await aRescuer.InvokeDialog(aParent, !aRunningOnDemand);
// If no symbols were rescued, let the user know what's going on. He might
// have clicked cancel by mistake, and should have some indication of that.
if (!aRescuer.GetChosenCandidateCount()) {
await aParent.ShowModalDialog('KICAD_MESSAGE_DIALOG', [], {
message: 'No symbols were rescued.',
caption: 'Project Rescue Helper',
style: wxOK,
});
// Set the modified flag even on Cancel. Many users seem to instinctively want to Save at
// this point, due to the reloading of the symbols, so we'll make the save button active.
return true;
}
aRescuer.OpenRescueLibrary();
if (!aRescuer.DoRescues()) {
aRescuer.UndoRescues();
return false;
}
aRescuer.WriteRescueLibrary(aParent);
return true;
}
/** `InvokeDialogRescueEach( aParent, aRescuer, aCurrentSheet, aGalBackEndType, aAskShowAgain )`. */
protected async invokeDialogRescueEach(
aParent: SCH_EDIT_FRAME,
aAskShowAgain: boolean,
): Promise<void> {
const arg: DIALOG_RESCUE_EACH_ARG = {
candidates: this.m_all_candidates,
symbols: this.m_symbols,
currentSheet: this.m_currentSheet,
askShowAgain: aAskShowAgain,
chosen: this.m_all_candidates.map(() => true),
};
// TransferDataFromWindow: the checked rows; Cancel / Never Show Again clear the choice.
if ((await aParent.ShowModalDialog('DIALOG_RESCUE_EACH', [], arg)) !== wxID_OK) {
this.m_chosen_candidates = [];
return;
}
this.m_chosen_candidates = this.m_all_candidates.filter((_c, index) => arg.chosen[index]);
}
}
export class SYMBOL_LIB_TABLE_RESCUER extends RESCUER {
private readonly m_rescueLibSymbols: LIB_SYMBOL[] = [];
private readonly m_properties = new Map<string, string>();
FindCandidates(): void {
RESCUE_SYMBOL_LIB_TABLE_CANDIDATE.FindRescues(this, this.m_all_candidates);
}
InvokeDialog(aParent: SCH_EDIT_FRAME, aAskShowAgain: boolean): Promise<void> {
return this.invokeDialogRescueEach(aParent, aAskShowAgain);
}
OpenRescueLibrary(): void {
this.m_properties.set(SCH_IO_KICAD_SEXPR.PropBuffering, '');
const fn = GetRescueLibraryFileName(this.m_schematic);
const manager = Pgm().GetLibraryManager();
const adapter = SymbolLibAdapter(this.m_prj);
// If a rescue library already exists copy the contents of that library so we do not
// lose any previous rescues.
const row = manager.GetRow(LIBRARY_TABLE_TYPE.SYMBOL, fn.name);
if (row) {
if (SCH_IO_MGR.EnumFromStr(row.Type()) === SCH_FILE_T.SCH_KICAD)
fn.ext = KiCadSymbolLibFileExtension;
for (const symbol of adapter.GetSymbols(fn.name))
this.m_rescueLibSymbols.push(LIB_SYMBOL.copyOf(symbol));
}
}
WriteRescueLibrary(_aParent: SCH_EDIT_FRAME): boolean {
const manager = Pgm().GetLibraryManager();
const fn = GetRescueLibraryFileName(this.m_schematic);
const optRow = manager.GetRow(LIBRARY_TABLE_TYPE.SYMBOL, fn.name);
fn.ext = KiCadSymbolLibFileExtension;
try {
const pi = SCH_IO_MGR.FindPlugin(SCH_FILE_T.SCH_KICAD)!;
for (const symbol of this.m_rescueLibSymbols)
pi.SaveSymbol(fullPathOf(fn), LIB_SYMBOL.copyOf(symbol), this.m_properties);
pi.SaveLibrary(fullPathOf(fn));
} catch (ioe) {
if (!(ioe instanceof IO_ERROR)) throw ioe;
DisplayErrorMessage(`Failed to save rescue library ${fullPathOf(fn)}.`, ioe.message);
return false;
}
// If the rescue library already exists in the symbol library table no need save it to add
// it to the table.
if (!optRow || SCH_IO_MGR.EnumFromStr(optRow.Type()) === SCH_FILE_T.SCH_LEGACY) {
const uri = `\${KIPRJMOD}/${fn.name}.${fn.ext}`;
const libNickname = fn.name;
const projectTable = manager.Table(LIBRARY_TABLE_TYPE.SYMBOL, LIBRARY_TABLE_SCOPE.PROJECT);
if (!projectTable) return false; // wxCHECK
const row = projectTable.Row(libNickname) ?? projectTable.InsertRow();
row.SetNickname(libNickname);
row.SetURI(uri);
row.SetType('KiCad');
const saved = projectTable.Save();
if (!saved.ok) {
// wxMessageBox( …, _( "File Save Error" ), wxOK | wxICON_ERROR )
DisplayErrorMessage(`Error saving library table:\n\n${saved.error.message}`);
return false;
}
}
// Update the schematic symbol library links since the library list has changed.
const schematic = new SCH_SCREENS(this.m_schematic.Root());
schematic.UpdateSymbolLinks();
return true;
}
AddSymbol(aNewSymbol: LIB_SYMBOL): void {
this.m_rescueLibSymbols.push(LIB_SYMBOL.copyOf(aNewSymbol));
}
}