layout-data 0.2.0 → 0.3.0

package/src/structure.js

@@ -0,0 +1,238 @@
+// Expansion and validation of data block structures (doc/spec.md §3,
+// doc/design.md §3.1). Part of the data layer.
+import { FLOAT32_MAX } from "./codecs.js";
+import { is_reserved_name } from "./reserved.js";
+
+/** @import { Layout_Item } from "./typedefs.js" */
+/** @import { Data_Struct } from "./internal_types.js" */
+
+function add_item(data_struct, item, base_offset, name_prefix) {
+	const items = data_struct.items;
+	// every entry that is not a pure inclusion is a tag, whatever its name: duplicated
+	// and invalid names are kept and reported by validate_structure
+	if (item.includes === undefined || item.name !== undefined) items.push(item);
+	if (name_prefix && typeof item.name === "string") item.name = name_prefix + item.name;
+
+	item.offset = item.offset + base_offset;
+	const length = item.offset + item.length;
+	if (data_struct.length < length) data_struct.length = length;
+
+	const includes = item.includes;
+	if (includes && Array.isArray(includes)) {
+		for (const _item of includes) {
+			add_item(data_struct, { ..._item }, item.offset, item.name_prefix);
+		}
+		// The "includes" and "coupling" attributes can only be chosen one at a time.
+		return;
+	}
+
+	const coupling = [];
+	const _coupling = item.coupling;
+	if (_coupling && Array.isArray(_coupling)) {
+		for (const _cp of _coupling) {
+			const cp = { ..._cp };
+			add_item(data_struct, cp, item.offset, item.name_prefix);
+			cp.coupling ??= [];
+			cp.coupling.push(item.name);
+			coupling.push(cp);
+		}
+		share_init_value(item, coupling);
+	}
+	item.coupling = coupling.map((item) => item.name);
+}
+
+// Items whose init_value is given both on the word and on some of its bits,
+// with the names of those bits; reported by validate_structure.
+const init_conflicts = new WeakMap();
+
+/**
+ * Only one side of a combined word gives the init values (doc/spec.md §3):
+ * either the word, whose bits then take theirs from it, or the bits, from
+ * which the word is composed (a bit without init_value is false).
+ */
+function share_init_value(word, bits) {
+	const given = bits.filter((bit) => bit.init_value !== undefined);
+	if (word.init_value !== undefined && given.length > 0) {
+		// keep the given values (the bits are written after the word) and
+		// report the conflict; the other bits still take theirs from the word
+		init_conflicts.set(word, given.map((bit) => bit.name));
+	}
+	const size = word.length >> 3;
+	// big-endian word: byte k of the word holds bits (size - 1 - k) * 8 ..
+	// a bit outside the word has no value in it (reported by validate_structure)
+	const bit_value = (bit) => {
+		const relative = bit.offset - word.offset;
+		if (!(relative >= 0 && relative < word.length)) return 0;
+		return 2 ** ((size - 1 - (relative >> 3)) * 8 + relative % 8);
+	};
+	if (word.init_value === undefined) {
+		word.init_value = 0;
+		for (const bit of bits) {
+			bit.init_value ??= false;
+			if (bit.init_value === true) word.init_value += bit_value(bit);
+		}
+		return;
+	}
+	if (typeof word.init_value !== "number") return;
+	for (const bit of bits) {
+		if (bit.init_value !== undefined) continue;
+		const value = bit_value(bit);
+		bit.init_value = value > 0 && Math.floor(word.init_value / value) % 2 === 1;
+	}
+}
+
+/**
+ * Expands a list of items (resolving `includes` and `coupling`, making offsets
+ * absolute) into the given structure. Internal. It changes the items it is given.
+ *
+ * @param {{name: string}} data_struct - The structure to fill in; only the name is given.
+ * @param {Layout_Item[]} items
+ * @returns {Data_Struct} The same object, now complete.
+ */
+export function build_structure(data_struct, items) {
+	data_struct.length = 0;
+	data_struct.items = [];
+	if (!items) return data_struct;
+	for (const item of items) {
+		add_item(data_struct, item, 0);
+	}
+	return data_struct;
+}
+
+/**
+ * Bit length of each tag type (lower case names).
+ *
+ * @type {Record<string, number>}
+ */
+export const TYPE_BITS = {
+	bool: 1,
+	byte: 8, sint: 8, usint: 8,
+	int: 16, uint: 16, word: 16,
+	dint: 32, udint: 32, dword: 32, real: 32,
+};
+
+/**
+ * A tag name: letters, digits and `_`, not starting with a digit, an
+ * identifier in every language (doc/spec-data-api.md §6.2).
+ */
+const TAG_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// value range of each integer type
+const INTEGER_RANGES = {
+	byte: [0, 0xff], usint: [0, 0xff], sint: [-0x80, 0x7f],
+	int: [-0x8000, 0x7fff], uint: [0, 0xffff], word: [0, 0xffff],
+	dint: [-0x80000000, 0x7fffffff], udint: [0, 0xffffffff], dword: [0, 0xffffffff],
+};
+
+function check_init_value(item, type) {
+	const value = item.init_value;
+	if (type === "bool") return typeof value === "boolean";
+	if (typeof value !== "number") return false;
+	if (type === "real") return Number.isFinite(value) && Math.abs(value) <= FLOAT32_MAX;
+	const [min, max] = INTEGER_RANGES[type];
+	return Number.isInteger(value) && value >= min && value <= max;
+}
+
+/**
+ * Validates a structure built by build_structure against the layout rules
+ * (doc/spec.md §3, doc/design.md §3.1). Internal.
+ *
+ * @param {Data_Struct} data_struct
+ * @returns {string[]} descriptions of all violations, empty when the layout is valid
+ */
+export function validate_structure(data_struct) {
+	const errors = [];
+	const struct_name = data_struct.name;
+	const report = (item, message) => errors.push(`${struct_name}.${item.name}: ${message}`);
+	const items = data_struct.items;
+
+	// names
+	const by_name = new Map();
+	for (const item of items) {
+		if (by_name.has(item.name)) report(item, "duplicated name");
+		else by_name.set(item.name, item);
+		if (typeof item.name !== "string" || !TAG_NAME.test(item.name)) {
+			report(item, "name is not an identifier (letters, digits and \"_\", not starting with a digit)");
+		} else if (is_reserved_name(item.name)) {
+			report(item, "name is a reserved name");
+		}
+	}
+
+	// type, length, alignment and init_value
+	const valid_items = [];
+	for (const item of items) {
+		const type = item.type?.toLowerCase();
+		if (!(type in TYPE_BITS)) {
+			report(item, `unknown type ${item.type}`);
+			continue;
+		}
+		if (item.length !== TYPE_BITS[type]) {
+			report(item, `length ${item.length} does not match type ${item.type}`);
+		}
+		if (type !== "bool") {
+			if (item.offset % 8 !== 0) {
+				report(item, `offset ${item.offset} is not on a byte boundary`);
+			} else if (TYPE_BITS[type] > 8 && (item.offset >> 3) % 2 !== 0) {
+				report(item, `byte offset ${item.offset >> 3} is not even`);
+			}
+		}
+		const conflict = init_conflicts.get(item);
+		if (conflict) {
+			report(item, `init_value is given both on the word and on its bits ${conflict.join(", ")}`);
+		}
+		if (!check_init_value(item, type)) {
+			report(item, `init_value ${item.init_value} is not valid for type ${item.type}`);
+		}
+		valid_items.push({ item, type, end: item.offset + TYPE_BITS[type] });
+	}
+
+	// non-Bool tags must not overlap
+	const words = valid_items
+		.filter(({ type }) => type !== "bool")
+		.sort((a, b) => a.item.offset - b.item.offset);
+	let last = null;
+	for (const word of words) {
+		if (last && word.item.offset < last.end) {
+			report(word.item, `overlaps ${last.item.name}`);
+		}
+		if (!last || word.end > last.end) last = word;
+	}
+
+	// each bit belongs to at most one Bool, and a Bool inside a non-Bool tag
+	// must be one of its coupled bits
+	const bits = new Map();
+	for (const { item, type } of valid_items) {
+		if (type !== "bool") continue;
+		const other = bits.get(item.offset);
+		if (other) report(item, `shares bit ${item.offset} with ${other.name}`);
+		else bits.set(item.offset, item);
+		for (const word of words) {
+			if (item.offset < word.item.offset || item.offset >= word.end) continue;
+			if (!item.coupling?.includes(word.item.name)) {
+				report(item, `lies inside ${word.item.name} but is not one of its coupled bits`);
+			}
+		}
+	}
+
+	// coupled bits of a combined tag must lie inside it
+	for (const { item, type, end } of valid_items) {
+		if (type === "bool" || !item.coupling?.length) continue;
+		for (const bit_name of item.coupling) {
+			const bit = by_name.get(bit_name);
+			if (!bit) {
+				report(item, `coupled bit ${bit_name} does not exist`);
+			} else if (bit.type?.toLowerCase() !== "bool") {
+				report(item, `coupled tag ${bit_name} is not a Bool`);
+			} else if (bit.offset < item.offset || bit.offset >= end) {
+				report(item, `coupled bit ${bit_name} lies outside it`);
+			}
+		}
+	}
+
+	// whole registers
+	if (data_struct.length % 16 !== 0) {
+		errors.push(`${struct_name}: length ${data_struct.length} bits is not a whole number of registers`);
+	}
+
+	return errors;
+}

