@ts-for-gir/lib 4.0.0-beta.4 → 4.0.0-beta.40

package/src/utils/types.ts

@@ -0,0 +1,247 @@
+import type { GirAliasElement } from "@gi.ts/parser";
+import { GirDirection } from "@gi.ts/parser";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import {
+	AnyType,
+	ArrayType,
+	BinaryType,
+	BooleanType,
+	NativeType,
+	NeverType,
+	NumberType,
+	ObjectType,
+	StringType,
+	ThisType,
+	type TypeExpression,
+	TypeIdentifier,
+	Uint8ArrayType,
+	UnknownType,
+	VoidType,
+} from "../gir.ts";
+
+/**
+ * Get the type expression for an alias element
+ */
+export function getAliasType(
+	namespace: string,
+	_ns: IntrospectedNamespace,
+	parameter: GirAliasElement,
+): TypeExpression {
+	let name = parameter.type?.[0].$.name || "unknown";
+
+	const nameParts = name.split(" ");
+
+	if (nameParts.length === 1) {
+		name = nameParts[0];
+	} else {
+		name = nameParts[1];
+	}
+
+	return parseTypeExpression(namespace, name);
+}
+
+/**
+ * Parse a type string into namespace and name components
+ */
+export function parseTypeString(type: string): { namespace: string | null; name: string } {
+	if (type.includes(".")) {
+		const parts = type.split(".");
+
+		if (parts.length > 2) {
+			throw new Error(`Invalid type string ${type} passed.`);
+		}
+
+		const [namespace, name] = parts;
+
+		return { name, namespace };
+	} else {
+		return { name: type, namespace: null };
+	}
+}
+
+/**
+ * Parse a type identifier from namespace and type string
+ */
+export function parseTypeIdentifier(namespace: string, type: string): TypeIdentifier {
+	const baseType = parseTypeString(type);
+
+	if (baseType.namespace) {
+		return new TypeIdentifier(baseType.name, baseType.namespace);
+	} else {
+		return new TypeIdentifier(baseType.name, namespace);
+	}
+}
+
+/**
+ * Parse a type expression from namespace and type string
+ */
+export function parseTypeExpression(namespace: string, type: string): TypeExpression {
+	const baseType = parseTypeString(type);
+	if (baseType.namespace) {
+		if (baseType.namespace === namespace) {
+			return new TypeIdentifier(baseType.name, namespace);
+		}
+		return new TypeIdentifier(baseType.name, baseType.namespace).sanitize();
+	} else {
+		const primitiveType = resolvePrimitiveType(baseType.name);
+
+		if (primitiveType !== null) {
+			return primitiveType;
+		} else {
+			return new TypeIdentifier(baseType.name, namespace);
+		}
+	}
+}
+
+/**
+ * Resolve primitive array types with their correct depth
+ */
+export function resolvePrimitiveArrayType(name: string, arrayDepth: number): [TypeExpression, number] | null {
+	if (arrayDepth > 0) {
+		switch (name) {
+			case "gint8":
+			case "guint8":
+				return [Uint8ArrayType, arrayDepth - 1];
+			case "gunichar":
+				return [StringType, arrayDepth - 1];
+		}
+	}
+
+	const resolvedName = resolvePrimitiveType(name);
+
+	if (resolvedName) {
+		return [resolvedName, arrayDepth];
+	} else {
+		return null;
+	}
+}
+
+/**
+ * Check if a type name is a primitive type
+ */
+export function isPrimitiveType(name: string): boolean {
+	return resolvePrimitiveType(name) !== null;
+}
+
+/**
+ * Resolve primitive type names to TypeExpression instances
+ */
+export function resolvePrimitiveType(name: string): TypeExpression | null {
+	switch (name) {
+		case "":
+			console.error(`Resolving '' to any on ${name}`);
+			return AnyType;
+		case "filename":
+			return StringType;
+		// Pass this through
+		case "GType":
+			return new TypeIdentifier("GType", "GObject");
+		case "utf8":
+			return StringType;
+		case "void": // Support TS "void"
+		case "none":
+			return VoidType;
+		// TODO Some libraries are bad and don't use g-prefixed numerical types
+		case "uint":
+		case "int":
+		case "uint8":
+		case "int8":
+		case "uint16":
+		case "int16":
+		case "uint32":
+		case "int32":
+		case "int64":
+		case "uint64":
+		case "double":
+		case "long":
+		case "float":
+		// Most libraries will use these though:
+		case "gshort":
+		case "guint32":
+		case "guint16":
+		case "gint16":
+		case "gint8":
+		case "gint32":
+		case "gushort":
+		case "gfloat":
+		case "gchar":
+		case "guint":
+		case "glong":
+		case "gulong":
+		case "gint":
+		case "guint8":
+		case "guint64":
+		case "gint64":
+		case "gdouble":
+		case "gssize":
+		case "gsize":
+		case "time_t": // C standard library time type (seconds since Unix epoch)
+		case "ulong": // C standard library unsigned long type
+			return NumberType;
+		case "gboolean":
+			return BooleanType;
+		case "gpointer": // This is typically used in callbacks to pass data, so we'll allow anything.
+			return AnyType;
+		case "object": // Support TS "object"
+			return ObjectType;
+		case "va_list":
+			return AnyType;
+		case "guintptr": // You can't use pointers in GJS! (at least that I'm aware of)
+			return NeverType;
+		case "never": // Support TS "never"
+			return NeverType;
+		case "unknown": // Support TS "unknown"
+			return UnknownType;
+		case "any": // Support TS "any"
+			return AnyType;
+		case "this": // Support TS "this"
+			return ThisType;
+		case "number": // Support TS "number"
+			return NumberType;
+		case "gunichar":
+		case "string": // Support TS "string"
+			return StringType;
+		case "boolean": // Support TS "boolean"
+			return BooleanType;
+	}
+
+	return null;
+}
+
+/**
+ * Resolve directional types based on GIR direction
+ */
+export function resolveDirectedType(type: TypeExpression, direction: GirDirection): TypeExpression | null {
+	if (type instanceof ArrayType) {
+		if (
+			(direction === GirDirection.In || direction === GirDirection.Inout) &&
+			type.type.equals(Uint8ArrayType) &&
+			type.arrayDepth === 0
+		) {
+			return new BinaryType(type, StringType);
+		} else {
+			// Rewrap arrays if they have directional types
+			return type.rewrap(resolveDirectedType(type.type, direction) ?? type.type);
+		}
+	} else if (type instanceof TypeIdentifier) {
+		if ((direction === GirDirection.In || direction === GirDirection.Inout) && type.is("GLib", "Bytes")) {
+			return new BinaryType(type, Uint8ArrayType);
+		} else if (type.is("GObject", "Value")) {
+			if (direction === GirDirection.In || direction === GirDirection.Inout) {
+				return new BinaryType(type, AnyType);
+			} else {
+				// GJS converts GObject.Value out parameters to their unboxed type, which we don't know,
+				// so type as `unknown`
+				return UnknownType;
+			}
+		} else if (type.is("GLib", "HashTable")) {
+			if (direction === GirDirection.In) {
+				return new BinaryType(new NativeType("{ [key: string]: any }"), type);
+			} else {
+				return type;
+			}
+		}
+	}
+
+	return null;
+}

