@gtkx/gir 0.10.5 → 0.11.0

package/dist/{parser.js → internal/parser.js}

@@ -1,10 +1,10 @@
 /**
- * GObject Introspection XML (GIR) parser module.
+ * GObject Introspection XML (GIR) parser.
  *
  * Parses GIR files to extract type information for GTK/GLib libraries.
- * Used by the code generator to create TypeScript bindings.
+ * Outputs raw GIR types that are then normalized by the normalizer.
  *
- * @packageDocumentation
+ * @internal
  */
 import { XMLParser } from "fast-xml-parser";
 const ARRAY_ELEMENT_PATHS = new Set([
@@ -57,26 +57,9 @@ const ensureArray = (value) => Array.isArray(value) ? value : [];
 /**
  * Parser for GObject Introspection XML (GIR) files.
  *
- * Converts GIR XML into structured TypeScript objects that can be used
- * for code generation. Handles all GIR elements including classes,
- * interfaces, functions, signals, properties, and type information.
- *
- * @example
- * ```tsx
- * import { GirParser } from "@gtkx/gir";
- * import { readFileSync } from "fs";
- *
- * const parser = new GirParser();
- * const xml = readFileSync("Gtk-4.0.gir", "utf-8");
- * const namespace = parser.parse(xml);
- *
- * console.log(namespace.name); // "Gtk"
- * console.log(namespace.classes.length); // Number of GTK classes
- * ```
- *
- * @see {@link GirNamespace} for the parsed output structure
+ * Converts GIR XML into raw TypeScript objects.
  */
-export class GirParser {
+export class RawGirParser {
     parser;
     constructor() {
         this.parser = new XMLParser({
@@ -90,26 +73,7 @@ export class GirParser {
         });
     }
     /**
-     * Parses a GIR XML string into a structured namespace object.
-     *
-     * @param girXml - The raw XML content of a GIR file
-     * @returns A parsed namespace containing all type information
-     * @throws Error if the XML is missing required repository or namespace elements
-     *
-     * @example
-     * ```tsx
-     * const namespace = parser.parse(girXml);
-     *
-     * // Access parsed classes
-     * for (const cls of namespace.classes) {
-     *   console.log(`Class: ${cls.name}, Parent: ${cls.parent}`);
-     * }
-     *
-     * // Access parsed functions
-     * for (const fn of namespace.functions) {
-     *   console.log(`Function: ${fn.name} -> ${fn.returnType.name}`);
-     * }
-     * ```
+     * Parses a GIR XML string into a raw namespace object.
      */
     parse(girXml) {
         const parsed = this.parser.parse(girXml);
@@ -153,7 +117,7 @@ export class GirParser {
         return classes.map((cls) => ({
             name: String(cls["@_name"] ?? ""),
             cType: String(cls["@_c:type"] ?? cls["@_glib:type-name"] ?? ""),
-            parent: String(cls["@_parent"] ?? ""),
+            parent: cls["@_parent"] ? String(cls["@_parent"]) : undefined,
             abstract: cls["@_abstract"] === "1",
             glibTypeName: cls["@_glib:type-name"] ? String(cls["@_glib:type-name"]) : undefined,
             glibGetType: cls["@_glib:get-type"] ? String(cls["@_glib:get-type"]) : undefined,
@@ -202,6 +166,7 @@ export class GirParser {
             .filter((method) => method["@_introspectable"] !== "0")
             .map((method) => {
             const returnValue = method["return-value"];
+            const finishFunc = method["@_glib:finish-func"];
             return {
                 name: String(method["@_name"] ?? ""),
                 cIdentifier: String(method["@_c:identifier"] ?? ""),
@@ -212,6 +177,7 @@ export class GirParser {
                 throws: method["@_throws"] === "1",
                 doc: extractDoc(method),
                 returnDoc: returnValue ? extractDoc(returnValue) : undefined,
+                finishFunc: finishFunc || undefined,
             };
         });
     }
@@ -304,20 +270,13 @@ export class GirParser {
             return { name: "void" };
         }
         const typeName = typeNode["@_name"] ? String(typeNode["@_name"]) : undefined;
-        if (typeName === "GLib.List" || typeName === "GLib.SList") {
-            const innerType = (typeNode.type ?? typeNode.array);
-            return {
-                name: "array",
-                cType: typeNode["@_c:type"] ? String(typeNode["@_c:type"]) : undefined,
-                isArray: true,
-                elementType: innerType ? this.parseType(innerType) : undefined,
-            };
+        const cType = typeNode["@_c:type"] ? String(typeNode["@_c:type"]) : undefined;
+        const containerResult = this.parseGLibContainerType(typeName, typeNode, cType);
+        if (containerResult) {
+            return containerResult;
         }
         if (typeName) {
-            return {
-                name: typeName,
-                cType: typeNode["@_c:type"] ? String(typeNode["@_c:type"]) : undefined,
-            };
+            return { name: typeName, cType };
         }
         const isArrayNode = typeNode.type ||
             typeNode["@_zero-terminated"] !== undefined ||
@@ -332,6 +291,56 @@ export class GirParser {
         }
         return { name: "void" };
     }
+    extractTypeParameters(typeNode) {
+        const types = [];
+        const typeChildren = typeNode.type;
+        if (Array.isArray(typeChildren)) {
+            for (const child of typeChildren) {
+                types.push(this.parseType(child));
+            }
+        }
+        else if (typeChildren) {
+            types.push(this.parseType(typeChildren));
+        }
+        return types;
+    }
+    parseGLibContainerType(typeName, typeNode, cType) {
+        if (typeName === "GLib.HashTable") {
+            const typeParams = this.extractTypeParameters(typeNode);
+            return {
+                name: "GLib.HashTable",
+                cType,
+                isArray: false,
+                containerType: "ghashtable",
+                typeParameters: typeParams.length >= 2 ? typeParams : undefined,
+                elementType: typeParams[1],
+            };
+        }
+        if (typeName === "GLib.PtrArray" || typeName === "GLib.Array") {
+            const typeParams = this.extractTypeParameters(typeNode);
+            return {
+                name: typeName,
+                cType,
+                isArray: true,
+                containerType: (typeName === "GLib.PtrArray" ? "gptrarray" : "garray"),
+                typeParameters: typeParams.length > 0 ? typeParams : undefined,
+                elementType: typeParams[0],
+            };
+        }
+        if (typeName === "GLib.List" || typeName === "GLib.SList") {
+            const innerType = (typeNode.type ?? typeNode.array);
+            const elementType = innerType ? this.parseType(innerType) : undefined;
+            return {
+                name: "array",
+                cType,
+                isArray: true,
+                containerType: (typeName === "GLib.List" ? "glist" : "gslist"),
+                typeParameters: elementType ? [elementType] : undefined,
+                elementType,
+            };
+        }
+        return null;
+    }
     parseProperties(properties) {
         if (!properties || !Array.isArray(properties)) {
             return [];
@@ -379,6 +388,9 @@ export class GirParser {
             disguised: record["@_disguised"] === "1",
             glibTypeName: record["@_glib:type-name"] ? String(record["@_glib:type-name"]) : undefined,
             glibGetType: record["@_glib:get-type"] ? String(record["@_glib:get-type"]) : undefined,
+            isGtypeStructFor: record["@_glib:is-gtype-struct-for"]
+                ? String(record["@_glib:is-gtype-struct-for"])
+                : undefined,
             fields: this.parseFields(ensureArray(record.field)),
             methods: this.parseMethods(ensureArray(record.method)),
             constructors: this.parseConstructors(ensureArray(record.constructor)),

package/dist/internal/raw-types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Raw GIR type definitions.
+ *
+ * These types represent the structure of parsed GIR XML data before normalization.
+ * They are internal to the @gtkx/gir package and not exported publicly.
+ *
+ * @internal
+ */
+import type { ContainerType } from "../types.js";
+export type { ContainerType };
+/**
+ * Represents a parsed GIR namespace (library).
+ *
+ * Contains all type definitions from a single GIR file, including
+ * classes, interfaces, functions, enums, records, and callbacks.
+ */
+export type RawNamespace = {
+    name: string;
+    version: string;
+    sharedLibrary: string;
+    cPrefix: string;
+    classes: RawClass[];
+    interfaces: RawInterface[];
+    functions: RawFunction[];
+    enumerations: RawEnumeration[];
+    bitfields: RawEnumeration[];
+    records: RawRecord[];
+    callbacks: RawCallback[];
+    constants: RawConstant[];
+    doc?: string;
+};
+/**
+ * A constant value defined in a GIR namespace.
+ */
+export type RawConstant = {
+    name: string;
+    cType: string;
+    value: string;
+    type: RawType;
+    doc?: string;
+};
+/**
+ * A callback type definition (function pointer type).
+ */
+export type RawCallback = {
+    name: string;
+    cType: string;
+    returnType: RawType;
+    parameters: RawParameter[];
+    doc?: string;
+};
+/**
+ * A GObject interface definition.
+ */
+export type RawInterface = {
+    name: string;
+    cType: string;
+    glibTypeName?: string;
+    prerequisites: string[];
+    methods: RawMethod[];
+    properties: RawProperty[];
+    signals: RawSignal[];
+    doc?: string;
+};
+/**
+ * A GObject class definition.
+ */
+export type RawClass = {
+    name: string;
+    cType: string;
+    parent?: string;
+    abstract?: boolean;
+    glibTypeName?: string;
+    glibGetType?: string;
+    cSymbolPrefix?: string;
+    implements: string[];
+    methods: RawMethod[];
+    constructors: RawConstructor[];
+    functions: RawFunction[];
+    properties: RawProperty[];
+    signals: RawSignal[];
+    doc?: string;
+};
+/**
+ * A GLib record (boxed type or struct).
+ */
+export type RawRecord = {
+    name: string;
+    cType: string;
+    opaque?: boolean;
+    disguised?: boolean;
+    glibTypeName?: string;
+    glibGetType?: string;
+    isGtypeStructFor?: string;
+    fields: RawField[];
+    methods: RawMethod[];
+    constructors: RawConstructor[];
+    functions: RawFunction[];
+    doc?: string;
+};
+/**
+ * A field within a record or class.
+ */
+export type RawField = {
+    name: string;
+    type: RawType;
+    writable?: boolean;
+    readable?: boolean;
+    private?: boolean;
+    doc?: string;
+};
+/**
+ * A method on a class, interface, or record.
+ */
+export type RawMethod = {
+    name: string;
+    cIdentifier: string;
+    returnType: RawType;
+    parameters: RawParameter[];
+    throws?: boolean;
+    doc?: string;
+    returnDoc?: string;
+    /** For async methods, the name of the corresponding finish function */
+    finishFunc?: string;
+};
+/**
+ * A constructor for a class or record.
+ */
+export type RawConstructor = {
+    name: string;
+    cIdentifier: string;
+    returnType: RawType;
+    parameters: RawParameter[];
+    throws?: boolean;
+    doc?: string;
+    returnDoc?: string;
+};
+/**
+ * A standalone function or static method.
+ */
+export type RawFunction = {
+    name: string;
+    cIdentifier: string;
+    returnType: RawType;
+    parameters: RawParameter[];
+    throws?: boolean;
+    doc?: string;
+    returnDoc?: string;
+};
+/**
+ * A parameter to a function, method, or callback.
+ */
+export type RawParameter = {
+    name: string;
+    type: RawType;
+    direction?: "in" | "out" | "inout";
+    callerAllocates?: boolean;
+    nullable?: boolean;
+    optional?: boolean;
+    scope?: "async" | "call" | "notified";
+    closure?: number;
+    destroy?: number;
+    transferOwnership?: "none" | "full" | "container";
+    doc?: string;
+};
+/**
+ * A type reference in GIR.
+ *
+ * Type names may be unqualified (e.g., "Widget") for local types
+ * or qualified (e.g., "GObject.Object") for cross-namespace references.
+ */
+export type RawType = {
+    name: string;
+    cType?: string;
+    isArray?: boolean;
+    elementType?: RawType;
+    typeParameters?: RawType[];
+    containerType?: ContainerType;
+    transferOwnership?: "none" | "full" | "container";
+    nullable?: boolean;
+};
+/**
+ * A GObject property definition.
+ */
+export type RawProperty = {
+    name: string;
+    type: RawType;
+    readable?: boolean;
+    writable?: boolean;
+    constructOnly?: boolean;
+    hasDefault?: boolean;
+    getter?: string;
+    setter?: string;
+    doc?: string;
+};
+/**
+ * A GObject signal definition.
+ */
+export type RawSignal = {
+    name: string;
+    when?: "first" | "last" | "cleanup";
+    returnType?: RawType;
+    parameters?: RawParameter[];
+    doc?: string;
+};
+/**
+ * An enumeration or bitfield definition.
+ */
+export type RawEnumeration = {
+    name: string;
+    cType: string;
+    members: RawEnumerationMember[];
+    doc?: string;
+};
+/**
+ * A member of an enumeration or bitfield.
+ */
+export type RawEnumerationMember = {
+    name: string;
+    value: string;
+    cIdentifier: string;
+    doc?: string;
+};

package/dist/internal/raw-types.js

@@ -0,0 +1,9 @@
+/**
+ * Raw GIR type definitions.
+ *
+ * These types represent the structure of parsed GIR XML data before normalization.
+ * They are internal to the @gtkx/gir package and not exported publicly.
+ *
+ * @internal
+ */
+export {};

package/dist/intrinsics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Intrinsic (primitive) types that are not namespace-qualified.
+ *
+ * These are fundamental GLib/GObject types that exist outside of any namespace.
+ * When normalizing type references, intrinsic types remain as-is rather than
+ * being qualified with a namespace prefix.
+ */
+export declare const INTRINSIC_TYPES: Set<string>;
+/**
+ * Checks if a type name is an intrinsic (primitive) type.
+ *
+ * @param typeName - The type name to check
+ * @returns True if the type is intrinsic and should not be namespace-qualified
+ */
+export declare const isIntrinsicType: (typeName: string) => boolean;
+/**
+ * String type names (utf8 and filename).
+ */
+export declare const STRING_TYPES: Set<string>;
+/**
+ * Checks if a type name is a string type.
+ */
+export declare const isStringType: (typeName: string) => boolean;
+/**
+ * Numeric type names (integers and floats).
+ */
+export declare const NUMERIC_TYPES: Set<string>;
+/**
+ * Checks if a type name is a numeric type.
+ */
+export declare const isNumericType: (typeName: string) => boolean;
+/**
+ * Void type names.
+ */
+export declare const VOID_TYPES: Set<string>;
+/**
+ * Checks if a type name is void.
+ */
+export declare const isVoidType: (typeName: string) => boolean;

package/dist/intrinsics.js

@@ -0,0 +1,122 @@
+/**
+ * Intrinsic (primitive) types that are not namespace-qualified.
+ *
+ * These are fundamental GLib/GObject types that exist outside of any namespace.
+ * When normalizing type references, intrinsic types remain as-is rather than
+ * being qualified with a namespace prefix.
+ */
+export const INTRINSIC_TYPES = new Set([
+    "void",
+    "none",
+    "gboolean",
+    "gint",
+    "gint8",
+    "gint16",
+    "gint32",
+    "gint64",
+    "gchar",
+    "gshort",
+    "glong",
+    "gssize",
+    "goffset",
+    "gintptr",
+    "guint",
+    "guint8",
+    "guint16",
+    "guint32",
+    "guint64",
+    "guchar",
+    "gushort",
+    "gulong",
+    "gsize",
+    "guintptr",
+    "gfloat",
+    "gdouble",
+    "gpointer",
+    "gconstpointer",
+    "utf8",
+    "filename",
+    "GType",
+    "GParamSpec",
+    "GVariant",
+    "int",
+    "uint",
+    "long",
+    "ulong",
+    "float",
+    "double",
+    "size_t",
+    "ssize_t",
+]);
+/**
+ * Checks if a type name is an intrinsic (primitive) type.
+ *
+ * @param typeName - The type name to check
+ * @returns True if the type is intrinsic and should not be namespace-qualified
+ */
+export const isIntrinsicType = (typeName) => {
+    return INTRINSIC_TYPES.has(typeName);
+};
+/**
+ * String type names (utf8 and filename).
+ */
+export const STRING_TYPES = new Set(["utf8", "filename"]);
+/**
+ * Checks if a type name is a string type.
+ */
+export const isStringType = (typeName) => {
+    return STRING_TYPES.has(typeName);
+};
+/**
+ * Numeric type names (integers and floats).
+ */
+export const NUMERIC_TYPES = new Set([
+    "gint",
+    "guint",
+    "gint8",
+    "guint8",
+    "gint16",
+    "guint16",
+    "gint32",
+    "guint32",
+    "gint64",
+    "guint64",
+    "gchar",
+    "guchar",
+    "gshort",
+    "gushort",
+    "glong",
+    "gulong",
+    "gsize",
+    "gssize",
+    "goffset",
+    "gintptr",
+    "guintptr",
+    "gfloat",
+    "gdouble",
+    "int",
+    "uint",
+    "long",
+    "ulong",
+    "float",
+    "double",
+    "size_t",
+    "ssize_t",
+    "GType",
+]);
+/**
+ * Checks if a type name is a numeric type.
+ */
+export const isNumericType = (typeName) => {
+    return NUMERIC_TYPES.has(typeName);
+};
+/**
+ * Void type names.
+ */
+export const VOID_TYPES = new Set(["void", "none"]);
+/**
+ * Checks if a type name is void.
+ */
+export const isVoidType = (typeName) => {
+    return VOID_TYPES.has(typeName);
+};