@gtkx/codegen 0.21.0

package/src/writers/boxed-field-accessor.ts

@@ -0,0 +1,306 @@
+import { toCamelCase, toIdentifier } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirField } from "../gir/field.js";
+import type { FieldSlot } from "../gir/size.js";
+import type { GirTypeRef } from "../gir/type-ref.js";
+import { type BoxedFieldSlot, computeBoxedFieldSlots } from "./boxed-layout.js";
+import { typeRefIsClassStruct } from "./class-struct-record.js";
+import { wrapReturnValue } from "./return-wrap.js";
+import { renderTsType } from "./ts-type.js";
+import { renderFfiType } from "./value.js";
+
+/**
+ * Renders the `get` / `set` accessor pair for a single boxed field.
+ *
+ * The accessor reads through the runtime's `read(handle, ffiType, offset)`
+ * (or `write` for the setter), with bitfield members threading through a
+ * read-modify-write sequence into their shared storage word. Fields whose
+ * type cannot be marshaled at present (callbacks, varargs, inline arrays
+ * of complex types) are skipped silently.
+ *
+ * @param context - The module context
+ * @param slot - The field plus its layout slot
+ * @param claimedNames - Names already used by emitted methods
+ */
+export const renderBoxedFieldAccessor = (
+    context: ModuleContext,
+    slot: BoxedFieldSlot,
+    claimedNames: ReadonlySet<string>,
+    siblingFields: readonly GirField[],
+): string | undefined => {
+    const { field } = slot;
+    if (field.private) return undefined;
+    if (!field.readable && !field.writable) return undefined;
+    if (field.callback !== undefined) return undefined;
+    if (field.type === undefined) return undefined;
+    if (typeRefIsClassStruct(context, field.type)) return undefined;
+    const jsName = toIdentifier(toCamelCase(field.name));
+    if (claimedNames.has(jsName)) return undefined;
+    if (jsName === "constructor") return undefined;
+
+    const structArray = renderStructArrayAccessor(context, { field, jsName, slot: slot.slot, siblingFields });
+    if (structArray !== undefined) return structArray;
+
+    if (!isAccessorEligibleType(field.type)) {
+        const tsType = renderTsType(context, field.type, false);
+        const modifier = field.writable ? "declare" : "declare readonly";
+        return `${modifier} ${jsName}: ${tsType};`;
+    }
+
+    const ffiType = renderFfiType(context, field.type, "none");
+    const tsType = renderTsType(context, field.type, false);
+    const accessorOptions: AccessorOptions = {
+        context,
+        jsName,
+        tsType,
+        ffiType,
+        slot: slot.slot,
+        fieldType: field.type,
+    };
+    const blocks: string[] = [getterBlock(accessorOptions)];
+    if (field.writable) {
+        blocks.push(setterBlock(accessorOptions));
+    }
+    return blocks.join("\n\n");
+};
+
+const isAccessorEligibleType = (ref: GirTypeRef): boolean => {
+    switch (ref.kind) {
+        case "primitive":
+            return ref.category !== "void" && ref.category !== "unichar";
+        case "named":
+            return true;
+        case "array":
+            return ref.fixedSize !== undefined;
+        case "list":
+        case "hashtable":
+            return false;
+        case "callback":
+        case "varargs":
+            return false;
+    }
+};
+
+const resolveInlineStructFields = (
+    context: ModuleContext,
+    ref: GirTypeRef | undefined,
+): readonly GirField[] | undefined => {
+    if (ref === undefined || ref.kind !== "named") return undefined;
+    if (ref.cType?.endsWith("*") === true) return undefined;
+    const resolved = context.repository.resolveNamed(ref.namespaceName ?? context.namespace.name, ref.typeName);
+    if (resolved === undefined || resolved.kind !== "boxed") return undefined;
+    if (resolved.value.cType?.endsWith("*") === true) return undefined;
+    if (resolved.value.fields.length === 0) return undefined;
+    return resolved.value.fields;
+};
+
+const arrayLengthExpression = (
+    arrayRef: Extract<GirTypeRef, { kind: "array" }>,
+    siblingFields: readonly GirField[],
+): string | undefined => {
+    if (arrayRef.fixedSize !== undefined) return String(arrayRef.fixedSize);
+    if (arrayRef.lengthParameterIndex === undefined) return undefined;
+    const lengthField = siblingFields.filter((field) => !field.private)[arrayRef.lengthParameterIndex];
+    if (lengthField === undefined) return undefined;
+    return `this.${toIdentifier(toCamelCase(lengthField.name))}`;
+};
+
+const renderElementReadObject = (context: ModuleContext, fields: readonly GirField[], baseOffset: number): string => {
+    const { slots } = computeBoxedFieldSlots(context, fields);
+    const entries: string[] = [];
+    for (const { field, slot } of slots) {
+        if (field.private || field.type === undefined || field.callback !== undefined) continue;
+        const jsName = toIdentifier(toCamelCase(field.name));
+        const offset = baseOffset + slot.byteOffset;
+        const nested = resolveInlineStructFields(context, field.type);
+        if (nested !== undefined) {
+            entries.push(`${jsName}: ${renderElementReadObject(context, nested, offset)}`);
+            continue;
+        }
+        if (!isAccessorEligibleType(field.type)) continue;
+        const ffi = renderFfiType(context, field.type, "none");
+        if (slot.bitWidth === undefined) {
+            entries.push(
+                `${jsName}: read(__array, ${ffi}, __base + ${offset}) as ${renderTsType(context, field.type, false)}`,
+            );
+            continue;
+        }
+        const shift = slot.bitOffset ?? 0;
+        entries.push(
+            `${jsName}: (((read(__array, ${ffi}, __base + ${offset}) as number) >>> ${shift}) & ${bitMask(slot.bitWidth)})`,
+        );
+    }
+    return `{ ${entries.join(", ")} }`;
+};
+
+type ElementWriteOptions = {
+    readonly fields: readonly GirField[];
+    readonly baseOffset: number;
+    readonly valuePath: string;
+    readonly out: string[];
+};
+
+const appendElementWriteStatements = (context: ModuleContext, options: ElementWriteOptions): void => {
+    const { fields, baseOffset, valuePath, out } = options;
+    const { slots } = computeBoxedFieldSlots(context, fields);
+    for (const { field, slot } of slots) {
+        if (field.private || field.type === undefined || field.callback !== undefined) continue;
+        const valueExpr = `${valuePath}.${toIdentifier(toCamelCase(field.name))}`;
+        const offset = baseOffset + slot.byteOffset;
+        const nested = resolveInlineStructFields(context, field.type);
+        if (nested !== undefined) {
+            appendElementWriteStatements(context, { fields: nested, baseOffset: offset, valuePath: valueExpr, out });
+            continue;
+        }
+        if (!isAccessorEligibleType(field.type)) continue;
+        const ffi = renderFfiType(context, field.type, "none");
+        if (slot.bitWidth === undefined) {
+            out.push(`write(__array, ${ffi}, __base + ${offset}, ${valueExpr});`);
+            continue;
+        }
+        const mask = bitMask(slot.bitWidth);
+        const shift = slot.bitOffset ?? 0;
+        out.push(
+            `write(__array, ${ffi}, __base + ${offset}, ((read(__array, ${ffi}, __base + ${offset}) & ~(${mask} << ${shift})) | ((Number(${valueExpr}) & ${mask}) << ${shift})) >>> 0);`,
+        );
+    }
+};
+
+type StructArrayTarget = {
+    readonly field: GirField;
+    readonly jsName: string;
+    readonly slot: FieldSlot;
+    readonly siblingFields: readonly GirField[];
+};
+
+type StructArrayAccessorOptions = {
+    readonly context: ModuleContext;
+    readonly jsName: string;
+    readonly tsType: string;
+    readonly bufferType: string;
+    readonly offset: number;
+    readonly lengthExpr: string;
+    readonly elementSize: number;
+    readonly elementFields: readonly GirField[];
+};
+
+const structArrayGetterBlock = (options: StructArrayAccessorOptions): string => {
+    const { context, jsName, tsType, bufferType, offset, lengthExpr, elementSize, elementFields } = options;
+    const element = renderElementReadObject(context, elementFields, 0);
+    const loop = [`const __base = __index * ${elementSize};`, `__result.push(${element});`].join("\n");
+    const body = [
+        `const __array = read(getHandle(this), ${bufferType}, ${offset});`,
+        `const __result: ${tsType} = [];`,
+        `for (let __index = 0; __index < ${lengthExpr}; __index++) {`,
+        indent(loop, 1),
+        "}",
+        "return __result;",
+    ].join("\n");
+    return `get ${jsName}(): ${tsType} {\n${indent(body, 1)}\n}`;
+};
+
+const structArraySetterBlock = (options: StructArrayAccessorOptions): string => {
+    const { context, jsName, tsType, bufferType, offset, elementSize, elementFields } = options;
+    const writes: string[] = [];
+    appendElementWriteStatements(context, {
+        fields: elementFields,
+        baseOffset: 0,
+        valuePath: "__element",
+        out: writes,
+    });
+    const loop = [`const __element = __value[__index];`, `const __base = __index * ${elementSize};`, ...writes].join(
+        "\n",
+    );
+    const body = [
+        `const __array = read(getHandle(this), ${bufferType}, ${offset});`,
+        `for (let __index = 0; __index < __value.length; __index++) {`,
+        indent(loop, 1),
+        "}",
+        `write(getHandle(this), ${bufferType}, ${offset}, __array);`,
+    ].join("\n");
+    return `set ${jsName}(__value: ${tsType}) {\n${indent(body, 1)}\n}`;
+};
+
+const renderStructArrayAccessor = (context: ModuleContext, target: StructArrayTarget): string | undefined => {
+    const { field, jsName, slot, siblingFields } = target;
+    const arrayRef = field.type;
+    if (arrayRef === undefined || arrayRef.kind !== "array" || slot.bitWidth !== undefined) return undefined;
+    const elementFields = resolveInlineStructFields(context, arrayRef.element);
+    if (elementFields === undefined) return undefined;
+    const lengthExpr = arrayLengthExpression(arrayRef, siblingFields);
+    if (lengthExpr === undefined) return undefined;
+    const elementSize = computeBoxedFieldSlots(context, elementFields).size;
+    if (elementSize === 0) return undefined;
+
+    context.addNativeImport("read");
+    context.addRuntimeImport("getHandle");
+    context.addRuntimeImport("t");
+    const options: StructArrayAccessorOptions = {
+        context,
+        jsName,
+        tsType: renderTsType(context, arrayRef, false),
+        bufferType: `t.struct("borrowed", ${lengthExpr} * ${elementSize})`,
+        offset: slot.byteOffset,
+        lengthExpr,
+        elementSize,
+        elementFields,
+    };
+    const blocks: string[] = [];
+    if (field.readable) blocks.push(structArrayGetterBlock(options));
+    if (field.writable) {
+        context.addNativeImport("write");
+        blocks.push(structArraySetterBlock(options));
+    }
+    return blocks.length === 0 ? undefined : blocks.join("\n\n");
+};
+
+type AccessorOptions = {
+    readonly context: ModuleContext;
+    readonly jsName: string;
+    readonly tsType: string;
+    readonly ffiType: string;
+    readonly slot: FieldSlot;
+    readonly fieldType: GirTypeRef;
+};
+
+const getterBlock = (options: AccessorOptions): string => {
+    const { context, jsName, tsType, ffiType, slot, fieldType } = options;
+    context.addNativeImport("read");
+    context.addRuntimeImport("getHandle");
+    if (slot.bitWidth === undefined) {
+        const valueExpression = `read(getHandle(this), ${ffiType}, ${slot.byteOffset})`;
+        const wrapped = wrapReturnValue(context, {
+            ref: fieldType,
+            transfer: "none",
+            nullable: false,
+            valueExpression,
+        });
+        const body = `return ${wrapped};`;
+        return `get ${jsName}(): ${tsType} {\n${indent(body, 1)}\n}`;
+    }
+    const mask = bitMask(slot.bitWidth);
+    const shift = slot.bitOffset ?? 0;
+    const body = `const __unit = read(getHandle(this), ${ffiType}, ${slot.byteOffset}) as number;\nreturn (((__unit >>> ${shift}) & ${mask}) >>> 0) as ${tsType};`;
+    return `get ${jsName}(): ${tsType} {\n${indent(body, 1)}\n}`;
+};
+
+const setterBlock = (options: AccessorOptions): string => {
+    const { context, jsName, tsType, ffiType, slot } = options;
+    context.addNativeImport("write");
+    context.addRuntimeImport("getHandle");
+    if (slot.bitWidth === undefined) {
+        const body = `write(getHandle(this), ${ffiType}, ${slot.byteOffset}, value);`;
+        return `set ${jsName}(value: ${tsType}) {\n${indent(body, 1)}\n}`;
+    }
+    context.addNativeImport("read");
+    const mask = bitMask(slot.bitWidth);
+    const shift = slot.bitOffset ?? 0;
+    const body = `const __unit = read(getHandle(this), ${ffiType}, ${slot.byteOffset}) as number;\nconst __next = ((__unit & ~(${mask} << ${shift})) | ((Number(value) & ${mask}) << ${shift})) >>> 0;\nwrite(getHandle(this), ${ffiType}, ${slot.byteOffset}, __next);`;
+    return `set ${jsName}(value: ${tsType}) {\n${indent(body, 1)}\n}`;
+};
+
+const bitMask = (width: number): number => {
+    if (width >= 32) return 0xffffffff;
+    return (1 << width) - 1;
+};

