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

package/src/utils/gir-parsing.ts

@@ -0,0 +1,262 @@
+import type {
+	GirCallableParamElement,
+	GirCallableReturn,
+	GirConstantElement,
+	GirDocElement,
+	GirFieldElement,
+	GirFunctionElement,
+	GirInfoAttrs,
+	GirMethodElement,
+	GirType,
+} from "@gi.ts/parser";
+import { GirDirection } from "@gi.ts/parser";
+import { LazyReporter } from "@ts-for-gir/reporter";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import {
+	ArrayType,
+	ClosureType,
+	GenerifiedTypeIdentifier,
+	NativeType,
+	NullableType,
+	type TypeExpression,
+	TypeIdentifier,
+	VoidType,
+} from "../gir.ts";
+import type { IntrospectedMetadata } from "../types/introspected.ts";
+import { deprecatedVersion, introducedVersion, isDeprecated } from "./girs.ts";
+import { isPrimitiveType, parseTypeExpression, resolvePrimitiveArrayType } from "./types.ts";
+
+export const girParsingReporter = new LazyReporter("GirParsing");
+
+/**
+ * Parse documentation from a GIR element
+ */
+export function parseDoc(element: GirDocElement): string | null {
+	const el = element.doc?.[0]?._;
+
+	return el ? `${el}` : null;
+}
+
+/**
+ * Parse deprecated documentation from a GIR element
+ */
+export function parseDeprecatedDoc(element: GirDocElement): string | null {
+	return element["doc-deprecated"]?.[0]?._ ?? null;
+}
+
+/**
+ * Parse metadata from a GIR element
+ */
+export function parseMetadata(element: { $: GirInfoAttrs } & GirDocElement): IntrospectedMetadata | undefined {
+	const version = introducedVersion(element);
+	const deprecatedIn = deprecatedVersion(element);
+	const deprecated = isDeprecated(element);
+	const doc = parseDeprecatedDoc(element);
+
+	if (!version && !deprecated && !deprecatedIn && !doc) {
+		return undefined;
+	}
+
+	return {
+		...(deprecated ? { deprecated } : {}),
+		...(doc ? { deprecatedDoc: doc } : {}),
+		...(deprecatedIn ? { deprecatedVersion: deprecatedIn } : {}),
+		...(version ? { introducedVersion: version } : {}),
+	};
+}
+
+/**
+ * This function determines whether a given type is a "pointer type"...
+ * Any type where the c:type ends with *
+ */
+function isPointerType(types: GirType[] | undefined) {
+	const type = types?.[0];
+	if (!type) return false;
+
+	const ctype = type.$["c:type"];
+	if (!ctype) return false;
+
+	const typeName = type.$.name;
+	if (!typeName) return false;
+
+	if (isPrimitiveType(typeName)) return false;
+
+	return ctype.endsWith("*");
+}
+
+/**
+ * Decode the type from GIR elements
+ */
+export function getType(
+	ns: IntrospectedNamespace,
+	param?: GirConstantElement | GirCallableReturn | GirFieldElement,
+): TypeExpression {
+	const modName = ns.namespace;
+
+	if (!param) return VoidType;
+
+	let name = "";
+	let arrayDepth: number | null = null;
+	let length: number | null = null;
+	let isPointer = false;
+
+	const parameter = param as GirCallableParamElement;
+	if (parameter.array?.[0]) {
+		arrayDepth = 1;
+
+		const [array] = parameter.array;
+
+		if (array.$ && array.$.length != null) {
+			length = array.$.length;
+		}
+
+		if (array.type?.[0].$?.name) {
+			name = array.type[0].$.name;
+		} else if (array.array) {
+			let arr = array;
+			let depth = 1;
+
+			while (Array.isArray(arr.array)) {
+				arr = arr.array[0];
+				depth++;
+			}
+
+			const possibleName = arr.type?.[0].$.name;
+			if (possibleName) {
+				name = possibleName;
+			} else {
+				name = "unknown";
+				const cType = (arr.type?.[0].$ as Record<string, string>)?.["c:type"] || "unknown";
+				girParsingReporter
+					.get()
+					.reportTypeResolutionWarning(
+						cType,
+						ns.namespace,
+						`Failed to find array type in ${ns.packageName}, marking as unknown`,
+						`c:type=${cType}`,
+					);
+			}
+			arrayDepth = depth;
+			isPointer = isPointerType(array.type);
+		} else {
+			name = "unknown";
+		}
+	} else if (parameter.type?.[0]?.$) {
+		const possibleName = parameter.type[0].$.name;
+		if (possibleName) {
+			name = possibleName;
+		} else {
+			name = "unknown";
+			const cType = (parameter.type[0].$ as Record<string, string>)?.["c:type"] || "unknown";
+			girParsingReporter
+				.get()
+				.reportTypeResolutionWarning(
+					cType,
+					modName,
+					`Failed to find type in ${modName}, marking as unknown`,
+					`c:type=${cType}`,
+				);
+		}
+		isPointer = isPointerType(parameter.type);
+	} else if (parameter.varargs || (parameter.$ && parameter.$.name === "...")) {
+		arrayDepth = 1;
+		name = "any";
+	} else {
+		name = "unknown";
+		girParsingReporter
+			.get()
+			.reportTypeResolutionWarning(
+				"varargs",
+				modName,
+				`Unknown varargs type in ${modName}, marking as unknown`,
+				parameter.$ ? JSON.stringify(parameter.$) : undefined,
+			);
+	}
+
+	let closure = null as null | number;
+
+	if (parameter.$?.closure) {
+		closure = parameter.$.closure;
+	}
+
+	const nullable = parameter.$ && parameter.$.nullable === "1";
+	const allowNone = parameter.$ && parameter.$["allow-none"] === "1";
+
+	const x = name.split(" ");
+	if (x.length === 1) {
+		name = x[0];
+	} else {
+		name = x[1];
+	}
+
+	let variableType: TypeExpression = parseTypeExpression(ns.namespace, name);
+
+	if (variableType instanceof TypeIdentifier) {
+		if (variableType.is("GLib", "List") || variableType.is("GLib", "SList")) {
+			// TODO: $?.name was not necessary in gi.ts, but TelepathyLogger
+			// fails to generate now.
+			const listType = parameter?.type?.[0].type?.[0]?.$?.name;
+
+			if (listType) {
+				name = listType;
+				variableType = parseTypeExpression(ns.namespace, name);
+
+				arrayDepth = 1;
+			}
+		} else if (variableType.is("GLib", "HashTable")) {
+			const keyType = parameter?.type?.[0]?.type?.[0]?.$.name;
+			const valueType = parameter?.type?.[0]?.type?.[1]?.$.name;
+
+			if (keyType && valueType) {
+				const key = parseTypeExpression(ns.namespace, keyType);
+				const value = parseTypeExpression(ns.namespace, valueType);
+
+				variableType = new GenerifiedTypeIdentifier("HashTable", "GLib", [key, value]);
+			}
+		}
+	}
+
+	if (arrayDepth != null) {
+		const primitiveArrayType = resolvePrimitiveArrayType(name, arrayDepth);
+
+		if (primitiveArrayType) {
+			const [primitiveName, primitiveArrayDepth] = primitiveArrayType;
+
+			variableType = ArrayType.new({
+				type: primitiveName,
+				arrayDepth: primitiveArrayDepth,
+				length,
+			});
+		} else {
+			variableType = ArrayType.new({ type: variableType, arrayDepth, length });
+		}
+	} else if (closure != null) {
+		variableType = ClosureType.new({ type: variableType, user_data: closure });
+	}
+
+	if (
+		parameter.$ &&
+		(parameter.$.direction === GirDirection.Inout || parameter.$.direction === GirDirection.Out) &&
+		(nullable || allowNone) &&
+		!(variableType instanceof NativeType)
+	) {
+		return new NullableType(variableType);
+	}
+
+	if ((!parameter.$?.direction || parameter.$.direction === GirDirection.In) && nullable) {
+		return new NullableType(variableType);
+	}
+
+	variableType.isPointer = isPointer;
+
+	return variableType;
+}
+
+/**
+ * Check if a function/method element has a shadow attribute
+ */
+export function hasShadow(
+	obj: GirFunctionElement | GirMethodElement,
+): obj is GirFunctionElement & { $: { shadows: string } } {
+	return obj.$.shadows != null;
+}

