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

package/src/gir/property.ts

@@ -0,0 +1,218 @@
+import type { FormatGenerator } from "../generators/generator.ts";
+import { makeNullable, type TypeExpression } from "../gir.ts";
+import type { GirFieldElement, GirPropertyElement } from "../index.ts";
+import type { OptionsLoad } from "../types/index.ts";
+import type { Options } from "../types/introspected.ts";
+import { getType, parseDoc, parseMetadata } from "../utils/gir-parsing.ts";
+import { isIntrospectable } from "../utils/girs.ts";
+import type { GirVisitor } from "../visitor.ts";
+import type { IntrospectedEnum } from "./enum.ts";
+import { IntrospectedBase } from "./introspected-base.ts";
+import { IntrospectedClassMember } from "./introspected-class-member.ts";
+import type { IntrospectedBaseClass } from "./introspected-classes.ts";
+
+export class IntrospectedField extends IntrospectedClassMember {
+	readonly type: TypeExpression;
+	readonly optional: boolean = false;
+	readonly computed: boolean;
+	readonly isStatic: boolean;
+	readonly writable: boolean;
+	readonly isNative: boolean = false;
+
+	copy(options?: { parent?: IntrospectedBaseClass; type?: TypeExpression; isStatic?: boolean }): IntrospectedField {
+		const { type, name, parent, optional, computed, isStatic, writable } = this;
+
+		return new IntrospectedField({
+			name,
+			parent,
+			type: options?.type ?? type,
+			optional,
+			computed,
+			isStatic: options?.isStatic ?? isStatic,
+			writable,
+		})._copyBaseProperties(this);
+	}
+
+	constructor({
+		name,
+		parent,
+		type,
+		computed = false,
+		optional = false,
+		isStatic = false,
+		writable = true,
+		...args
+	}: Options<{
+		name: string;
+		parent?: IntrospectedBaseClass | null;
+		type: TypeExpression;
+		computed?: boolean;
+		optional?: boolean;
+		isStatic?: boolean;
+		writable?: boolean;
+	}>) {
+		super(name, parent ?? null, { ...args });
+
+		this.type = type;
+		this.computed = computed;
+		this.optional = optional;
+		this.isStatic = isStatic;
+		this.writable = writable;
+	}
+
+	asString<T extends FormatGenerator<unknown>>(generator: T): ReturnType<T["generateField"]> {
+		return generator.generateField(this) as ReturnType<T["generateField"]>;
+	}
+
+	accept(visitor: GirVisitor): IntrospectedField {
+		const node = this.copy({
+			type: visitor.visitType?.(this.type) ?? this.type,
+		});
+
+		return visitor.visitField?.(node) ?? node;
+	}
+
+	static fromXML(field: GirFieldElement, parent: IntrospectedBaseClass): IntrospectedField {
+		const namespace = parent.namespace;
+		const name = field.$.name;
+		const _name = name.replace(/[-]/g, "_");
+		const f = new IntrospectedField({
+			name: _name,
+			parent,
+			type: getType(namespace, field),
+			isPrivate: field.$.private === "1",
+			isIntrospectable: isIntrospectable(field),
+		});
+
+		return f;
+	}
+}
+
+export class JSField extends IntrospectedField {
+	isNative = true;
+}
+
+export class IntrospectedProperty extends IntrospectedBase<IntrospectedEnum | IntrospectedBaseClass> {
+	type: TypeExpression;
+
+	readonly writable: boolean = false;
+	readonly readable: boolean = true;
+	readonly constructOnly: boolean;
+	/** GIR default-value attribute: the default value of the property as a string. */
+	defaultValue?: string;
+	/** GIR getter attribute: name of the getter method for this property (used for nullable inference). */
+	getter?: string;
+
+	get namespace() {
+		return this.parent.namespace;
+	}
+
+	copy(options?: {
+		name?: string;
+		parent?: IntrospectedBaseClass | IntrospectedEnum;
+		type?: TypeExpression;
+	}): IntrospectedProperty {
+		const { name, writable, readable, type, constructOnly, parent } = this;
+
+		const prop = new IntrospectedProperty({
+			name: options?.name ?? name,
+			writable,
+			readable,
+			type: options?.type ?? type,
+			constructOnly,
+			parent: options?.parent ?? parent,
+		})._copyBaseProperties(this);
+		prop.defaultValue = this.defaultValue;
+		prop.getter = this.getter;
+		return prop;
+	}
+
+	accept(visitor: GirVisitor): IntrospectedProperty {
+		const node = this.copy({
+			parent: this.parent,
+			type: visitor.visitType?.(this.type) ?? this.type,
+		});
+
+		return visitor.visitProperty?.(node) ?? node;
+	}
+
+	constructor({
+		name,
+		type,
+		writable,
+		readable,
+		constructOnly,
+		parent,
+		...args
+	}: Options<{
+		name: string;
+		type: TypeExpression;
+		writable: boolean;
+		readable: boolean;
+		constructOnly: boolean;
+		parent: IntrospectedBaseClass | IntrospectedEnum;
+	}>) {
+		super(name, parent, { ...args });
+
+		this.type = type;
+		this.writable = writable;
+		this.readable = readable;
+		this.constructOnly = constructOnly;
+	}
+
+	asString<T extends FormatGenerator<unknown>>(generator: T, construct?: boolean): ReturnType<T["generateProperty"]> {
+		return generator.generateProperty(this, construct) as ReturnType<T["generateProperty"]>;
+	}
+
+	toCamelCase() {
+		const [part, ...parts] = this.name.split("_");
+
+		if (parts.length === 0) {
+			return this.copy({
+				name: part,
+				parent: this.parent,
+			});
+		}
+
+		const camelCase = `${part}${parts.map((s) => `${s[0].toUpperCase()}${s.slice(1)}`).join("")}`;
+
+		return this.copy({
+			name: camelCase,
+			parent: this.parent,
+		});
+	}
+
+	static fromXML(
+		element: GirPropertyElement,
+		parent: IntrospectedBaseClass | IntrospectedEnum,
+		options: OptionsLoad,
+	): IntrospectedProperty {
+		const ns = parent.namespace;
+		const name = element.$.name;
+		const _name = name.replace(/[-]/g, "_");
+		const property = new IntrospectedProperty({
+			name: _name,
+			writable: element.$?.writable === "1",
+			readable: element.$?.readable !== "0",
+			constructOnly: element.$?.["construct-only"] === "1",
+			type: getType(ns, element),
+			parent,
+			isIntrospectable: isIntrospectable(element),
+		});
+
+		if (options.loadDocs) {
+			property.doc = parseDoc(element);
+			property.metadata = parseMetadata(element);
+		}
+
+		property.defaultValue = element.$["default-value"];
+
+		property.getter = element.$.getter;
+
+		if (element.$.nullable === "1" || element.$["allow-none"] === "1") {
+			property.type = makeNullable(property.type);
+		}
+
+		return property;
+	}
+}

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"]>;
+	}
+}