@ts-for-gir/lib 4.0.0-beta.9 → 4.0.0-rc.2

package/src/gir/record.ts

@@ -0,0 +1,488 @@
+import { ConsoleReporter } from "@ts-for-gir/reporter";
+import type { FormatGenerator } from "../generators/generator.ts";
+import { ArrayType, ClassStructTypeIdentifier, NativeType, type TypeExpression, TypeIdentifier } from "../gir.ts";
+import type { GirRecordElement, GirUnionElement, OptionsLoad, RecordResolution } from "../types/index.ts";
+import { parseDoc, parseMetadata } from "../utils/gir-parsing.ts";
+import { sanitizeIdentifierName } from "../utils/naming.ts";
+import { resolveTypeIdentifier } from "../utils/type-resolution.ts";
+import { parseTypeIdentifier } from "../utils/types.ts";
+import type { GirVisitor } from "../visitor.ts";
+import { IntrospectedConstructor } from "./constructor.ts";
+import {
+	IntrospectedBaseClass,
+	type IntrospectedClassCallback,
+	IntrospectedClassFunction,
+	IntrospectedStaticClassFunction,
+} from "./introspected-classes.ts";
+import type { IntrospectedNamespace } from "./namespace.ts";
+import { IntrospectedField, type IntrospectedProperty } from "./property.ts";
+import type { IntrospectedSignal } from "./signal.ts";
+
+const log = new ConsoleReporter(true, "gir/class", true);
+
+export class IntrospectedRecord extends IntrospectedBaseClass {
+	private _isForeign: boolean = false;
+	private _structFor: ClassStructTypeIdentifier | null = null;
+	private _isSimple: boolean | null = null;
+	private _isSimpleWithoutPointers: string | null = null;
+	private _overriddenGType: string | null = null;
+
+	/**
+	 * Returns all signals for this record (records typically don't have signals)
+	 */
+	getAllSignals(): Array<{
+		name: string;
+		signal?: IntrospectedSignal;
+		isNotifySignal?: boolean;
+		isDetailSignal?: boolean;
+		parameterTypes?: string[];
+		returnType?: string;
+	}> {
+		// Records typically don't have signals, but we provide a consistent API
+		return [];
+	}
+
+	isForeign(): boolean {
+		return this._isForeign;
+	}
+
+	get structFor() {
+		return this._structFor;
+	}
+
+	get gtype() {
+		return this._overriddenGType ?? this.name;
+	}
+
+	overrideGType(gtype: string) {
+		this._overriddenGType = gtype;
+	}
+
+	getType(): TypeIdentifier {
+		if (this._structFor) {
+			return this._structFor;
+		}
+
+		return new TypeIdentifier(this.name, this.namespace.namespace);
+	}
+
+	someParent(predicate: (p: IntrospectedRecord) => boolean): boolean {
+		const resolution = this.resolveParents();
+		const parent = resolution.extends();
+
+		return !!parent && (predicate(parent.node) || parent.node.someParent(predicate));
+	}
+
+	findParent(predicate: (p: IntrospectedRecord) => boolean): IntrospectedRecord | undefined {
+		const resolution = this.resolveParents();
+
+		const parent = resolution.extends();
+
+		if (parent) {
+			if (predicate(parent.node)) return parent.node;
+
+			const found = parent.node.findParent(predicate);
+
+			if (found) return found;
+		}
+
+		return undefined;
+	}
+
+	findParentMap<K>(predicate: (p: IntrospectedRecord) => K | undefined): K | undefined {
+		const resolution = this.resolveParents();
+
+		const parent = resolution.extends();
+
+		if (parent) {
+			const result = predicate(parent.node);
+
+			if (result !== undefined) return result;
+
+			return parent.node.findParentMap(predicate);
+		}
+
+		return undefined;
+	}
+
+	accept(visitor: GirVisitor): IntrospectedRecord {
+		const node = this.copy({
+			constructors: this.constructors.map((c) => c.accept(visitor)),
+			members: this.members.map((m) => m.accept(visitor)),
+			props: this.props.map((p) => p.accept(visitor)),
+			fields: this.fields.map((f) => f.accept(visitor)),
+			callbacks: this.callbacks.map((c) => c.accept(visitor)),
+		});
+
+		return visitor.visitRecord?.(node) ?? node;
+	}
+
+	resolveParents(): RecordResolution {
+		const { namespace, superType } = this;
+
+		return {
+			*[Symbol.iterator]() {
+				let current = this.extends();
+
+				while (current !== undefined) {
+					yield current;
+					current = current.extends();
+				}
+			},
+			extends() {
+				const resolved_parent = superType ? resolveTypeIdentifier(namespace, superType) : undefined;
+				if (resolved_parent instanceof IntrospectedRecord) return resolved_parent.resolveParents();
+
+				return undefined;
+			},
+			node: this,
+			identifier: this.getType(),
+		};
+	}
+
+	copy(
+		options: {
+			parent?: undefined;
+			constructors?: IntrospectedConstructor[];
+			members?: IntrospectedClassFunction[];
+			props?: IntrospectedProperty[];
+			fields?: IntrospectedField[];
+			callbacks?: IntrospectedClassCallback[];
+		} = {},
+	): IntrospectedRecord {
+		const {
+			name,
+			namespace,
+			superType,
+			members,
+			constructors,
+			_isForeign,
+			_structFor,
+			_overriddenGType,
+			props,
+			fields,
+			callbacks,
+			generics,
+			mainConstructor,
+		} = this;
+
+		const clazz = new IntrospectedRecord({ name, namespace });
+
+		clazz._copyBaseProperties(this);
+
+		if (superType) {
+			clazz.superType = superType;
+		}
+
+		clazz._structFor = _structFor;
+		clazz._isForeign = _isForeign;
+		clazz._overriddenGType = _overriddenGType;
+		clazz.props = (options.props ?? props).map((p) => p.copy({ parent: clazz }));
+		clazz.fields = (options.fields ?? fields).map((f) => f.copy({ parent: clazz }));
+		clazz.callbacks = (options.callbacks ?? callbacks).map((c) => c.copy({ parent: clazz }));
+		clazz.mainConstructor = mainConstructor?.copy({ parent: clazz }) ?? null;
+		clazz.constructors = (options.constructors ?? constructors).map((c) => c.copy({ parent: clazz }));
+		clazz.members = (options.members ?? members).map((m) => m.copy({ parent: clazz }));
+		clazz.generics = [...generics];
+
+		return clazz;
+	}
+
+	static foreign(name: string, namespace: IntrospectedNamespace): IntrospectedRecord {
+		const foreignRecord = new IntrospectedRecord({ name, namespace });
+		foreignRecord._isForeign = true;
+		return foreignRecord;
+	}
+
+	static fromXML(
+		element: GirRecordElement | GirUnionElement,
+		namespace: IntrospectedNamespace,
+		options: OptionsLoad,
+	): IntrospectedRecord {
+		if (!element.$.name) {
+			throw new Error("Invalid GIR File: No name provided for union.");
+		}
+
+		const name = sanitizeIdentifierName(namespace.namespace, element.$.name);
+
+		if (options.verbose) {
+			log.debug(`  >> GirRecord: Parsing definition ${element.$.name} (${name})...`);
+		}
+
+		const clazz = new IntrospectedRecord({ name, namespace });
+
+		IntrospectedRecord.configureRecordProperties(element, clazz);
+		IntrospectedRecord.setupTypeStructOrResolveNames(element, clazz, namespace, name);
+		IntrospectedRecord.parseRecordDocumentation(element, clazz, options);
+		IntrospectedRecord.parseRecordMembers(element, clazz, options);
+
+		return clazz;
+	}
+
+	private static configureRecordProperties(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+	): void {
+		const isPrivate = IntrospectedRecord.isRecordPrivate(element);
+		clazz.setPrivate(isPrivate);
+
+		const isForeign = "foreign" in element.$ && element.$.foreign === "1";
+		clazz._isForeign = isForeign;
+	}
+
+	private static isRecordPrivate(element: GirRecordElement | GirUnionElement): boolean {
+		if (!element.$.name) {
+			return false;
+		}
+
+		return (
+			element.$.name.startsWith("_") ||
+			("disguised" in element.$ && element.$.disguised === "1") ||
+			("opaque" in element.$ && element.$.opaque === "1")
+		);
+	}
+
+	private static setupTypeStructOrResolveNames(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		namespace: IntrospectedNamespace,
+		name: string,
+	): void {
+		const gtypeStructFor = "glib:is-gtype-struct-for" in element.$ ? element.$["glib:is-gtype-struct-for"] : undefined;
+
+		if (typeof gtypeStructFor === "string" && gtypeStructFor) {
+			const structFor = parseTypeIdentifier(namespace.namespace, gtypeStructFor);
+			clazz._structFor = new ClassStructTypeIdentifier(structFor.name, structFor.namespace);
+		} else {
+			IntrospectedRecord.registerResolveNames(element, clazz, namespace, name);
+		}
+	}
+
+	private static registerResolveNames(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		namespace: IntrospectedNamespace,
+		name: string,
+	): void {
+		if (element.$["glib:type-name"]) {
+			clazz.resolve_names.push(element.$["glib:type-name"]);
+			namespace.registerResolveName(element.$["glib:type-name"], namespace.namespace, name);
+		}
+
+		if (element.$["c:type"]) {
+			clazz.resolve_names.push(element.$["c:type"]);
+			namespace.registerResolveName(element.$["c:type"], namespace.namespace, name);
+		}
+	}
+
+	private static parseRecordDocumentation(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		options: OptionsLoad,
+	): void {
+		if (options.loadDocs) {
+			clazz.doc = parseDoc(element);
+			clazz.metadata = parseMetadata(element);
+		}
+	}
+
+	private static parseRecordMembers(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		options: OptionsLoad,
+	): void {
+		try {
+			IntrospectedRecord.parseRecordMethods(element, clazz, options);
+			IntrospectedRecord.parseRecordConstructors(element, clazz, options);
+			IntrospectedRecord.parseRecordStaticMethods(element, clazz, options);
+			IntrospectedRecord.parseRecordFields(element, clazz);
+		} catch (e) {
+			log.reportParsingFailure(clazz.name, "record", clazz.namespace.namespace, e as Error);
+		}
+	}
+
+	private static parseRecordMethods(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		options: OptionsLoad,
+	): void {
+		if (element.method) {
+			clazz.members.push(...element.method.map((method) => IntrospectedClassFunction.fromXML(method, clazz, options)));
+		}
+	}
+
+	private static parseRecordConstructors(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		options: OptionsLoad,
+	): void {
+		if (Array.isArray(element.constructor)) {
+			element.constructor.forEach((ctor) => {
+				const c = IntrospectedConstructor.fromXML(ctor, clazz, options);
+				clazz.constructors.push(c);
+			});
+		}
+	}
+
+	private static parseRecordStaticMethods(
+		element: GirRecordElement | GirUnionElement,
+		clazz: IntrospectedRecord,
+		options: OptionsLoad,
+	): void {
+		if (element.function) {
+			clazz.members.push(
+				...element.function.map((func) => IntrospectedStaticClassFunction.fromXML(func, clazz, options)),
+			);
+		}
+	}
+
+	private static parseRecordFields(element: GirRecordElement | GirUnionElement, clazz: IntrospectedRecord): void {
+		if (element.field) {
+			clazz.fields.push(
+				...element.field
+					.filter((field) => !("callback" in field))
+					.map((field) => IntrospectedField.fromXML(field, clazz)),
+			);
+		}
+	}
+
+	/**
+	 * Calculate if a type expression is "simple" without pointers
+	 */
+	isSimpleTypeWithoutPointers(typeContainer: TypeExpression): boolean {
+		if (!this.isSimpleType(typeContainer)) {
+			return false;
+		}
+
+		if (typeContainer.isPointer) {
+			return false;
+		}
+
+		// Primitive types can be directly allocated.
+		if (typeContainer instanceof NativeType) {
+			return true;
+		}
+
+		if (typeContainer instanceof ArrayType) {
+			if (typeContainer.type.equals(this.getType())) {
+				return true;
+			}
+
+			return this.isSimpleTypeWithoutPointers(typeContainer.type);
+		}
+
+		if (typeContainer instanceof TypeIdentifier) {
+			const type = typeContainer;
+
+			const child_ns = this.namespace.assertInstalledImport(type.namespace);
+
+			const alias = child_ns.getAlias(type.name);
+			if (alias) {
+				return this.isSimpleTypeWithoutPointers(alias.type);
+			}
+
+			const child = child_ns.getClass(type.name);
+			if (child === this) {
+				return false;
+			}
+
+			if (child instanceof IntrospectedRecord) {
+				return child.isSimpleWithoutPointers() !== null;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Calculate if a type expression is "simple"
+	 */
+	isSimpleType(typeContainer: TypeExpression): boolean {
+		// Primitive types can be directly allocated.
+		if (typeContainer instanceof NativeType) {
+			return true;
+		}
+
+		if (typeContainer instanceof ArrayType) {
+			if (typeContainer.type.equals(this.getType())) {
+				return true;
+			}
+
+			return this.isSimpleType(typeContainer.type);
+		}
+
+		if (typeContainer instanceof TypeIdentifier) {
+			const type = typeContainer;
+
+			const child_ns = this.namespace.assertInstalledImport(type.namespace);
+
+			const alias = child_ns.getAlias(type.name);
+			if (alias) {
+				return this.isSimpleType(alias.type);
+			}
+
+			const child = child_ns.getClass(type.name);
+			if (child === this) {
+				return false;
+			}
+
+			if (child instanceof IntrospectedRecord) {
+				return child.isSimple();
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Check if a record is "simple" and can be constructed by GJS
+	 */
+	isSimple() {
+		// Records with no fields are not
+		// constructable.
+		if (this.fields.length === 0) {
+			return false;
+		}
+
+		// Because we may have to recursively check
+		// if types are instantiable we cache whether
+		// or not a given Record is simple.
+		if (this._isSimple !== null) {
+			return this._isSimple;
+		}
+
+		const isSimple = this.fields.every((f) => this.isSimpleType(f.type));
+
+		this._isSimple = isSimple;
+
+		return isSimple;
+	}
+
+	isSimpleWithoutPointers() {
+		// Records which are "simple without pointers" is a subset of
+		// "simple" records.
+		if (!this.isSimple()) {
+			return null;
+		}
+
+		// Because we may have to recursively check
+		// if types are instantiable we cache whether
+		// or not a given Record is simple.
+		if (this._isSimpleWithoutPointers !== null) {
+			return this._isSimpleWithoutPointers;
+		}
+
+		const isSimpleWithoutPointers = this.fields.find((f) => {
+			return !this.isSimpleTypeWithoutPointers(f.type);
+		});
+
+		if (!isSimpleWithoutPointers) this._isSimpleWithoutPointers = "all fields good";
+		else this._isSimpleWithoutPointers = null;
+
+		return this._isSimpleWithoutPointers;
+	}
+
+	asString<T extends FormatGenerator<unknown>>(generator: T): ReturnType<T["generateRecord"]> {
+		return generator.generateRecord(this) as ReturnType<T["generateRecord"]>;
+	}
+}

package/src/gir/registry.ts

@@ -0,0 +1,183 @@
+import { DefaultFormatter } from "../formatters/default.ts";
+import type { Formatter } from "../formatters/formatter.ts";
+import { JSONFormatter } from "../formatters/json.ts";
+import type { FormatGenerator } from "../generators/generator.ts";
+import { generify } from "../generics/generify.ts";
+import type { GirModule } from "../index.ts";
+import { inject } from "../injections/inject.ts";
+import type { GeneratorConstructor, OptionsGeneration, OptionsTransform } from "../types/index.ts";
+import { TwoKeyMap } from "../util.ts";
+import { ClassVisitor } from "../validators/class.ts";
+import { FunctionParametersVisitor } from "../validators/function-parameters.ts";
+import { InterfaceVisitor } from "../validators/interface.ts";
+import type { GirVisitor } from "../visitor.ts";
+import type { IntrospectedNamespace } from "./namespace.ts";
+
+export class NSRegistry {
+	mapping: TwoKeyMap<string, string, IntrospectedNamespace> = new TwoKeyMap();
+	private formatters: Map<string, Formatter> = new Map();
+	private generators: Map<string, GeneratorConstructor<unknown>> = new Map();
+	c_mapping: Map<string, { version: string; name: string }[]> = new Map();
+	transformations: GirVisitor[] = [];
+	subtypes = new TwoKeyMap<string, string, TwoKeyMap<string, string, boolean>>();
+
+	constructor() {
+		this.formatters.set("json", new JSONFormatter());
+	}
+
+	registerTransformation(visitor: GirVisitor) {
+		this.transformations.push(visitor);
+
+		// Apply transformations to already built namespaces.
+		this.mapping.forEach((n) => {
+			n.accept(visitor);
+		});
+	}
+
+	registerFormatter(output: string, formatter: Formatter) {
+		this.formatters.set(output, formatter);
+	}
+
+	getFormatter(output: string) {
+		return this.formatters.get(output) ?? new DefaultFormatter();
+	}
+
+	registerGenerator<T>(
+		output: string,
+		generator: { new (namespace: IntrospectedNamespace, options: OptionsGeneration): FormatGenerator<T> },
+	) {
+		this.generators.set(output, generator);
+	}
+
+	async getGenerator<T>(output: string): Promise<GeneratorConstructor<T> | undefined> {
+		// Handle loading external generators...
+		if (!this.generators.has(output)) {
+			let Generator: { default: GeneratorConstructor<unknown> };
+			try {
+				Generator = (await import(`@gi.ts/generator-${output}`)) as { default: GeneratorConstructor<unknown> };
+
+				if (Generator) {
+					console.log(`Loading generator "@gi.ts/generator-${output}"...`);
+					this.generators.set(output, Generator.default);
+					return Generator.default as GeneratorConstructor<T>;
+				}
+			} catch {
+				try {
+					Generator = (await import(`gi-ts-generator-${output}`)) as {
+						default: GeneratorConstructor<unknown>;
+					};
+
+					console.log(`Loading generator "gi-ts-generator-${output}"...`);
+					this.generators.set(output, Generator.default);
+					return Generator.default as GeneratorConstructor<T>;
+				} catch {
+					try {
+						Generator = (await import(`${output}`)) as { default: GeneratorConstructor<unknown> };
+
+						console.log(`Loading generator "${output}"...`);
+						this.generators.set(output, Generator.default);
+						return Generator.default as GeneratorConstructor<T>;
+					} catch {}
+				}
+			}
+		}
+
+		return this.generators.get(output) as GeneratorConstructor<T> | undefined;
+	}
+
+	private _transformNamespace(namespace: IntrospectedNamespace) {
+		this.transformations.forEach((t) => {
+			namespace.accept(t);
+		});
+	}
+
+	namespace(name: string, version: string): IntrospectedNamespace | null {
+		const namespace = this.mapping.get(name, version);
+
+		return namespace ?? null;
+	}
+
+	namespacesForPrefix(c_prefix: string): IntrospectedNamespace[] {
+		return (this.c_mapping.get(c_prefix) ?? []).map((c_mapping) =>
+			this.assertNamespace(c_mapping.name, c_mapping.version),
+		);
+	}
+
+	transform(options: OptionsTransform) {
+		const GLib = this.assertNamespace("GLib", "2.0");
+		const Gio = this.assertNamespace("Gio", "2.0");
+		const GObject = this.assertNamespace("GObject", "2.0");
+
+		// These follow the GLib version.
+		Gio.package_version = [...GLib.package_version];
+		GObject.package_version = [...GLib.package_version];
+
+		const interfaceVisitor = new InterfaceVisitor();
+		this.registerTransformation(interfaceVisitor);
+
+		const classVisitor = new ClassVisitor();
+		this.registerTransformation(classVisitor);
+
+		const enumParamsVisitor = new FunctionParametersVisitor();
+		this.registerTransformation(enumParamsVisitor);
+
+		console.log("Adding generics...");
+		generify(this, options.inferGenerics);
+
+		console.log("Injecting types...");
+		inject(this);
+	}
+
+	defaultVersionOf(name: string): string | null {
+		// GJS has a hard dependency on these versions.
+		if (name === "GLib" || name === "Gio" || name === "GObject") {
+			return "2.0";
+		}
+
+		const meta = this.mapping.getIfOnly(name);
+
+		if (meta) {
+			return meta[0];
+		}
+
+		return null;
+	}
+
+	assertDefaultVersionOf(name: string): string {
+		const version = this.defaultVersionOf(name);
+
+		if (version) {
+			return version;
+		}
+
+		// This mirrors GJS' and GI's default behavior.
+		// If we can't find a single version of an unspecified dependency, we throw an error.
+		throw new Error(`No single version found for unspecified dependency: ${JSON.stringify(name)}.`);
+	}
+
+	assertNamespace(name: string, version: string): IntrospectedNamespace {
+		const namespace = this.mapping.get(name, version) ?? null;
+
+		if (!namespace) {
+			throw new Error(`Namespace '${name}' not found.`);
+		}
+
+		return namespace;
+	}
+
+	register(namespace: GirModule): IntrospectedNamespace {
+		this.mapping.set(namespace.namespace, namespace.version, namespace);
+
+		namespace.c_prefixes.forEach((c_prefix) => {
+			const c_map = this.c_mapping.get(c_prefix) || [];
+
+			c_map.push({ name: namespace.namespace, version: namespace.version });
+
+			this.c_mapping.set(c_prefix, c_map);
+		});
+
+		this._transformNamespace(namespace);
+
+		return namespace;
+	}
+}