package/src/utils/girs.ts

@@ -0,0 +1,113 @@
+import type { GirInfoAttrs } from "@gi.ts/parser";
+import type { TsDoc } from "../types/index.ts";
+
+/**
+ * Split a package name into namespace and version
+ */
+export const splitModuleName = (packageName: string): { packageName: string; namespace: string; version: string } => {
+	// Workaround for Vte-4-2.91
+	if (packageName.startsWith("Vte-4")) {
+		return {
+			packageName,
+			namespace: "Vte",
+			version: packageName.replace("Vte-", ""),
+		};
+	}
+	if (!packageName.includes("-")) {
+		return {
+			packageName,
+			namespace: packageName,
+			version: "",
+		};
+	}
+	// There are modules that use multiple hyphens like 'GUPnP-DLNA-1.0'
+	const splits = packageName.split("-");
+	const version = splits.splice(-1, 1)[0];
+	const namespace = splits.join("");
+
+	return {
+		packageName,
+		namespace,
+		version,
+	};
+};
+
+/** Remove namespace prefix */
+export const removeNamespace = (type: string, namespace: string) => {
+	if (type.startsWith(`${namespace}.`)) {
+		type = type.substring(namespace.length + 1);
+	}
+	return type;
+};
+
+/** Remove class module name prefix */
+export const removeClassModule = removeNamespace;
+
+/**
+ * Add namespace prefix
+ */
+export const addNamespace = (type: string, namespace: string) => {
+	if (!type.startsWith(`${namespace}.`)) {
+		type = `${namespace}.${type}`;
+	}
+	return type;
+};
+
+/**
+ * Check if a line is a comment line
+ * @param line The line to check
+ * @returns Whether the line is a comment line or not
+ */
+export const isCommentLine = (line: string) => {
+	const lineTrim = line.trim();
+	return lineTrim.startsWith("//") || (lineTrim.startsWith("/*") && lineTrim.endsWith("*/"));
+};
+
+/**
+ * Convert a GirBoolean to a boolean
+ * @param boolStr The GirBoolean string
+ * @param defaultVal The default value
+ * @returns The boolean value
+ */
+export const girBool = (boolStr: string | undefined, defaultVal = false): boolean => {
+	if (boolStr) {
+		if (parseInt(boolStr, 10) === 0) return false;
+		return true;
+	}
+	return defaultVal;
+};
+
+export const printGirDocComment = (tsDoc: TsDoc, config: { noComments: boolean }) => {
+	const desc: string[] = [];
+	if (config.noComments) {
+		return desc.join("\n");
+	}
+
+	const text = tsDoc.text;
+
+	if (text) {
+		if (text) {
+			const lines = text.split("\n");
+			if (lines.length) {
+				for (const line of lines) {
+					desc.push(`${line}`);
+				}
+			}
+		}
+
+		for (const tag of tsDoc.tags) {
+			if (tag.paramName) {
+				desc.push(`@${tag.tagName} ${tag.paramName} ${tag.text}`);
+			} else {
+				desc.push(`@${tag.tagName} ${tag.text}`);
+			}
+		}
+	}
+	return desc.join("\n");
+};
+
+export const isIntrospectable = (e: { $?: GirInfoAttrs }) =>
+	!e || !e.$ || !e.$.introspectable || e.$.introspectable === "1";
+export const isDeprecated = (e: { $: GirInfoAttrs }) => e?.$ && e.$.deprecated === "1";
+export const deprecatedVersion = (e: { $: GirInfoAttrs }) => e?.$?.["deprecated-version"];
+export const introducedVersion = (e: { $: GirInfoAttrs }) => e?.$?.version;

