gobject-generator/Sources/SwiftGtkGenCore/IRModel.swift

/// A complete GIR repository, containing one or more namespaces.
///
/// Corresponds to the root `<repository>` element in a GIR XML file. A single
/// `.gir` file produces one `Repository` holding all namespaces defined within it.
public struct Repository {
    /// The namespaces contained in this repository.
    public var namespaces: [Namespace]
    /// The C header include path from `<c:include>` (e.g. `"gtk/gtk.h"`).
    public var cHeaderPath: String
    /// Link names for GIR dependencies derived from `<include>` elements.
    /// Derived at parse time from the library name and version (e.g. `"Gdk-4.0"` becomes `"gdk-4"`).
    public var includedLibraryLinks: [String]
    /// Package name from `<package>` element (e.g. `"gtk4"`).
    public var packageName: String
    /// Creates a new repository.
    /// - Parameter namespaces: The namespaces contained in this repository.
    public init(namespaces: [Namespace] = [], cHeaderPath: String = "", includedLibraryLinks: [String] = [], packageName: String = "") {
        self.namespaces = namespaces
        self.cHeaderPath = cHeaderPath
        self.includedLibraryLinks = includedLibraryLinks
        self.packageName = packageName
    }
}

/// A GIR namespace, grouping related type definitions within a repository.
///
/// Corresponds to the `<namespace>` element in a GIR XML file. A namespace
/// holds all type definitions — classes, interfaces, records, enumerations,
/// bitfields, callbacks, global functions, constants, and type aliases — that
/// belong to a single GIR namespace such as `Gtk` or `GObject`.
public struct Namespace {
    /// The namespace name, e.g. `"Gtk"`.
    public let name: String
    /// The namespace version string, e.g. `"4.0"`.
    public let version: String
    /// The shared library name from the GIR file (e.g. "libgtk-4.so.1").
    public var cSharedLibrary: String
    /// The C identifier prefix (e.g. "Gtk", "G").
    public var cIdentifierPrefix: String
    /// The GObject classes defined in this namespace.
    public var classes: [Class]
    /// The GObject interfaces defined in this namespace.
    public var interfaces: [Interface]
    /// The plain C records (structs) defined in this namespace.
    public var records: [Record]
    /// The enumerations defined in this namespace.
    public var enumerations: [Enumeration]
    /// The bitfield (flags) types defined in this namespace.
    public var bitfields: [Bitfield]
    /// The callback function types defined in this namespace.
    public var callbacks: [Callback]
    /// The global (namespace-level) functions defined in this namespace.
    public var functions: [GlobalFunction]
    /// The constants defined in this namespace.
    public var constants: [Constant]
    /// The type aliases defined in this namespace.
    public var aliases: [Alias]
    /// Creates a new namespace.
    /// - Parameters:
    ///   - name: The namespace name, e.g. `"Gtk"`.
    ///   - version: The namespace version string, e.g. `"4.0"`.
    ///   - cSharedLibrary: The shared library name (e.g. "libgtk-4.so.1").
    ///   - cIdentifierPrefix: The C identifier prefix (e.g. "Gtk", "G").
    ///   - classes: The GObject classes in the namespace.
    ///   - interfaces: The GObject interfaces in the namespace.
    ///   - records: The plain C records in the namespace.
    ///   - enumerations: The enumerations in the namespace.
    ///   - bitfields: The bitfield types in the namespace.
    ///   - callbacks: The callback types in the namespace.
    ///   - functions: The global functions in the namespace.
    ///   - constants: The constants in the namespace.
    ///   - aliases: The type aliases in the namespace.
    public init(name: String, version: String, cSharedLibrary: String = "", cIdentifierPrefix: String = "",
                classes: [Class] = [], interfaces: [Interface] = [],
                records: [Record] = [], enumerations: [Enumeration] = [], bitfields: [Bitfield] = [],
                callbacks: [Callback] = [], functions: [GlobalFunction] = [], constants: [Constant] = [],
                aliases: [Alias] = []) {
        self.name = name; self.version = version
        self.cSharedLibrary = cSharedLibrary; self.cIdentifierPrefix = cIdentifierPrefix
        self.classes = classes; self.interfaces = interfaces; self.records = records
        self.enumerations = enumerations; self.bitfields = bitfields; self.callbacks = callbacks
        self.functions = functions; self.constants = constants; self.aliases = aliases
    }
}

