@gtkx/codegen 0.21.0

package/src/writers/function.ts

@@ -0,0 +1,136 @@
+import { quote } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { arrayLiteral, indent, joinArgs } from "../dsl/emit.js";
+import { namespaceFunctionExportName } from "../dsl/identifier.js";
+import type { GirFunction } from "../gir/function.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import type { GirParameter } from "../gir/parameter.js";
+import { callableReferencesClassStruct } from "./class-struct-record.js";
+import { renderMethodBody, renderMethodReturnType, renderMethodSignature } from "./method.js";
+import { closureAndDestroyIndices, needsRefArg } from "./param-classify.js";
+import { renderFfiType, renderSelfFfiType, renderTrampolineType } from "./value.js";
+
+/**
+ * Renders the FFI argument list for a callable, as a TypeScript array
+ * literal suitable as the third argument to `t.fn(...)`.
+ *
+ * Includes the instance parameter (if any), every regular parameter, and
+ * the implicit `GError**` ref when `throws=1`.
+ *
+ * @param context - The module context
+ * @param fn - The callable
+ */
+const renderArgsLiteral = (context: ModuleContext, fn: GirFunction): string => {
+    const args: string[] = [];
+    const instanceOffset = fn.instance === undefined ? 0 : 1;
+    if (fn.instance !== undefined) {
+        context.addRuntimeImport("t");
+        args.push(`{ type: ${renderSelfFfiType(context, fn.instance)} }`);
+    }
+    const closureIndices = closureAndDestroyIndices(fn);
+    fn.parameters.forEach((parameter, index) => {
+        if (parameter.isVarargs) return;
+        if (closureIndices.has(index)) return;
+        const optional = parameter.direction === "in" && (parameter.nullable || parameter.optional);
+        args.push(argLiteral(context, parameter, optional, instanceOffset));
+    });
+    if (fn.throws) {
+        context.addRuntimeImport("t");
+        args.push(`{ type: t.ref(t.boxed("GError", "full", "libgobject-2.0.so.0", "g_error_get_type")) }`);
+    }
+    return arrayLiteral(args);
+};
+
+const argLiteral = (
+    context: ModuleContext,
+    parameter: GirParameter,
+    optional: boolean,
+    instanceOffset: number,
+): string => {
+    const trampoline = renderTrampolineType(context, parameter.type, parameter);
+    const inner = trampoline ?? renderFfiType(context, parameter.type, parameter.transferOwnership, instanceOffset);
+    const refWrapped = needsRefArg(context, parameter);
+    const expression = refWrapped ? `t.ref(${inner})` : inner;
+    return optional && !refWrapped ? `{ type: ${expression}, optional: true }` : `{ type: ${expression} }`;
+};
+
+/**
+ * Renders the `t.fn(library, symbol, args, returnType)` expression for a
+ * callable. Returns `undefined` when the callable cannot be bound (no C
+ * identifier or missing namespace shared-library).
+ *
+ * @param context - The module context
+ * @param fn - The callable
+ */
+export 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 args = renderArgsLiteral(context, fn);
+    const returnType = renderFfiType(
+        context,
+        fn.returnValue.type,
+        fn.returnValue.transferOwnership,
+        fn.instance === undefined ? 0 : 1,
+    );
+    return `t.fn(${joinArgs([quote(library), quote(fn.cIdentifier), args, returnType])})`;
+};
+
+/**
+ * Emits both the bound `const fooBinding = t.fn(...)` and the
+ * `export function camelName(...)` wrapper for a namespace-level callable.
+ *
+ * Silently skipped when {@link renderFnExpression} cannot bind the callable
+ * (e.g. macros, unintrospectable signatures) or when the GIR marks the
+ * callable as `introspectable="0"`.
+ *
+ * @param context - The module context
+ * @param fn - The callable
+ */
+export const emitNamespaceFunction = (context: ModuleContext, fn: GirFunction): void => {
+    if (!fn.introspectable) return;
+    if (fn.shadowedBy !== undefined) return;
+    if (callableReferencesClassStruct(context, fn)) return;
+    const expression = renderFnExpression(context, fn);
+    if (expression === undefined) return;
+    const bindingName = fn.cIdentifier;
+    if (bindingName === undefined) return;
+    context.module.appendBinding(`const ${bindingName} = ${expression};`, bindingName);
+
+    const exportName = namespaceFunctionExportName(bindingName, fn.name, context.namespace.cSymbolPrefixes);
+    const signature = renderMethodSignature(context, fn);
+    const returnType = renderMethodReturnType(context, fn);
+    const body = renderMethodBody(context, fn, { bindingExpression: bindingName, isStatic: true });
+    context.module.appendDeclaration(
+        `export function ${exportName}(${signature}): ${returnType} {\n${indent(body, 1)}\n}`,
+    );
+};
+
+/**
+ * Emits a namespace's self-bootstrap statements as module-load side effects:
+ * a call to its zero-argument `init` entry point and a `whenStopped`
+ * registration for its zero-argument `finalize` entry point.
+ *
+ * GTK-style libraries expose top-level `init`/`finalize` functions (`gtk_init`,
+ * `adw_init`, `gtk_source_finalize`, …). Calling `init()` as the module is
+ * imported initializes the library's runtime before any of its types are
+ * touched — without it a `Gdk` display lookup can run before `gtk_init`.
+ * Deferring `finalize` to `whenStopped` runs it during shutdown.
+ *
+ * @param context - The module context
+ * @param namespace - The namespace being generated
+ */
+export const emitNamespaceBootstrap = (context: ModuleContext, namespace: GirNamespace): void => {
+    for (const fn of namespace.functions) {
+        if (fn.parameters.length > 0) continue;
+        if (!fn.introspectable || fn.shadowedBy !== undefined || fn.cIdentifier === undefined) continue;
+        const exportName = namespaceFunctionExportName(fn.cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
+        if (fn.name === "init") {
+            context.module.appendRegistration(`${exportName}();`);
+        } else if (fn.name === "finalize") {
+            context.module.imports.addNamed("@gtkx/ffi", "whenStopped");
+            context.module.appendRegistration(`whenStopped().then(${exportName});`);
+        }
+    }
+};

package/src/writers/gtype-binding.ts

@@ -0,0 +1,48 @@
+import { quote } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+
+const TYPE_FROM_NAME_BINDING = "g_type_from_name";
+const TYPE_FROM_NAME_LIB = "libgobject-2.0.so.0";
+
+/**
+ * Renders the JS expression that resolves a class's `GType`, appending any
+ * required `t.fn` bindings to the module.
+ *
+ * For regular get-type symbols (`g_object_get_type`, `g_array_get_type`, …)
+ * the helper appends a `t.fn(...)` binding for the symbol and returns the bare
+ * function reference (`g_object_get_type`), which the runtime invokes once. For
+ * the GIR sentinel `"intern"` — used on `GVariant` and a few other types whose
+ * `GType` is registered intrinsically — it appends a binding for
+ * `g_type_from_name` and returns a `() => g_type_from_name("…")` thunk. Returns
+ * `undefined` when neither path is available.
+ *
+ * @param context - The module context
+ * @param getType - The C symbol name or the GIR sentinel `"intern"`
+ * @param glibTypeName - The GLib type name (for `"intern"` get-types)
+ */
+export const renderGetTypeReference = (
+    context: ModuleContext,
+    getType: string,
+    glibTypeName: string | undefined,
+): string | undefined => {
+    if (getType === "intern" || getType === "") {
+        if (glibTypeName === undefined) return undefined;
+        appendGTypeFromNameBinding(context);
+        return `() => ${TYPE_FROM_NAME_BINDING}(${quote(glibTypeName)})`;
+    }
+    appendGetTypeBinding(context, getType);
+    return getType;
+};
+
+const appendGetTypeBinding = (context: ModuleContext, getType: string): void => {
+    const lib = context.namespace.sharedLibrary ?? "";
+    const expression = `t.fn(${quote(lib)}, ${quote(getType)}, [], t.uint64)`;
+    context.module.appendBinding(`const ${getType} = ${expression};`, getType);
+};
+
+const appendGTypeFromNameBinding = (context: ModuleContext): void => {
+    const expression =
+        `t.fn(${quote(TYPE_FROM_NAME_LIB)}, ${quote(TYPE_FROM_NAME_BINDING)}, ` +
+        `[{ type: t.string("borrowed") }], t.uint64)`;
+    context.module.appendBinding(`const ${TYPE_FROM_NAME_BINDING} = ${expression};`, TYPE_FROM_NAME_BINDING);
+};

package/src/writers/inheritance.ts

@@ -0,0 +1,104 @@
+import { toCamelCase, toIdentifier } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import type { GirClass } from "../gir/class.js";
+import type { GirProperty } from "../gir/property.js";
+import { type ResolvedQualifiedClass, resolveQualifiedClass, splitQualifiedName } from "../gir/qualified-name.js";
+import { qualifyTypeRef } from "../gir/qualify.js";
+
+/**
+ * A directly-implemented interface resolved to its declaration and the
+ * namespace that declares it.
+ */
+export type ResolvedInterface = {
+    readonly klass: GirClass;
+    readonly namespaceName: string;
+};
+
+/**
+ * Resolves an `<implements>` entry to its `<interface>` declaration.
+ *
+ * Returns `undefined` when the name resolves to a non-interface entity or
+ * cannot be resolved at all.
+ *
+ * @param context - The module context
+ * @param name - The (possibly cross-namespace) interface name
+ */
+export const resolveImplementedInterface = (
+    context: ModuleContext,
+    name: string,
+    defaultNamespace: string = context.namespace.name,
+): ResolvedInterface | undefined => {
+    const { namespaceName, typeName } = splitQualifiedName(name, defaultNamespace);
+    const resolved = context.repository.resolveNamed(namespaceName, typeName);
+    if (resolved === undefined || resolved.kind !== "interface") return undefined;
+    return { klass: resolved.value, namespaceName: resolved.namespace.name };
+};
+
+/**
+ * Invokes `visit` for each ancestor class of `klass`, nearest first.
+ *
+ * Walks the same-namespace and cross-namespace parent chain, stopping at the
+ * first unresolved parent or a cycle. Each ancestor is reported together with
+ * the namespace it was resolved through so callers can qualify its references.
+ *
+ * @param context - The module context
+ * @param klass - The class whose ancestors to visit
+ * @param visit - Callback invoked once per resolved ancestor
+ */
+export const forEachAncestor = (
+    context: ModuleContext,
+    klass: GirClass,
+    visit: (ancestor: ResolvedQualifiedClass) => void,
+): void => {
+    const visited = new Set<string>();
+    let current =
+        klass.parent === undefined ? undefined : { name: klass.parent, defaultNamespace: context.namespace.name };
+    while (current !== undefined) {
+        const resolved = resolveQualifiedClass(context.repository, current.name, current.defaultNamespace);
+        if (resolved === undefined) break;
+        const key = `${resolved.namespaceName}.${resolved.klass.name}`;
+        if (visited.has(key)) break;
+        visited.add(key);
+        visit(resolved);
+        current = resolved.klass.parent
+            ? { name: resolved.klass.parent, defaultNamespace: resolved.namespaceName }
+            : undefined;
+    }
+};
+
+/**
+ * Collects the properties contributed by a class's directly-implemented
+ * interfaces that are not already declared on the class itself or inherited
+ * from an ancestor (or an ancestor-implemented interface).
+ *
+ * Each returned property carries its references re-rooted to the interface's
+ * namespace so the class writer can emit its accessor and constructor prop
+ * as if the property had been authored on the class.
+ *
+ * @param context - The module context
+ * @param klass - The implementing class
+ */
+export const collectInterfaceProperties = (context: ModuleContext, klass: GirClass): readonly GirProperty[] => {
+    const seen = new Set<string>();
+    for (const property of klass.properties) seen.add(toIdentifier(toCamelCase(property.name)));
+    forEachAncestor(context, klass, (ancestor) => {
+        for (const property of ancestor.klass.properties) seen.add(toIdentifier(toCamelCase(property.name)));
+        for (const implementName of ancestor.klass.implements) {
+            const iface = resolveImplementedInterface(context, implementName, ancestor.namespaceName);
+            if (iface === undefined) continue;
+            for (const property of iface.klass.properties) seen.add(toIdentifier(toCamelCase(property.name)));
+        }
+    });
+    const result: GirProperty[] = [];
+    for (const implementName of klass.implements) {
+        const iface = resolveImplementedInterface(context, implementName);
+        if (iface === undefined) continue;
+        for (const property of iface.klass.properties) {
+            const name = toIdentifier(toCamelCase(property.name));
+            if (seen.has(name)) continue;
+            seen.add(name);
+            result.push({ ...property, type: qualifyTypeRef(property.type, iface.namespaceName) });
+        }
+    }
+    return result;
+};

package/src/writers/interface.ts

@@ -0,0 +1,168 @@
+import { toPascalCase } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirClass } from "../gir/class.js";
+import type { GirFunction } from "../gir/function.js";
+import { splitQualifiedName } from "../gir/qualified-name.js";
+import { qualifyFunction } from "../gir/qualify.js";
+import {
+    appendMethodBinding,
+    type Callables,
+    dedupeCallables,
+    emitBindings,
+    indexMethodsByName,
+    renderInstanceMethod,
+    renderPlainTypeMembers,
+} from "./callables.js";
+import { renderVfuncMetadata } from "./class-struct.js";
+import { renderGetTypeReference } from "./gtype-binding.js";
+import { resolveImplementedInterface } from "./inheritance.js";
+import { methodExportName } from "./method.js";
+import { renderPropertyAccessor } from "./property-accessor.js";
+import { appendNativeClassRegistration } from "./registration.js";
+import { renderSignalMembers } from "./signal.js";
+
+/**
+ * Emits a class declaration for a `<interface>` element.
+ *
+ * Interfaces have no GIR parent — they extend the GObject base
+ * (`GObject.Object`) in the generated output because every implementor is
+ * itself a GObject. Methods, static functions, and constructors are
+ * surfaced on the interface class just like a regular class so JS callers
+ * can dispatch them directly on interface-typed values.
+ *
+ * @param context - The module context
+ * @param iface - The interface to emit
+ */
+export const emitInterface = (context: ModuleContext, iface: GirClass): void => {
+    if (!iface.introspectable) return;
+    if (iface.name.length === 0) return;
+    const className = toPascalCase(iface.name);
+    const callables: Callables = {
+        constructors: dedupeCallables(iface.constructors),
+        functions: dedupeCallables(iface.functions),
+        methods: dedupeCallables(iface.methods),
+    };
+    emitBindings(context, callables);
+
+    const parent = resolveInterfaceParent(context);
+    const members = renderInterfaceMembers(context, iface, callables);
+    const body = members.map((member) => indent(member, 1)).join("\n\n");
+    context.module.appendDeclaration(`export class ${className} extends ${parent} {\n${body}\n}`);
+
+    const prerequisiteRefs = iface.prerequisites
+        .map((name) => resolvePrerequisiteReference(context, name))
+        .filter((entry): entry is string => entry !== undefined);
+    if (prerequisiteRefs.length > 0) {
+        context.module.appendDeclaration(`export interface ${className} extends ${prerequisiteRefs.join(", ")} {}`);
+    }
+
+    appendInterfaceRegistrations(context, iface, className);
+};
+
+const renderInterfaceMembers = (context: ModuleContext, iface: GirClass, callables: Callables): readonly string[] => {
+    const className = toPascalCase(iface.name);
+    const { members, claimedNames } = renderPlainTypeMembers({
+        context,
+        className,
+        callables,
+        hasGType: true,
+        wrap: "interface",
+    });
+    appendPrerequisiteMethods(context, iface, members, claimedNames);
+    const methodByName = indexMethodsByName(callables.methods);
+    for (const property of iface.properties) {
+        const block = renderPropertyAccessor(context, property, claimedNames, methodByName);
+        if (block !== undefined) members.push(block);
+    }
+    members.push(...renderSignalMembers(context, iface));
+    return members;
+};
+
+/**
+ * Copies the methods of an interface's transitive prerequisite interfaces onto
+ * the interface wrapper class.
+ *
+ * A `Gtk.SelectionModel` value is also a `Gio.ListModel`, but the JS wrapper
+ * only exposes `getNItems`/`getItem` if those prerequisite methods are emitted
+ * on the wrapper. Each prerequisite interface's methods are re-rooted to its
+ * namespace, bound, and emitted as direct members; names already provided by
+ * the interface itself are skipped.
+ *
+ * @param context - The module context
+ * @param iface - The interface being emitted
+ * @param members - The accumulating member list
+ * @param claimedNames - Names already emitted on the interface body
+ */
+const appendPrerequisiteMethods = (
+    context: ModuleContext,
+    iface: GirClass,
+    members: string[],
+    claimedNames: Set<string>,
+): void => {
+    for (const method of collectPrerequisiteMethods(context, iface)) {
+        const name = methodExportName(method);
+        if (name === "constructor" || claimedNames.has(name)) continue;
+        const block = renderInstanceMethod(context, method);
+        if (block === undefined) continue;
+        appendMethodBinding(context, method);
+        members.push(block);
+        claimedNames.add(name);
+    }
+};
+
+const collectPrerequisiteMethods = (context: ModuleContext, iface: GirClass): readonly GirFunction[] => {
+    const result: GirFunction[] = [];
+    const visited = new Set<string>();
+    const seen = new Set<string>();
+    for (const method of iface.methods) {
+        if (method.introspectable) seen.add(methodExportName(method));
+    }
+    const visit = (klass: GirClass, namespaceName: string): void => {
+        for (const prerequisiteName of klass.prerequisites) {
+            const prerequisite = resolveImplementedInterface(context, prerequisiteName, namespaceName);
+            if (prerequisite === undefined) continue;
+            const key = `${prerequisite.namespaceName}.${prerequisite.klass.name}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+            for (const method of dedupeCallables(prerequisite.klass.methods)) {
+                const name = methodExportName(method);
+                if (seen.has(name)) continue;
+                seen.add(name);
+                result.push(qualifyFunction(method, prerequisite.namespaceName));
+            }
+            visit(prerequisite.klass, prerequisite.namespaceName);
+        }
+    };
+    visit(iface, context.namespace.name);
+    return result;
+};
+
+const appendInterfaceRegistrations = (context: ModuleContext, iface: GirClass, className: string): void => {
+    const getTypeRef =
+        iface.glibGetType === undefined
+            ? undefined
+            : renderGetTypeReference(context, iface.glibGetType, iface.glibTypeName);
+    appendNativeClassRegistration(context, {
+        className,
+        role: "interface",
+        getTypeRef,
+        vfuncs: renderVfuncMetadata(context, iface),
+    });
+};
+
+const resolveInterfaceParent = (context: ModuleContext): string => {
+    if (context.namespace.name === "GObject") return "Object";
+    const alias = context.addCrossNamespaceImport("GObject");
+    return `${alias}.Object`;
+};
+
+const resolvePrerequisiteReference = (context: ModuleContext, name: string): string | undefined => {
+    const { namespaceName, typeName } = splitQualifiedName(name, context.namespace.name);
+    const resolved = context.repository.resolveNamed(namespaceName, typeName);
+    if (resolved === undefined) return undefined;
+    if (resolved.kind !== "interface" && resolved.kind !== "class") return undefined;
+    if (namespaceName === context.namespace.name) return toPascalCase(typeName);
+    const alias = context.addCrossNamespaceImport(namespaceName);
+    return `${alias}.${toPascalCase(typeName)}`;
+};