Framework
libgir2swift
The core library that parses GObject Introspection (GIR) XML and generates Swift wrapper code.
Overview
libgir2swift implements the full GIR-to-Swift transformation pipeline. It is used by the gir2swift command-line tool and can be embedded in other tools that need to process .gir files programmatically.
The library is organised into three layers:
-
Models — Swift types that mirror the GIR XML schema, plus the GIR document class and the Gir2Swift command structure.
-
Emitting — Code-generation routines that turn parsed GIR models into Swift source text.
-
Utilities — Helpers for planning, incremental generation, post-processing, and string manipulation.
Parsing a GIR file
The central class is GIR. Construct it by passing a memory buffer that contains the raw bytes of a .gir file:
import libgir2swift
let data = try Data(contentsOf: girURL, options: .alwaysMapped)
let gir: GIR? = data.withUnsafeBytes { bytes in
GIR(buffer: bytes.bindMemory(to: CChar.self), quiet: false)
}After construction, gir exposes typed collections for every GIR element kind: interfaces, records, unions, classes, functions, callbacks, and more.
GIR element hierarchy
All GIR elements derive from GIR.Thing. The inheritance hierarchy mirrors the GIR XML schema:
Thing
└── Datatype
├── CType
│ ├── Alias
│ ├── Constant
│ ├── Argument
│ ├── Property
│ │ └── Field
│ └── Record
│ ├── Class
│ │ └── Interface
│ └── Union
├── Enumeration
│ └── Bitfield
└── Method
├── Function
│ ├── Signal
│ └── CallbackType system
GIRType represents a resolved GIR type together with its Swift and C names, namespace, parent type, and the TypeConversion operations available to it. TypeReference tracks pointer levels and const qualifiers for a type used in a specific position (e.g., a function parameter or return value).
Topics
Command and configuration
Structure representing the gir2swift executable, including command line arguments
GIR document
Representation of a GIR file
GIR element models
GIR named thing class
GIR type class
a type with an underlying C type entry
a type alias is just a type with an underlying C type
data type representing a function/method argument or return type
a bitfield is defined akin to an enumeration
a callback is the same as a function, except that the type definition is a @convention(c) callback definition
a class data type record
an entry for a constant
an enumeration entry
a field is a Property
a function is the same as a method
an inteface is similar to a class, but can be part of a more complex type graph
data type representing a function/method
a property is a C type
a data type record to create a protocol/struct/class for
a signal is equivalent to a function
a union data type record
Type system
Representation of a fundamental type, its relationship to other types, and casting operations
Representation of a string type, its relationship to other types, and casting operations
Representation of a raw pointer type, its relationship to other types, and casting operations
Representation of a record type (struct or class), its relationship to other types, and casting operations
Representation of a generic type (struct or class), its relationship to other types, and casting operations
Representation of a opaque pointer type, its relationship to other types, and casting operations
Type conversion operation. This root class is used for aliases/equal type conversions, i.e., casts are no-ops.
Parent/Child class conversion operation
Parent/Child class conversion operation with optional upcast
Custom type conversion operation
Nested type conversion operation
Enum type conversion operation.
Bit field (OptionSet) type conversion operation.
Raw pointer conversion
Reference to a GIR type.
Structures
a pair of getters and setters (both cannot be nil at the same time)
Functions
Swift code type definition of a bitfield
Swift code representation of a bit field value
Swift code for calling the underlying setter function and assigning the raw return value
Swift code for a @convention(c) callback type declaration
Swift code for a @convention(c) callback parameter
SwiftDoc representation of comments
Swift code for computed properties
Swift code representation of a constant
Swift code for the parameters of a constructor
Swift code for constructor first argument prefix extracted from a method name
Swift code for convenience constructors
Swift code for passing a setter to a method of a record / class
Swift representation of deprecation
Swift code for field properties
Swift code for a @convention(c) callback type declaration
Swift code for calling the underlying function and assigning the raw return value
Default implementation for functions
return setter/getter pairs from a list of methods
Convert the given String to SwiftDoc
Return code for instances (e.g. fields)
Swift code for methods (with a given indentation)
Namespaced typealias code representation for a given data type
Swift code representation of a type alias
Swift code for auto-prefixed arguments. This version will use Ref (struct) types instead of templats for nullable reference arguments with a default value of nil
Swift code for method parameters
Swift code for method parameters
Swift struct representation of a record/class as a wrapper of a pointer
Swift protocol representation of a record/class as a wrapper of a pointer
Default implementation for record methods as protocol extension.
Swift struct representation of a record/class as a wrapper of a pointer
Return code for functions/methods/convenience constructors
Generic return code for methods/types
Swift code for auto-prefixed return values
Swift code for method return values
Return code declaration for functions/methods/convenience constructors
Return the return type of a method,
Swift code for signal names without prefixes
Swift code for signal names with prefixes
Property definition for sub-records
Type alias for sub-records
Swift code representation of a callback as a type alias
Swift code representation of a free standing function
Swift code representation of an enum
Swift code representation of an enum
Swift code representation of a record
Swift code representation with code following the comments
Swift code representation of a type alias
Swift code representation of a constant
Return a unions-to-swift conversion closure for the array of functions passed in
Swift code for auto-prefixed arguments This version will use template types where possible, ignoring default values for those templates
Swift code for passing an argument to a free standing function
Swift code type alias representation of an enum
Swift typealias code representation for a given data type
Swift code representation of a type alias
Return a typed collection reference for the given, prefixed type name.
Swift code representation of an enum value
Type Aliases
An empty conversion has no explicit casting