@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/gir/namespace.ts

@@ -1,118 +1,139 @@
-import { boxedFromNode, boxedKind, type GirBoxed } from "./boxed.js";
+import type { ParseContext, TypeId } from "./type-id.js";
 import { callbackFromNode, type GirCallback } from "./callback.js";
 import { classFromNode, type GirClass } from "./class.js";
 import { enumFromNode, type GirEnum } from "./enum.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, childrenOf, type RawNode } from "./parse.js";
-import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
-
-/** A `<constant>` declaration at namespace level. */
-export type GirConstant = {
-    readonly name: string;
-    readonly cType: string | undefined;
-    readonly cIdentifier: string | undefined;
-    /** Constant value as the raw string from GIR. */
-    readonly value: string;
-    readonly type: GirTypeRef | undefined;
+import { attr, getChild, getChildren, getDoc, nameAttr, type RawNode } from "./parse.js";
+import { type GirRecord, isVtableRecord, recordFromNode } from "./record.js";
+import { typeRefFromNode } from "./type-ref.js";
+
+type GirConstant = {
+    name: string;
+    doc: string | undefined;
+    value: string;
+    type: TypeId | undefined;
 };
 
-/** A `<alias>` declaration at namespace level. */
-export type GirAlias = {
-    readonly name: string;
-    readonly target: GirTypeRef | undefined;
+type GirAlias = {
+    name: string;
+    doc: string | undefined;
+    cType: string | undefined;
+    target: TypeId | undefined;
+    targetCType: string | undefined;
 };
 
-/**
- * A single namespace loaded from one `.gir` file.
- *
- * The class lives in `namespace.ts` (mutable holder) because populating it
- * involves walking the raw XML tree once, materialising each construct.
- * After construction the public surface is read-only by convention.
- */
-export type GirNamespace = {
-    /** Namespace name (e.g. `"Gtk"`). */
-    readonly name: string;
-    /** Namespace version (e.g. `"4.0"`). */
-    readonly version: string;
-    /** `Name-Version` identifier (e.g. `"Gtk-4.0"`). */
-    readonly identifier: string;
-    /** Comma-separated `shared-library` value (passed verbatim to `t.fn(...)`). */
-    readonly sharedLibrary: string | undefined;
-    /** GIR `c:identifier-prefixes` (used to strip type prefixes). */
-    readonly cIdentifierPrefixes: readonly string[];
-    /** GIR `c:symbol-prefixes` (used to strip function prefixes). */
-    readonly cSymbolPrefixes: readonly string[];
-    /** Other namespaces referenced via `<include>`. */
-    readonly includes: readonly NamespaceInclude[];
-    readonly classes: readonly GirClass[];
-    readonly interfaces: readonly GirClass[];
-    readonly boxeds: readonly GirBoxed[];
-    readonly enums: readonly GirEnum[];
-    readonly callbacks: readonly GirCallback[];
-    readonly functions: readonly GirFunction[];
-    readonly constants: readonly GirConstant[];
-    readonly aliases: readonly GirAlias[];
+type GirNamespace = {
+    id: number;
+    name: string;
+    sharedLibrary: string | undefined;
+    cSymbolPrefixes: string[];
+    classes: GirClass[];
+    interfaces: GirClass[];
+    records: GirRecord[];
+    enums: GirEnum[];
+    callbacks: GirCallback[];
+    functions: GirFunction[];
+    constants: GirConstant[];
+    aliases: GirAlias[];
 };
 
-/** A `<include>` entry pointing at another namespace identifier. */
 type NamespaceInclude = {
-    readonly name: string;
-    readonly version: string;
+    name: string;
+    version: string;
+};
+
+type NamespaceHeader = {
+    name: string;
+    sharedLibrary: string | undefined;
+    cSymbolPrefixes: string[];
+    includes: NamespaceInclude[];
+    namespaceNode: RawNode;
 };
 
-/**
- * Builds a {@link GirNamespace} from a parsed `<repository>` root.
- *
- * @param repositoryNode - The raw `<repository>` element returned by `parseGirFile`
- */
-export const namespaceFromRepository = (repositoryNode: RawNode): GirNamespace => {
-    const includes = childrenOf(repositoryNode, "include").map<NamespaceInclude>((include) => ({
-        name: attr(include, "name") ?? "",
+const namespaceDirectory = (namespace: Pick<GirNamespace, "name">): string => namespace.name.toLowerCase();
+
+const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
+    const includes = getChildren(repositoryNode, "include").map<NamespaceInclude>((include) => ({
+        name: nameAttr(include),
         version: attr(include, "version") ?? "",
     }));
-    const namespaceNode = childrenOf(repositoryNode, "namespace")[0];
+
+    const namespaceNode = getChildren(repositoryNode, "namespace")[0];
+
     if (namespaceNode === undefined) {
         throw new Error("GIR repository has no <namespace> child");
     }
-    const name = attr(namespaceNode, "name") ?? "";
-    const version = attr(namespaceNode, "version") ?? "";
+
     return {
-        name,
-        version,
-        identifier: `${name}-${version}`,
+        name: nameAttr(namespaceNode),
         sharedLibrary: attr(namespaceNode, "shared-library"),
-        cIdentifierPrefixes: splitPrefixes(attr(namespaceNode, "c:identifier-prefixes")),
         cSymbolPrefixes: splitPrefixes(attr(namespaceNode, "c:symbol-prefixes")),
         includes,
-        classes: childrenOf(namespaceNode, "class").map((klass) => classFromNode(klass, false)),
-        interfaces: childrenOf(namespaceNode, "interface").map((iface) => classFromNode(iface, true)),
-        boxeds: collectBoxeds(namespaceNode),
-        enums: collectEnums(namespaceNode),
-        callbacks: childrenOf(namespaceNode, "callback").map(callbackFromNode),
-        functions: childrenOf(namespaceNode, "function").map((fn) => functionFromNode(fn, "function")),
-        constants: childrenOf(namespaceNode, "constant").map((constant) => ({
-            name: attr(constant, "name") ?? "",
-            cType: attr(constant, "c:type"),
-            cIdentifier: attr(constant, "c:identifier"),
-            value: attr(constant, "value") ?? "",
-            type: typeRefFromSlot(constant),
-        })),
-        aliases: childrenOf(namespaceNode, "alias").map((alias) => ({
-            name: attr(alias, "name") ?? "",
-            target: typeRefFromSlot(alias),
-        })),
+        namespaceNode,
     };
 };
 
-const splitPrefixes = (raw: string | undefined): readonly string[] =>
+const createNamespaceShell = (header: NamespaceHeader, id: number): GirNamespace => ({
+    id,
+    name: header.name,
+    sharedLibrary: header.sharedLibrary,
+    cSymbolPrefixes: header.cSymbolPrefixes,
+    classes: [],
+    interfaces: [],
+    records: [],
+    enums: [],
+    callbacks: [],
+    functions: [],
+    constants: [],
+    aliases: [],
+});
+
+const populateNamespaceBody = (shell: GirNamespace, namespaceNode: RawNode, context: ParseContext): void => {
+    shell.classes = getChildren(namespaceNode, "class").map((klass) => classFromNode(klass, false, context));
+    shell.interfaces = getChildren(namespaceNode, "interface").map((iface) => classFromNode(iface, true, context));
+    shell.records = collectRecords(namespaceNode, context);
+    shell.enums = collectEnums(namespaceNode);
+    shell.callbacks = getChildren(namespaceNode, "callback").map((callback) => callbackFromNode(callback, context));
+    shell.functions = getChildren(namespaceNode, "function").map((fn) => functionFromNode(fn, context));
+
+    shell.constants = getChildren(namespaceNode, "constant").map((constant) => ({
+        name: nameAttr(constant),
+        doc: getDoc(constant),
+        value: attr(constant, "value") ?? "",
+        type: typeRefFromNode(constant, context),
+    }));
+
+    shell.aliases = getChildren(namespaceNode, "alias").map((alias) => ({
+        name: nameAttr(alias),
+        doc: getDoc(alias),
+        cType: attr(alias, "c:type"),
+        target: typeRefFromNode(alias, context),
+        targetCType: attr(getChild(alias, "type"), "c:type"),
+    }));
+};
+
+const splitPrefixes = (raw: string | undefined): string[] =>
     (raw ?? "").split(",").filter((prefix) => prefix.length > 0);
 
-const collectBoxeds = (namespaceNode: RawNode): readonly GirBoxed[] => [
-    ...childrenOf(namespaceNode, "record").map((record) => boxedFromNode(record, boxedKind(record), false)),
-    ...childrenOf(namespaceNode, "union").map((union) => boxedFromNode(union, boxedKind(union), true)),
+const collectRecords = (namespaceNode: RawNode, context: ParseContext): GirRecord[] => [
+    ...getChildren(namespaceNode, "record").map((record) =>
+        recordFromNode(record, isVtableRecord(record), false, context),
+    ),
+    ...getChildren(namespaceNode, "union").map((union) => recordFromNode(union, isVtableRecord(union), true, context)),
 ];
 
-const collectEnums = (namespaceNode: RawNode) => [
-    ...childrenOf(namespaceNode, "enumeration").map((enumeration) => enumFromNode(enumeration, "enumeration")),
-    ...childrenOf(namespaceNode, "bitfield").map((bitfield) => enumFromNode(bitfield, "bitfield")),
+const collectEnums = (namespaceNode: RawNode): GirEnum[] => [
+    ...getChildren(namespaceNode, "enumeration").map((enumeration) => enumFromNode(enumeration, "enumeration")),
+    ...getChildren(namespaceNode, "bitfield").map((bitfield) => enumFromNode(bitfield, "bitfield")),
 ];
+
+export {
+    namespaceDirectory,
+    parseNamespaceHeader,
+    createNamespaceShell,
+    populateNamespaceBody,
+    type GirConstant,
+    type GirAlias,
+    type GirNamespace,
+    type NamespaceHeader,
+};

package/src/gir/nullable-overrides.ts

@@ -0,0 +1,5 @@
+const PARAMETERS_MISSING_NULLABLE_ANNOTATION: Map<string, string[]> = new Map([
+    ["gtk_fixed_layout_child_set_transform", ["transform"]],
+]);
+
+export { PARAMETERS_MISSING_NULLABLE_ANNOTATION };

package/src/gir/parameter.ts

@@ -1,120 +1,129 @@
-import { attr, attrBool, childOf, type RawNode } from "./parse.js";
-import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+import type { ParseContext, TypeId } from "./type-id.js";
+import {
+    attr,
+    getChild,
+    getChildren,
+    getDoc,
+    intAttr,
+    isAttrTrue,
+    nameAttr,
+    parseEnumAttr,
+    type RawNode,
+} from "./parse.js";
+import { typeRefFromNode } from "./type-ref.js";
 
-/** Direction of a `<parameter>` (`in`, `out`, `inout`). */
 type ParameterDirection = "in" | "out" | "inout";
-
-/**
- * Lifetime conveyed by `transfer-ownership`. Mirrors the GIR vocabulary one
- * for one; the marshal layer translates to the runtime's `Ownership` set.
- */
-export type ParameterTransfer = "none" | "full" | "container";
-
-/** Lifetime of a callback parameter (`scope=…`). */
+type ParameterTransfer = "none" | "full" | "container";
 type CallbackScope = "call" | "notified" | "async" | "forever";
 
-/**
- * A `<parameter>` or `<instance-parameter>` of a callable.
- *
- * Only the bits the FFI writers actually look at are retained; the original
- * raw node is dropped so the domain model is self-describing.
- */
-export type GirParameter = {
-    /** Parameter name as authored in GIR (often snake_case). */
-    readonly name: string;
-    /** Typed slot of the parameter, or `undefined` for `<varargs/>`. */
-    readonly type: GirTypeRef | undefined;
-    readonly direction: ParameterDirection;
-    readonly transferOwnership: ParameterTransfer;
-    readonly nullable: boolean;
-    readonly optional: boolean;
-    /** `caller-allocates="1"` — used in out parameters that fill a caller buffer. */
-    readonly callerAllocates: boolean;
-    /** Lifetime of a callback parameter (defined only when the parameter is a callback). */
-    readonly scope: CallbackScope | undefined;
-    /** Index of the paired `gpointer user_data` parameter in the C signature. */
-    readonly closureIndex: number | undefined;
-    /** Index of the paired `GDestroyNotify` parameter in the C signature. */
-    readonly destroyIndex: number | undefined;
-    /** `true` for `<instance-parameter>` (the implicit `self` of a method). */
-    readonly isInstance: boolean;
-    /** `<varargs/>` parameter; not marshalable. */
-    readonly isVarargs: boolean;
+type GirParameter = {
+    name: string;
+    type: TypeId | undefined;
+    direction: ParameterDirection;
+    transferOwnership: ParameterTransfer;
+    nullable: boolean;
+    optional: boolean;
+    callerAllocates: boolean;
+    scope: CallbackScope | undefined;
+    closureIndex: number | undefined;
+    destroyIndex: number | undefined;
+    isVarargs: boolean;
 };
 
-/**
- * Builds a {@link GirParameter} from a `<parameter>` or `<instance-parameter>`.
- *
- * @param node - The XML element
- * @param isInstance - Whether the source element was `<instance-parameter>`
- */
-export const parameterFromNode = (node: RawNode, isInstance: boolean): GirParameter => {
-    const direction = (attr(node, "direction") ?? "in") as ParameterDirection;
-    const transferOwnership = (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer;
-    const closure = attr(node, "closure");
-    const destroy = attr(node, "destroy");
-    return {
-        name: attr(node, "name") ?? "",
-        type: typeRefFromSlot(node),
-        direction,
-        transferOwnership,
-        nullable: attrBool(node, "nullable") || attrBool(node, "allow-none"),
-        optional: attrBool(node, "optional"),
-        callerAllocates: attrBool(node, "caller-allocates"),
-        scope: attr(node, "scope") as CallbackScope | undefined,
-        closureIndex: closure === undefined ? undefined : Number.parseInt(closure, 10),
-        destroyIndex: destroy === undefined ? undefined : Number.parseInt(destroy, 10),
-        isInstance,
-        isVarargs: childOf(node, "varargs") !== undefined,
-    };
+type GirReturnValue = {
+    type: TypeId | undefined;
+    transferOwnership: ParameterTransfer;
+    nullable: boolean;
+    skip: boolean;
+};
+
+type GirCallable = {
+    name: string;
+    doc: string | undefined;
+    parameters: GirParameter[];
+    returnValue: GirReturnValue;
+    throws: boolean;
+    introspectable: boolean;
 };
 
-/**
- * Whether a parameter is a pure out-parameter: `direction="out"` and not
- * caller-allocated, so it marshals through a `{ value }` cell the callee writes into.
- *
- * @param parameter - The parameter to test
- */
-export const isOutParameter = (parameter: GirParameter): boolean =>
+const DIRECTIONS: Set<ParameterDirection> = new Set(["in", "out", "inout"]);
+const TRANSFERS: Set<ParameterTransfer> = new Set(["none", "full", "container"]);
+const SCOPES: Set<CallbackScope> = new Set(["call", "notified", "async", "forever"]);
+
+const transferOwnership = (node: RawNode): ParameterTransfer =>
+    parseEnumAttr(attr(node, "transfer-ownership"), TRANSFERS, "none", "transfer-ownership");
+
+// `allow-none` is the legacy spelling of two different attributes: on an in-parameter it means the
+// value may be NULL (`nullable`), but on an out-parameter it means the caller may pass a NULL
+// location (`optional`). Folding it into `nullable` for an out-parameter would claim the returned
+// value can be null for the 494 out-parameters across the installed GIRs that only say `allow-none`.
+const isInDirection = (node: RawNode): boolean =>
+    parseEnumAttr(attr(node, "direction"), DIRECTIONS, "in", "direction") === "in";
+
+const hasNullableAttr = (node: RawNode): boolean =>
+    isAttrTrue(node, "nullable") || (isInDirection(node) && isAttrTrue(node, "allow-none"));
+
+const hasOptionalAttr = (node: RawNode): boolean =>
+    isAttrTrue(node, "optional") || (!isInDirection(node) && isAttrTrue(node, "allow-none"));
+
+const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter => ({
+    name: nameAttr(node),
+    type: typeRefFromNode(node, context),
+    direction: parseEnumAttr(attr(node, "direction"), DIRECTIONS, "in", "direction"),
+    transferOwnership: transferOwnership(node),
+    nullable: hasNullableAttr(node),
+    optional: hasOptionalAttr(node),
+    callerAllocates: isAttrTrue(node, "caller-allocates"),
+    scope: parseEnumAttr(attr(node, "scope"), SCOPES, undefined, "scope"),
+    closureIndex: intAttr(node, "closure"),
+    destroyIndex: intAttr(node, "destroy"),
+    isVarargs: getChild(node, "varargs") !== undefined,
+});
+
+const isOutParameter = (parameter: GirParameter): boolean =>
     parameter.direction === "out" && !parameter.callerAllocates;
 
-/**
- * Whether a parameter is a caller-allocated out-parameter: `direction="out"`
- * with `caller-allocates="1"`, passed as a pre-built handle the callee fills
- * in place rather than through a `{ value }` cell.
- *
- * @param parameter - The parameter to test
- */
-export const isCallerAllocatedOut = (parameter: GirParameter): boolean =>
+const isCallerAllocatedOut = (parameter: GirParameter): boolean =>
     parameter.direction === "out" && parameter.callerAllocates;
 
-/**
- * Whether a parameter is an inout parameter (`direction="inout"`).
- *
- * @param parameter - The parameter to test
- */
-export const isInoutParameter = (parameter: GirParameter): boolean => parameter.direction === "inout";
-
-/** A `<return-value>` plus its inferred type and transfer settings. */
-export type GirReturnValue = {
-    readonly type: GirTypeRef | undefined;
-    readonly transferOwnership: ParameterTransfer;
-    readonly nullable: boolean;
-};
+const isInoutParameter = (parameter: GirParameter): boolean => parameter.direction === "inout";
 
-/**
- * Builds a {@link GirReturnValue} from a `<return-value>` element, or returns a
- * void return when the element is missing.
- *
- * @param node - The `<return-value>` element, or `undefined`
- */
-export const returnValueFromNode = (node: RawNode | undefined): GirReturnValue => {
+const returnValueFromNode = (node: RawNode | undefined, context: ParseContext): GirReturnValue => {
     if (node === undefined) {
-        return { type: undefined, transferOwnership: "none", nullable: false };
+        return { type: undefined, transferOwnership: "none", nullable: false, skip: false };
     }
+
+    return {
+        type: typeRefFromNode(node, context),
+        transferOwnership: transferOwnership(node),
+        nullable: hasNullableAttr(node),
+        skip: isAttrTrue(node, "skip"),
+    };
+};
+
+const parseCallable = (node: RawNode, context: ParseContext): GirCallable => {
+    const parametersNode = getChild(node, "parameters");
+    const parameterNodes = getChildren(parametersNode, "parameter");
+
     return {
-        type: typeRefFromSlot(node),
-        transferOwnership: (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer,
-        nullable: attrBool(node, "nullable") || attrBool(node, "allow-none"),
+        name: nameAttr(node),
+        doc: getDoc(node),
+        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, context)),
+        returnValue: returnValueFromNode(getChild(node, "return-value"), context),
+        throws: isAttrTrue(node, "throws"),
+        introspectable: isAttrTrue(node, "introspectable", true),
     };
 };
+
+export {
+    transferOwnership,
+    parameterFromNode,
+    isOutParameter,
+    isCallerAllocatedOut,
+    isInoutParameter,
+    parseCallable,
+    type ParameterTransfer,
+    type GirParameter,
+    type GirReturnValue,
+    type GirCallable,
+};