@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/gi/record-layout.ts

@@ -0,0 +1,221 @@
+import type { GirField } from "../../gir/field.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { EntityType, GirType } from "../../gir/type.js";
+import type { ModuleContext } from "../../writer/context.js";
+import {
+    computeFieldSlots,
+    type FieldLayout,
+    type FieldLayoutInput,
+    type FieldSlot,
+    layoutOfPrimitive,
+} from "../../gir/size.js";
+
+type ResolvedRecordValue = Extract<EntityType, { kind: "record" }>["value"];
+
+type RecordFieldSlot = {
+    field: GirField;
+    slot: FieldSlot;
+};
+
+const POINTER_LAYOUT: FieldLayout = { size: 8, align: 8 };
+const recordLayoutCache: Map<string, FieldLayout> = new Map();
+
+// GIR carries no alignment attribute, and a type whose alignment exceeds its widest member cannot be
+// derived from the field list: Graphene models `graphene_simd4f_t` as four `gfloat`, which computes
+// to align 4 while the real type is a 16-byte SIMD vector. Keying the override on `c:type` keeps it
+// to the handful of types where the XML genuinely cannot express the ABI.
+const ALIGNMENT_OVERRIDES: Map<string, FieldLayout> = new Map([
+    ["graphene_simd4f_t", { size: 16, align: 16 }],
+    ["graphene_simd4x4f_t", { size: 64, align: 16 }],
+]);
+
+const computeRecordFieldSlots = (
+    context: ModuleContext,
+    fields: GirField[],
+    isUnion = false,
+): { slots: RecordFieldSlot[]; size: number } => {
+    const inputs: FieldLayoutInput[] = Array.from(fields, (field) => 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("computeRecordFieldSlots: parallel arrays diverged");
+        }
+
+        return { field, slot };
+    });
+
+    return { slots, size: result.size };
+};
+
+const bitMask = (width: number): number => {
+    if (width >= 32) {
+        return 0xFF_FF_FF_FF;
+    }
+
+    return (1 << width) - 1;
+};
+
+const mergeBitfield = (readExpr: string, valueExpr: string, mask: number, shift: number): string => {
+    const maskExpr = String(mask);
+    const shiftExpr = String(shift);
+
+    return (
+        `((${readExpr} & ~(${maskExpr} << ${shiftExpr})) | ` +
+        `((Number(${valueExpr}) & ${maskExpr}) << ${shiftExpr})) >>> 0`
+    );
+};
+
+const fieldLayoutInput = (context: ModuleContext, field: GirField, visited: Set<string>): FieldLayoutInput => {
+    if (field.inlineMembers !== undefined) {
+        const layout = inlineMemberLayout(context, field.inlineMembers, field.inlineIsUnion, visited);
+
+        return { layout, bits: undefined };
+    }
+
+    if (field.type === undefined) {
+        return { layout: POINTER_LAYOUT, bits: undefined };
+    }
+
+    return { layout: layoutOfType(context, field.type, field.cType, visited), bits: field.bits };
+};
+
+const inlineMemberLayout = (
+    context: ModuleContext,
+    members: GirField[],
+    isUnion: boolean,
+    visited: Set<string>,
+): FieldLayout => {
+    const inputs = Array.from(members, (member) => fieldLayoutInput(context, member, visited));
+
+    if (inputs.length === 0) {
+        return { size: 0, align: 1 };
+    }
+
+    const { size } = computeFieldSlots(inputs, isUnion);
+
+    return { size, align: Math.max(1, ...inputs.map((input) => input.layout.align)) };
+};
+
+const pointerOr = (occurrenceCType: string | undefined, otherwise: () => FieldLayout): FieldLayout =>
+    occurrenceCType?.endsWith("*") === true ? POINTER_LAYOUT : otherwise();
+
+const layoutOfType = (
+    context: ModuleContext,
+    ref: TypeId,
+    occurrenceCType: string | undefined,
+    visited: Set<string>,
+): FieldLayout => {
+    const type = context.library.typeFor(ref);
+
+    if (type === undefined) {
+        return POINTER_LAYOUT;
+    }
+
+    switch (type.kind) {
+        case "primitive": {
+            return pointerOr(occurrenceCType, () => layoutOfPrimitive(type.category));
+        }
+        case "carray": {
+            return arrayLayout(context, type, visited);
+        }
+        case "list":
+        case "hashtable":
+        case "callback":
+        case "varargs":
+        case "class":
+        case "interface": {
+            return POINTER_LAYOUT;
+        }
+        case "enum": {
+            return pointerOr(occurrenceCType, () => layoutOfPrimitive("int32"));
+        }
+        case "record": {
+            return pointerOr(occurrenceCType, () => layoutOfRecord(context, type, visited));
+        }
+        case "alias": {
+            return pointerOr(occurrenceCType, () => resolveAliasLayout(context, type, visited));
+        }
+    }
+};
+
+const arrayLayout = (
+    context: ModuleContext,
+    ref: Extract<GirType, { kind: "carray" }>,
+    visited: Set<string>,
+): FieldLayout => {
+    if (ref.fixedSize === undefined) {
+        return POINTER_LAYOUT;
+    }
+
+    const elementLayout = layoutOfType(context, ref.element, ref.elementCType, visited);
+
+    return { size: elementLayout.size * ref.fixedSize, align: elementLayout.align };
+};
+
+const declaredLayout = (record: ResolvedRecordValue): FieldLayout | undefined => {
+    if (record.cType?.endsWith("*") === true) {
+        return POINTER_LAYOUT;
+    }
+
+    return record.cType === undefined ? undefined : ALIGNMENT_OVERRIDES.get(record.cType);
+};
+
+const layoutOfRecord = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "record" }>,
+    visited: Set<string>,
+): FieldLayout => {
+    const declared = declaredLayout(resolved.value);
+
+    if (declared !== undefined) {
+        return declared;
+    }
+
+    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[] = Array.from(resolved.value.fields, (field) =>
+        fieldLayoutInput(context, field, nextVisited));
+
+    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 resolveAliasLayout = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "alias" }>,
+    visited: Set<string>,
+): FieldLayout => {
+    const ref = resolved.value.target;
+
+    if (ref === undefined) {
+        return POINTER_LAYOUT;
+    }
+
+    return layoutOfType(context, ref, resolved.value.targetCType, visited);
+};
+
+export { computeRecordFieldSlots, bitMask, mergeBitfield, type RecordFieldSlot };