/// A GObject class definition.
///
/// Corresponds to the `<class>` element in a GIR XML file. Models a GObject
/// class with its parent class, implemented interfaces, constructors, methods,
/// properties, signals, and associated functions.
public struct Class {
    /// The class name, e.g. `"Widget"`.
    public let name: String
    /// The corresponding C type name, e.g. `"GtkWidget"`.
    public let cType: String
    /// The name of the parent class, or `nil` for the root `GObject` class.
    public let parent: String?
    /// Whether this class is abstract and cannot be instantiated directly.
    public var isAbstract: Bool
    /// The names of interfaces this class implements.
    public var implements: [String]
    /// The constructors for this class.
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    public var constructors: [Constructor]
    /// The methods of this class.
    public var methods: [Method]
    /// The GObject properties of this class.
    public var properties: [Property]
    /// The signals emitted by this class.
    public var signals: [Signal]
    /// The functions associated with this class.
    public var functions: [GlobalFunction]
    /// Creates a new class definition.
    /// - Parameters:
    ///   - name: The class name, e.g. `"Widget"`.
    ///   - cType: The corresponding C type name, e.g. `"GtkWidget"`.
    ///   - parent: The name of the parent class, or `nil` if root.
    ///   - isAbstract: Whether the class is abstract. Defaults to `false`.
    ///   - implements: The names of implemented interfaces. Defaults to empty.
    ///   - constructors: The constructors. Defaults to empty.
    ///   - methods: The methods. Defaults to empty.
    ///   - properties: The properties. Defaults to empty.
    ///   - signals: The signals. Defaults to empty.
    ///   - functions: The associated functions. Defaults to empty.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, parent: String?, isAbstract: Bool = false,
                implements: [String] = [], constructors: [Constructor] = [], methods: [Method] = [],
                properties: [Property] = [], signals: [Signal] = [], functions: [GlobalFunction] = [],
                doc: String? = nil) {
        self.name = name; self.cType = cType; self.parent = parent
        self.isAbstract = isAbstract; self.implements = implements
        self.constructors = constructors; self.methods = methods
        self.properties = properties; self.signals = signals; self.functions = functions
        self.doc = doc
    }
}

/// A GObject interface definition.
///
/// Corresponds to the `<interface>` element in a GIR XML file. An interface
/// declares methods, properties, and signals that implementing classes must
/// provide, along with prerequisite types that must be satisfied first.
public struct Interface {
    /// The interface name, e.g. `"Buildable"`.
    public let name: String
    /// The corresponding C type name, e.g. `"GtkBuildable"`.
    public let cType: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The methods declared by this interface.
    public var methods: [Method]
    /// The properties declared by this interface.
    public var properties: [Property]
    /// The signals declared by this interface.
    public var signals: [Signal]
    /// The prerequisite types a class must satisfy to implement this interface.
    public var prereqs: [String]
    /// Creates a new interface definition.
    /// - Parameters:
    ///   - name: The interface name.
    ///   - cType: The corresponding C type name.
    ///   - methods: The methods declared by the interface. Defaults to empty.
    ///   - properties: The properties declared by the interface. Defaults to empty.
    ///   - signals: The signals declared by the interface. Defaults to empty.
    ///   - prereqs: The prerequisite types. Defaults to empty.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, methods: [Method] = [], properties: [Property] = [],
                signals: [Signal] = [], prereqs: [String] = [], doc: String? = nil) {
        self.name = name; self.cType = cType; self.methods = methods
        self.properties = properties; self.signals = signals; self.prereqs = prereqs
        self.doc = doc
    }
}

