Files
vibemake-pcb-studio/common/fp_lib_table.ts
T
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

214 lines
8.5 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 footprint library table. Counterpart: `common/fp_lib_table.cpp`
* (FP_LIB_TABLE / LIB_TABLE_ROW), the `fp-lib-table` file that maps a library
* *nickname* to a `.pretty` directory.
*
* Two rules from upstream matter here, and both are strict:
*
* - **A library exists only if a table row registers it.** A `.pretty`
* directory sitting next to the project is not a library; FP_LIB_TABLE
* resolves an FPID's nickname through the project table then the global
* one, and an unregistered directory resolves to nothing (cvpcb then marks
* the assignment with SYMBOLS_LISTBOX's warning colour).
* - **The nickname is the row's, not the directory's.** The ECC83 demo stores
* `Footprints:Valve_ECC-83-1` because its table names
* `${KIPRJMOD}/footprints.pretty` "Footprints".
*
* Only the project table lives in a file here; the hosted libraries stand in
* for the global table, and their nicknames are the index's library names.
*/
import {
LIBRARY_TABLE,
LIBRARY_TABLE_SCOPE,
LIBRARY_TABLE_TYPE,
} from './libraries/library_table.js';
/** A LIB_TABLE_ROW: `(lib (name "X")(type "KiCad")(uri "…")(options "")(descr ""))`. */
export interface FpLibRow {
name: string;
type: string;
uri: string;
options: string;
descr: string;
/** `(disabled)`, the row's "Enable" checkbox; a disabled row is not loaded. */
disabled?: boolean;
/** `(hidden)`, the row's "Show" checkbox (symbol tables only). */
hidden?: boolean;
}
/**
* Parse an `fp-lib-table` file through LIBRARY_TABLE. Malformed text yields no
* rows (upstream's whole-table rejection); a row with no name is dropped and a
* row with no type reads as "KiCad", as this reader always has.
*/
export function parseFpLibTable(text: string): FpLibRow[] {
return fpLibRowsOf(new LIBRARY_TABLE(true, text, LIBRARY_TABLE_SCOPE.PROJECT));
}
/** A LIBRARY_TABLE's rows as the editor's records. */
export function fpLibRowsOf(table: LIBRARY_TABLE): FpLibRow[] {
return table
.Rows()
.map((r) => ({
name: r.Nickname(),
type: r.Type() || 'KiCad',
uri: r.URI(),
options: r.Options(),
descr: r.Description(),
disabled: r.Disabled(),
...(r.Hidden() ? { hidden: true } : {}),
}))
.filter((r) => r.name);
}
/** The editor's records as a LIBRARY_TABLE of the given type (`LIBRARY_TABLE::InsertRow`). */
export function libraryTableOf(
rows: readonly FpLibRow[],
type: LIBRARY_TABLE_TYPE,
scope = LIBRARY_TABLE_SCOPE.PROJECT,
): LIBRARY_TABLE {
const table = LIBRARY_TABLE.Empty(scope, type);
for (const r of rows) {
const row = table.InsertRow();
row.SetNickname(r.name);
row.SetType(r.type || 'KiCad');
row.SetURI(r.uri);
row.SetOptions(r.options);
row.SetDescription(r.descr);
row.SetDisabled(!!r.disabled);
row.SetHidden(!!r.hidden);
}
return table;
}
/** Write the rows back as an `fp-lib-table` file (LIBRARY_TABLE::Save's text). */
export function serializeFpLibTable(rows: readonly FpLibRow[]): string {
return libraryTableOf(rows, LIBRARY_TABLE_TYPE.FOOTPRINT).FormatForSave();
}
/** The `.pretty` directory a row's URI points at, without the extension
* ("${KIPRJMOD}/footprints.pretty" -> "footprints"). */
export function rowPrettyDir(row: FpLibRow): string {
const uri = row.uri.replace(/\\/g, '/').replace(/\/+$/, '');
const base = uri.split('/').pop() ?? '';
return /\.pretty$/i.test(base) ? base.replace(/\.pretty$/i, '') : '';
}
/** The `.pretty` directory of a project footprint path ("proj/foo.pretty/x.kicad_mod"
* -> "foo"), or '' when the file is not inside one. */
export function prettyDirOf(path: string): string {
const m = /([^/]+)\.pretty\//i.exec(path.replace(/\\/g, '/'));
return m?.[1] ?? '';
}
/**
* The nickname a project `.kicad_mod` path is reachable under, the enabled
* table row whose URI points at its `.pretty` directory. Returns '' when no
* row registers that directory: unregistered libraries do not exist, exactly
* as FP_LIB_TABLE::FindRow finds nothing for them.
*/
export function projectLibraryNickname(rows: readonly FpLibRow[], path: string): string {
const dir = prettyDirOf(path);
if (!dir) return '';
const row = rows.find((r) => !r.disabled && rowPrettyDir(r).toLowerCase() === dir.toLowerCase());
return row ? row.name : '';
}
/** Read the project's `fp-lib-table` out of its files, if it has one. */
export function projectFpLibTable(files: readonly { name: string; text: string }[]): FpLibRow[] {
const file = files.find((f) => /(^|\/)fp-lib-table$/i.test(f.name.replace(/\\/g, '/')));
return file ? parseFpLibTable(file.text) : [];
}
/** Path of the project's `fp-lib-table`, existing or to be created (it sits
* next to the `.kicad_pro`). */
export function projectFpLibTablePath(files: readonly { name: string; text: string }[]): string {
const existing = files.find((f) => /(^|\/)fp-lib-table$/i.test(f.name.replace(/\\/g, '/')));
if (existing) return existing.name;
const pro = files.find((f) => /\.kicad_pro$/i.test(f.name))?.name.replace(/\\/g, '/');
const dir = pro?.includes('/') ? pro.slice(0, pro.lastIndexOf('/') + 1) : '';
return `${dir}fp-lib-table`;
}
/** The `.pretty` directories present in the project, with the nickname (if any)
* each is registered under, what "Add Existing" offers. */
export function projectPrettyDirs(
files: readonly { name: string; text: string }[],
rows: readonly FpLibRow[],
): { dir: string; path: string; registeredAs: string }[] {
const seen = new Map<string, string>();
for (const f of files) {
const norm = f.name.replace(/\\/g, '/');
if (!/\.kicad_mod$/i.test(norm)) continue;
const dir = prettyDirOf(norm);
if (!dir || seen.has(dir)) continue;
const at = norm.toLowerCase().indexOf(`${dir.toLowerCase()}.pretty/`);
seen.set(dir, norm.slice(0, at + dir.length + '.pretty'.length));
}
return [...seen].map(([dir, path]) => ({
dir,
path,
registeredAs: rows.find((r) => rowPrettyDir(r).toLowerCase() === dir.toLowerCase())?.name ?? '',
}));
}
/** A library brought into the project, or why it was not. */
export type ADD_LIBRARY_RESULT =
| { ok: true; nickname: string; files: { name: string; text: string }[] }
| { ok: false; error: string };
/**
* `PCB_BASE_EDIT_FRAME::AddLibrary` (footprint_libraries_utils.cpp:484) for a folder read off the
* computer: its `.kicad_mod` files copied into the project under `<name>.pretty/`, beside the
* `fp-lib-table`, and the project table given a KiCad row for it at `${KIPRJMOD}/<name>.pretty`.
* The nickname is the folder's name less `.pretty`, as `fn.GetName()` is.
*
* Web deltas: upstream points the row at the folder where it lies, which a page cannot, so the
* folder is copied - and refused rather than written over a library folder of the same name.
* A folder not named `.pretty` (a vendor download) gets the extension, which is how the project
* finds its libraries. Only the folder's own `.kicad_mod` files are a library (`FP_CACHE::Load`
* reads no subfolder); one with none is refused rather than added empty.
*/
export function AddFootprintLibraryToProject(
aProjectFiles: readonly { name: string; text: string }[],
aFolder: { name: string; files: readonly { path: string; text: string }[] },
): ADD_LIBRARY_RESULT {
const tablePath = projectFpLibTablePath(aProjectFiles);
const dir = tablePath.slice(0, tablePath.lastIndexOf('/') + 1);
const libDir = /\.pretty$/i.test(aFolder.name) ? aFolder.name : `${aFolder.name}.pretty`;
const nickname = libDir.replace(/\.pretty$/i, '');
const footprints = aFolder.files.filter(
(f) => !f.path.includes('/') && /\.kicad_mod$/i.test(f.path),
);
if (nickname === '') return { ok: false, error: 'The folder has no name.' };
if (footprints.length === 0)
return { ok: false, error: `No footprint files (*.kicad_mod) in '${aFolder.name}'.` };
const target = `${dir}${libDir}/`.toLowerCase();
if (aProjectFiles.some((f) => f.name.replace(/\\/g, '/').toLowerCase().startsWith(target)))
return { ok: false, error: `The project already has a library folder '${libDir}'.` };
const rows = [
...projectFpLibTable(aProjectFiles),
{ name: nickname, type: 'KiCad', uri: `\${KIPRJMOD}/${libDir}`, options: '', descr: '' },
];
return {
ok: true,
nickname,
files: [
...footprints.map((f) => ({ name: `${dir}${libDir}/${f.path}`, text: f.text })),
{ name: tablePath, text: serializeFpLibTable(rows) },
],
};
}