package/src/store/gi/record.ts

@@ -0,0 +1,89 @@
+import type { GirRecord } from "../../gir/record.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { indentMembers } from "../../writer/emit.js";
+import { type Callables, dedupeCallables, generateBindings, renderPlainTypeMembers } from "./callables.js";
+import { isClassStructRecord } from "./class-struct-record.js";
+import { renderSourceGtype } from "./gtype-binding.js";
+import { renderRecordConstructor, renderRecordConstructorPropsInterface } from "./record-constructor.js";
+import { renderRecordFieldAccessor } from "./record-field-accessor.js";
+import { computeRecordFieldSlots } from "./record-layout.js";
+import { appendWrapperClassRegistration } from "./registration.js";
+
+const isGErrorRecord = (context: ModuleContext, record: GirRecord): boolean =>
+    context.namespace.name === "GLib" && record.glibGetType === "g_error_get_type";
+
+const generateRecord = (context: ModuleContext, record: GirRecord): void => {
+    if (!record.introspectable) {
+        return;
+    }
+
+    if (record.isVtable) {
+        return;
+    }
+
+    if (record.name.length === 0) {
+        return;
+    }
+
+    if (isClassStructRecord(context.library, context.namespace.name, record)) {
+        return;
+    }
+
+    const className = record.name;
+    const isErrorSubclass = isGErrorRecord(context, record);
+
+    const callables: Callables = {
+        constructors: dedupeCallables(record.constructors),
+        functions: dedupeCallables(record.functions),
+        methods: dedupeCallables(record.methods),
+    };
+
+    generateBindings(context, callables);
+    const members = renderRecordMembers(context, record, className, callables);
+    const body = indentMembers(members);
+    const heritage = isErrorSubclass ? " extends globalThis.Error" : "";
+    context.module.appendDeclaration(`${renderJsDoc(record.doc)}export class ${className}${heritage} {\n${body}\n}`);
+    context.module.appendDeclaration(renderRecordConstructorPropsInterface(context, record, className));
+    const gtypeExpr = renderSourceGtype(context, record);
+
+    appendWrapperClassRegistration(context, {
+        className,
+        gtypeExpr,
+    });
+};
+
+const renderRecordMembers = (
+    context: ModuleContext,
+    record: GirRecord,
+    className: string,
+    callables: Callables,
+): string[] => {
+    const isErrorSubclass = isGErrorRecord(context, record);
+
+    const { members, claimedNames } = renderPlainTypeMembers({
+        context,
+        className,
+        callables,
+        hasGtype: record.glibGetType !== undefined,
+    });
+
+    members.unshift(renderRecordConstructor(context, record, className, isErrorSubclass));
+    const { slots } = computeRecordFieldSlots(context, record.fields, record.isUnion);
+
+    for (const slot of slots) {
+        const block = renderRecordFieldAccessor(context, slot, claimedNames, record.fields);
+
+        if (block !== undefined) {
+            members.push(block);
+        }
+    }
+
+    if (isErrorSubclass) {
+        members.push('get name(): string {\n    return "GLib.Error";\n}');
+    }
+
+    return members;
+};
+
+export { generateRecord };