/// A plain C record (struct) definition.
///
/// Corresponds to the `<record>` element in a GIR XML file. Records are
/// value types in C and may be opaque (no fields exposed), disguised
/// (typedef'd without `struct` keyword), or have fully accessible fields.
public struct Record {
    /// The record name.
    public let name: String
    /// The corresponding C type name.
    public let cType: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Whether the record is opaque (fields are not introspectable).
    public var isOpaque: Bool
    /// Whether the record is disguised (typedef'd without the `struct` keyword).
    public var isDisguised: Bool
    /// The fields of the record, if introspectable.
    public var fields: [Field]
    /// The methods operating on this record.
    public var methods: [Method]
    /// Creates a new record definition.
    /// - Parameters:
    ///   - name: The record name.
    ///   - cType: The corresponding C type name.
    ///   - isOpaque: Whether the record is opaque. Defaults to `false`.
    ///   - isDisguised: Whether the record is disguised. Defaults to `false`.
    ///   - fields: The fields of the record. Defaults to empty.
    ///   - methods: The record methods. Defaults to empty.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, isOpaque: Bool = false, isDisguised: Bool = false,
                fields: [Field] = [], methods: [Method] = [], doc: String? = nil) {
        self.name = name; self.cType = cType; self.isOpaque = isOpaque
        self.isDisguised = isDisguised; self.fields = fields; self.methods = methods; self.doc = doc
    }
}

/// A field within a C record.
///
/// Corresponds to the `<field>` element in a GIR XML file. Describes a named
/// member of a C struct, including its type and read/write permissions.
public struct Field {
    /// The field name.
    public let name: String
    /// The GIR type of the field.
    public let type: GIRType
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Whether the field is readable (accessible for reading).
    public let isReadable: Bool
    /// Whether the field is writable (accessible for writing).
    public let isWritable: Bool
    /// Creates a new field.
    /// - Parameters:
    ///   - name: The field name.
    ///   - type: The GIR type of the field.
    ///   - isReadable: Whether the field is readable. Defaults to `true`.
    ///   - isWritable: Whether the field is writable. Defaults to `false`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, type: GIRType, isReadable: Bool = true, isWritable: Bool = false, doc: String? = nil) {
        self.name = name; self.type = type; self.isReadable = isReadable; self.isWritable = isWritable; self.doc = doc
    }
}

/// A GObject enumeration type.
///
/// Corresponds to the `<enumeration>` element in a GIR XML file. Defines a
/// set of named integer constants with their C identifiers and numeric values.
public struct Enumeration {
    /// The enumeration name.
    public let name: String
    /// The corresponding C type name.
    public let cType: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The members (enum values) of this enumeration.
    public var members: [EnumMember]
    /// Creates a new enumeration.
    /// - Parameters:
    ///   - name: The enumeration name.
    ///   - cType: The corresponding C type name.
    ///   - members: The enum members. Defaults to empty.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, members: [EnumMember] = [], doc: String? = nil) {
        self.name = name; self.cType = cType; self.members = members; self.doc = doc
    }
}

/// A single member (value) of an enumeration or bitfield.
///
/// Corresponds to the `<member>` element in a GIR XML file. Each member
/// has a name, its associated numeric value, and the full C identifier.
public struct EnumMember {
    /// The member name, e.g. `"visible"`.
    public let name: String
    /// The numeric value as a string, e.g. `"1"`.
    public let value: String
    /// The full C identifier, e.g. `"GTK_WIDGET_VISIBLE"`.
    public let cIdentifier: String
    /// Creates a new enum member.
    /// - Parameters:
    ///   - name: The member name.
    ///   - value: The numeric value as a string.
    ///   - cIdentifier: The full C identifier.
    public init(name: String, value: String, cIdentifier: String) {
        self.name = name; self.value = value; self.cIdentifier = cIdentifier
    }
}

/// A GObject bitfield (flags) type.
///
/// Corresponds to the `<bitfield>` element in a GIR XML file. Defines a set
/// of named flags that can be combined with bitwise operations. Each member
/// represents a single bit in the flags value.
public struct Bitfield {
    /// The bitfield type name.
    public let name: String
    /// The corresponding C type name.
    public let cType: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The individual flag members.
    public var members: [EnumMember]
    /// Creates a new bitfield type.
    /// - Parameters:
    ///   - name: The bitfield type name.
    ///   - cType: The corresponding C type name.
    ///   - members: The flag members. Defaults to empty.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, members: [EnumMember] = [], doc: String? = nil) {
        self.name = name; self.cType = cType; self.members = members; self.doc = doc
    }
}