package/src/utils/index.ts

@@ -0,0 +1,14 @@
+export * from "./conflicts.ts";
+export * from "./documentation.ts";
+export * from "./files.ts";
+export * from "./generation.ts";
+export * from "./gir-parsing.ts";
+export * from "./girs.ts";
+export * from "./naming.ts";
+export * from "./numbers.ts";
+export * from "./objects.ts";
+export * from "./path.ts";
+export * from "./registry.ts";
+export * from "./strings.ts";
+export * from "./type-resolution.ts";
+export * from "./types.ts";

package/src/utils/naming.ts

@@ -0,0 +1,188 @@
+import { RESERVED_NAMESPACE_NAMES } from "../constants.ts";
+import { isFirstCharNumeric, upperCamelCase } from "./strings.ts";
+
+// Reserved words for identifier sanitization
+const reservedWords = [
+	"abstract",
+	"arguments",
+	"await",
+	"boolean",
+	"break",
+	"byte",
+	"case",
+	"catch",
+	"char",
+	"class",
+	"const",
+	"continue",
+	"constructor", // This isn't technically reserved, but it's problematic.
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"eval",
+	"export",
+	"extends",
+	"false",
+	"final",
+	"finally",
+	"for",
+	"function",
+	"goto",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"native",
+	"new",
+	"null",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"short",
+	"static",
+	"super",
+	"switch",
+	"synchronized",
+	"this",
+	"throw",
+	"throws",
+	"transient",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"volatile",
+	"while",
+	"with",
+	"yield",
+];
+
+// Map to store sanitized identifiers
+export const SanitizedIdentifiers = new Map<string, string>();
+
+/**
+ * Transform a package name to import name format (lowercase)
+ * @param packageName The package name to transform
+ * @returns The transformed import name
+ */
+export function transformImportName(packageName: string): string {
+	return packageName.toLowerCase();
+}
+
+/**
+ * Transform a module namespace name to the proper format
+ * Handles numeric names and reserved namespace names
+ * @param name The namespace name to transform
+ * @returns The transformed namespace name
+ */
+export function transformModuleNamespaceName(name: string): string {
+	// Handle numeric names - prepend 'TODO_' if name starts with a number
+	name = transformNumericName(name);
+
+	// Convert to upperCamelCase
+	name = upperCamelCase(name);
+
+	// Handle reserved namespace names
+	if (RESERVED_NAMESPACE_NAMES[name]) {
+		name = `${name}_`;
+	}
+
+	return name;
+}
+
+/**
+ * Transform names starting with numbers by prepending 'TODO_'
+ * In JavaScript there can be no variables, methods, class names or enum names that start with a number
+ * @param name The name to transform
+ * @returns The transformed name
+ */
+function transformNumericName(name: string): string {
+	if (isFirstCharNumeric(name)) {
+		name = `TODO_${name}`;
+	}
+	return name;
+}
+
+/**
+ * Sanitize identifier name to be valid JavaScript identifier
+ * @param namespace The namespace for the identifier (can be null)
+ * @param name The name to sanitize
+ * @returns The sanitized identifier name
+ */
+export function sanitizeIdentifierName(namespace: string | null, name: string): string {
+	// This is a unique case where the name is "empty".
+	if (name === "") {
+		return "''";
+	}
+
+	let sanitized_name = name.replace(/[^A-z0-9_]/gi, "_");
+
+	if (reservedWords.includes(sanitized_name)) {
+		sanitized_name = `__${sanitized_name}`;
+	}
+
+	if (sanitized_name.match(/^[^A-z_]/) != null) {
+		sanitized_name = `__${sanitized_name}`;
+	}
+
+	if (namespace && sanitized_name !== name) {
+		SanitizedIdentifiers.set(`${namespace}.${name}`, `${namespace}.${sanitized_name}`);
+	}
+
+	return sanitized_name;
+}
+
+/**
+ * Sanitize namespace name - fix broken namespacing in some GIRs
+ * @param namespace The namespace to sanitize
+ * @returns The sanitized namespace
+ */
+export function sanitizeNamespace(namespace: string): string {
+	if (namespace === "Tracker_Vala") {
+		return "Tracker";
+	}
+
+	return namespace;
+}
+
+/**
+ * Sanitize member names for safe usage
+ * @param name The member name to sanitize
+ * @returns The sanitized member name
+ */
+export function sanitizeMemberName(name: string): string {
+	// This is a unique case where the name is "empty".
+	if (name === "") {
+		return "''";
+	}
+
+	return name.replace(/[^A-z0-9_]/gi, "_");
+}
+
+/**
+ * Check if a name would be invalid as JavaScript identifier
+ * @param name The name to check
+ * @returns True if the name would be invalid
+ */
+export function isInvalid(name: string): boolean {
+	if (reservedWords.includes(name)) {
+		return true;
+	}
+
+	const sanitized = sanitizeMemberName(name);
+
+	if (sanitized.match(/^[^A-z_]/) != null) {
+		return true;
+	}
+
+	return false;
+}

