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

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);
+}

package/lib/constants.d.ts

@@ -1,26 +0,0 @@
-import { LibraryVersion } from './library-version.js';
-/**
- * In gjs all classes have a static name property but the classes listed below already have a static name property
- */
-export declare const STATIC_NAME_ALREADY_EXISTS: string[];
-export declare const COMMENT_REG_EXP: RegExp;
-export declare const PARAM_REG_EXP: RegExp;
-export declare const OPT_PARAM_REG_EXP: RegExp;
-export declare const NEW_LINE_REG_EXP: RegExp;
-export declare const MAX_CLASS_PARENT_DEPTH = 100;
-export declare const PACKAGE: {
-    name: string;
-    version: string;
-    description: string;
-    license: string;
-    homepage: string;
-    author: string;
-};
-export declare const APP_NAME = "ts-for-gir";
-export declare const APP_USAGE = "TypeScript type definition generator for GObject introspection GIR files";
-export declare const APP_SOURCE = "https://github.com/gjsify/ts-for-gir";
-export declare const APP_VERSION: string;
-export declare const PACKAGE_DESC: (packageName: string, libraryVersion?: LibraryVersion) => string;
-export declare const PACKAGE_KEYWORDS: (packageName: string) => string;
-export declare const GENERIC_NAMES: string[];
-export declare const SIGNAL_METHOD_NAMES: string[];

package/lib/constants.js

@@ -1,28 +0,0 @@
-import { __dirname, readJsonFile } from './utils.js';
-import { join } from 'path';
-/**
- * In gjs all classes have a static name property but the classes listed below already have a static name property
- */
-export const STATIC_NAME_ALREADY_EXISTS = ['GMime.Charset', 'Camel.StoreInfo'];
-export const COMMENT_REG_EXP = /\/\*.*\*\//g;
-export const PARAM_REG_EXP = /[0-9a-zA-Z_]*:/g;
-export const OPT_PARAM_REG_EXP = /[0-9a-zA-Z_]*\?:/g;
-export const NEW_LINE_REG_EXP = /[\n\r]+/g;
-export const MAX_CLASS_PARENT_DEPTH = 100;
-export const PACKAGE = await readJsonFile(join(__dirname, '../package.json'));
-export const APP_NAME = 'ts-for-gir';
-export const APP_USAGE = 'TypeScript type definition generator for GObject introspection GIR files';
-export const APP_SOURCE = 'https://github.com/gjsify/ts-for-gir';
-export const APP_VERSION = PACKAGE.version;
-export const PACKAGE_DESC = (packageName, libraryVersion) => {
-    if (libraryVersion) {
-        return `GJS TypeScript type definitions for ${packageName}, generated from library version ${libraryVersion.toString()}`;
-    }
-    return `GJS TypeScript type definitions for ${packageName}`;
-};
-export const PACKAGE_KEYWORDS = (packageName) => {
-    return `"Gir", "TypeScript", "types", "GObject-Introspection", "GJS", "${packageName}"`;
-};
-export const GENERIC_NAMES = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'K'];
-export const SIGNAL_METHOD_NAMES = ['connect', 'emit', 'disconnect', 'connect_after', 'emit'];
-//# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA;AAE9E,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAA;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAA;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAA;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAA;AAE1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA;AAEzC,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,YAAY,CAOtC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAA;AAEtC,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAA;AACpC,MAAM,CAAC,MAAM,SAAS,GAAG,0EAA0E,CAAA;AACnG,MAAM,CAAC,MAAM,UAAU,GAAG,sCAAsC,CAAA;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAA;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAmB,EAAE,cAA+B,EAAE,EAAE;IACjF,IAAI,cAAc,EAAE,CAAC;QACjB,OAAO,uCAAuC,WAAW,oCAAoC,cAAc,CAAC,QAAQ,EAAE,EAAE,CAAA;IAC5H,CAAC;IACD,OAAO,uCAAuC,WAAW,EAAE,CAAA;AAC/D,CAAC,CAAA;AACD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,WAAmB,EAAE,EAAE;IACpD,OAAO,kEAAkE,WAAW,GAAG,CAAA;AAC3F,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEzF,MAAM,CAAC,MAAM,mBAAmB,GAAa,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,CAAC,CAAA"}