/// A callback function type.
///
/// Corresponds to the `<callback>` element in a GIR XML file. Describes the
/// function signature — parameters and return type — for a C callback used
/// in signal handlers, virtual functions, or asynchronous operations.
public struct Callback {
    /// The callback type name.
    public let name: String
    /// The corresponding C type name.
    public let cType: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The parameters of the callback function.
    public var parameters: [Parameter]
    /// The return type of the callback function.
    public var returnType: GIRType
    /// Creates a new callback type.
    /// - Parameters:
    ///   - name: The callback type name.
    ///   - cType: The corresponding C type name.
    ///   - parameters: The callback parameters. Defaults to empty.
    ///   - returnType: The return type. Defaults to `.void`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, parameters: [Parameter] = [], returnType: GIRType = .void, doc: String? = nil) {
        self.name = name; self.cType = cType; self.parameters = parameters; self.returnType = returnType; self.doc = doc
    }
}

/// A constructor for a GObject class.
///
/// Corresponds to the `<constructor>` element in a GIR XML file. Constructors
/// are special methods that create new instances of a GObject type, typically
/// wrapping C functions like `gtk_widget_new()`.
public struct Constructor {
    /// The constructor name.
    public let name: String
    /// The corresponding C function identifier.
    public let cIdentifier: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The parameters accepted by the constructor.
    public var parameters: [Parameter]
    /// The return type — typically the constructed object type.
    public var returnType: GIRType
    /// Creates a new constructor definition.
    /// - Parameters:
    ///   - name: The constructor name.
    ///   - cIdentifier: The corresponding C function identifier.
    ///   - parameters: The constructor parameters. Defaults to empty.
    ///   - returnType: The return type. Defaults to `.void`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cIdentifier: String, parameters: [Parameter] = [], returnType: GIRType = .void, doc: String? = nil) {
        self.name = name; self.cIdentifier = cIdentifier
        self.parameters = parameters; self.returnType = returnType; self.doc = doc
    }
}

/// A method of a GObject class, interface, or record.
///
/// Corresponds to the `<method>` element in a GIR XML file. Methods are
/// instance functions that operate on a particular type, identified by their
/// C function name.
public struct Method {
    /// The method name, e.g. `"set_visible"`.
    public let name: String
    /// The corresponding C function identifier, e.g. `"gtk_widget_set_visible"`.
    public let cIdentifier: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The parameters of the method, typically excluding the instance parameter.
    public var parameters: [Parameter]
    /// The return type of the method.
    public var returnType: GIRType
    /// Creates a new method definition.
    /// - Parameters:
    ///   - name: The method name.
    ///   - cIdentifier: The corresponding C function identifier.
    ///   - parameters: The method parameters. Defaults to empty.
    ///   - returnType: The return type. Defaults to `.void`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cIdentifier: String, parameters: [Parameter] = [], returnType: GIRType = .void, doc: String? = nil) {
        self.name = name; self.cIdentifier = cIdentifier
        self.parameters = parameters; self.returnType = returnType; self.doc = doc
    }
}

/// A GObject property definition.
///
/// Corresponds to the `<property>` element in a GIR XML file. Properties are
/// named, typed attributes on GObject classes with configurable read/write
/// access and construct-time-only semantics.
public struct Property {
    /// The property name, e.g. `"label"`.
    public let name: String
    /// The GIR type of the property.
    public var type: GIRType
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Whether the property is readable (has a getter).
    public var isReadable: Bool
    /// Whether the property is writable (has a setter).
    public var isWritable: Bool
    /// Whether the property can only be set during object construction.
    public var isConstructOnly: Bool
    /// Creates a new property definition.
    /// - Parameters:
    ///   - name: The property name.
    ///   - type: The GIR type of the property.
    ///   - isReadable: Whether the property is readable. Defaults to `true`.
    ///   - isWritable: Whether the property is writable. Defaults to `false`.
    ///   - isConstructOnly: Whether the property is construct-only. Defaults to `false`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, type: GIRType, isReadable: Bool = true, isWritable: Bool = false, isConstructOnly: Bool = false, doc: String? = nil) {
        self.name = name; self.type = type
        self.isReadable = isReadable; self.isWritable = isWritable; self.isConstructOnly = isConstructOnly; self.doc = doc
    }
}