package/src/typedefs.js

@@ -0,0 +1,143 @@
+// Type definitions of the public interface. This file has no run-time content:
+// the JSDoc here is the source of the generated declaration file (dist/types).
+// The types of the internals are in internal_types.js and are not exported.
+
+/**
+ * An entry of a layout description that defines a tag (doc/spec-data-api.md §6.2).
+ *
+ * @typedef {object} Tag_Item
+ * @property {string} name - Tag name.
+ * @property {string} type - Tag type, case-insensitive (see Tag_Type).
+ * @property {number} offset - Bit offset, relative to the parent entry until expanded.
+ * @property {number} [length] - Length in bits, filled in from the type when omitted.
+ * @property {number | boolean} [init_value] - Initial value.
+ * @property {string} [comment] - Description, rendered into the generated types.
+ * @property {boolean} [is_combined] - Descriptive mark of a combined word; the linkage is decided by `coupling`.
+ * @property {Tag_Item[] | string} [coupling] - The bits of a combined word, as an inline list or the name of a fragment.
+ * @property {never} [includes] - A tag entry does not include entries.
+ */
+
+/**
+ * An entry of a layout description that splices in other entries (doc/spec-data-api.md §6.2).
+ *
+ * @typedef {object} Include_Item
+ * @property {Layout_Item[] | string} includes - The entries to include, as an inline list or the name of a fragment.
+ * @property {number} offset - Bit offset by which the included entries are shifted as a whole.
+ * @property {string} [name_prefix] - Prefix of the names of the included entries.
+ * @property {never} [name] - An inclusion defines no tag.
+ * @property {never} [type] - An inclusion defines no tag.
+ */
+
+/**
+ * One entry of a layout description, as written by the user in a layout file
+ * or given to register_layout (doc/spec-data-api.md §6).
+ *
+ * @typedef {Tag_Item | Include_Item} Layout_Item
+ */
+
+/**
+ * A layout description: `layouts` maps layout names to lists of entries, and
+ * every other key is a fragment, a list of entries that can be named
+ * (doc/spec-data-api.md §6.1).
+ *
+ * @typedef {{ layouts?: Record<string, Layout_Item[]> } & Record<string, Layout_Item[] | Record<string, Layout_Item[]> | undefined>} Layout_Description
+ */
+
+/**
+ * One tag of a compiled layout (doc/spec-data-api.md §6.6), read-only:
+ * `name`; `type`, as written in the description; `offset`, the absolute bit
+ * offset; `length` in bits; `init_value`; `comment`, if given; `coupling`,
+ * the tag names of the bits of a combined word, or of the combined words a
+ * bit belongs to.
+ *
+ * @typedef {Readonly<{
+ *   name: string,
+ *   type: string,
+ *   offset: number,
+ *   length: number,
+ *   init_value: number | boolean,
+ *   comment?: string,
+ *   coupling: readonly string[],
+ * }>} Layout_Tag
+ */
+
+/**
+ * A compiled layout (doc/spec-data-api.md §6.6), read-only and deeply frozen:
+ * `name`; `length` in bits; `size` in bytes; `items`, the tags in layout
+ * order (a combined word before its bits).
+ *
+ * @typedef {Readonly<{
+ *   name: string,
+ *   length: number,
+ *   size: number,
+ *   items: readonly Layout_Tag[],
+ * }>} Layout
+ */
+
+/**
+ * Device byte order of an IO buffer (doc/spec-data-api.md §2.9).
+ *
+ * @typedef {"BE" | "LE" | "BEBS" | "LEBS"} Endian
+ */
+
+/**
+ * A source of layouts: the path of a YAML 1.2 layout file, or a description
+ * that is already parsed (the same structure as the file, doc/spec-data-api.md §6.1).
+ *
+ * @typedef {string | Layout_Description} Layout_Source
+ */
+
+/**
+ * The result of registering a layout description.
+ *
+ * @typedef {object} Registered_Layouts
+ * @property {Record<string, Layout>} layouts
+ * @property {Record<string, Layout_Item[]>} fragments
+ */
+
+/**
+ * Type of a tag, in lower case: the type of `Ltag.type` (doc/spec-data-api.md §1).
+ *
+ * @typedef {"bool" | "byte" | "usint" | "sint" | "int" | "uint" | "word" | "dint" | "udint" | "dword" | "real"} Tag_Type
+ */
+
+/**
+ * The listeners of the events of an Ldata that the library emits.
+ *
+ * @typedef {object} Data_Events
+ * @property {(name: string, old_value: number | boolean, new_value: number | boolean) => void} change
+ * @property {(data: import("./Ldata.js").Ldata) => void} write
+ * @property {(kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void} access
+ */
+
+/**
+ * A class-level access listener: called for the accesses to every Ldata
+ * (doc/spec-data-api.md §2.8).
+ *
+ * @typedef {(data: import("./Ldata.js").Ldata, kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void} Class_Access_Listener
+ */
+
+/**
+ * The listener of an event of an Ldata: typed for `change` and `write`, any
+ * listener for another name (doc/spec-data-api.md §2.7).
+ *
+ * @template {string | symbol} E
+ * @typedef {E extends keyof Data_Events ? Data_Events[E] : (...args: any[]) => void} Data_Listener
+ */
+
+/**
+ * The listeners of the events of an Ltag that the library emits.
+ *
+ * @typedef {object} Tag_Events
+ * @property {(old_value: number | boolean, new_value: number | boolean) => void} change
+ */
+
+/**
+ * The listener of an event of an Ltag: typed for `change`, any listener for
+ * another name (doc/spec-data-api.md §3).
+ *
+ * @template {string | symbol} E
+ * @typedef {E extends keyof Tag_Events ? Tag_Events[E] : (...args: any[]) => void} Tag_Listener
+ */
+
+export {};

