@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/file-attribute-info-list.d.ts

@@ -1,14 +1,44 @@
 import { FileAttributeInfoFlags, FileAttributeType } from "./enums.js";
+/**
+ * Acts as a lightweight registry for possible valid file attributes.
+ * The registry stores Key-Value pair formats as #GFileAttributeInfos.
+ */
 export declare class FileAttributeInfoList {
     ptr: unknown;
+    /**
+     * Creates a new file attribute info list.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Adds a new attribute with `name` to the @list, setting
+     * its `type` and @flags.
+     * @param name - the name of the attribute to add.
+     * @param type - the #GFileAttributeType for the attribute.
+     * @param flags - #GFileAttributeInfoFlags for the attribute.
+     */
     add(name: string, type: FileAttributeType, flags: FileAttributeInfoFlags): void;
+    /**
+     * Makes a duplicate of a file attribute info list.
+     */
     dup(): FileAttributeInfoList;
+    /**
+     * Gets the file attribute with the name `name` from @list.
+     * @param name - the name of the attribute to look up.
+     */
     lookup(name: string): number;
+    /**
+     * References a file attribute info list.
+     */
     ref(): FileAttributeInfoList;
+    /**
+     * Removes a reference from the given @list. If the reference count
+     * falls to zero, the `list` is deleted.
+     */
     unref(): void;
+    /** an array of #GFileAttributeInfos. */
     get infos(): number;
+    /** the number of values in the array. */
     get nInfos(): number;
     set nInfos(value: number);
 }

package/dist/generated/gio/file-attribute-info-list.js

