@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/analysis/descriptor-render.ts

@@ -0,0 +1,407 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import type { GirCallback } from "../gir/callback.js";
+import type { Library } from "../gir/library.js";
+import {
+    type GirParameter,
+    type GirReturnValue,
+    isCallerAllocatedOut,
+    isInoutParameter,
+    isOutParameter,
+    type ParameterTransfer,
+} from "../gir/parameter.js";
+import type { PrimitiveCategory } from "../gir/primitives.js";
+import type { EntityType, GirType } from "../gir/type.js";
+import type { CArrayType, ListFlavor, TypeId } from "../gir/type-id.js";
+import { isRecordInout } from "../store/gi/param-marshal.js";
+import { computeRecordFieldSlots } from "../store/gi/record-layout.js";
+import type { ModuleContext } from "../writer/context.js";
+import {
+    type ListDescriptorName,
+    type Ownership,
+    type ScalarDescriptorName,
+    tArray,
+    tBoxed,
+    tByteArray,
+    tCallback,
+    tEnum,
+    tFixedArray,
+    tFlags,
+    tFundamental,
+    tGtype,
+    tHashTable,
+    tInt32,
+    tList,
+    tObject,
+    tRef,
+    tScalar,
+    tSizedArray,
+    tString,
+    tStruct,
+    tUint32,
+    tUint64,
+    tVoid,
+} from "./descriptor.js";
+
+const transferOwnership = (transfer: ParameterTransfer): Ownership => {
+    if (transfer === "full") return "full";
+    if (transfer === "container") return "full";
+    return "borrowed";
+};
+
+const deriveElementTransfer = (transfer: ParameterTransfer): ParameterTransfer =>
+    transfer === "container" ? "none" : transfer;
+
+type RenderDescriptorOptions = {
+    argIndexOffset?: number;
+    callerAllocated?: boolean;
+};
+
+const isVoidRef = (library: Library, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) return true;
+    const type = library.typeOf(ref);
+    return type?.kind === "primitive" && type.category === "void";
+};
+
+export const isInlineCallbackRef = (library: Library, ref: TypeId | undefined): boolean =>
+    ref !== undefined && library.typeOf(ref)?.kind === "callback" && library.nameOf(ref) === undefined;
+
+export const omitsPrimaryReturn = (library: Library, returnValue: GirReturnValue): boolean =>
+    isVoidRef(library, returnValue.type) || returnValue.skip;
+
+export const renderDescriptor = (
+    context: ModuleContext,
+    ref: TypeId | undefined,
+    transfer: ParameterTransfer = "none",
+    options: RenderDescriptorOptions = {},
+): string => {
+    if (ref === undefined) return tVoid;
+    const { argIndexOffset = 0 } = options;
+    const ownership = transferOwnership(transfer);
+    const type = context.library.typeOf(ref);
+    if (type === undefined) return tObject(ownership);
+    switch (type.kind) {
+        case "primitive":
+            return primitiveExpression(type.category, ownership);
+        case "varargs":
+        case "callback":
+            return tVoid;
+        case "class":
+        case "interface":
+        case "record":
+        case "enum":
+        case "alias":
+            return expressionForResolved(context, type, transfer, options);
+        case "carray":
+            return arrayExpression(context, type, transfer, argIndexOffset);
+        case "list": {
+            if (type.flavor === "gbytearray") return tByteArray(ownership);
+            const element = renderDescriptor(context, type.element, deriveElementTransfer(transfer), {
+                argIndexOffset,
+            });
+            return tList(LIST_HELPERS[type.flavor], element, ownership);
+        }
+        case "hashtable": {
+            const elementTransfer = deriveElementTransfer(transfer);
+            const key = renderDescriptor(context, type.key, elementTransfer, { argIndexOffset });
+            const value = renderDescriptor(context, type.value, elementTransfer, { argIndexOffset });
+            return tHashTable(key, value, ownership);
+        }
+    }
+};
+
+const resolveCallbackType = (context: ModuleContext, ref: TypeId | undefined): GirCallback | undefined => {
+    if (ref === undefined) return undefined;
+    const type = context.library.typeOf(ref);
+    if (type?.kind !== "callback") return undefined;
+    return type.value;
+};
+
+export const isScalarRef = (library: Library, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) return false;
+    const type = library.typeOf(ref);
+    if (type === undefined) return false;
+    if (type.kind === "primitive") return type.category !== "string" && type.category !== "void";
+    if (type.kind === "enum") return true;
+    if (type.kind === "alias") return type.value.target !== undefined && isScalarRef(library, type.value.target);
+    return false;
+};
+
+export const isCellInout = (library: Library, parameter: GirParameter): boolean =>
+    isInoutParameter(parameter) && isScalarRef(library, parameter.type);
+
+export const renderParamDescriptor = (
+    context: ModuleContext,
+    parameter: GirParameter,
+    ref: TypeId | undefined,
+): string => {
+    if (isCellInout(context.library, parameter)) {
+        return tRef(renderDescriptor(context, ref, parameter.transferOwnership), true);
+    }
+    if (isOutParameter(parameter)) {
+        return tRef(renderDescriptor(context, ref, parameter.transferOwnership));
+    }
+    return renderDescriptor(context, ref, parameter.transferOwnership, {
+        callerAllocated: isCallerAllocatedOut(parameter) || isRecordInout(context, parameter),
+    });
+};
+
+export const renderCallbackType = (
+    context: ModuleContext,
+    ref: TypeId | undefined,
+    owningParameter: GirParameter,
+    argOverrides?: Map<number, string>,
+): string | undefined => {
+    const callback = resolveCallbackType(context, ref);
+    if (callback === undefined) return undefined;
+    const argTypes = callback.parameters.map(
+        (parameter, index) => argOverrides?.get(index) ?? renderParamDescriptor(context, parameter, parameter.type),
+    );
+    let userDataIndex: number | undefined;
+    callback.parameters.forEach((parameter, index) => {
+        if (parameter.name === "user_data" || parameter.name === "data") userDataIndex = index;
+    });
+    const returnRef = callback.returnValue.type;
+    const returnType = isVoidRef(context.library, returnRef)
+        ? tVoid
+        : renderDescriptor(context, returnRef, callback.returnValue.transferOwnership);
+    const options: string[] = [];
+    if (owningParameter.destroyIndex !== undefined) options.push("hasDestroy: true");
+    if (userDataIndex !== undefined) options.push(`userDataIndex: ${userDataIndex}`);
+    if (owningParameter.scope !== undefined) options.push(`scope: ${sourceStringLiteral(owningParameter.scope)}`);
+    const optionsArg = options.length > 0 ? `{ ${options.join(", ")} }` : undefined;
+    return tCallback(argTypes, returnType, optionsArg);
+};
+
+const LIST_HELPERS: Record<Exclude<ListFlavor, "gbytearray">, ListDescriptorName> = {
+    glist: "list",
+    gslist: "slist",
+    gptrarray: "ptrArray",
+    garray: "gArray",
+};
+
+const primitiveExpression = (category: PrimitiveCategory, ownership: Ownership): string => {
+    if (category === "void") return tVoid;
+    if (category === "string") return tString(ownership);
+    if (category === "pointer") return tUint64;
+    if (category === "gtype") return tGtype;
+    return tScalar(category satisfies ScalarDescriptorName);
+};
+
+type FundamentalDescriptor = {
+    lib: string;
+    refFunc: string;
+    unrefFunc: string;
+    typeName: string | undefined;
+    ownership: Ownership;
+    wrapperClass?: string | undefined;
+};
+
+const referenceAddingFunc = (refFunc: string): string =>
+    refFunc.endsWith("_ref_sink") ? refFunc.slice(0, -"_sink".length) : refFunc;
+
+const renderFundamental = (descriptor: FundamentalDescriptor): string => {
+    const { lib, refFunc, unrefFunc, typeName, ownership, wrapperClass } = descriptor;
+    return tFundamental(lib, referenceAddingFunc(refFunc), unrefFunc, {
+        ownership,
+        typeName,
+        wrapperClass,
+    });
+};
+
+const classOrInterfaceExpression = (
+    resolved: Extract<EntityType, { kind: "class" | "interface" }>,
+    ownership: Ownership,
+): string => {
+    const cls = resolved.value;
+    if (cls.glibRefFunc === undefined || cls.glibUnrefFunc === undefined) {
+        return tObject(ownership);
+    }
+    return renderFundamental({
+        lib: resolved.namespace.sharedLibrary ?? "",
+        refFunc: cls.glibRefFunc,
+        unrefFunc: cls.glibUnrefFunc,
+        typeName: cls.glibTypeName,
+        ownership,
+    });
+};
+
+type AncestorFundamental = {
+    lib: string;
+    refFunc: string;
+    unrefFunc: string;
+    typeName: string | undefined;
+};
+
+const fundamentalAncestor = (
+    context: ModuleContext,
+    start: Extract<EntityType, { kind: "class" | "interface" }>,
+): AncestorFundamental | undefined => {
+    const seen = new Set<string>();
+    let current: GirType | undefined = start;
+    while (current !== undefined && (current.kind === "class" || current.kind === "interface")) {
+        const key = `${current.namespace.name}.${current.value.name}`;
+        if (seen.has(key)) return undefined;
+        seen.add(key);
+        const cls = current.value;
+        if (cls.fundamental && cls.glibRefFunc !== undefined && cls.glibUnrefFunc !== undefined) {
+            return {
+                lib: current.namespace.sharedLibrary ?? "",
+                refFunc: cls.glibRefFunc,
+                unrefFunc: cls.glibUnrefFunc,
+                typeName: cls.glibTypeName,
+            };
+        }
+        if (cls.parent === undefined) return undefined;
+        current = context.library.resolveType(current.namespace.name, cls.parent);
+    }
+    return undefined;
+};
+
+export const renderSelfDescriptor = (context: ModuleContext, instance: GirParameter): string => {
+    const ref = instance.type;
+    if (ref === undefined) return tObject("borrowed");
+    const type = context.library.typeOf(ref);
+    if (type === undefined) return tObject("borrowed");
+    if (type.kind === "class" || type.kind === "interface") {
+        const ancestor = fundamentalAncestor(context, type);
+        return ancestor === undefined ? tObject("borrowed") : renderFundamental({ ...ancestor, ownership: "borrowed" });
+    }
+    if (type.kind === "record") {
+        return recordExpression(context, type, transferOwnership(instance.transferOwnership));
+    }
+    return tObject("borrowed");
+};
+
+type ResolvedRecord = Extract<EntityType, { kind: "record" }>["value"];
+
+const recordRefPair = (record: ResolvedRecord): { refFunc: string | undefined; unrefFunc: string | undefined } => ({
+    refFunc: record.glibRefFunc ?? record.copyFunc,
+    unrefFunc: record.glibUnrefFunc ?? record.freeFunc,
+});
+
+const recordNeedsFallbackClass = (record: ResolvedRecord): boolean => {
+    const { refFunc, unrefFunc } = recordRefPair(record);
+    if (refFunc !== undefined && unrefFunc !== undefined) return record.glibTypeName === undefined;
+    return record.glibGetType === undefined;
+};
+
+const structExpression = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "record" }>,
+    ownership: Ownership,
+    callerAllocated: boolean,
+): string => {
+    const { size } = computeRecordFieldSlots(context, resolved.value.fields, resolved.value.isUnion);
+    const wrapperClass = context.qualify(resolved.namespace.name, resolved.value.name);
+    return tStruct(ownership, {
+        size: size > 0 ? size : undefined,
+        wrapperClass,
+        callerAllocated,
+    });
+};
+
+const recordExpression = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "record" }>,
+    ownership: Ownership,
+    callerAllocated = false,
+): string => {
+    const record = resolved.value;
+    const { refFunc, unrefFunc } = recordRefPair(record);
+    const wrapperClass = recordNeedsFallbackClass(record)
+        ? context.qualify(resolved.namespace.name, record.name)
+        : undefined;
+    if (refFunc !== undefined && unrefFunc !== undefined) {
+        const lib = resolved.namespace.sharedLibrary ?? "";
+        return renderFundamental({
+            lib,
+            refFunc,
+            unrefFunc,
+            typeName: record.glibTypeName,
+            ownership,
+            wrapperClass,
+        });
+    }
+    if (record.glibGetType === undefined) {
+        return structExpression(context, resolved, ownership, callerAllocated);
+    }
+    const glibName = record.glibTypeName ?? record.cType ?? record.name;
+    const { size } = computeRecordFieldSlots(context, record.fields, record.isUnion);
+    return tBoxed(glibName, {
+        ownership,
+        sharedLibrary: resolved.namespace.sharedLibrary,
+        getTypeFnName: record.glibGetType,
+        callerAllocated,
+        size: size > 0 ? size : undefined,
+    });
+};
+
+const expressionForResolved = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "class" | "interface" | "record" | "enum" | "alias" }>,
+    transfer: ParameterTransfer,
+    options: RenderDescriptorOptions,
+): string => {
+    const ownership = transferOwnership(transfer);
+    switch (resolved.kind) {
+        case "class":
+        case "interface":
+            return classOrInterfaceExpression(resolved, ownership);
+        case "record":
+            return recordExpression(context, resolved, ownership, options.callerAllocated ?? false);
+        case "enum": {
+            const getter = resolved.value.glibGetType;
+            const signed = resolved.value.members.some((member) => member.value.startsWith("-"));
+            if (getter === undefined || getter === "") return signed ? tInt32 : tUint32;
+            const lib = resolved.namespace.sharedLibrary ?? "";
+            return resolved.value.kind === "bitfield" ? tFlags(lib, getter, signed) : tEnum(lib, getter, signed);
+        }
+        case "alias":
+            return aliasExpression(context, resolved.value.target, transfer, options);
+    }
+};
+
+const arrayExpression = (
+    context: ModuleContext,
+    ref: CArrayType,
+    transfer: ParameterTransfer,
+    argIndexOffset: number,
+): string => {
+    const ownership = transferOwnership(transfer);
+    const element = renderDescriptor(context, ref.element, deriveElementTransfer(transfer), { argIndexOffset });
+    const size = inlineElementSize(context, ref.element, ref.elementCType);
+    if (ref.lengthParameterIndex !== undefined) {
+        return tSizedArray(element, ref.lengthParameterIndex + argIndexOffset, ownership, size);
+    }
+    if (ref.fixedSize !== undefined) {
+        return tFixedArray(element, ref.fixedSize, ownership, size);
+    }
+    return tArray(element, ownership, size);
+};
+
+const inlineElementSize = (
+    context: ModuleContext,
+    element: TypeId | undefined,
+    elementCType: string | undefined,
+): number | undefined => {
+    if (element === undefined) return undefined;
+    if (elementCType?.includes("*")) return undefined;
+    const type = context.library.typeOf(element);
+    if (type?.kind !== "record") return undefined;
+    const record = type.value;
+    if (record.opaque || record.disguised || record.fields.length === 0) return undefined;
+    const { size } = computeRecordFieldSlots(context, record.fields, record.isUnion);
+    return size > 0 ? size : undefined;
+};
+
+const aliasExpression = (
+    context: ModuleContext,
+    target: TypeId | undefined,
+    transfer: ParameterTransfer,
+    options: RenderDescriptorOptions,
+): string => {
+    if (target === undefined) {
+        return tObject(transferOwnership(transfer));
+    }
+    return renderDescriptor(context, target, transfer, options);
+};