package/src/types.js

@@ -0,0 +1,74 @@
+// Renders TypeScript declarations of registered layouts, for editor completion
+// of the tag accessors (doc/spec-data-api.md §6.7, doc/design.md §4).
+
+/** A name that can be part of a type name: an identifier of JavaScript, in any script. */
+const IDENTIFIER = /^[\p{ID_Start}_$][\p{ID_Continue}$‌‍]*$/u;
+
+/**
+ * Renders a text as a doc comment, one line or several, with the `*` and `/`
+ * pair that would end the comment early escaped.
+ *
+ * @param {string} text
+ * @param {string} indent
+ * @returns {string[]}
+ */
+function doc_comment(text, indent) {
+	const lines = String(text).replaceAll("*/", "*\\/").split(/\r?\n/);
+	if (lines.length === 1) return [`${indent}/** ${lines[0]} */`];
+	return [`${indent}/**`, ...lines.map((line) => `${indent} * ${line}`.trimEnd()), `${indent} */`];
+}
+
+/**
+ * Renders a declaration file with, for each layout, an interface of its tags
+ * (`<Layout>_Tags`, one property per tag) and the type of its data block
+ * (`<Layout>_Ldata`). The layout name is used as it is, with the case it has,
+ * so that the type names are those of `new Ldata("<Layout>", ...)` and layouts
+ * with different names never get the same type name.
+ *
+ * In JavaScript a JSDoc cast names the type of the value, which an editor
+ * uses for completion and, with `checkJs`, to check the tags:
+ *
+ * ```js
+ * const pump = /** @type {import("./layout_types.js").Pump_Ldata} *\/ (new Ldata("Pump", "pump_1"));
+ * ```
+ *
+ * @param {Record<string, import("./typedefs.js").Layout>} layouts - Registered layouts by name.
+ * @param {object} [options]
+ * @param {string} [options.source] - The layout file, named in the header; the header names none when it is omitted.
+ * @param {string} [options.ldata_module] - Module specifier of Ldata, relative to the output file; "layout-data" by default.
+ * @returns {string}
+ * @throws {Error} With `errors`, when the name of a layout is not an identifier, which a type name needs.
+ */
+export function render_types(layouts, { source, ldata_module = "layout-data" } = {}) {
+	const names = Object.keys(layouts);
+	const errors = names
+		.filter((name) => !IDENTIFIER.test(name))
+		.map((name) => `layout ${JSON.stringify(name)}: the name is not an identifier, so it cannot be part of a type name`);
+	if (errors.length > 0) {
+		const error = new Error(`cannot render the types of the layouts:\n${errors.join("\n")}`);
+		error.errors = errors;
+		throw error;
+	}
+
+	const lines = [
+		source === undefined ? "// Generated by render_types. Do not edit." : `// Generated from ${source}. Do not edit.`,
+		`import type { Ldata } from ${JSON.stringify(ldata_module)};`,
+	];
+	if (names.length > 0) {
+		lines.push(
+			"//",
+			"// In JavaScript, a JSDoc cast names the type of the value:",
+			`//   const data = /** @type {import("<this file>").${names[0]}_Ldata} */ (new Ldata("${names[0]}", "data_1"));`,
+		);
+	}
+	for (const [name, layout] of Object.entries(layouts)) {
+		lines.push("", `/** Tags of the ${name} data block. */`, `export interface ${name}_Tags {`);
+		for (const item of layout.items) {
+			if (item.comment) lines.push(...doc_comment(item.comment, "\t"));
+			const ts_type = item.type.toLowerCase() === "bool" ? "boolean" : "number";
+			lines.push(`\t${item.name}: ${ts_type};`);
+		}
+		lines.push("}", "", `/** A ${name} data block, with its tags as properties. */`, `export type ${name}_Ldata = Ldata & ${name}_Tags;`);
+	}
+	return `${lines.join("\n")}\n`;
+}