package/src/validators/class.ts

@@ -0,0 +1,324 @@
+import { IntrospectedDirectAllocationConstructor } from "../gir/direct-allocation-constructor.ts";
+import { IntrospectedError } from "../gir/error.ts";
+import type { IntrospectedBaseClass, IntrospectedClass, IntrospectedInterface } from "../gir/introspected-classes.ts";
+import { IntrospectedClassFunction, IntrospectedStaticClassFunction } from "../gir/introspected-classes.ts";
+import { IntrospectedRecord } from "../gir/record.ts";
+import { AnyType, NativeType, TypeIdentifier } from "../gir.ts";
+import { resolveTypeIdentifier } from "../utils/type-resolution.ts";
+import { GirVisitor } from "../visitor.ts";
+
+const filterIntrospectableClassMembers = <T extends IntrospectedBaseClass>(node: T): T => {
+	node.fields = node.fields.filter((field) => field.isIntrospectable);
+	node.props = node.props.filter((prop) => prop.isIntrospectable);
+	node.callbacks = node.callbacks.filter((prop) => prop.isIntrospectable);
+	node.constructors = node.constructors.filter((prop) => prop.isIntrospectable);
+	node.members = node.members.filter((prop) => prop.isIntrospectable);
+
+	return node;
+};
+
+const PROTECTED_FIELD_NAMES = ["parent_instance", "parent", "parent_class", "object_class"];
+
+const filterProtectedFields = <T extends IntrospectedBaseClass>(node: T): T => {
+	const set = new Set(PROTECTED_FIELD_NAMES);
+
+	node.fields = node.fields.filter((f) => {
+		return !set.has(f.name);
+	});
+
+	return node;
+};
+
+/**
+ * Filters fields, properties, and members to ensure they are not named
+ * after reserved object keys (prototype, constructor)
+ */
+const filterReservedProperties = <T extends IntrospectedBaseClass>(node: T): T => {
+	const set = new Set(["prototype", "constructor"]);
+
+	node.fields = node.fields.filter((f) => {
+		return !set.has(f.name);
+	});
+
+	node.props = node.props.filter((p) => {
+		return !set.has(p.name);
+	});
+
+	node.members = node.members.filter((m) => {
+		return !set.has(m.name);
+	});
+
+	return node;
+};
+
+const filterConflictingNamedClassMembers = <T extends IntrospectedBaseClass>(node: T): T => {
+	// Props shadow members
+	node.members = node.members.filter((m) => {
+		return !node.props.some((prop) => prop.name === m.name && !(m instanceof IntrospectedStaticClassFunction));
+	});
+
+	// Props and members shadow fields
+	node.fields = node.fields.filter(
+		(f) =>
+			!node.members.some((n) => n.name === f.name && !(n instanceof IntrospectedStaticClassFunction)) &&
+			!node.props.some((n) => n.name === f.name),
+	);
+
+	return node;
+};
+
+/**
+ * Subtypes of ParamSpec are not supported (e.g. a subtype of ParamSpecString).
+ *
+ * First, we transform the node to use ParamSpec as a parent and then flag it
+ * to not emit.
+ *
+ * If a generator doesn't follow the emit() standard, the parent type will at least
+ * be valid.
+ *
+ * @param node
+ * @returns
+ */
+const fixParamSpecSubtypes = <T extends IntrospectedBaseClass>(node: T): T => {
+	if (node.superType?.namespace === "GObject" && node.superType.name.startsWith("ParamSpec")) {
+		// We don't assert this import because we don't want to force libraries
+		// to unnecessarily import GObject.
+		node.superType = new TypeIdentifier("ParamSpec", "GObject");
+
+		node.noEmit();
+	}
+
+	return node;
+};
+
+/**
+ * Checks if a class implements a GObject.Object-based interface
+ * If the class is missing a direct parent we inject GObject.Object
+ * as a stand-in considering it already indirectly inherits
+ * from it.
+ *
+ * @param node
+ */
+const fixMissingParent = <T extends IntrospectedBaseClass>(node: T): T => {
+	const { namespace } = node;
+
+	if (node.superType == null) {
+		const isGObject = node.someParent((p) => p.getType().is("GObject", "Object"));
+
+		if (isGObject) {
+			node.superType = namespace.assertInstalledImport("GObject").assertClass("Object").getType();
+		}
+	}
+
+	return node;
+};
+
+/**
+ * Fields cannot be array types, error types,
+ * or class-like types in GJS. This strips
+ * fields which have these "complex" types.
+ *
+ * @param node
+ */
+const removeComplexFields = <T extends IntrospectedBaseClass>(node: T): T => {
+	const { namespace } = node;
+
+	node.fields = node.fields.filter((f) => {
+		const type = f.type.deepUnwrap();
+
+		if (type instanceof NativeType) {
+			return true;
+		}
+
+		if (type instanceof TypeIdentifier) {
+			// Find the type for the identifier
+			const classNode = resolveTypeIdentifier(namespace, type);
+
+			// Don't allow private or disguised fields
+			if (classNode?.isPrivate) {
+				return false;
+			}
+
+			// Only allow fields pointing to simple structs.
+			if (classNode && classNode instanceof IntrospectedRecord && !classNode.isSimple()) {
+				return false;
+			}
+
+			const en = namespace.assertInstalledImport(type.namespace).getEnum(type.name);
+
+			if (!(en instanceof IntrospectedError)) {
+				return true;
+			}
+
+			return false;
+		}
+
+		return true;
+	});
+
+	return node;
+};
+
+/**
+ * TODO: Consider making this transformation optional.
+ *
+ * If we are referencing an unknown library, any-ify the type.
+ *
+ * @param node
+ */
+const removeReferencesToMissingLibraries = <T extends IntrospectedBaseClass>(node: T): T => {
+	const { namespace } = node;
+
+	node.fields = node.fields.map((f) => {
+		const type = f.type.deepUnwrap();
+
+		if (type instanceof TypeIdentifier) {
+			// Find the type for the identifier
+			const nsNode = namespace.getInstalledImport(type.namespace);
+
+			// Don't allow private or disguised fields
+			if (!nsNode) {
+				return f.copy({ type: AnyType });
+			}
+		}
+
+		return f;
+	});
+
+	return node;
+};
+
+const removePrivateFields = <T extends IntrospectedBaseClass>(node: T): T => {
+	node.fields = node.fields.filter((f) => {
+		return !f.isPrivate && !f.name.startsWith("_");
+	});
+
+	return node;
+};
+
+/**
+ * Boxed types have a specific order of preference for
+ * which constructor will be used...
+ *
+ * 1. Zero Args Constructor
+ * 2. Direct Allocation (if the type is simple)
+ * 3. The new() constructor
+ * 4. The first constructor
+ *
+ * @param node
+ */
+const resolveMainConstructor = (node: IntrospectedRecord): IntrospectedRecord => {
+	const newConstructor = node.constructors.find((c) => c.name === "new");
+	const zeroArgsConstructor = node.constructors.find((c) => c.parameters.length === 0);
+	const firstConstructor = node.constructors?.[0];
+
+	if (node.isForeign()) {
+		node.mainConstructor = null;
+
+		return node;
+	}
+
+	if (zeroArgsConstructor || node.isSimpleWithoutPointers()) {
+		node.mainConstructor = IntrospectedDirectAllocationConstructor.fromFields(node.fields, node);
+
+		return node;
+	}
+
+	const resolvedConstructor = newConstructor ?? firstConstructor;
+	if (resolvedConstructor) {
+		node.mainConstructor = resolvedConstructor.copy();
+	}
+
+	if (node.isSimple()) {
+		node.mainConstructor = IntrospectedDirectAllocationConstructor.fromFields(node.fields, node);
+
+		return node;
+	}
+
+	return node;
+};
+
+const mergeStaticDefinitions = (node: IntrospectedClass): IntrospectedClass => {
+	if (!node.staticDefinition) {
+		return node;
+	}
+
+	const { namespace } = node;
+	const staticDefinition = namespace.getClass(node.staticDefinition);
+
+	if (!(staticDefinition instanceof IntrospectedRecord)) {
+		return node;
+	}
+
+	const staticMethods = staticDefinition.members
+		.filter((m) => m instanceof IntrospectedClassFunction)
+		.map((m) => {
+			// Convert the class function to a static class function
+			const { name, parameters, output_parameters, isIntrospectable } = m;
+
+			return new IntrospectedStaticClassFunction({
+				name,
+				parameters,
+				output_parameters,
+				return_type: m.return(),
+				parent: node,
+				isIntrospectable,
+			});
+		});
+
+	for (const staticMethod of staticMethods) {
+		if (
+			!node.members.some(
+				(member) => member.name === staticMethod.name && member instanceof IntrospectedStaticClassFunction,
+			)
+		) {
+			node.members.push(staticMethod);
+		}
+	}
+
+	return node;
+};
+
+function chainVisitors<T>(node: T, ...args: ((node: T) => T)[]) {
+	let currentNode = node;
+
+	for (const visitor of args) {
+		currentNode = visitor(currentNode);
+	}
+
+	return currentNode;
+}
+
+export class ClassVisitor extends GirVisitor {
+	visitClass = (node: IntrospectedClass) =>
+		chainVisitors(
+			node,
+			removeReferencesToMissingLibraries,
+			fixMissingParent,
+			fixParamSpecSubtypes,
+			removeComplexFields,
+			removePrivateFields,
+			mergeStaticDefinitions,
+			filterConflictingNamedClassMembers,
+			filterIntrospectableClassMembers,
+			filterProtectedFields,
+			filterReservedProperties,
+		);
+
+	visitInterface = (node: IntrospectedInterface) =>
+		chainVisitors(node, filterIntrospectableClassMembers, filterReservedProperties);
+
+	visitRecord = (node: IntrospectedRecord) =>
+		chainVisitors(
+			node,
+			fixMissingParent,
+			fixParamSpecSubtypes,
+			resolveMainConstructor,
+			removeComplexFields,
+			removePrivateFields,
+			filterConflictingNamedClassMembers,
+			filterIntrospectableClassMembers,
+			filterProtectedFields,
+			filterReservedProperties,
+		);
+}

