layout-data 0.0.0-stage → 0.3.0

package/src/dispatch.js

@@ -0,0 +1,23 @@
+// Dispatch of events that does not stop at a listener that throws
+// (doc/spec-data-api.md §4.4, doc/design.md §5.1). Internal.
+
+/**
+ * Calls every listener of an event, in the order they subscribed, and pushes
+ * what a listener throws to `errors` instead of letting it stop the others.
+ * A `once` listener removes itself as usual.
+ *
+ * @param {import("node:events").EventEmitter | undefined} emitter - Nothing happens for undefined.
+ * @param {string} event
+ * @param {any[]} args
+ * @param {unknown[]} errors
+ */
+export function emit_all(emitter, event, args, errors) {
+	if (!emitter) return;
+	for (const listener of emitter.rawListeners(event)) {
+		try {
+			listener.apply(emitter, args);
+		} catch (error) {
+			errors.push(error);
+		}
+	}
+}

package/src/endian.js

@@ -0,0 +1,197 @@
+// Conversion between the device byte order of an IO buffer and the big-endian
+// buffer of an Ldata, per compiled layout entry (doc/spec-data-api.md §2.9,
+// doc/design.md §6). Device byte order acts per 16-bit register and per 32-bit
+// value; the IO buffer is indexed like the Ldata buffer. Only io_index_table is
+// exported by the package: Ldata calls the other functions with its own buffer.
+import { compiled_of } from "./registry.js";
+
+/** @import { Endian, Layout } from "./typedefs.js" */
+/** @import { Layout_Entry } from "./internal_types.js" */
+
+// The device byte orders; there are no aliases.
+const ENDIANS = ["BE", "LE", "BEBS", "LEBS"];
+
+// Endians that swap the two bytes of a 16-bit register.
+const BYTE_SWAP_ENDIANS = ["LE", "BEBS"];
+
+/**
+ * Throws for a byte order that is not one of BE, LE, BEBS and LEBS, instead of
+ * treating it as BE and corrupting the data silently.
+ *
+ * @param {string} endian
+ * @throws {RangeError}
+ */
+export function check_endian(endian) {
+	if (!ENDIANS.includes(endian)) {
+		throw new RangeError(`unknown byte order ${endian}: use BE, LE, BEBS or LEBS`);
+	}
+}
+
+/**
+ * Converts the endianness of a 2-byte value between the specified endian format and Big Endian (BE).
+ *
+ * This function performs bidirectional conversion:
+ * - If the data is not in BE, it converts it to BE.
+ * - If the data is in BE, it converts it to the specified endian format.
+ *
+ * @param {Uint8Array} buffer_from - The source buffer containing the data to be converted.
+ * @param {Uint8Array} buffer_to - The destination buffer where the converted data will be written.
+ * @param {number} index - The starting index in the buffers for the 2-byte value.
+ * @param {Endian} endian - The endian format to convert to/from.
+ */
+function convert_endian_2byte(buffer_from, buffer_to, index, endian) {
+	if (BYTE_SWAP_ENDIANS.includes(endian)) { // LE, BEBS: BA
+		buffer_to[index] = buffer_from[index + 1];
+		buffer_to[index + 1] = buffer_from[index];
+	} else { // BE, LEBS: AB
+		buffer_to[index] = buffer_from[index];
+		buffer_to[index + 1] = buffer_from[index + 1];
+	}
+}
+
+/**
+ * Converts the endianness of a 4-byte value between the specified endian format and Big Endian (BE).
+ *
+ * This function performs bidirectional conversion:
+ * - If the data is not in BE, it converts it to BE.
+ * - If the data is in BE, it converts it to the specified endian format.
+ *
+ * The function handles different endian formats:
+ * - LE (Little Endian): DCBA <-> ABCD
+ * - BEBS (Big Endian Byte Swap): BADC <-> ABCD
+ * - LEBS (Little Endian Byte Swap): CDAB <-> ABCD
+ *
+ * @param {Uint8Array} buffer_from - The source buffer containing the data to be converted.
+ * @param {Uint8Array} buffer_to - The destination buffer where the converted data will be written.
+ * @param {number} index - The starting index in the buffers for the 4-byte value.
+ * @param {Endian} endian - The endian format to convert to/from.
+ */
+function convert_endian_4bytes(buffer_from, buffer_to, index, endian) {
+	switch (endian) {
+		case "LE": { // DCBA <-> ABCD
+			buffer_to[index] = buffer_from[index + 3];
+			buffer_to[index + 1] = buffer_from[index + 2];
+			buffer_to[index + 2] = buffer_from[index + 1];
+			buffer_to[index + 3] = buffer_from[index];
+			break;
+		}
+		case "BEBS": { // BADC <-> ABCD
+			buffer_to[index] = buffer_from[index + 1];
+			buffer_to[index + 1] = buffer_from[index];
+			buffer_to[index + 2] = buffer_from[index + 3];
+			buffer_to[index + 3] = buffer_from[index + 2];
+			break;
+		}
+		case "LEBS": { // CDAB <-> ABCD
+			buffer_to[index] = buffer_from[index + 2];
+			buffer_to[index + 1] = buffer_from[index + 3];
+			buffer_to[index + 2] = buffer_from[index];
+			buffer_to[index + 3] = buffer_from[index + 1];
+			break;
+		}
+		default: { // BE
+			for (let k = 0; k < 4; k++) buffer_to[index + k] = buffer_from[index + k];
+		}
+	}
+}
+
+/**
+ * Index in a device-ordered IO buffer of the byte of a single-byte entry
+ * (Bool, Byte, SInt, USInt): when the endian swaps the register bytes, the
+ * byte sits in the other half of its register.
+ *
+ * @param {number} byte - Byte offset of the entry.
+ * @param {Endian} endian - Device byte order.
+ * @returns {number}
+ */
+export function io_index(byte, endian) {
+	return BYTE_SWAP_ENDIANS.includes(endian) ? byte ^ 1 : byte;
+}
+
+/**
+ * The index in a device-ordered IO buffer of every byte of a data block: the
+ * byte `i` of the block is the byte `table[i]` of the IO buffer. The table
+ * makes loading and storing a whole block a plain byte copy, and it agrees
+ * with `load_entry` / `store_entry` for every entry (a Bool or a single-byte
+ * entry maps as `io_index`, a multi-byte entry as its endian).
+ *
+ * @param {Layout} layout - The compiled layout of the data block.
+ * @param {Endian} endian - Device byte order: BE, LE, BEBS or LEBS.
+ * @returns {Int32Array}
+ * @throws {RangeError} For another byte order.
+ */
+export function io_index_table(layout, endian) {
+	check_endian(endian);
+	const table = new Int32Array(layout.size);
+	for (let i = 0; i < table.length; i++) table[i] = io_index(i, endian);
+	for (const { byte, size, type } of compiled_of(layout).entries.values()) {
+		if (size !== 4 || type === "bool") continue;
+		for (let k = 0; k < 4; k++) {
+			switch (endian) {
+				case "LE": table[byte + k] = byte + 3 - k; break;
+				case "BEBS": table[byte + k] = byte + (k ^ 1); break;
+				case "LEBS": table[byte + k] = byte + ((k + 2) % 4); break;
+				default: table[byte + k] = byte + k;
+			}
+		}
+	}
+	return table;
+}
+
+/**
+ * Byte range [start, end) an entry occupies in a device-ordered IO buffer.
+ *
+ * @param {Layout_Entry} entry
+ * @param {Endian} endian - Device byte order.
+ * @returns {{start: number, end: number}}
+ */
+export function io_range(entry, endian) {
+	const start = entry.size === 1 ? io_index(entry.byte, endian) : entry.byte;
+	return { start, end: start + entry.size };
+}
+
+/**
+ * Copies an entry from a device-ordered IO buffer into a big-endian buffer.
+ * A Bool only changes its own bit. No change is detected here, and the byte
+ * order and the range in the IO buffer are not checked (Ldata does).
+ *
+ * @param {Layout_Entry} entry
+ * @param {Uint8Array} io_buffer - The device-ordered source.
+ * @param {Uint8Array} buffer - The big-endian destination.
+ * @param {Endian} endian - Device byte order.
+ */
+export function load_entry(entry, io_buffer, buffer, endian) {
+	const { byte, size, mask } = entry;
+	if (entry.type === "bool") {
+		const value = io_buffer[io_index(byte, endian)] & mask;
+		buffer[byte] = value ? buffer[byte] | mask : buffer[byte] & ~mask;
+	} else if (size === 1) {
+		buffer[byte] = io_buffer[io_index(byte, endian)];
+	} else if (size === 2) {
+		convert_endian_2byte(io_buffer, buffer, byte, endian);
+	} else {
+		convert_endian_4bytes(io_buffer, buffer, byte, endian);
+	}
+}
+
+/**
+ * Copies an entry from a big-endian buffer into a device-ordered IO buffer.
+ *
+ * @param {Layout_Entry} entry
+ * @param {Uint8Array} buffer - The big-endian source.
+ * @param {Uint8Array} io_buffer - The device-ordered destination.
+ * @param {Endian} endian - Device byte order.
+ */
+export function store_entry(entry, buffer, io_buffer, endian) {
+	const { byte, size, mask } = entry;
+	if (entry.type === "bool") {
+		const index = io_index(byte, endian);
+		io_buffer[index] = buffer[byte] & mask ? io_buffer[index] | mask : io_buffer[index] & ~mask;
+	} else if (size === 1) {
+		io_buffer[io_index(byte, endian)] = buffer[byte];
+	} else if (size === 2) {
+		convert_endian_2byte(buffer, io_buffer, byte, endian);
+	} else {
+		convert_endian_4bytes(buffer, io_buffer, byte, endian);
+	}
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// Public interface of the package (doc/design.md §1).
+export { Ldata } from "./Ldata.js";
+export { Ltag } from "./Ltag.js";
+export { register_layout } from "./layout.js";
+export { get_layout } from "./registry.js";
+export { io_index_table } from "./endian.js";
+export { render_types } from "./types.js";
+export * from "./typedefs.js";

package/src/internal_types.js

@@ -0,0 +1,47 @@
+// Type definitions of the internals. This file has no run-time content, and
+// index.js does not export it: the compiled data of a layout is not part of
+// the public interface (doc/spec-data-api.md §6.6).
+
+/**
+ * Codec of one tag type on a big-endian buffer (doc/design.md §4).
+ *
+ * @typedef {object} Codec
+ * @property {number} size - Size in bytes.
+ * @property {(value: any) => string | null} check - The reason a value is refused, null if it can be written.
+ * @property {(buffer: Buffer, byte: number, mask: number) => number | boolean} get
+ * @property {(buffer: Buffer, byte: number, mask: number, value: number | boolean) => void} set
+ */
+
+/**
+ * One tag of a compiled layout.
+ *
+ * @typedef {object} Layout_Entry
+ * @property {string} name
+ * @property {import("./typedefs.js").Tag_Type} type - Lower case type name.
+ * @property {number | boolean} init_value
+ * @property {number} byte - Byte offset.
+ * @property {number} index - Position among the entries of the layout.
+ * @property {number} size - Size in bytes.
+ * @property {number} mask - Bit mask of a Bool, 0xff otherwise.
+ * @property {Codec} codec
+ */
+
+/**
+ * The expanded structure of a data block (the result of build_structure).
+ *
+ * @typedef {object} Data_Struct
+ * @property {string} name
+ * @property {number} length - Total length in bits.
+ * @property {import("./typedefs.js").Layout_Item[]} items
+ */
+
+/**
+ * The compiled data of a layout, kept apart from the public Layout
+ * (doc/design.md §3).
+ *
+ * @typedef {object} Compiled_Layout
+ * @property {Map<string, Layout_Entry>} entries
+ * @property {Layout_Entry[][]} tags_at_byte - The entries covering each byte.
+ */
+
+export {};

package/src/layout.js

@@ -0,0 +1,303 @@
+import { readFileSync } from "node:fs";
+import { parseDocument } from "yaml";
+import { CODECS } from "./codecs.js";
+import { register, registered_of, set_compiled } from "./registry.js";
+import { build_structure, validate_structure, TYPE_BITS } from "./structure.js";
+
+/** @import { Layout_Source, Registered_Layouts, Layout } from "./typedefs.js" */
+/** @import { Data_Struct } from "./internal_types.js" */
+
+/**
+ * The canonical text of a value: object keys sorted, `comment` left out (it
+ * does not change how a layout works) and the type names in lower case.
+ */
+function canonical(value, key) {
+	if (Array.isArray(value)) return `[${value.map((v) => canonical(v)).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const fields = Object.keys(value).filter((k) => k !== "comment" && value[k] !== undefined).sort();
+		return `{${fields.map((k) => `${JSON.stringify(k)}:${canonical(value[k], k)}`).join(",")}}`;
+	}
+	if (key === "type" && typeof value === "string") return JSON.stringify(value.toLowerCase());
+	return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * Compiles an expanded structure (the result of build_structure) into a Layout
+ * (doc/design.md §3) and registers it under its name, the one source of the
+ * layouts an Ldata is created from. Registering a structure whose canonical
+ * text equals the registered one of that name gives the registered Layout, so
+ * the same layout described twice is compiled once; another structure under a
+ * used name throws. Throws on an unknown type or a duplicated tag name; the
+ * other layout rules are checked by validate_structure. Internal.
+ *
+ * @param {Data_Struct} data_struct
+ * @returns {Layout}
+ * @throws {Error} When the name is used by another layout.
+ */
+export function register_structure(data_struct) {
+	const { name } = data_struct;
+	if (typeof name !== "string" || name === "") throw new Error("a layout needs a name");
+	const key = key_of(data_struct);
+	const known = registered_of(name);
+	if (known) {
+		if (known.key !== key) throw new Error(`another layout is already named ${name}`);
+		return known.layout;
+	}
+	const layout = compile_structure(data_struct);
+	register(name, { key, layout });
+	return layout;
+}
+
+function key_of(data_struct) {
+	return canonical({ name: data_struct.name, length: data_struct.length, items: data_struct.items });
+}
+
+function compile_structure(data_struct) {
+	const size = data_struct.length >> 3;
+	const entries = new Map();
+	const tags_at_byte = Array.from({ length: size }, () => []);
+	for (const item of data_struct.items) {
+		const { name, offset, init_value } = item;
+		const type = item.type.toLowerCase();
+		const codec = CODECS[type];
+		const fail = (message) => {
+			throw new Error(`${data_struct.name}.${name}: ${message}`);
+		};
+		if (!codec) fail(`unknown tag type ${item.type}`);
+		if (entries.has(name)) fail("duplicated tag name");
+		// defensive checks of what an Ldata relies on; validate_structure reports them all
+		if (type !== "bool" && offset % 8 !== 0) fail(`bit offset ${offset % 8} on a ${item.type}`);
+		if (codec.size > 1 && (offset >> 3) % 2 !== 0) fail(`${item.type} at the odd byte ${offset >> 3}`);
+		if (!["number", "boolean"].includes(typeof init_value)) fail(`init_value ${init_value} is not a number or boolean`);
+		const byte = offset >> 3;
+		const entry = {
+			name, type, init_value, byte,
+			index: entries.size,
+			size: codec.size,
+			mask: type === "bool" ? 1 << (offset % 8) : 0xff,
+			codec,
+		};
+		entries.set(name, entry);
+		// entries keep the item order: a combined word comes before its bits
+		for (let i = byte; i < byte + codec.size && i < size; i++) tags_at_byte[i].push(entry);
+	}
+
+	// the public layout holds the name, the sizes and frozen copies of the items;
+	// the entries and the lookup table stay out of reach (doc/spec-data-api.md §6.6)
+	const layout = Object.freeze({
+		name: data_struct.name,
+		length: data_struct.length,
+		size,
+		items: Object.freeze(data_struct.items.map(public_tag)),
+	});
+	set_compiled(layout, { entries, tags_at_byte });
+	return layout;
+}
+
+/**
+ * The frozen description of a tag of the public layout: the documented fields
+ * only, the length filled in from the type when the item has none.
+ */
+function public_tag(item) {
+	const tag = {
+		name: item.name,
+		type: item.type,
+		offset: item.offset,
+		length: item.length ?? TYPE_BITS[item.type.toLowerCase()],
+		init_value: item.init_value,
+	};
+	if (item.comment !== undefined) tag.comment = item.comment;
+	tag.coupling = Object.freeze([...(item.coupling ?? [])]);
+	return Object.freeze(tag);
+}
+
+/**
+ * Resolves the fragment references of a list of items: `coupling` and
+ * `includes` given as a fragment name are replaced by a copy of that
+ * fragment, recursively. Omitted lengths are filled in from the type.
+ */
+function resolve_items(list, fragments, stack, where, errors) {
+	if (!Array.isArray(list)) {
+		errors.push(`${where}: expected a list of items`);
+		return [];
+	}
+	const resolve_ref = (ref, field) => {
+		if (Array.isArray(ref)) return resolve_items(ref, fragments, stack, where, errors);
+		if (typeof ref !== "string") {
+			errors.push(`${where}: ${field} must be a fragment name or a list of items`);
+			return [];
+		}
+		if (stack.includes(ref)) {
+			errors.push(`${where}: circular fragment reference ${[...stack, ref].join(" -> ")}`);
+			return [];
+		}
+		if (!Object.hasOwn(fragments, ref)) {
+			errors.push(`${where}: unknown fragment ${ref}`);
+			return [];
+		}
+		return resolve_items(fragments[ref], fragments, [...stack, ref], `fragment ${ref}`, errors);
+	};
+	return list.map((_item) => {
+		const item = { ..._item };
+		if (item.coupling !== undefined) item.coupling = resolve_ref(item.coupling, "coupling");
+		if (item.includes !== undefined) item.includes = resolve_ref(item.includes, "includes");
+		const bits = TYPE_BITS[item.type?.toLowerCase()];
+		if (item.length === undefined && bits !== undefined) item.length = bits;
+		return item;
+	});
+}
+
+/**
+ * Reads the sources of the layouts (doc/design.md §3), merges their layouts
+ * and fragments into one description and registers it with
+ * register_layout_data. Each source is the path of a YAML layout file or a
+ * parsed description; a list of sources is merged, so a layout may name a
+ * fragment of any source whatever the order. The root key `layouts` of a
+ * source maps layout names to item lists; every other root key is a fragment
+ * referenced by name.
+ *
+ * @param {Layout_Source | Layout_Source[]} sources
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the sources are not valid.
+ */
+export function register_sources(sources) {
+	const errors = [];
+	const list = Array.isArray(sources) ? sources : [sources];
+	if (list.length === 0) errors.push("no source is given");
+	const origins = [];
+	const layout_defs = {};
+	const fragment_defs = {};
+	// the origin of each layout and fragment, to name both in a duplicate
+	const owners = { layout: new Map(), fragment: new Map() };
+	const add = (origin, root) => {
+		origins.push(origin);
+		if (root === null || typeof root !== "object" || Array.isArray(root)) {
+			errors.push(`${origin}: the root must be a mapping`);
+			return;
+		}
+		const { layouts, ...fragments } = root;
+		if (layouts !== undefined && (layouts === null || typeof layouts !== "object" || Array.isArray(layouts))) {
+			errors.push(`${origin}: the root key \`layouts\` must map layout names to item lists`);
+			return;
+		}
+		const merge = (kind, defs, into) => {
+			for (const [name, value] of Object.entries(defs)) {
+				if (owners[kind].has(name)) {
+					errors.push(`${kind} ${name} is defined in ${owners[kind].get(name)} and ${origin}`);
+					continue;
+				}
+				owners[kind].set(name, origin);
+				into[name] = value;
+			}
+		};
+		merge("layout", layouts ?? {}, layout_defs);
+		merge("fragment", fragments, fragment_defs);
+	};
+	list.forEach((source, index) => {
+		const label = Array.isArray(sources) ? `layout description #${index + 1}` : "layout description";
+		if (Array.isArray(source)) {
+			errors.push(`${label}: a list of sources must not contain a list`);
+		} else if (typeof source === "string") {
+			let text;
+			try {
+				text = readFileSync(source, "utf8");
+			} catch (error) {
+				errors.push(error.message);
+				return;
+			}
+			const doc = parseDocument(text, { version: "1.2" });
+			if (doc.errors.length > 0) errors.push(...doc.errors.map((e) => `${source}: ${e.message}`));
+			else add(source, doc.toJS());
+		} else {
+			add(label, source);
+		}
+	});
+	if (errors.length === 0 && Object.keys(layout_defs).length === 0) errors.push("no layout is defined in the sources");
+	if (errors.length > 0) throw layout_error("layout sources", errors);
+	return register_layout_data({ layouts: layout_defs, ...fragment_defs }, origins.join(", "));
+}
+
+/** Set once a call of register_layout has registered the layouts. */
+let registered_once = false;
+
+/**
+ * Registers the layouts of the sources, once per process: a layout is
+ * described, registered under its name, and then used by that name
+ * (doc/spec-data-api.md §6.4). Nothing is registered when a source is not
+ * valid, and such a call does not use up the single call.
+ *
+ * @param {Layout_Source | Layout_Source[]} sources - The path of a YAML layout file, a parsed description, or a list of them.
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the sources are not valid.
+ * @throws {Error} When the layouts were registered by an earlier call.
+ */
+export function register_layout(sources) {
+	if (registered_once) throw new Error("register_layout can be called only once");
+	const result = register_sources(sources);
+	registered_once = true;
+	return result;
+}
+
+function layout_error(subject, errors) {
+	const error = new Error(`invalid ${subject}:\n${errors.join("\n")}`);
+	error.errors = errors;
+	return error;
+}
+
+/**
+ * The conflicts of structures with the layouts registered under their names.
+ *
+ * @param {Record<string, Data_Struct>} structs - By layout name.
+ * @returns {string[]}
+ */
+function find_conflicts(structs) {
+	const conflicts = [];
+	for (const [name, struct] of Object.entries(structs)) {
+		const known = registered_of(name);
+		if (known && known.key !== key_of(struct)) conflicts.push(`layout ${name}: another layout is already named ${name}`);
+	}
+	return conflicts;
+}
+
+/**
+ * Registers the layouts of one description that is parsed and complete: the
+ * root key `layouts` and the fragments the layouts name. Internal.
+ *
+ * @param {Record<string, any>} root - The parsed description: `layouts` and the fragments.
+ * @param {string} [origin] - Names the source in errors.
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the description is not valid.
+ */
+export function register_layout_data(root, origin = "the given object") {
+	const fail = (errors) => {
+		throw layout_error(`layout description from ${origin}`, errors);
+	};
+	if (root === null || typeof root !== "object" || Array.isArray(root)) fail(["the root must be a mapping"]);
+	const { layouts: layout_defs, ...fragment_defs } = root;
+	if (layout_defs === null || typeof layout_defs !== "object" || Array.isArray(layout_defs)) {
+		fail(["the root key `layouts` must map layout names to item lists"]);
+	}
+
+	const errors = [];
+	const fragments = {};
+	for (const [name, list] of Object.entries(fragment_defs)) {
+		fragments[name] = resolve_items(list, fragment_defs, [name], `fragment ${name}`, errors);
+	}
+	const structs = {};
+	for (const [name, list] of Object.entries(layout_defs)) {
+		const items = resolve_items(list, fragment_defs, [], `layout ${name}`, errors);
+		structs[name] = build_structure({ name }, items);
+	}
+	if (errors.length === 0) {
+		for (const struct of Object.values(structs)) errors.push(...validate_structure(struct));
+	}
+	if (errors.length === 0) {
+		// all or none: a conflict is found before any of the layouts is registered
+		errors.push(...find_conflicts(structs));
+	}
+	if (errors.length > 0) fail(errors);
+
+	const layouts = {};
+	for (const [name, struct] of Object.entries(structs)) layouts[name] = register_structure(struct);
+	return { layouts, fragments };
+}