@ts-for-gir/cli 3.0.0-beta.10

package/src/utils.ts

@@ -0,0 +1,433 @@
+/* eslint-disable @typescript-eslint/unbound-method */
+import lodash from 'lodash'
+import Path from 'path'
+import fs from 'fs'
+import { getTsconfig, TsConfigJsonResolved } from 'get-tsconfig'
+import { fileURLToPath } from 'url'
+import { Environment, GirInfoAttrs, TsType, FileInfo } from './types/index.js'
+import { inspect } from 'util'
+import { Logger } from './logger.js'
+
+import { COMMENT_REG_EXP, PARAM_REG_EXP, OPT_PARAM_REG_EXP } from './constants.js'
+
+export { inspect }
+
+/**
+ * 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
+
+/**
+ * Split a package name into namespace and version
+ */
+export const splitModuleName = (packageName: string): { packageName: string; namespace: string; version: string } => {
+    // 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
+}
+
+/**
+ * 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'
+}
+
+/**
+ * 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 => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return !isNaN((str as any) - parseFloat(str))
+}
+
+/**
+ * Get the first character of a string
+ * @param str The string to get the first character from
+ * @returns The first character
+ */
+export const getFirstChar = (str: string): string => {
+    return str.charAt(0)
+}
+
+/**
+ * Get the last character of a string
+ * @param str The string to get the last character from
+ * @returns The last character
+ */
+export const getLastChar = (str: string): string => {
+    return str.charAt(str.length - 1)
+}
+
+/**
+ * Check if the first character of a string is numeric
+ * @param str The string to check
+ * @returns Whether the first character is numeric or not
+ */
+export const isFirstCharNumeric = (str: string): boolean => {
+    return isNumeric(getFirstChar(str))
+}
+
+/**
+ * Convert a string to camelCase
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const camelCase = (str: string): string => {
+    return str
+        .replace(/\s(.)|(\s|-|_|\.)(.)/g, (a) => {
+            return a.toUpperCase()
+        })
+        .replace(/(\s|-|_|\.)/g, '')
+}
+
+/**
+ * Convert a string to lowerCamelCase
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const lowerCamelCase = (str: string): string => {
+    str = camelCase(str)
+    str = getFirstChar(str).toLowerCase() + str.slice(1)
+    return str
+}
+
+/**
+ * Convert a string to UpperCamelCase
+ * @param str The string to convert
+ * @returns The converted string
+ */
+export const upperCamelCase = (str: string): string => {
+    str = camelCase(str)
+    str = getFirstChar(str).toUpperCase() + str.slice(1)
+    return str
+}
+
+/**
+ * Find a file in a list of directories
+ * @param dirs The directories to search in
+ * @param filename The filename to search for
+ * @returns The file info
+ */
+export const findFileInDirs = (dirs: string[], filename: string): FileInfo => {
+    const FileInfo: FileInfo = {
+        path: null,
+        filename,
+        exists: false,
+    }
+    for (const dir of dirs) {
+        const filePath = Path.join(dir, filename)
+        FileInfo.exists = fs.existsSync(filePath)
+        if (FileInfo.exists) {
+            FileInfo.path = filePath
+            return FileInfo
+        }
+    }
+
+    return FileInfo
+}
+
+/**
+ * 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 (target = new Set<T>([...target, ...source]))
+}
+
+export const stripParamNames = (func: string, ignoreTail = false): string => {
+    const g = func
+    func = func.replace(COMMENT_REG_EXP, '')
+    const lb = func.split('(', 2)
+    if (lb.length < 2) Logger.error(`Bad function definition ${g}`)
+    const rb = lb[1].split(')')
+    const tail = ignoreTail ? '' : rb[rb.length - 1]
+    let params = rb.slice(0, rb.length - 1).join(')')
+    params = params.replace(PARAM_REG_EXP, ':')
+    params = params.replace(OPT_PARAM_REG_EXP, '?:')
+    return `${lb[0]}(${params})${tail}`
+}
+
+/**
+ * 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('*/'))
+}
+
+/**
+ * Add indents to a string
+ * @param indents The number of indents
+ * @param spaceForIndent The number of spaces for each indent
+ * @returns The indented string
+ */
+export const generateIndent = (indents = 1, spaceForIndent = 4): string => {
+    return ' '.repeat(indents * spaceForIndent)
+}
+
+// Get __filename on ESM
+export const __filename = fileURLToPath(import.meta.url)
+// Get __dirname on ESM
+export const __dirname = Path.dirname(__filename)
+
+/**
+ * Get the output or input directory of the environment
+ * @param environment The environment to get the directory for
+ * @param baseDir The base directory
+ * @returns The path to the directory
+ */
+export const getEnvironmentDir = (environment: Environment, baseDir: string): string => {
+    if (!baseDir.endsWith(environment))
+        if (environment === 'gjs' && !baseDir.endsWith('/Gjs')) {
+            return Path.join(baseDir, 'Gjs')
+        }
+    if (environment === 'node' && !baseDir.endsWith('/node-gtk')) {
+        return Path.join(baseDir, 'node-gtk')
+    }
+    return baseDir
+}
+
+/**
+ * Get the destination path for the environment
+ * @param environment The environment to get the destination path for
+ * @param outputDir The output directory
+ * @param parts The path parts
+ * @returns The destination path
+ */
+export const getDestPath = (environment: Environment, outputDir: string, ...parts: string[]) => {
+    const outputEnvDir = getEnvironmentDir(environment, outputDir)
+    const destPath = Path.join(outputEnvDir, ...parts)
+    return destPath
+}
+
+/**
+ * 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) === 0) return false
+        return true
+    }
+    return defaultVal
+}
+
+/**
+ * Returns `true` if the definitions in `d1` and `d2` have equivalent signatures
+ * @param d1
+ * @param d2
+ */
+export const signaturesMatch = (d1: string, d2: string) => {
+    if (isCommentLine(d1) || isCommentLine(d2)) return false
+    return stripParamNames(d1) == stripParamNames(d2)
+}
+
+/**
+ * GirElements contains an attribute `introspectable`, which is a GirBoolean.
+ * If this is attribute is falsy the element is not introspectable,
+ * this means doesn't exist in the bindings, due in general to missing information in the annotations in the original C code
+ */
+export const girElementIsIntrospectable = (girElement?: { $: GirInfoAttrs & { name: string } }, name?: string) => {
+    if (!girElement) {
+        return false
+    }
+    name = name || girElement?.$?.name
+    if (!name) {
+        return false
+    }
+    // Handle introspectable only if the attribute is also present...
+    if (girElement.$.hasOwnProperty('introspectable') && girElement.$.introspectable !== undefined) {
+        return girBool(girElement.$.introspectable, true)
+    }
+    // ...otherwise we assume that it is introspectable
+    return true
+}
+
+/**
+ * Check if a type is optional
+ * @param types The types to check
+ * @returns Whether the type is optional or not
+ */
+export const typeIsOptional = (types: TsType[]) => {
+    for (const type of types) {
+        if (type.optional) return true
+    }
+    return false
+}
+
+/**
+ * Get a typescript or javascript config by path
+ * @param path The path to search for a tsconfig.json or jsconfig.json file
+ * @returns The config or null if not found
+ */
+export const getTsJsConfigByPath = (path: string) => {
+    try {
+        const config = getTsconfig(path)?.config
+        if (config) return config
+    } catch {
+        // ignored
+    }
+    return null
+}
+
+/**
+ * Given an directory path search for a tsconfig.json or jsconfig.json file in it or any of its parent directories, then read the file and parse it as json.
+ *
+ * @param path - The directory path to search for a tsconfig.json or jsconfig.json file
+ */
+export function readTsJsConfig(path: string) {
+    let config: null | false | TsConfigJsonResolved = null
+    let lastPath = ''
+    let currentPath = Path.resolve(path)
+    while (!config && currentPath !== lastPath) {
+        const tsConfigPath = Path.join(currentPath, 'tsconfig.json')
+        const jsConfigPath = Path.join(currentPath, 'jsconfig.json')
+        config =
+            (fs.existsSync(tsConfigPath) && getTsJsConfigByPath(tsConfigPath)) ||
+            (fs.existsSync(jsConfigPath) && getTsJsConfigByPath(jsConfigPath))
+        lastPath = currentPath
+        currentPath = Path.dirname(currentPath)
+    }
+
+    return config || null
+}