package/src/writers/boxed-layout.ts

@@ -0,0 +1,166 @@
+import type { ModuleContext } from "../dsl/context.js";
+import type { GirField } from "../gir/field.js";
+import { primitiveCategory } from "../gir/primitives.js";
+import type { ResolvedNamed } from "../gir/repository.js";
+import {
+    computeFieldSlots,
+    type FieldLayout,
+    type FieldLayoutInput,
+    type FieldSlot,
+    layoutOfPrimitive,
+} from "../gir/size.js";
+import type { GirTypeRef, NamedTypeRef } from "../gir/type-ref.js";
+
+const POINTER_LAYOUT: FieldLayout = { size: 8, align: 8 };
+
+/**
+ * Computed slot for a single boxed field, ready for accessor emission.
+ */
+export type BoxedFieldSlot = {
+    readonly field: GirField;
+    readonly slot: FieldSlot;
+};
+
+/**
+ * Computes per-field storage slots for a boxed record.
+ *
+ * Walks every field (private fields included so their storage occupies
+ * space) and resolves each to a primitive-size {@link FieldLayoutInput}.
+ * Private fields are returned with their slots so callers can filter on
+ * `field.private` while still seeing the layout-correct offsets of public
+ * fields after them.
+ *
+ * @param context - The module context
+ * @param fields - The boxed's field list in declaration order
+ */
+export const computeBoxedFieldSlots = (
+    context: ModuleContext,
+    fields: readonly GirField[],
+    isUnion = false,
+): { readonly slots: readonly BoxedFieldSlot[]; readonly size: number } => {
+    const inputs: FieldLayoutInput[] = [];
+    for (const field of fields) {
+        inputs.push(fieldLayoutInput(context, field, new Set()));
+    }
+    const result = computeFieldSlots(inputs, isUnion);
+    const slots = result.slots.map((slot, index) => {
+        const field = fields[index];
+        if (field === undefined) {
+            throw new Error("computeBoxedFieldSlots: parallel arrays diverged");
+        }
+        return { field, slot };
+    });
+    return { slots, size: result.size };
+};
+
+const fieldLayoutInput = (context: ModuleContext, field: GirField, visited: ReadonlySet<string>): FieldLayoutInput => {
+    if (field.callback !== undefined) {
+        return { layout: POINTER_LAYOUT, bits: undefined };
+    }
+    if (field.type === undefined) {
+        return { layout: POINTER_LAYOUT, bits: undefined };
+    }
+    return { layout: layoutOfType(context, field.type, visited), bits: field.bits };
+};
+
+const layoutOfType = (context: ModuleContext, ref: GirTypeRef, visited: ReadonlySet<string>): FieldLayout => {
+    switch (ref.kind) {
+        case "primitive":
+            return layoutOfPrimitive(ref.category);
+        case "named":
+            return layoutOfNamed(context, ref, visited);
+        case "array":
+            return arrayLayout(context, ref, visited);
+        case "list":
+        case "hashtable":
+        case "callback":
+        case "varargs":
+            return POINTER_LAYOUT;
+    }
+};
+
+const arrayLayout = (
+    context: ModuleContext,
+    ref: Extract<GirTypeRef, { kind: "array" }>,
+    visited: ReadonlySet<string>,
+): FieldLayout => {
+    if (ref.fixedSize === undefined) return POINTER_LAYOUT;
+    const elementLayout = layoutOfType(context, ref.element, visited);
+    return { size: elementLayout.size * ref.fixedSize, align: elementLayout.align };
+};
+
+const layoutOfNamed = (context: ModuleContext, ref: NamedTypeRef, visited: ReadonlySet<string>): FieldLayout => {
+    if (ref.cType?.endsWith("*") === true) return POINTER_LAYOUT;
+    const namespaceName = ref.namespaceName ?? context.namespace.name;
+    const resolved = context.repository.resolveNamed(namespaceName, ref.typeName);
+    if (resolved === undefined) return POINTER_LAYOUT;
+    return layoutOfResolved(context, resolved, visited);
+};
+
+const layoutOfResolved = (
+    context: ModuleContext,
+    resolved: ResolvedNamed,
+    visited: ReadonlySet<string>,
+): FieldLayout => {
+    switch (resolved.kind) {
+        case "class":
+        case "interface":
+            return POINTER_LAYOUT;
+        case "boxed":
+            return layoutOfBoxedRecord(context, resolved, visited);
+        case "enum":
+            return layoutOfPrimitive("int32");
+        case "callback":
+            return POINTER_LAYOUT;
+        case "alias":
+            return resolveAliasLayout(context, resolved, visited);
+    }
+};
+
+const layoutOfBoxedRecord = (
+    context: ModuleContext,
+    resolved: Extract<ResolvedNamed, { kind: "boxed" }>,
+    visited: ReadonlySet<string>,
+): FieldLayout => {
+    if (resolved.value.cType?.endsWith("*") === true) return POINTER_LAYOUT;
+    const key = `${resolved.namespace.name}.${resolved.value.name}`;
+    if (visited.has(key)) return POINTER_LAYOUT;
+    const cached = recordLayoutCache.get(key);
+    if (cached !== undefined) return cached;
+    const nextVisited = new Set(visited);
+    nextVisited.add(key);
+    const inputs: FieldLayoutInput[] = [];
+    for (const field of resolved.value.fields) {
+        if (field.callback !== undefined) {
+            inputs.push({ layout: POINTER_LAYOUT, bits: undefined });
+            continue;
+        }
+        if (field.type === undefined) {
+            inputs.push({ layout: POINTER_LAYOUT, bits: undefined });
+            continue;
+        }
+        inputs.push({ layout: layoutOfType(context, field.type, nextVisited), bits: field.bits });
+    }
+    if (inputs.length === 0) return POINTER_LAYOUT;
+    const { size } = computeFieldSlots(inputs, resolved.value.isUnion);
+    const align = Math.max(1, ...inputs.map((input) => input.layout.align));
+    const layout: FieldLayout = { size, align };
+    recordLayoutCache.set(key, layout);
+    return layout;
+};
+
+const recordLayoutCache = new Map<string, FieldLayout>();
+
+const resolveAliasLayout = (
+    context: ModuleContext,
+    resolved: Extract<ResolvedNamed, { kind: "alias" }>,
+    visited: ReadonlySet<string>,
+): FieldLayout => {
+    const ref = resolved.targetRef;
+    if (ref === undefined) return POINTER_LAYOUT;
+    if (ref.kind === "named") {
+        const primitive = primitiveCategory(ref.typeName);
+        if (primitive !== undefined) return layoutOfPrimitive(primitive);
+    }
+    return layoutOfType(context, ref, visited);
+};