/// A GObject signal definition.
///
/// Corresponds to the `<signal>` element in a GIR XML file. Signals are
/// typed event emitters on GObject classes. Each signal has a parameter list,
/// a return value, and may support detailed (string-parameterized) connections.
public struct Signal {
    /// The signal name, e.g. `"clicked"`.
    public let name: String
    /// The parameters emitted with the signal.
    public var parameters: [Parameter]
    /// The return type of the signal handler.
    public var returnType: GIRType
    /// Whether the signal supports detail strings (e.g. `"notify::label"`).
    public var isDetailed: Bool
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Creates a new signal definition.
    /// - Parameters:
    ///   - name: The signal name.
    ///   - parameters: The signal parameters. Defaults to empty.
    ///   - returnType: The handler return type. Defaults to `.void`.
    ///   - isDetailed: Whether the signal supports detail strings. Defaults to `false`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, parameters: [Parameter] = [], returnType: GIRType = .void, isDetailed: Bool = false, doc: String? = nil) {
        self.name = name; self.parameters = parameters; self.returnType = returnType; self.isDetailed = isDetailed; self.doc = doc
    }
}

/// A global (namespace-level) function.
///
/// Corresponds to the `<function>` element at the namespace level in a GIR
/// XML file. These are free functions not associated with any particular
/// type, such as utility or factory functions.
public struct GlobalFunction {
    /// The function name.
    public let name: String
    /// The corresponding C function identifier.
    public let cIdentifier: String
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// The parameters of the function.
    public var parameters: [Parameter]
    /// The return type of the function.
    public var returnType: GIRType
    /// Creates a new global function definition.
    /// - Parameters:
    ///   - name: The function name.
    ///   - cIdentifier: The corresponding C function identifier.
    ///   - parameters: The function parameters. Defaults to empty.
    ///   - returnType: The return type. Defaults to `.void`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cIdentifier: String, parameters: [Parameter] = [], returnType: GIRType = .void, doc: String? = nil) {
        self.name = name; self.cIdentifier = cIdentifier
        self.parameters = parameters; self.returnType = returnType; self.doc = doc
    }
}

/// A constant value definition.
///
/// Corresponds to the `<constant>` element in a GIR XML file. Constants are
/// named immutable values with a specific GIR type, such as enum defaults or
/// version numbers.
public struct Constant {
    /// The constant name.
    public let name: String
    /// The constant value as a string representation.
    public let value: String
    /// The GIR type of the constant.
    public var type: GIRType
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Creates a new constant definition.
    /// - Parameters:
    ///   - name: The constant name.
    ///   - value: The constant value as a string representation.
    ///   - type: The GIR type of the constant.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, value: String, type: GIRType, doc: String? = nil) {
        self.name = name; self.value = value; self.type = type; self.doc = doc
    }
}

/// A type alias definition.
///
/// Corresponds to the `<alias>` element in a GIR XML file. Provides an
/// alternative name (with an optional C type) for an existing GIR type,
/// useful for platform-specific or convenience typedefs.
public struct Alias {
    /// The alias name.
    public let name: String
    /// The corresponding C type name.
    public let cType: String
    /// The underlying GIR type this alias refers to.
    public var target: GIRType
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Creates a new type alias.
    /// - Parameters:
    ///   - name: The alias name.
    ///   - cType: The corresponding C type name.
    ///   - target: The underlying GIR type to alias.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, cType: String, target: GIRType, doc: String? = nil) {
        self.name = name; self.cType = cType; self.target = target; self.doc = doc
    }
}

// MARK: - Shared Types