package/src/store/gi/registration.ts

@@ -0,0 +1,44 @@
+import type { ModuleContext } from "../../writer/context.js";
+
+type WrapperClassRegistration = {
+    className: string;
+    gtypeExpr?: string | undefined;
+    vfuncs?: string | undefined;
+};
+
+type InterfaceRegistration = {
+    className: string;
+    makerName: string;
+    gtypeExpr?: string | undefined;
+    vfuncs?: string | undefined;
+};
+
+const appendWrapperClassRegistration = (
+    context: ModuleContext,
+    registration: WrapperClassRegistration,
+): void => {
+    const { className, gtypeExpr, vfuncs } = registration;
+
+    if (gtypeExpr === undefined) {
+        return;
+    }
+
+    context.addRuntimeImport("registerWrapperClass");
+    const args = vfuncs === undefined ? gtypeExpr : `${gtypeExpr}, ${vfuncs}`;
+    context.module.appendRegistration(`registerWrapperClass(${className}, ${args});`);
+};
+
+const appendInterfaceRegistration = (context: ModuleContext, registration: InterfaceRegistration): void => {
+    const { className, makerName, gtypeExpr, vfuncs } = registration;
+
+    if (gtypeExpr === undefined) {
+        return;
+    }
+
+    context.addRuntimeImport("registerInterface");
+    const base = `${className}, ${gtypeExpr}, ${makerName}`;
+    const args = vfuncs === undefined ? base : `${base}, ${vfuncs}`;
+    context.module.appendRegistration(`registerInterface(${args});`);
+};
+
+export { appendWrapperClassRegistration, appendInterfaceRegistration };

package/src/store/gi/return-wrap.ts