@@ -1,7 +1,14 @@
 import { call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * Acts as a lightweight registry for possible valid file attributes.
+ * The registry stores Key-Value pair formats as #GFileAttributeInfos.
+ */
 export class FileAttributeInfoList {
     ptr;
+    /**
+     * Creates a new file attribute info list.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
@@ -12,6 +19,13 @@ export class FileAttributeInfoList {
             innerType: "GFileAttributeInfoList",
         });
     }
+    /**
+     * Adds a new attribute with `name` to the @list, setting
+     * its `type` and @flags.
+     * @param name - the name of the attribute to add.
+     * @param type - the #GFileAttributeType for the attribute.
+     * @param flags - #GFileAttributeInfoFlags for the attribute.
+     */
     add(name, type, flags) {
         call("libgio-2.0.so.0", "g_file_attribute_info_list_add", [
             {
@@ -32,6 +46,9 @@ export class FileAttributeInfoList {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Makes a duplicate of a file attribute info list.
+     */
     dup() {
         const ptr = call("libgio-2.0.so.0", "g_file_attribute_info_list_dup", [
             {
@@ -46,6 +63,10 @@ export class FileAttributeInfoList {
         });
         return getObject(ptr, FileAttributeInfoList);
     }
+    /**
+     * Gets the file attribute with the name `name` from @list.
+     * @param name - the name of the attribute to look up.
+     */
     lookup(name) {
         return call("libgio-2.0.so.0", "g_file_attribute_info_list_lookup", [
             {
@@ -58,6 +79,9 @@ export class FileAttributeInfoList {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * References a file attribute info list.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_file_attribute_info_list_ref", [
             {
@@ -72,6 +96,10 @@ export class FileAttributeInfoList {
         });
         return getObject(ptr, FileAttributeInfoList);
     }
+    /**
+     * Removes a reference from the given @list. If the reference count
+     * falls to zero, the `list` is deleted.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_file_attribute_info_list_unref", [
             {
@@ -80,9 +108,11 @@ export class FileAttributeInfoList {
             },
         ], { type: "undefined" });
     }
+    /** an array of #GFileAttributeInfos. */
     get infos() {
         return read(this.ptr, { type: "int", size: 64, unsigned: true }, 0);
     }
+    /** the number of values in the array. */
     get nInfos() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 8);
     }

package/dist/generated/gio/file-attribute-matcher.d.ts

@@ -1,14 +1,84 @@
+/** Determines if a string matches a file attribute. */
 export declare class FileAttributeMatcher {
     ptr: unknown;
+    /**
+     * Creates a new file attribute matcher, which matches attributes
+     * against a given string. #GFileAttributeMatchers are reference
+     * counted structures, and are created with a reference count of 1. If
+     * the number of references falls to 0, the #GFileAttributeMatcher is
+     * automatically destroyed.
+     *
+     * The `attributes` string should be formatted with specific keys separated
+     * from namespaces with a double colon. Several "namespace::key" strings may be
+     * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
+     * The wildcard "*" may be used to match all keys and namespaces, or
+     * "namespace::*" will match all keys in a given namespace.
+     *
+     * ## Examples of file attribute matcher strings and results
+     *
+     * - `"*"`: matches all attributes.
+     * - `"standard::is-hidden"`: matches only the key is-hidden in the
+     * standard namespace.
+     * - `"standard::type,unix::*"`: matches the type key in the standard
+     * namespace and all keys in the unix namespace.
+     * @param attributes - an attribute string to match.
+     */
     constructor(attributes: string);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Checks if the matcher will match all of the keys in a given namespace.
+     * This will always return %TRUE if a wildcard character is in use (e.g. if
+     * matcher was created with "standard::*" and `ns` is "standard", or if matcher was created
+     * using "*" and namespace is anything.)
+     *
+     * TODO: this is awkwardly worded.
+     * @param ns - a string containing a file attribute namespace.
+     */
     enumerateNamespace(ns: string): boolean;
+    /**
+     * Gets the next matched attribute from a #GFileAttributeMatcher.
+     */
     enumerateNext(): string | null;
+    /**
+     * Checks if an attribute will be matched by an attribute matcher. If
+     * the matcher was created with the "*" matching string, this function
+     * will always return %TRUE.
+     * @param attribute - a file attribute key.
+     */
     matches(attribute: string): boolean;
+    /**
+     * Checks if an attribute matcher only matches a given attribute. Always
+     * returns %FALSE if "*" was used when creating the matcher.
+     * @param attribute - a file attribute key.
+     */
     matchesOnly(attribute: string): boolean;
+    /**
+     * References a file attribute matcher.
+     */
     ref(): FileAttributeMatcher;
+    /**
+     * Subtracts all attributes of `subtract` from `matcher` and returns
+     * a matcher that supports those attributes.
+     *
+     * Note that currently it is not possible to remove a single
+     * attribute when the `matcher` matches the whole namespace - or remove
+     * a namespace or attribute when the matcher matches everything. This
+     * is a limitation of the current implementation, but may be fixed
+     * in the future.
+     * @param subtract - The matcher to subtract
+     */
     subtract(subtract?: FileAttributeMatcher | null): FileAttributeMatcher | null;
+    /**
+     * Prints what the matcher is matching against. The format will be
+     * equal to the format passed to g_file_attribute_matcher_new().
+     * The output however, might not be identical, as the matcher may
+     * decide to use a different order or omit needless parts.
+     */
     toString(): string;
+    /**
+     * Unreferences @matcher. If the reference count falls below 1,
+     * the `matcher` is automatically freed.
+     */
     unref(): void;
 }

package/dist/generated/gio/file-attribute-matcher.js

@@ -1,5 +1,6 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/** Determines if a string matches a file attribute. */
 export class FileAttributeMatcher {
     ptr;
     constructor(...args) {
@@ -15,6 +16,15 @@ export class FileAttributeMatcher {
             },
         ], { type: "boxed", borrowed: true, innerType: "GFileAttributeMatcher" });
     }
+    /**
+     * Checks if the matcher will match all of the keys in a given namespace.
+     * This will always return %TRUE if a wildcard character is in use (e.g. if
+     * matcher was created with "standard::*" and `ns` is "standard", or if matcher was created
+     * using "*" and namespace is anything.)
+     *
+     * TODO: this is awkwardly worded.
+     * @param ns - a string containing a file attribute namespace.
+     */
     enumerateNamespace(ns) {
         return call("libgio-2.0.so.0", "g_file_attribute_matcher_enumerate_namespace", [
             {
@@ -27,6 +37,9 @@ export class FileAttributeMatcher {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the next matched attribute from a #GFileAttributeMatcher.
+     */
     enumerateNext() {
         return call("libgio-2.0.so.0", "g_file_attribute_matcher_enumerate_next", [
             {
@@ -35,6 +48,12 @@ export class FileAttributeMatcher {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Checks if an attribute will be matched by an attribute matcher. If
+     * the matcher was created with the "*" matching string, this function
+     * will always return %TRUE.
+     * @param attribute - a file attribute key.
+     */
     matches(attribute) {
         return call("libgio-2.0.so.0", "g_file_attribute_matcher_matches", [
             {
@@ -47,6 +66,11 @@ export class FileAttributeMatcher {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if an attribute matcher only matches a given attribute. Always
+     * returns %FALSE if "*" was used when creating the matcher.
+     * @param attribute - a file attribute key.
+     */
     matchesOnly(attribute) {
         return call("libgio-2.0.so.0", "g_file_attribute_matcher_matches_only", [
             {
@@ -59,6 +83,9 @@ export class FileAttributeMatcher {
             },
         ], { type: "boolean" });
     }
+    /**
+     * References a file attribute matcher.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_file_attribute_matcher_ref", [
             {
@@ -73,6 +100,17 @@ export class FileAttributeMatcher {
         });
         return getObject(ptr, FileAttributeMatcher);
     }
+    /**
+     * Subtracts all attributes of `subtract` from `matcher` and returns
+     * a matcher that supports those attributes.
+     *
+     * Note that currently it is not possible to remove a single
+     * attribute when the `matcher` matches the whole namespace - or remove
+     * a namespace or attribute when the matcher matches everything. This
+     * is a limitation of the current implementation, but may be fixed
+     * in the future.
+     * @param subtract - The matcher to subtract
+     */
     subtract(subtract) {
         const ptr = call("libgio-2.0.so.0", "g_file_attribute_matcher_subtract", [
             {
@@ -99,6 +137,12 @@ export class FileAttributeMatcher {
             return null;
         return getObject(ptr, FileAttributeMatcher);
     }
+    /**
+     * Prints what the matcher is matching against. The format will be
+     * equal to the format passed to g_file_attribute_matcher_new().
+     * The output however, might not be identical, as the matcher may
+     * decide to use a different order or omit needless parts.
+     */
     toString() {
         return call("libgio-2.0.so.0", "g_file_attribute_matcher_to_string", [
             {
@@ -107,6 +151,10 @@ export class FileAttributeMatcher {
             },
         ], { type: "string" });
     }
+    /**
+     * Unreferences @matcher. If the reference count falls below 1,
+     * the `matcher` is automatically freed.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_file_attribute_matcher_unref", [
             {

package/dist/generated/gio/file-enumerator.d.ts

@@ -4,20 +4,242 @@ import { Cancellable } from "./cancellable.js";
 import { File } from "./file.js";
 import { FileInfo } from "./file-info.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects,
+ * returning a [class@Gio.FileInfo] structure for each file enumerated (e.g.
+ * [method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each
+ * of the children within a directory).
+ *
+ * To get the next file's information from a `GFileEnumerator`, use
+ * [method@Gio.FileEnumerator.next_file] or its asynchronous version,
+ * [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous
+ * version will return a list of [class@Gio.FileInfo] objects, whereas the
+ * synchronous will only return the next file in the enumerator.
+ *
+ * The ordering of returned files is unspecified for non-Unix
+ * platforms; for more information, see [method@GLib.Dir.read_name].  On Unix,
+ * when operating on local files, returned files will be sorted by
+ * inode number.  Effectively you can assume that the ordering of
+ * returned files will be stable between successive calls (and
+ * applications) assuming the directory is unchanged.
+ *
+ * If your application needs a specific ordering, such as by name or
+ * modification time, you will have to implement that in your
+ * application code.
+ *
+ * To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or
+ * its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once
+ * a `GFileEnumerator` is closed, no further actions may be performed
+ * on it, and it should be freed with [method@GObject.Object.unref].
+ */
 export declare class FileEnumerator extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Releases all resources used by this enumerator, making the
+     * enumerator return %G_IO_ERROR_CLOSED on all calls.
+     *
+     * This will be automatically called when the last reference
+     * is dropped, but you might want to call this function to make
+     * sure resources are released as early as possible.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     close(cancellable?: Cancellable | null): boolean;
+    /**
+     * Asynchronously closes the file enumerator.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
+     * g_file_enumerator_close_finish().
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     closeAsync(ioPriority: number, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+     *
+     * If the file enumerator was already closed when g_file_enumerator_close_async()
+     * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
+     * return %FALSE. If the file enumerator had pending operation when the close
+     * operation was started, then this function will report %G_IO_ERROR_PENDING, and
+     * return %FALSE.  If `cancellable` was not %NULL, then the operation may have been
+     * cancelled by triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
+     * returned.
+     * @param result - a #GAsyncResult.
+     */
     closeFinish(result: AsyncResult): boolean;
+    /**
+     * Return a new #GFile which refers to the file named by `info` in the source
+     * directory of @enumerator.  This function is primarily intended to be used
+     * inside loops with g_file_enumerator_next_file().
+     *
+     * To use this, %G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the
+     * attributes list used when creating the #GFileEnumerator.
+     *
+     * This is a convenience method that's equivalent to:
+     * |[<!-- language="C" -->
+     * gchar *name = g_file_info_get_name (info);
+     * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
+     * name);
+     * ]|
+     * @param info - a #GFileInfo gotten from g_file_enumerator_next_file()
+     */
     getChild(info: FileInfo): File;
+    /**
+     * Get the #GFile container which is being enumerated.
+     */
     getContainer(): File;
+    /**
+     * Checks if the file enumerator has pending operations.
+     */
     hasPending(): boolean;
+    /**
+     * Checks if the file enumerator has been closed.
+     */
     isClosed(): boolean;
+    /**
+     * This is a version of g_file_enumerator_next_file() that's easier to
+     * use correctly from C programs.  With g_file_enumerator_next_file(),
+     * the gboolean return value signifies "end of iteration or error", which
+     * requires allocation of a temporary #GError.
+     *
+     * In contrast, with this function, a %FALSE return from
+     * g_file_enumerator_iterate() *always* means
+     * "error".  End of iteration is signaled by `out_info` or `out_child` being %NULL.
+     *
+     * Another crucial difference is that the references for `out_info` and
+     * `out_child` are owned by `direnum` (they are cached as hidden
+     * properties).  You must not unref them in your own code.  This makes
+     * memory management significantly easier for C code in combination
+     * with loops.
+     *
+     * Finally, this function optionally allows retrieving a #GFile as
+     * well.
+     *
+     * You must specify at least one of `out_info` or @out_child.
+     *
+     * The code pattern for correctly using g_file_enumerator_iterate() from C
+     * is:
+     *
+     * |[
+     * direnum = g_file_enumerate_children (file, ...);
+     * while (TRUE)
+     * {
+     * GFileInfo *info;
+     * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
+     * goto out;
+     * if (!info)
+     * break;
+     * ... do stuff with "info"; do not unref it! ...
+     * }
+     *
+     * out:
+     * g_object_unref (direnum); // Note: frees the last `info` ]|
+     * @param outInfo - Output location for the next #GFileInfo, or %NULL
+     * @param outChild - Output location for the next #GFile, or %NULL
+     * @param cancellable - a #GCancellable
+     */
     iterate(outInfo?: Ref<FileInfo> | null, outChild?: Ref<File> | null, cancellable?: Cancellable | null): boolean;
+    /**
+     * Returns information for the next file in the enumerated object.
+     * Will block until the information is available. The #GFileInfo
+     * returned from this function will contain attributes that match the
+     * attribute string that was passed when the #GFileEnumerator was created.
+     *
+     * See the documentation of #GFileEnumerator for information about the
+     * order of returned files.
+     *
+     * On error, returns %NULL and sets `error` to the error. If the
+     * enumerator is at the end, %NULL will be returned and `error` will
+     * be unset.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     nextFile(cancellable?: Cancellable | null): FileInfo | null;
+    /**
+     * Request information for a number of files from the enumerator asynchronously.
+     * When all I/O for the operation is finished the `callback` will be called with
+     * the requested information.
+     *
+     * See the documentation of #GFileEnumerator for information about the
+     * order of returned files.
+     *
+     * Once the end of the enumerator is reached, or if an error occurs, the
+     * `callback` will be called with an empty list. In this case, the previous call
+     * to g_file_enumerator_next_files_async() will typically have returned fewer
+     * than `num_files` items.
+     *
+     * If a request is cancelled the callback will be called with
+     * %G_IO_ERROR_CANCELLED.
+     *
+     * This leads to the following pseudo-code usage:
+     * |[
+     * g_autoptr(GFile) dir = get_directory ();
+     * g_autoptr(GFileEnumerator) enumerator = NULL;
+     * g_autolist(GFileInfo) files = NULL;
+     * g_autoptr(GError) local_error = NULL;
+     *
+     * enumerator = yield g_file_enumerate_children_async (dir,
+     * G_FILE_ATTRIBUTE_STANDARD_NAME ","
+     * G_FILE_ATTRIBUTE_STANDARD_TYPE,
+     * G_FILE_QUERY_INFO_NONE,
+     * G_PRIORITY_DEFAULT,
+     * cancellable,
+     * …,
+     * &local_error);
+     * if (enumerator == NULL)
+     * g_error ("Error enumerating: %s", local_error->message);
+     *
+     * // Loop until no files are returned, either because the end of the enumerator
+     * // has been reached, or an error was returned.
+     * do
+     * {
+     * files = yield g_file_enumerator_next_files_async (enumerator,
+     * 5,  // number of files to request
+     * G_PRIORITY_DEFAULT,
+     * cancellable,
+     * …,
+     * &local_error);
+     *
+     * // Process the returned files, but don’t assume that exactly 5 were returned.
+     * for (GList *l = files; l != NULL; l = l->next)
+     * {
+     * GFileInfo *info = l->data;
+     * handle_file_info (info);
+     * }
+     * }
+     * while (files != NULL);
+     *
+     * if (local_error != NULL &&
+     * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
+     * g_error ("Error while enumerating: %s", local_error->message);
+     * ]|
+     *
+     * During an async request no other sync and async calls are allowed, and will
+     * result in %G_IO_ERROR_PENDING errors.
+     *
+     * Any outstanding I/O request with higher priority (lower numerical value) will
+     * be executed before an outstanding request with lower priority. Default
+     * priority is %G_PRIORITY_DEFAULT.
+     * @param numFiles - the number of file info objects to request
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     nextFilesAsync(numFiles: number, ioPriority: number, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
+     * @param result - a #GAsyncResult.
+     */
     nextFilesFinish(result: AsyncResult): FileInfo[];
+    /**
+     * Sets the file enumerator as having pending operations.
+     * @param pending - a boolean value.
+     */
     setPending(pending: boolean): void;
     connect(signal: "notify", handler: (self: FileEnumerator, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;