package/src/validators/function-parameters.ts

@@ -0,0 +1,52 @@
+import type { IntrospectedEnum } from "../gir/enum.ts";
+import type { IntrospectedFunction } from "../gir/function.ts";
+import type { IntrospectedBaseClass, IntrospectedClassFunction } from "../gir/introspected-classes.ts";
+
+import { NullableType, TypeIdentifier } from "../gir.ts";
+import { GirVisitor } from "../visitor.ts";
+
+export class FunctionParametersVisitor extends GirVisitor {
+	/**
+	 * Marks all enum parameters of a function as nullable,
+	 * because GJS allows null values for enum parameters and treats them as a 0 value.
+	 * See issue [#207](https://github.com/gjsify/ts-for-gir/issues/207).
+	 */
+	private makeEnumParamsNullable(node: IntrospectedFunction): IntrospectedFunction;
+	private makeEnumParamsNullable<T extends IntrospectedBaseClass | IntrospectedEnum>(
+		node: IntrospectedClassFunction<T>,
+	): IntrospectedClassFunction<T>;
+	private makeEnumParamsNullable(
+		node: IntrospectedFunction | IntrospectedClassFunction,
+	): IntrospectedFunction | IntrospectedClassFunction {
+		return node.copy({
+			parameters: node.parameters.map((param) => {
+				const type = param.type.deepUnwrap();
+				if (type instanceof TypeIdentifier) {
+					// Get the namespace where this type should be defined
+					const ns = node.namespace.assertInstalledImport(type.namespace);
+
+					// Check if the type is an enum
+					const isEnumType = !!ns.getEnum(type.name);
+
+					// If it is, make the parameter nullable
+					if (isEnumType) {
+						return param.copy({
+							type: new NullableType(param.type),
+						});
+					}
+				}
+				return param;
+			}),
+		});
+	}
+
+	visitFunction = (node: IntrospectedFunction): IntrospectedFunction => {
+		return this.makeEnumParamsNullable(node);
+	};
+
+	visitClassFunction = <T extends IntrospectedBaseClass | IntrospectedEnum>(
+		node: IntrospectedClassFunction<T>,
+	): IntrospectedClassFunction<T> => {
+		return this.makeEnumParamsNullable(node);
+	};
+}