package/templates/Gjs/GObject-2.0.d.ts

@@ -0,0 +1,238 @@
+// A few things here are inspired by gi.ts 
+// See https://gitlab.gnome.org/ewlsh/gi.ts/-/blob/master/packages/lib/src/generators/dts/gobject.ts
+// Copyright Evan Welsh
+
+export type GType<T = unknown> = {
+    __type__(arg: never): T
+    name: string
+};
+
+// Extra interfaces used to help define GObject classes in js; these
+// aren't part of gi.
+export interface SignalDefinition {
+    flags?: SignalFlags
+    accumulator: number
+    return_type?: GType
+    param_types?: GType[]
+}
+
+export interface MetaInfo<Props, Interfaces, Sigs> {
+    GTypeName?: string
+    GTypeFlags?: TypeFlags
+    Properties?: Props
+    Signals?: Sigs
+    Implements?: Interfaces
+    CssName?: string
+    Template?: Uint8Array | GLib.Bytes
+    Children?: string[]
+    InternalChildren?: string[]
+}
+
+/** Interface of GObject Interface should be implemented by all GObject interfaces */
+export class Interface<T = unknown> {
+    static _classInit: (cls: any) => any;
+    __name__: string;
+    _construct: (params: any, ...otherArgs: any[]) => any;
+    _init: (params: any) => void;
+    $gtype?: GType<T>;
+}
+
+/**
+ * Use this to signify a function that must be overridden in an
+ * implementation of the interface.
+ */
+export class NotImplementedError extends Error {
+    get name(): 'NotImplementedError'
+}
+
+// Expose GObject static properties for ES6 classes
+
+export const GTypeName: unique symbol;
+export const requires: unique symbol;
+export const interfaces: unique symbol;
+export const properties: unique symbol;
+export const signals: unique symbol;
+
+export let gtypeNameBasedOnJSPath: boolean;
+
+export let TYPE_BOOLEAN: GType<boolean>;
+export let Boolean: BooleanConstructor;
+
+export let TYPE_ENUM: GType<number>;
+export let TYPE_FLAGS: GType<number>;
+
+export let TYPE_DOUBLE: GType<number>;
+export let Double: NumberConstructor;
+
+export let TYPE_STRING: GType<string>;
+export let String: StringConstructor;
+
+export let TYPE_NONE: GType<undefined>;
+export let TYPE_POINTER: GType<undefined>;
+export let TYPE_BOXED: GType<unknown>;
+export let TYPE_PARAM: GType<unknown>;
+export let TYPE_INTERFACE: GType<unknown>;
+export let TYPE_OBJECT: GType<object>;
+export let TYPE_VARIANT: GType<GLib.Variant>;
+export let TYPE_INT: GType<number>;
+export let TYPE_UINT: GType<number>;
+export let TYPE_INT64: GType<number>;
+export let TYPE_UINT64: GType<number>;
+
+// fake enum for signal accumulators, keep in sync with gi/object.c
+export enum AccumulatorType {
+    NONE=0,
+    FIRST_WINS=1,
+    TRUE_HANDLED=2,
+}
+
+// A simple workaround if you have a class with .connect, .disconnect or .emit
+// methods (such as Gio.Socket.connect or NMClient.Device.disconnect)
+// The original g_signal_* functions are not introspectable anyway, because
+// we need our own handling of signal argument marshalling
+export function signal_connect(object: Object, name: string, handler: (...args: any[]) => any): number
+export function signal_connect_after(object: Object, name: string, handler: (...args: any[]) => any): number
+export function signal_emit_by_name(object: Object, ...nameAndArgs: any[]): void
+
+/**
+ * Finds the first signal handler that matches certain selection criteria.
+ * The criteria are passed as properties of a match object.
+ * The match object has to be non-empty for successful matches.
+ * If no handler was found, a falsy value is returned.
+ *
+ * @param instance the instance owning the signal handler to be found.
+ * @param match a properties object indicating whether to match by signal ID, detail, or callback function.
+ * @param match.signalId signal the handler has to be connected to.
+ * @param match.detail signal detail the handler has to be connected to.
+ * @param match.func the callback function the handler will invoke.
+ * @returns A valid non-0 signal handler ID for a successful match.
+ */
+export function signal_handler_find(instance: Object, match: {signalId: string, detail: string, func: (...args: any[]) => any}): number | bigint | object | null
+
+/**
+ * Blocks all handlers on an instance that match certain selection criteria.
+ * The criteria are passed as properties of a match object.
+ * The match object has to have at least `func` for successful matches.
+ * If no handlers were found, 0 is returned, the number of blocked handlers
+ * otherwise.
+ *
+ * @param instance the instance owning the signal handler to be found.
+ * @param match a properties object indicating whether to match by signal ID, detail, or callback function.
+ * @param match.signalId signal the handler has to be connected to.
+ * @param match.detail signal detail the handler has to be connected to.
+ * @param match.func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_block_matched(instance: Object, match: {signalId: string, detail: string, func: (...args: any[]) => any}): number
+
+/**
+ * Disconnects all handlers on an instance that match certain selection
+ * criteria.
+ * The criteria are passed as properties of a match object.
+ * The match object has to have at least `func` for successful matches.
+ * If no handlers were found, 0 is returned, the number of disconnected
+ * handlers otherwise.
+ *
+ * @param instance the instance owning the signal handler
+ *   to be found.
+ * @param match a properties object indicating whether to match by signal ID, detail, or callback function.
+ * @param match.signalId signal the handler has to be connected to.
+ * @param match.detail signal detail the handler has to be connected to.
+ * @param match.func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_unblock_matched(instance: Object, match: {signalId: string, detail: string, func: (...args: any[]) => any}): number
+
+/**
+ * Disconnects all handlers on an instance that match certain selection
+ * criteria.
+ * The criteria are passed as properties of a match object.
+ * The match object has to have at least `func` for successful matches.
+ * If no handlers were found, 0 is returned, the number of disconnected
+ * handlers otherwise.
+ *
+ * @param instance the instance owning the signal handler
+ *   to be found.
+ * @param match a properties object indicating whether to match by signal ID, detail, or callback function.
+ * @param match.signalId signal the handler has to be connected to.
+ * @param match.detail signal detail the handler has to be connected to.
+ * @param match.func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_disconnect_matched(instance: Object, match: {signalId: string, detail: string, func: (...args: any[]) => any}): number
+
+// Also match the macros used in C APIs, even though they're not introspected
+
+/**
+ * Blocks all handlers on an instance that match `func`.
+ *
+ * @param instance the instance to block handlers from.
+ * @param func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_block_by_func(instance: Object, func: (...args: any[]) => any): number;
+
+/**
+ * Unblocks all handlers on an instance that match `func`.
+ *
+ * @function
+ * @param instance the instance to unblock handlers from.
+ * @param func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_unblock_by_func(instance: Object, func: (...args: any[]) => any): number;
+
+/**
+ * Disconnects all handlers on an instance that match `func`.
+ *
+ * @param instance the instance to remove handlers from.
+ * @param func the callback function the handler will invoke.
+ * @returns The number of handlers that matched.
+ */
+export function signal_handlers_disconnect_by_func(instance: Object, func: (...args: any[]) => any): number;
+export function signal_handlers_disconnect_by_data(): void;
+
+export type Property<K extends ParamSpec> = K extends ParamSpecBoolean
+    ? boolean
+    : K extends ParamSpecDouble | ParamSpecInt | ParamSpecUInt | ParamSpecFloat | ParamSpecLong
+    ? number
+    : K extends ParamSpecInt64 | ParamSpecUInt64 | ParamSpecULong
+    ? number
+    : K extends ParamSpecFlags
+    ? number
+    : K extends ParamSpecString | ParamSpecUnichar
+    ? string
+    : K extends ParamSpecValueArray
+    ? any[]
+    : K extends ParamSpecObject // TODO?: <infer T>
+    ? ParamSpecObject // T
+    : K extends ParamSpecEnum // TODO?: <infer T><infer E>
+    ? ParamSpecEnum // E
+    : K extends ParamSpecBoxed // TODO?: <infer T><infer B>
+    ? ParamSpecBoxed //B
+    : K extends ParamSpecVariant
+    ? GLib.Variant
+    : any;
+
+// TODO: What about the generated class Closure 
+export type TClosure<R = any, P = any> = (...args: P[]) => R;
+
+// This should be replaces by a class of GObject.Object as soon as once we have implemented inheritance
+export class AnyClass {}
+
+export function registerClass<
+    T extends AnyClass,
+    Props extends { [key: string]: ParamSpec },
+    Interfaces extends { $gtype: GType }[],
+    Sigs extends {
+        [key: string]: {
+            param_types?: readonly GType[];
+            [key: string]: any;
+        };
+    }
+>(
+    options: MetaInfo<Props, Interfaces, Sigs>,
+    cls: T
+): T;
+
+export function registerClass<T extends AnyClass>(cls: T): T