@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/gi/function.ts

@@ -0,0 +1,173 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirFunction } from "../../gir/function.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { tFn } from "../../analysis/descriptor.js";
+import { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { arrayLiteral, renderBlock } from "../../writer/emit.js";
+import { matchAsyncFinish } from "./async.js";
+import { hasClassStructReference } from "./class-struct-record.js";
+import {
+    planCallArgs,
+    renderMethodBody,
+    renderMethodReturnType,
+    renderMethodSignature,
+    renderPromisifiedBody,
+    renderPromisifiedSignature,
+    renderReturnDescriptor,
+} from "./method.js";
+
+const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | undefined => {
+    if (fn.cIdentifier === undefined) {
+        return undefined;
+    }
+
+    const library = context.namespace.sharedLibrary;
+
+    if (library === undefined) {
+        return undefined;
+    }
+
+    context.addRuntimeImport("t");
+    const params = planCallArgs(context, fn).map((arg) => arg.paramLiteral);
+    const ret = renderReturnDescriptor(context, fn);
+
+    return tFn(library, fn.cIdentifier, { args: arrayLiteral(params), returns: ret, throws: fn.throws });
+};
+
+// `moved-to` names the type member this function is also reachable as, so the namespace-level copy
+// is a second export of one binding. Suppressing it is only right when that member is really
+// emitted: 15 of Gtk-4.0's 28 `moved-to` targets are enum or error-domain members codegen emits no
+// static for, and dropping those would delete API with nothing to replace it.
+const isMovedOntoEmittedMember = (context: ModuleContext, fn: GirFunction): boolean => {
+    const [typeName, memberName] = fn.movedTo?.split(".") ?? [];
+
+    if (typeName === undefined || memberName === undefined) {
+        return false;
+    }
+
+    const resolved = context.library.resolveType(context.namespace.name, typeName);
+
+    if (resolved?.kind !== "class" && resolved?.kind !== "interface" && resolved?.kind !== "record") {
+        return false;
+    }
+
+    const members = [...resolved.value.methods, ...resolved.value.functions, ...resolved.value.constructors];
+
+    return members.some((member) => member.name === memberName);
+};
+
+const canEmitNamespaceFunction = (context: ModuleContext, fn: GirFunction): boolean =>
+    fn.introspectable &&
+    !isMovedOntoEmittedMember(context, fn) &&
+    fn.shadowedBy === undefined &&
+    fn.cIdentifier !== undefined &&
+    !hasClassStructReference(context, fn) &&
+    !hasCallerAllocatedArrayLength(context.library, fn);
+
+const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): void => {
+    if (!canEmitNamespaceFunction(context, fn)) {
+        return;
+    }
+
+    const expression = renderFnExpression(context, fn);
+
+    if (expression === undefined) {
+        return;
+    }
+
+    const cIdentifier = fn.cIdentifier;
+
+    if (cIdentifier === undefined) {
+        return;
+    }
+
+    const bindingName = toCamelIdentifier(cIdentifier);
+    context.module.appendBinding(`const ${bindingName} = ${expression};`, cIdentifier);
+    const exportName = namespaceFunctionExportName(cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
+    const declaration = renderNamespaceFunctionDeclaration(context, fn, exportName, bindingName);
+    context.module.appendDeclaration(`${renderJsDoc(fn.doc)}${declaration}`);
+};
+
+const renderNamespaceFunctionDeclaration = (
+    context: ModuleContext,
+    fn: GirFunction,
+    exportName: string,
+    bindingName: string,
+): string => {
+    const finishFn = matchAsyncFinish(context.library, fn, context.namespace.functions);
+    const finishCIdentifier = finishFn?.cIdentifier;
+
+    if (finishFn !== undefined && finishCIdentifier !== undefined && canEmitNamespaceFunction(context, finishFn)) {
+        const finishExport = namespaceFunctionExportName(
+            finishCIdentifier,
+            finishFn.name,
+            context.namespace.cSymbolPrefixes,
+        );
+
+        const { signature, returnType } = renderPromisifiedSignature(context, fn, finishFn);
+        const body = renderPromisifiedBody(context, fn, finishExport, bindingName);
+
+        return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+    }
+
+    const signature = renderMethodSignature(context, fn);
+    const returnType = renderMethodReturnType(context, fn);
+    const body = renderMethodBody(context, fn, { bindingExpression: bindingName });
+
+    return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+};
+
+const namespaceFunctionExportName = (cIdentifier: string, girName: string, symbolPrefixes: string[]): string => {
+    if (girName.length > 0) {
+        return toCamelIdentifier(girName);
+    }
+
+    const stripped = stripLongestPrefix(cIdentifier, symbolPrefixes);
+
+    return toCamelIdentifier(stripped);
+};
+
+const stripLongestPrefix = (input: string, prefixes: string[]): string => {
+    let best = "";
+
+    for (const prefix of prefixes) {
+        const candidate = `${prefix}_`;
+
+        if (input.startsWith(candidate) && candidate.length > best.length) {
+            best = candidate;
+        }
+    }
+
+    return best.length === 0 ? input : input.slice(best.length);
+};
+
+const isBootstrapFunction = (fn: GirFunction): boolean =>
+    fn.parameters.length === 0 && fn.introspectable && fn.shadowedBy === undefined && fn.cIdentifier !== undefined;
+
+const appendBootstrapRegistration = (context: ModuleContext, fn: GirFunction, exportName: string): void => {
+    if (fn.name === "init") {
+        context.module.appendRegistration(`${exportName}();`);
+
+        return;
+    }
+
+    if (fn.name === "finalize") {
+        context.addRuntimeImport("onExit");
+        context.module.appendRegistration(`onExit(${exportName});`);
+    }
+};
+
+const generateNamespaceBootstrap = (context: ModuleContext, namespace: GirNamespace): void => {
+    for (const fn of namespace.functions) {
+        if (!isBootstrapFunction(fn) || fn.cIdentifier === undefined) {
+            continue;
+        }
+
+        const exportName = namespaceFunctionExportName(fn.cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
+        appendBootstrapRegistration(context, fn, exportName);
+    }
+};
+
+export { renderFnExpression, generateNamespaceFunction, namespaceFunctionExportName, generateNamespaceBootstrap };

package/src/store/gi/gtype-binding.ts

@@ -0,0 +1,46 @@
+import { sourceStringLiteral } from "@gtkx/utils";
+import type { ModuleContext } from "../../writer/context.js";
+import { PRIMITIVE_TS_TYPE } from "../../gir/primitives.js";
+
+type TypeSource = {
+    glibGetType: string | undefined;
+    glibTypeName: string | undefined;
+};
+
+const gtypeTsType = (context: ModuleContext): string =>
+    context.namespace.name === "GObject" ? "Type" : PRIMITIVE_TS_TYPE.gtype;
+
+const gtypeMemberDeclaration = (context: ModuleContext): string => `declare __type__: ${gtypeTsType(context)};`;
+
+const renderInternGtype = (context: ModuleContext, typeName: string | undefined): string | undefined => {
+    if (typeName === undefined) {
+        return undefined;
+    }
+
+    if (context.namespace.name !== "GObject") {
+        context.addRuntimeImport("typeFromName");
+    }
+
+    return `typeFromName(${sourceStringLiteral(typeName)})`;
+};
+
+const renderResolveGtype = (context: ModuleContext, typeFnName: string): string => {
+    context.addRuntimeImport("resolveType");
+    const lib = context.namespace.sharedLibrary ?? "";
+
+    return `resolveType(${sourceStringLiteral(lib)}, ${sourceStringLiteral(typeFnName)})`;
+};
+
+const renderGtypeExpression = (
+    context: ModuleContext,
+    typeFnName: string,
+    typeName: string | undefined,
+): string | undefined =>
+    typeFnName === "intern" ? renderInternGtype(context, typeName) : renderResolveGtype(context, typeFnName);
+
+const renderSourceGtype = (context: ModuleContext, source: TypeSource): string | undefined =>
+    source.glibGetType === undefined
+        ? undefined
+        : renderGtypeExpression(context, source.glibGetType, source.glibTypeName);
+
+export { gtypeTsType, gtypeMemberDeclaration, renderSourceGtype };

package/src/store/gi/interface.ts

@@ -0,0 +1,222 @@
+import { pascalCase } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { reservedSignalMemberRename, resolvePrerequisiteReference } from "../../analysis/inheritance.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
+import {
+    type Callables,
+    dedupeCallables,
+    generateBindings,
+    type InstanceScope,
+    instanceScope,
+    renderClassInstanceMember,
+    renderInstanceMethodSignature,
+    renderStaticHead,
+} from "./callables.js";
+import { renderSourceGtype } from "./gtype-binding.js";
+import { methodExportName } from "./method.js";
+import {
+    type PropertyAccessorArgs,
+    renderPropertyAccessor,
+    renderPropertyAccessorSignature,
+} from "./property-accessor.js";
+import { appendInterfaceRegistration } from "./registration.js";
+import { renderSignalDeclarations, renderSignalMembers } from "./signal.js";
+import { renderVfuncMetadata } from "./vtable.js";
+
+type InterfaceMemberRenderers = {
+    renderMethod: (
+        context: ModuleContext,
+        callable: GirFunction,
+        scope: InstanceScope,
+        nameOverride?: string,
+    ) => string | undefined;
+    renderProperty: (args: PropertyAccessorArgs) => string | undefined;
+};
+
+type MethodMemberOptions = {
+    context: ModuleContext;
+    className: string;
+    scope: InstanceScope;
+    callables: Callables;
+    renderers: InterfaceMemberRenderers;
+    claimedNames: Set<string>;
+};
+
+type PropertyMemberOptions = {
+    context: ModuleContext;
+    iface: GirClass;
+    scope: InstanceScope;
+    renderers: InterfaceMemberRenderers;
+    claimedNames: Set<string>;
+};
+
+const generateInterface = (context: ModuleContext, iface: GirClass): void => {
+    if (!iface.introspectable) {
+        return;
+    }
+
+    if (iface.name.length === 0) {
+        return;
+    }
+
+    const className = pascalCase(iface.name);
+
+    const callables: Callables = {
+        constructors: dedupeCallables(iface.constructors),
+        functions: dedupeCallables(iface.functions),
+        methods: dedupeCallables(iface.methods),
+    };
+
+    generateBindings(context, callables);
+    const gtypeExpr = renderSourceGtype(context, iface);
+    context.module.appendDeclaration(renderInterfaceType(context, iface, className, callables));
+    context.module.appendDeclaration(renderInterfaceClass(context, className, callables, gtypeExpr));
+
+    for (const declaration of renderSignalDeclarations(context, iface, className, true)) {
+        context.module.appendDeclaration(declaration);
+    }
+
+    context.module.appendDeclaration(renderInterfaceMaker(context, iface, className, callables));
+
+    appendInterfaceRegistration(context, {
+        className,
+        makerName: makerName(className),
+        gtypeExpr,
+        vfuncs: renderVfuncMetadata(context, iface),
+    });
+};
+
+const makerName = (className: string): string => `make${className}`;
+
+const interfaceTypeExtends = (context: ModuleContext, iface: GirClass): string => {
+    const refs = iface.prerequisites
+        .map((name) => resolvePrerequisiteReference(context, name))
+        .filter((entry): entry is string => entry !== undefined);
+
+    if (refs.length > 0) {
+        return refs.join(", ");
+    }
+
+    return context.qualify("GObject", "Object");
+};
+
+const renderInterfaceType = (
+    context: ModuleContext,
+    iface: GirClass,
+    className: string,
+    callables: Callables,
+): string => {
+    const members = renderInterfaceTypeMembers(context, iface, callables);
+
+    return `${renderJsDoc(iface.doc)}${renderBracedOrEmpty(
+        `export interface ${className} extends ${interfaceTypeExtends(context, iface)}`,
+        members.join("\n"),
+    )}`;
+};
+
+const collectMethodMembers = (options: MethodMemberOptions): string[] => {
+    const { context, className, scope, callables, renderers, claimedNames } = options;
+    const members: string[] = [];
+
+    for (const callable of callables.methods) {
+        const rename = reservedSignalMemberRename(className, callable);
+        const block = renderers.renderMethod(context, callable, scope, rename);
+
+        if (block === undefined) {
+            continue;
+        }
+
+        members.push(block);
+        claimedNames.add(rename ?? methodExportName(callable));
+    }
+
+    return members;
+};
+
+const collectPropertyMembers = (options: PropertyMemberOptions): string[] => {
+    const { context, iface, scope, renderers, claimedNames } = options;
+    const members: string[] = [];
+
+    for (const property of iface.properties) {
+        const block = renderers.renderProperty({ context, property, claimedNames, methodByName: scope.methodByName });
+
+        if (block !== undefined) {
+            members.push(block);
+        }
+    }
+
+    return members;
+};
+
+const renderInterfaceMembers = (
+    context: ModuleContext,
+    iface: GirClass,
+    callables: Callables,
+    renderers: InterfaceMemberRenderers,
+): string[] => {
+    const className = pascalCase(iface.name);
+    const scope = instanceScope(className, callables);
+    const claimedNames: Set<string> = new Set();
+    const methodMembers = collectMethodMembers({ context, className, scope, callables, renderers, claimedNames });
+    const propertyMembers = collectPropertyMembers({ context, iface, scope, renderers, claimedNames });
+
+    return [...methodMembers, ...propertyMembers];
+};
+
+const renderInterfaceTypeMembers = (context: ModuleContext, iface: GirClass, callables: Callables): string[] =>
+    renderInterfaceMembers(context, iface, callables, {
+        renderMethod: renderInstanceMethodSignature,
+        renderProperty: renderPropertyAccessorSignature,
+    });
+
+const renderInterfaceClass = (
+    context: ModuleContext,
+    className: string,
+    callables: Callables,
+    gtypeExpr: string | undefined,
+): string => {
+    const members: string[] = [];
+
+    if (gtypeExpr !== undefined) {
+        members.push(renderInterfaceHasInstance(context, className, gtypeExpr));
+    }
+
+    members.push(...renderStaticHead(context, callables, className));
+
+    return renderBracedOrEmpty(`export abstract class ${className}`, members.join("\n\n"));
+};
+
+const renderInterfaceHasInstance = (context: ModuleContext, className: string, gtypeExpr: string): string => {
+    context.addRuntimeImport("valueIsA");
+
+    return renderBlock(
+        `static [Symbol.hasInstance](value: unknown): value is ${className}`,
+        `return valueIsA(value, ${gtypeExpr});`,
+    );
+};
+
+const renderInterfaceMaker = (
+    context: ModuleContext,
+    iface: GirClass,
+    className: string,
+    callables: Callables,
+): string => {
+    context.addRuntimeTypeImport("Mixin");
+    const members = renderInterfaceInstanceMembers(context, iface, callables);
+    const classExpression = renderBracedOrEmpty("class extends Base", members.join("\n\n"));
+
+    return `export const ${makerName(className)}: Mixin = (Base) =>\n${classExpression};`;
+};
+
+const renderInterfaceInstanceMembers = (context: ModuleContext, iface: GirClass, callables: Callables): string[] => [
+    ...renderInterfaceMembers(context, iface, callables, {
+        renderMethod: renderClassInstanceMember,
+        renderProperty: renderPropertyAccessor,
+    }),
+    ...renderSignalMembers(context, iface),
+];
+
+export { generateInterface };

package/src/store/gi/item-comparators.ts

@@ -0,0 +1,138 @@
+import type { GirFunction } from "../../gir/function.js";
+import type { GirParameter } from "../../gir/parameter.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { tObject } from "../../analysis/descriptor.js";
+import { inputParameters, parameterIdentifier } from "../../analysis/param-structure.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { resolveInterface } from "../../gir/ancestry.js";
+import { callbackAsFunction, type GirCallback } from "../../gir/callback.js";
+
+const COMPARATOR_CALLBACK_TYPES = new Set([
+    "GLib.CompareFunc",
+    "GLib.CompareDataFunc",
+    "GLib.EqualFunc",
+    "GLib.EqualFuncFull",
+]);
+
+const OBJECT_ITEM_COMPARATOR_OWNERS = new Set(["Gtk.CustomSorter"]);
+
+const qualifiedName = (context: ModuleContext, ref: TypeId): string | undefined => {
+    const name = context.library.nameFor(ref);
+
+    return name === undefined ? undefined : `${name.namespaceName}.${name.typeName}`;
+};
+
+const isListModelImplementor = (context: ModuleContext, ref: TypeId): boolean => {
+    const resolved = context.library.typeFor(ref);
+
+    if (resolved?.kind !== "class") {
+        return false;
+    }
+
+    return resolved.value.implements.some((interfaceName) => {
+        const iface = resolveInterface(context.library, resolved.namespace.name, interfaceName);
+
+        return iface?.namespaceName === "Gio" && iface.klass.name === "ListModel";
+    });
+};
+
+const isObjectItemComparator = (context: ModuleContext, fn: GirFunction): boolean => {
+    const ownerRef = fn.instance?.type ?? fn.returnValue.type;
+
+    if (ownerRef === undefined) {
+        return false;
+    }
+
+    const owner = qualifiedName(context, ownerRef);
+
+    if (owner !== undefined && OBJECT_ITEM_COMPARATOR_OWNERS.has(owner)) {
+        return true;
+    }
+
+    return isListModelImplementor(context, ownerRef);
+};
+
+const isItemPointer = (context: ModuleContext, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) {
+        return false;
+    }
+
+    const resolved = context.library.typeFor(ref);
+
+    return resolved?.kind === "primitive" && resolved.category === "pointer";
+};
+
+const itemComparatorCallback = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): GirCallback | undefined => {
+    if (parameter.type === undefined) {
+        return undefined;
+    }
+
+    const resolved = context.library.typeFor(parameter.type);
+
+    if (resolved?.kind !== "callback") {
+        return undefined;
+    }
+
+    const name = qualifiedName(context, parameter.type);
+
+    if (name === undefined || !COMPARATOR_CALLBACK_TYPES.has(name)) {
+        return undefined;
+    }
+
+    return isObjectItemComparator(context, fn) ? resolved.value : undefined;
+};
+
+const itemComparatorArgDescriptors = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): Map<number, string> | undefined => {
+    const callback = itemComparatorCallback(context, fn, parameter);
+
+    if (callback === undefined) {
+        return undefined;
+    }
+
+    const overrides: Map<number, string> = new Map();
+    const items = inputParameters(context.library, callbackAsFunction(callback));
+
+    for (const { parameter: item, index } of items) {
+        if (isItemPointer(context, item.type)) {
+            overrides.set(index, tObject("borrowed"));
+        }
+    }
+
+    return overrides.size > 0 ? overrides : undefined;
+};
+
+const itemComparatorTsType = (
+    context: ModuleContext,
+    fn: GirFunction,
+    parameter: GirParameter,
+): string | undefined => {
+    const callback = itemComparatorCallback(context, fn, parameter);
+
+    if (callback === undefined) {
+        return undefined;
+    }
+
+    const itemType = `${context.qualify("GObject", "Object")} | null`;
+
+    const args = inputParameters(context.library, callbackAsFunction(callback)).map(({ parameter: item, index }) => {
+        const tsType = isItemPointer(context, item.type) ? itemType : renderTsType(context, item.type, item.nullable);
+
+        return `${parameterIdentifier(item, index)}: ${tsType}`;
+    });
+
+    const returnType = renderTsType(context, callback.returnValue.type, callback.returnValue.nullable);
+    const fnType = `(${args.join(", ")}) => ${returnType}`;
+
+    return parameter.nullable ? `(${fnType}) | null` : fnType;
+};
+
+export { itemComparatorArgDescriptors, itemComparatorTsType };