package/src/utils/numbers.ts

@@ -0,0 +1,8 @@
+/**
+ * Checking whether a string is numeric
+ * @param str The string to check
+ * @returns Whether the string is numeric or not
+ */
+export const isNumeric = (str: string): boolean => {
+	return !Number.isNaN(Number(str) - parseFloat(str));
+};

package/src/utils/objects.ts

@@ -0,0 +1,129 @@
+import lodash from "lodash";
+
+export { inspect } from "node:util";
+
+/**
+ * Performs a deep comparison between two values to determine if they are
+ * equivalent.
+ *
+ * **Note:** This method supports comparing arrays, array buffers, booleans,
+ * date objects, error objects, maps, numbers, `Object` objects, regexes,
+ * sets, strings, symbols, and typed arrays. `Object` objects are compared
+ * by their own, not inherited, enumerable properties. Functions and DOM
+ * nodes are **not** supported.
+ *
+ * @category Lang
+ * @param value The value to compare.
+ * @param other The other value to compare.
+ * @returns Returns `true` if the values are equivalent, else `false`.
+ * @example
+ *
+ * var object = { 'user': 'fred' };
+ * var other = { 'user': 'fred' };
+ *
+ * _.isEqual(object, other);
+ * // => true
+ *
+ * object === other;
+ * // => false
+ */
+export const isEqual = lodash.isEqual;
+
+/**
+ * Creates an array of values by running each element in collection through iteratee. The iteratee is
+ * invoked with three arguments: (value, index|key, collection).
+ *
+ * Many lodash methods are guarded to work as iteratees for methods like _.every, _.filter, _.map, _.mapValues,
+ * _.reject, and _.some.
+ *
+ * The guarded methods are:
+ * ary, callback, chunk, clone, create, curry, curryRight, drop, dropRight, every, fill, flatten, invert, max,
+ * min, parseInt, slice, sortBy, take, takeRight, template, trim, trimLeft, trimRight, trunc, random, range,
+ * sample, some, sum, uniq, and words
+ *
+ * @param collection The collection to iterate over.
+ * @param iteratee The function invoked per iteration.
+ * @return Returns the new mapped array.
+ */
+export const map = lodash.map;
+
+/**
+ * Iterates over elements of collection, returning the first element predicate returns truthy for.
+ * The predicate is invoked with three arguments: (value, index|key, collection).
+ *
+ * @param collection The collection to search.
+ * @param predicate The function invoked per iteration.
+ * @param fromIndex The index to search from.
+ * @return Returns the matched element, else undefined.
+ */
+export const find = lodash.find;
+
+/**
+ * Recursively merges own and inherited enumerable properties of source
+ * objects into the destination object, skipping source properties that resolve
+ * to `undefined`. Array and plain object properties are merged recursively.
+ * Other objects and value types are overridden by assignment. Source objects
+ * are applied from left to right. Subsequent sources overwrite property
+ * assignments of previous sources.
+ *
+ * **Note:** This method mutates `object`.
+ *
+ * @category Object
+ * @param object The destination object.
+ * @param [sources] The source objects.
+ * @returns Returns `object`.
+ * @example
+ *
+ * var users = {
+ *   'data': [{ 'user': 'barney' }, { 'user': 'fred' }]
+ * };
+ *
+ * var ages = {
+ *   'data': [{ 'age': 36 }, { 'age': 40 }]
+ * };
+ *
+ * _.merge(users, ages);
+ * // => { 'data': [{ 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }] }
+ */
+export const merge = lodash.merge;
+
+/**
+ * Creates a shallow clone of value.
+ *
+ * Note: This method is loosely based on the structured clone algorithm and supports cloning arrays,
+ * array buffers, booleans, date objects, maps, numbers, Object objects, regex's, sets, strings, symbols,
+ * and typed arrays. The own enumerable properties of arguments objects are cloned as plain objects. An empty
+ * object is returned for not cloneable values such as error objects, functions, DOM nodes, and WeakMaps.
+ *
+ * @param value The value to clone.
+ * @return Returns the cloned value.
+ */
+export const clone = lodash.clone;
+
+/**
+ * This method is like clone except that it recursively clones value.
+ *
+ * @param value The value to recursively clone.
+ * @return Returns the deep cloned value.
+ */
+export const cloneDeep = lodash.cloneDeep;
+
+/**
+ * Checking whether some variable is iterable
+ * @see https://stackoverflow.com/a/32538867
+ * @param obj Variable to check for iterable
+ * @returns Whether the variable is iterable or not
+ */
+export const isIterable = (obj: unknown[]): boolean => {
+	return obj != null && typeof obj[Symbol.iterator] === "function";
+};
+
+/**
+ * Union (a ∪ b): create a set that contains the elements of both set a and set b.
+ * See https://2ality.com/2015/01/es6-set-operations.html#union
+ * @param target
+ * @param source
+ */
+export const union = <T>(target: Set<T> | T[], source: Set<T> | T[]): Set<T> => {
+	return new Set<T>([...target, ...source]);
+};