package/src/analysis/descriptor.ts

@@ -0,0 +1,263 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import { joinArgs } from "../writer/emit.js";
+
+export type Ownership = "borrowed" | "full";
+
+type DescriptorName =
+    | "bind"
+    | "int8"
+    | "uint8"
+    | "int16"
+    | "uint16"
+    | "int32"
+    | "uint32"
+    | "int64"
+    | "uint64"
+    | "bigint64"
+    | "biguint64"
+    | "gtype"
+    | "float32"
+    | "float64"
+    | "boolean"
+    | "void"
+    | "unichar"
+    | "buffer"
+    | "string"
+    | "object"
+    | "boxed"
+    | "struct"
+    | "fundamental"
+    | "ref"
+    | "hashTable"
+    | "enum"
+    | "flags"
+    | "array"
+    | "list"
+    | "slist"
+    | "ptrArray"
+    | "gArray"
+    | "byteArray"
+    | "sizedArray"
+    | "fixedArray"
+    | "callback"
+    | "fn";
+
+type DescriptorNames = { [K in DescriptorName]: `t.${K}` };
+
+const T: DescriptorNames = {
+    bind: "t.bind",
+    int8: "t.int8",
+    uint8: "t.uint8",
+    int16: "t.int16",
+    uint16: "t.uint16",
+    int32: "t.int32",
+    uint32: "t.uint32",
+    int64: "t.int64",
+    uint64: "t.uint64",
+    bigint64: "t.bigint64",
+    biguint64: "t.biguint64",
+    gtype: "t.gtype",
+    float32: "t.float32",
+    float64: "t.float64",
+    boolean: "t.boolean",
+    void: "t.void",
+    unichar: "t.unichar",
+    buffer: "t.buffer",
+    string: "t.string",
+    object: "t.object",
+    boxed: "t.boxed",
+    struct: "t.struct",
+    fundamental: "t.fundamental",
+    ref: "t.ref",
+    hashTable: "t.hashTable",
+    enum: "t.enum",
+    flags: "t.flags",
+    array: "t.array",
+    list: "t.list",
+    slist: "t.slist",
+    ptrArray: "t.ptrArray",
+    gArray: "t.gArray",
+    byteArray: "t.byteArray",
+    sizedArray: "t.sizedArray",
+    fixedArray: "t.fixedArray",
+    callback: "t.callback",
+    fn: "t.fn",
+};
+
+const call = (name: DescriptorName, args: Array<string | undefined>): string => `${T[name]}(${joinArgs(args)})`;
+
+const optionsObject = (parts: Array<string | undefined>): string | undefined => {
+    const present = parts.filter((part): part is string => part !== undefined);
+    return present.length === 0 ? undefined : `{ ${present.join(", ")} }`;
+};
+
+export const tVoid: string = T.void;
+
+export const tBoolean: string = T.boolean;
+
+export const tUint8: string = T.uint8;
+
+export const tUint32: string = T.uint32;
+
+export const tInt32: string = T.int32;
+
+export const tUint64: string = T.uint64;
+
+export const tGtype: string = T.gtype;
+
+export const tBuffer: string = T.buffer;
+
+export type ScalarDescriptorName =
+    | "boolean"
+    | "int8"
+    | "uint8"
+    | "int16"
+    | "uint16"
+    | "int32"
+    | "uint32"
+    | "int64"
+    | "uint64"
+    | "bigint64"
+    | "biguint64"
+    | "float32"
+    | "float64"
+    | "unichar";
+
+export const tScalar = (name: ScalarDescriptorName): string => T[name];
+
+export const tString = (ownership: Ownership, length?: string): string =>
+    call("string", [sourceStringLiteral(ownership), length]);
+
+export const tObject = (ownership: Ownership): string => call("object", [sourceStringLiteral(ownership)]);
+
+export type BoxedOptions = {
+    ownership: Ownership;
+    sharedLibrary: string | undefined;
+    getTypeFnName: string;
+    callerAllocated: boolean;
+    size: number | undefined;
+};
+
+export const tBoxed = (glibName: string, options: BoxedOptions): string =>
+    call("boxed", [
+        sourceStringLiteral(glibName),
+        optionsObject([
+            `ownership: ${sourceStringLiteral(options.ownership)}`,
+            options.sharedLibrary === undefined
+                ? undefined
+                : `sharedLibrary: ${sourceStringLiteral(options.sharedLibrary)}`,
+            `getTypeFnName: ${sourceStringLiteral(options.getTypeFnName)}`,
+            options.callerAllocated ? "callerAllocated: true" : undefined,
+            options.size === undefined ? undefined : `size: ${options.size}`,
+        ]),
+    ]);
+
+export type StructOptions = {
+    size: number | string | undefined;
+    wrapperClass: string | undefined;
+    callerAllocated: boolean;
+};
+
+export const tStruct = (ownership: Ownership, options: StructOptions): string =>
+    call("struct", [
+        sourceStringLiteral(ownership),
+        optionsObject([
+            options.size === undefined ? undefined : `size: ${options.size}`,
+            options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
+            options.callerAllocated ? "callerAllocated: true" : undefined,
+        ]),
+    ]);
+
+export const tInlineStruct = (): string =>
+    tStruct("borrowed", { size: undefined, wrapperClass: undefined, callerAllocated: false });
+
+export type FundamentalOptions = {
+    ownership: Ownership;
+    typeName: string | undefined;
+    wrapperClass: string | undefined;
+};
+
+export const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options: FundamentalOptions): string =>
+    call("fundamental", [
+        sourceStringLiteral(lib),
+        sourceStringLiteral(refFunc),
+        sourceStringLiteral(unrefFunc),
+        optionsObject([
+            `ownership: ${sourceStringLiteral(options.ownership)}`,
+            options.typeName === undefined ? undefined : `typeName: ${sourceStringLiteral(options.typeName)}`,
+            options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
+        ]),
+    ]);
+
+export const tRef = (inner: string, inout = false): string => call("ref", [inner, inout ? "true" : undefined]);
+
+export const tHashTable = (key: string, value: string, ownership: Ownership): string =>
+    call("hashTable", [key, value, sourceStringLiteral(ownership)]);
+
+export const tEnum = (lib: string, getType: string, signed: boolean): string =>
+    call("enum", [sourceStringLiteral(lib), sourceStringLiteral(getType), String(signed)]);
+
+export const tFlags = (lib: string, getType: string, signed: boolean): string =>
+    call("flags", [sourceStringLiteral(lib), sourceStringLiteral(getType), String(signed)]);
+
+export const tByteArray = (ownership: Ownership): string => call("byteArray", [sourceStringLiteral(ownership)]);
+
+export type ListDescriptorName = "list" | "slist" | "ptrArray" | "gArray";
+
+export const tList = (name: ListDescriptorName, element: string, ownership: Ownership): string =>
+    call(name, [element, sourceStringLiteral(ownership)]);
+
+export const tArray = (element: string, ownership?: Ownership, elementSize?: number): string =>
+    call("array", [
+        element,
+        ownership === undefined ? undefined : sourceStringLiteral("array"),
+        ownership === undefined ? undefined : sourceStringLiteral(ownership),
+        elementSize === undefined ? undefined : `{ elementSize: ${elementSize} }`,
+    ]);
+
+export const tSizedArray = (
+    element: string,
+    lengthIndex: number,
+    ownership?: Ownership,
+    elementSize?: number,
+): string =>
+    call("sizedArray", [
+        element,
+        String(lengthIndex),
+        ownership === undefined ? undefined : sourceStringLiteral(ownership),
+        elementSize === undefined ? undefined : String(elementSize),
+    ]);
+
+export const tFixedArray = (element: string, length: number, ownership?: Ownership, elementSize?: number): string =>
+    call("fixedArray", [
+        element,
+        String(length),
+        ownership === undefined ? undefined : sourceStringLiteral(ownership),
+        elementSize === undefined ? undefined : String(elementSize),
+    ]);
+
+export const tCallback = (argTypes: string[], returnType: string, options?: string): string =>
+    call("callback", [`[${argTypes.join(", ")}]`, returnType, options]);
+
+type BindArgs = {
+    libExpr: string;
+    symbolExpr: string;
+    argList: string;
+    returnType: string;
+};
+
+export const tBind = (args: BindArgs): string =>
+    call("bind", [args.libExpr, args.symbolExpr, args.argList, args.returnType]);
+
+export const tFn = (
+    lib: string,
+    cIdentifier: string,
+    spec: { args: string; returns: string; throws: boolean },
+): string => {
+    const throwsEntry = spec.throws ? ", throws: true" : "";
+    return call("fn", [
+        sourceStringLiteral(lib),
+        sourceStringLiteral(cIdentifier),
+        `{ args: ${spec.args}, returns: ${spec.returns}${throwsEntry} }`,
+    ]);
+};