package/src/writers/boxed.ts

@@ -0,0 +1,77 @@
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirBoxed } from "../gir/boxed.js";
+import { renderBoxedConstructor, renderBoxedConstructorPropsInterface } from "./boxed-constructor.js";
+import { renderBoxedFieldAccessor } from "./boxed-field-accessor.js";
+import { computeBoxedFieldSlots } from "./boxed-layout.js";
+import { type Callables, dedupeCallables, emitBindings, renderPlainTypeMembers } from "./callables.js";
+import { isClassStructRecord } from "./class-struct-record.js";
+import { renderGetTypeReference } from "./gtype-binding.js";
+import { appendNativeClassRegistration } from "./registration.js";
+
+/**
+ * Emits a class declaration plus optional boxed registration for a
+ * `<record>`, `<union>`, or `<glib:boxed>`.
+ *
+ * Walks constructors, static functions, and methods just like
+ * {@link emitClass}, attaching them to the boxed class. Field accessors
+ * and construction metadata are emitted by their dedicated writers.
+ *
+ * Vtable records (`glib:is-gtype-struct-for`) are skipped here — they are
+ * consumed by the owning class's vtable registration. Class- and
+ * interface-struct records (`GTypeClass`, `GEnumClass`, …) are likewise skipped
+ * as they are runtime vtables rather than marshallable values.
+ *
+ * @param context - The module context
+ * @param boxed - The boxed to emit
+ */
+export const emitBoxed = (context: ModuleContext, boxed: GirBoxed): void => {
+    if (!boxed.introspectable) return;
+    if (boxed.kind === "vtable") return;
+    if (boxed.name.length === 0) return;
+    if (isClassStructRecord(context.namespace.name, boxed)) return;
+    const className = boxed.name;
+    const callables: Callables = {
+        constructors: dedupeCallables(boxed.constructors),
+        functions: dedupeCallables(boxed.functions),
+        methods: dedupeCallables(boxed.methods),
+    };
+    emitBindings(context, callables);
+
+    const members = renderBoxedMembers(context, boxed, className, callables);
+    const body = members.map((member) => indent(member, 1)).join("\n\n");
+    context.module.appendDeclaration(`export class ${className} {\n${body}\n}`);
+    context.module.appendDeclaration(renderBoxedConstructorPropsInterface(context, boxed, className));
+
+    const getTypeRef =
+        boxed.glibGetType === undefined
+            ? undefined
+            : renderGetTypeReference(context, boxed.glibGetType, boxed.glibTypeName);
+    appendNativeClassRegistration(context, {
+        className,
+        role: "boxed",
+        getTypeRef,
+    });
+};
+
+const renderBoxedMembers = (
+    context: ModuleContext,
+    boxed: GirBoxed,
+    className: string,
+    callables: Callables,
+): readonly string[] => {
+    const { members, claimedNames } = renderPlainTypeMembers({
+        context,
+        className,
+        callables,
+        hasGType: boxed.glibGetType !== undefined,
+        wrap: "boxed",
+    });
+    members.unshift(renderBoxedConstructor(context, boxed, className));
+    const { slots } = computeBoxedFieldSlots(context, boxed.fields, boxed.isUnion);
+    for (const slot of slots) {
+        const block = renderBoxedFieldAccessor(context, slot, claimedNames, boxed.fields);
+        if (block !== undefined) members.push(block);
+    }
+    return members;
+};