/// A parameter of a function, method, constructor, callback, or signal.
///
/// Corresponds to the `<parameter>` element in a GIR XML file. Describes the
/// parameter's name, type, nullability, optionality, ownership transfer rules,
/// and whether it is the implicit instance parameter (equivalent to `self`).
public struct Parameter {
    /// The parameter name.
    public let name: String
    /// The GIR type of the parameter.
    public var type: GIRType
    /// Documentation comment from the GIR XML `<doc>` element.
    public var doc: String?
    /// Whether the parameter may be `nil` (NULL).
    public var isNullable: Bool
    /// Whether the parameter is optional (may be omitted at the call site).
    public var isOptional: Bool
    /// How ownership is transferred for this parameter.
    public var transferOwnership: TransferOwnership
    /// Whether this is the implicit instance parameter (self) of a method.
    public var isInstanceParameter: Bool
    /// Creates a new parameter definition.
    /// - Parameters:
    ///   - name: The parameter name.
    ///   - type: The GIR type of the parameter.
    ///   - isNullable: Whether the parameter may be nil. Defaults to `false`.
    ///   - isOptional: Whether the parameter is optional. Defaults to `false`.
    ///   - transferOwnership: How ownership is transferred. Defaults to `.none`.
    ///   - isInstanceParameter: Whether this is the instance parameter. Defaults to `false`.
    ///   - doc: Documentation comment from the GIR XML.
    public init(name: String, type: GIRType, isNullable: Bool = false, isOptional: Bool = false,
                transferOwnership: TransferOwnership = .none, isInstanceParameter: Bool = false, doc: String? = nil) {
        self.name = name; self.type = type; self.isNullable = isNullable
        self.isOptional = isOptional; self.transferOwnership = transferOwnership
        self.isInstanceParameter = isInstanceParameter; self.doc = doc
    }
}

/// Describes how ownership of a value is transferred between caller and callee.
///
/// Maps to the `transfer-ownership` attribute in GIR XML. Controls memory
/// management semantics: whether the caller must free the returned value
/// (`.full`), whether only the container is owned (`.container`), or whether
/// no ownership transfer occurs (`.none`).
public enum TransferOwnership: String {
    /// No transfer; the caller does not own the value and must not free it.
    case none
    /// Full transfer; the caller owns the value and is responsible for freeing it.
    case full
    /// Container transfer; the caller owns the container but not its elements.
    case container
}

/// A GIR type reference, covering primitives, named type references, arrays, and optionals.
///
/// Corresponds to the `<type>` element in GIR XML. This recursive enum models
/// the full GIR type system: scalar primitives, named type references pointing
/// to other GIR types, arrays (both GArray and C-style fixed arrays), and
/// nullable/optional wrappers.
public indirect enum GIRType: Equatable {
    /// No return value (void).
    case void
    /// A boolean value, mapped from `gboolean`.
    case boolean
    /// A signed 8-bit integer, mapped from `gint8`.
    case int8
    /// A signed 16-bit integer, mapped from `gint16`.
    case int16
    /// A signed 32-bit integer, mapped from `gint32`.
    case int32
    /// A signed 64-bit integer, mapped from `gint64`.
    case int64
    /// An unsigned 8-bit integer, mapped from `guint8`.
    case uint8
    /// An unsigned 16-bit integer, mapped from `guint16`.
    case uint16
    /// An unsigned 32-bit integer, mapped from `guint32`.
    case uint32
    /// An unsigned 64-bit integer, mapped from `guint64`.
    case uint64
    /// A single-precision floating-point value, mapped from `gfloat`.
    case float
    /// A double-precision floating-point value, mapped from `gdouble`.
    case double
    /// A null-terminated UTF-8 string, mapped from `utf8`.
    case string
    /// A filename string (platform-dependent encoding), mapped from `filename`.
    case filename
    /// An opaque pointer, mapped from `gpointer`.
    case pointer
    /// A reference to a named type, possibly from another namespace.
    /// - Parameters:
    ///   - String: The type name, e.g. `"Widget"`.
    ///   - namespace: The namespace qualifier, or `nil` for the current namespace.
    case typeRef(String, namespace: String?)
    /// A dynamically-sized GArray of the given element type.
    case array(GIRType)
    /// A C-style fixed-size array of the given element type.
    case cArray(GIRType)
    /// An optional (nullable) value of the given type.
    case `optional`(GIRType)

    /// Creates a type reference in the current namespace.
    /// - Parameter name: The unqualified type name.
    /// - Returns: A `typeRef` with no namespace qualifier.
    public static func typeRef(_ name: String) -> GIRType {
        .typeRef(name, namespace: nil)
    }
}