package/src/validators/interface.ts

@@ -0,0 +1,20 @@
+import type { IntrospectedInterface } from "../gir/introspected-classes.ts";
+import { GirVisitor } from "../visitor.ts";
+
+export class InterfaceVisitor extends GirVisitor {
+	visitInterface = (node: IntrospectedInterface): IntrospectedInterface => {
+		// If an interface does not list a prerequisite type, we fill it with GObject.Object
+		if (!node.noParent && node.superType == null) {
+			const gobject = node.namespace.assertInstalledImport("GObject");
+			const GObject = gobject.assertClass("Object");
+
+			if (!GObject) {
+				throw new Error(`GObject.Object could not be found while generating ${node.namespace.namespace}.${node.name}`);
+			}
+
+			node.superType = GObject.getType();
+		}
+
+		return node;
+	};
+}

package/src/visitor.ts

@@ -0,0 +1,58 @@
+import type { IntrospectedAlias } from "./gir/alias.ts";
+import type { IntrospectedCallback } from "./gir/callback.ts";
+import type { IntrospectedConstant } from "./gir/const.ts";
+import type { IntrospectedConstructor } from "./gir/constructor.ts";
+import type { IntrospectedDirectAllocationConstructor } from "./gir/direct-allocation-constructor.ts";
+import type { IntrospectedEnum } from "./gir/enum.ts";
+import type { GirEnumMember } from "./gir/enum-member.ts";
+import type { IntrospectedError } from "./gir/error.ts";
+import type { IntrospectedFunction } from "./gir/function.ts";
+import type {
+	IntrospectedBaseClass,
+	IntrospectedClass,
+	IntrospectedClassCallback,
+	IntrospectedClassFunction,
+	IntrospectedInterface,
+	IntrospectedStaticClassFunction,
+	IntrospectedVirtualClassFunction,
+} from "./gir/introspected-classes.ts";
+import type { IntrospectedNamespace } from "./gir/namespace.ts";
+import type { IntrospectedFunctionParameter } from "./gir/parameter.ts";
+import type { IntrospectedField, IntrospectedProperty } from "./gir/property.ts";
+import type { IntrospectedRecord } from "./gir/record.ts";
+import type { IntrospectedSignal, IntrospectedSignalType } from "./gir/signal.ts";
+import type { TypeExpression } from "./gir.ts";
+
+export abstract class GirVisitor {
+	visitType?: (node: TypeExpression) => TypeExpression;
+	visitCallback?: (node: IntrospectedCallback) => IntrospectedCallback;
+	visitClassCallback?: (node: IntrospectedClassCallback) => IntrospectedClassCallback;
+	visitAlias?: (node: IntrospectedAlias) => IntrospectedAlias;
+	visitConstructor?: (node: IntrospectedConstructor) => IntrospectedConstructor;
+	visitDirectAllocationConstructor?: (
+		node: IntrospectedDirectAllocationConstructor,
+	) => IntrospectedDirectAllocationConstructor;
+	visitConstructorFunction?: (node: IntrospectedConstructor) => IntrospectedConstructor;
+	visitRecord?: (node: IntrospectedRecord) => IntrospectedRecord;
+	visitInterface?: (node: IntrospectedInterface) => IntrospectedInterface;
+	visitEnumMember?: (node: GirEnumMember) => GirEnumMember;
+	visitError?: (node: IntrospectedError) => IntrospectedError;
+	visitEnum?: (node: IntrospectedEnum) => IntrospectedEnum;
+	visitConst?: (node: IntrospectedConstant) => IntrospectedConstant;
+	visitClass?: (node: IntrospectedClass) => IntrospectedClass;
+	visitParameter?: (node: IntrospectedFunctionParameter) => IntrospectedFunctionParameter;
+	visitProperty?: (node: IntrospectedProperty) => IntrospectedProperty;
+	visitField?: (node: IntrospectedField) => IntrospectedField;
+	visitSignal?: (node: IntrospectedSignal, type?: IntrospectedSignalType) => IntrospectedSignal;
+	visitFunction?: (node: IntrospectedFunction) => IntrospectedFunction;
+	visitClassFunction?: <T extends IntrospectedBaseClass | IntrospectedEnum>(
+		node: IntrospectedClassFunction<T>,
+	) => IntrospectedClassFunction<T>;
+	visitStaticClassFunction?: (node: IntrospectedStaticClassFunction) => IntrospectedStaticClassFunction;
+	visitVirtualClassFunction?: (node: IntrospectedVirtualClassFunction) => IntrospectedVirtualClassFunction;
+	visitNamespace?: (node: IntrospectedNamespace) => IntrospectedNamespace;
+}
+
+export function visit(namespace: IntrospectedNamespace, visitor: GirVisitor) {
+	namespace.accept(visitor);
+}