@@ -0,0 +1,100 @@
+import type { PrimitiveCategory } from "../../gir/primitives.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderDescriptor } from "../../analysis/descriptor-render.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+
+type WrapReturnOptions = {
+    ref: TypeId | undefined;
+    nullable: boolean;
+    valueExpression: string;
+};
+
+const BIGINT_CATEGORIES: Set<PrimitiveCategory> = new Set(["gtype", "bigint64", "biguint64"]);
+
+const wrapReturnValue = (context: ModuleContext, options: WrapReturnOptions): string => {
+    const { ref, nullable, valueExpression } = options;
+
+    if (ref === undefined) {
+        return valueExpression;
+    }
+
+    const type = context.library.typeFor(ref);
+
+    if (type === undefined) {
+        return wrapValue(context, ref, valueExpression);
+    }
+
+    switch (type.kind) {
+        case "primitive": {
+            return wrapPrimitive(type.category, nullable, valueExpression);
+        }
+        case "varargs": {
+            return `(${valueExpression} as unknown[])`;
+        }
+        case "callback": {
+            return wrapCallback(context, ref, valueExpression);
+        }
+        case "enum": {
+            return `(${valueExpression} as number)`;
+        }
+        case "alias": {
+            return wrapAlias(context, type.value.target, nullable, valueExpression);
+        }
+        case "carray":
+        case "class":
+        case "hashtable":
+        case "interface":
+        case "list":
+        case "record": {
+            return wrapValue(context, ref, valueExpression);
+        }
+    }
+};
+
+const wrapCallback = (context: ModuleContext, ref: TypeId, valueExpression: string): string =>
+    context.library.nameFor(ref) === undefined
+        ? `(${valueExpression} as unknown[])`
+        : `(${valueExpression} as ${renderTsType(context, ref, false)})`;
+
+const wrapAlias = (
+    context: ModuleContext,
+    target: TypeId | undefined,
+    isNullable: boolean,
+    valueExpression: string,
+): string =>
+    target === undefined
+        ? valueExpression
+        : wrapReturnValue(context, { ref: target, nullable: isNullable, valueExpression });
+
+const wrapValue = (context: ModuleContext, ref: TypeId, valueExpression: string): string => {
+    context.addRuntimeImport("fromNative");
+    const descriptor = context.hoistDescriptor(renderDescriptor(context, ref, "none"));
+
+    return `(fromNative(${descriptor}, ${valueExpression}) as ${renderTsType(context, ref, false)})`;
+};
+
+const wrapStringPrimitive = (isNullable: boolean, valueExpression: string): string =>
+    `(${valueExpression} as ${isNullable ? "string | null" : "string"})`;
+
+const wrapPrimitive = (category: PrimitiveCategory, isNullable: boolean, valueExpression: string): string => {
+    if (category === "void") {
+        return valueExpression;
+    }
+
+    if (category === "string") {
+        return wrapStringPrimitive(isNullable, valueExpression);
+    }
+
+    if (category === "boolean") {
+        return `Boolean(${valueExpression})`;
+    }
+
+    if (BIGINT_CATEGORIES.has(category)) {
+        return `(${valueExpression} as bigint)`;
+    }
+
+    return `(${valueExpression} as number)`;
+};
+
+export { wrapReturnValue };

package/src/store/gi/runtime-override.ts

@@ -0,0 +1,46 @@
+import type { GirFunction } from "../../gir/function.js";
+
+type RuntimeOverride = {
+    generics?: string;
+    signature: string;
+    returnType: string;
+    body: string;
+};
+
+const RUNTIME_OVERRIDES: Map<string, RuntimeOverride> = new Map([
+    [
+        "g_value_get_boxed",
+        {
+            generics: "<T = unknown>",
+            signature: "",
+            returnType: "T",
+            body: 'throw new Error("g_value_get_boxed: runtime override not installed");',
+        },
+    ],
+    [
+        "g_value_set_boxed",
+        {
+            signature: "boxed: object | null",
+            returnType: "void",
+            body: 'throw new Error("g_value_set_boxed: runtime override not installed");',
+        },
+    ],
+]);
+
+const renderRuntimeOverride = (callable: GirFunction, memberName: string): string | undefined => {
+    if (callable.cIdentifier === undefined) {
+        return undefined;
+    }
+
+    const override = RUNTIME_OVERRIDES.get(callable.cIdentifier);
+
+    if (override === undefined) {
+        return undefined;
+    }
+
+    const generics = override.generics ?? "";
+
+    return `${memberName}${generics}(${override.signature}): ${override.returnType} {\n    ${override.body}\n}`;
+};
+
+export { renderRuntimeOverride };