@girs/gfls-1 4.2.0 → 4.3.0

package/README.md

@@ -5,25 +5,25 @@
 ![downloads/week](https://img.shields.io/npm/dw/@girs/gfls-1)
 
 
-GJS TypeScript type definitions for Gfls-1 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.2.0.
+GJS TypeScript type definitions for Gfls-1 using [ts-for-gir](https://github.com/gjsify/ts-for-gir) v4.3.0.
 
 ## Install
 
-To use this type definitions, install them with NPM:
+Install the type definitions with npm:
 ```bash
 npm install @girs/gfls-1
 ```
 
 ## Usage
 
-You can import this package into your project like this:
+Import it like any other module:
 ```ts
 import Gfls from '@girs/gfls-1';
 ```
 
 ### Ambient Modules
 
-You can also use [ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules) to import this module like you would do this in JavaScript.
+[Ambient modules](https://github.com/gjsify/ts-for-gir/tree/main/packages/cli#ambient-modules) let you write the same import you would in plain JavaScript.
 For this you need to include `@girs/gfls-1` or `@girs/gfls-1/ambient` in your `tsconfig` or entry point Typescript file:
 
 `index.ts`:
@@ -42,7 +42,7 @@ import '@girs/gfls-1'
 }
 ```
 
-Now you can import the ambient module with TypeScript support: 
+The ambient module now resolves with types:
 
 ```ts
 import Gfls from 'gi://Gfls?version=1';
@@ -50,7 +50,7 @@ import Gfls from 'gi://Gfls?version=1';
 
 ### Global import
 
-You can also import the module with Typescript support using the global `imports.gi` object of GJS.
+GJS's global `imports.gi` works too, with types.
 For this you need to include `@girs/gfls-1` or `@girs/gfls-1/import` in your `tsconfig` or entry point Typescript file:
 
 `index.ts`:
@@ -69,7 +69,7 @@ import '@girs/gfls-1'
 }
 ```
 
-Now you have also type support for this, too:
+That form carries types as well:
 
 ```ts
 const Gfls = imports.gi.Gfls;
@@ -77,7 +77,7 @@ const Gfls = imports.gi.Gfls;
 
 ### Bundle
 
-Depending on your project configuration, it is recommended to use a bundler like [esbuild](https://esbuild.github.io/). You can find examples using different bundlers [here](https://github.com/gjsify/ts-for-gir/tree/main/examples).
+Most projects want a bundler. [esbuild](https://esbuild.github.io/) is the smallest thing that works; the [examples directory](https://github.com/gjsify/ts-for-gir/tree/main/examples) has setups for several others.
 
 ## Other packages
 

package/gfls-1.d.ts

@@ -32,6 +32,53 @@ export namespace Gfls {
      */
 
 
+    /**
+     * @gir-type Enum
+     */
+    export namespace IconvResult {
+        export const $gtype: GObject.GType<IconvResult>;
+    }
+
+    /**
+     * Used as the result value of `gfls_iconv_feed()`.
+     * @gir-type Enum
+     * @since 0.4
+     */
+    enum IconvResult {
+        /**
+         * Everything OK.
+         */
+        OK,
+        /**
+         * An error occurred.
+         */
+        ERROR,
+        /**
+         * Stopped at an invalid character in
+         *   the `inbuf`; or the character could not be represented in the target
+         *   character set. `*inbuf` is left pointing to the beginning of the invalid or
+         *   unconvertible sequence.
+         */
+        ILLEGAL_SEQUENCE,
+        /**
+         * The input byte sequence ends with
+         *   an incomplete multi-byte character. `*inbuf` is left pointing to the
+         *   beginning of the incomplete multi-byte character.
+         */
+        INCOMPLETE_INPUT,
+        /**
+         * The output buffer has no more
+         *   room for the next converted character.
+         */
+        OUTPUT_BUFFER_FULL,
+        /**
+         * A number of nonreversible
+         *   conversions have been performed.
+         */
+        LOSSY_CONVERSION,
+    }
+
+
     /**
      * An error code used with the `GFLS_LOADER_ERROR` domain.
      * @gir-type Struct
@@ -65,106 +112,72 @@ export namespace Gfls {
 
 
     /**
-     * Free the resources allocated by Gfls. For example it unrefs the singleton
-     * objects.
+     * This function converts `input_bytes` from a codeset to another.
      * 
-     * It is not mandatory to call this function, it's just to be friendlier to
-     * memory debugging tools. This function is meant to be called at the end of
-     * `main()`. It can be called several times.
-     * @since 0.1
-     */
-    function finalize(): void;
-
-    /**
-     * Initializes the Gfls library (e.g. for the internationalization).
+     * `from_codeset` and `to_codeset` must be compatible with iconv, see
+     * `gfls_iconv_open()`.
      * 
-     * This function can be called several times, but is meant to be called at the
-     * beginning of `main()`, before any other Gfls function call.
-     * @since 0.1
-     */
-    function init(): void;
-
-    /**
-     * This function starts a read operation on `input_stream`. It is meant to be
-     * used as the only read operation on `input_stream`, to get a {@link GLib.Bytes} as a
-     * result, with `max_size` as the provided maximum number of bytes to read.
+     * Note that `from_codeset` and `to_codeset` can be equal. It is useful to
+     * identify the valid characters from the invalid ones.
      * 
-     * `expected_size` is typically a {@link Gio.File} size as returned by
-     * `g_file_info_get_size()`. But note that in that case, the returned {@link GLib.Bytes} may
-     * contain a different number of bytes than what was expected (the
-     * TOC/TOU problem: time of check to time of use). `expected_size` is used as an
-     * indication to how much memory to allocate initially.
+     * The output is the combination of `output_bytes` and
+     * `output_bytes_valid_region`. Output bytes that are part of
+     * `output_bytes_valid_region` are the valid characters (successfully converted).
+     * The other output bytes are invalid characters (copied as is from
+     * `input_bytes`).
      * 
-     * See the {@link Gio.AsyncResult} documentation to know how to use this function.
-     * @param input_stream a {@link Gio.InputStream}.
-     * @param expected_size the expected number of bytes contained in `input_stream`.
-     * @param max_size the maximum number of bytes to read.
-     * @param io_priority the I/O priority of the request. E.g. `G_PRIORITY_LOW`,   `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`.
-     * @param cancellable optional {@link Gio.Cancellable} object, `null` to ignore.
-     * @since 0.1
+     * If `allow_invalid_characters` is `false`:
+     * - As soon as an invalid character is encountered, `false` is returned by this
+     *   function and `output_bytes` and `output_bytes_valid_region` will return
+     *   `null`.
+     * - Otherwise, if everything goes well, `true` is returned alongside the
+     *   `output_bytes` and `output_bytes_valid_region` (the latter contains in this
+     *   case only one, valid sub-region).
+     * @param input_bytes the input {@link GLib.Bytes} to convert.
+     * @param to_codeset destination codeset.
+     * @param from_codeset source codeset.
+     * @param allow_invalid_characters whether invalid characters are allowed.
+     * @returns `true` on success, `false` otherwise.
+     * @since 0.4
      */
-    function input_stream_read_async(input_stream: Gio.InputStream, expected_size: bigint | number, max_size: bigint | number, io_priority: number, cancellable: Gio.Cancellable | null): globalThis.Promise<GLib.Bytes>;
+    function encoding_convert(input_bytes: GLib.Bytes | Uint8Array, to_codeset: string, from_codeset: string, allow_invalid_characters: boolean): [boolean, GLib.Bytes, BytesRegion];
+
     /**
-     * This function starts a read operation on `input_stream`. It is meant to be
-     * used as the only read operation on `input_stream`, to get a {@link GLib.Bytes} as a
-     * result, with `max_size` as the provided maximum number of bytes to read.
+     * Tries a conversion on `input_bytes`, discarding the output.
      * 
-     * `expected_size` is typically a {@link Gio.File} size as returned by
-     * `g_file_info_get_size()`. But note that in that case, the returned {@link GLib.Bytes} may
-     * contain a different number of bytes than what was expected (the
-     * TOC/TOU problem: time of check to time of use). `expected_size` is used as an
-     * indication to how much memory to allocate initially.
+     * `from_codeset` and `to_codeset` must be compatible with iconv, see
+     * `gfls_iconv_open()`.
      * 
-     * See the {@link Gio.AsyncResult} documentation to know how to use this function.
-     * @param input_stream a {@link Gio.InputStream}.
-     * @param expected_size the expected number of bytes contained in `input_stream`.
-     * @param max_size the maximum number of bytes to read.
-     * @param io_priority the I/O priority of the request. E.g. `G_PRIORITY_LOW`,   `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`.
-     * @param cancellable optional {@link Gio.Cancellable} object, `null` to ignore.
-     * @param callback a {@link Gio.AsyncReadyCallback} to call when the operation   is finished.
-     * @since 0.1
+     * If `input_bytes` ends with an incomplete multi-byte character, that part is
+     * ignored. So `input_bytes` can be for example the first chunk of a file when
+     * loading it.
+     * @param input_bytes a {@link GLib.Bytes}.
+     * @param to_codeset destination codeset.
+     * @param from_codeset source codeset.
+     * @returns `true` if and only if `input_bytes` can be converted without errors,   without invalid characters and without fallback characters.
+     * @since 0.4
      */
-    function input_stream_read_async(input_stream: Gio.InputStream, expected_size: bigint | number, max_size: bigint | number, io_priority: number, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<Gio.InputStream> | null): void;
+    function encoding_try_convert(input_bytes: GLib.Bytes | Uint8Array, to_codeset: string, from_codeset: string): boolean;
+
     /**
-     * This function starts a read operation on `input_stream`. It is meant to be
-     * used as the only read operation on `input_stream`, to get a {@link GLib.Bytes} as a
-     * result, with `max_size` as the provided maximum number of bytes to read.
-     * 
-     * `expected_size` is typically a {@link Gio.File} size as returned by
-     * `g_file_info_get_size()`. But note that in that case, the returned {@link GLib.Bytes} may
-     * contain a different number of bytes than what was expected (the
-     * TOC/TOU problem: time of check to time of use). `expected_size` is used as an
-     * indication to how much memory to allocate initially.
+     * Free the resources allocated by Gfls. For example it unrefs the singleton
+     * objects.
      * 
-     * See the {@link Gio.AsyncResult} documentation to know how to use this function.
-     * @param input_stream a {@link Gio.InputStream}.
-     * @param expected_size the expected number of bytes contained in `input_stream`.
-     * @param max_size the maximum number of bytes to read.
-     * @param io_priority the I/O priority of the request. E.g. `G_PRIORITY_LOW`,   `G_PRIORITY_DEFAULT` or `G_PRIORITY_HIGH`.
-     * @param cancellable optional {@link Gio.Cancellable} object, `null` to ignore.
-     * @param callback a {@link Gio.AsyncReadyCallback} to call when the operation   is finished.
+     * It is not mandatory to call this function, it's just to be friendlier to
+     * memory debugging tools. This function is meant to be called at the end of
+     * `main()`. It can be called several times.
      * @since 0.1
      */
-    function input_stream_read_async(input_stream: Gio.InputStream, expected_size: bigint | number, max_size: bigint | number, io_priority: number, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<Gio.InputStream> | null): globalThis.Promise<GLib.Bytes> | void;
+    function finalize(): void;
 
     /**
-     * Finishes an operation started with `gfls_input_stream_read_async()`.
-     * 
-     * If `is_truncated` is set to `true`, it is not an error (`error` is not set), and
-     * a {@link GLib.Bytes} is returned. However, since `gfls_input_stream_read_async()` is meant
-     * to be used as the only read operation on `input_stream`, it is an undefined
-     * behavior if you try to read more content from `input_stream`.
+     * Initializes the Gfls library (e.g. for the internationalization).
      * 
-     * The data contained in the resulting {@link GLib.Bytes} is always zero-terminated, but
-     * this is not included in the {@link GLib.Bytes} length. The resulting {@link GLib.Bytes} should be
-     * freed with `g_bytes_unref()` when no longer in use.
-     * @param input_stream a {@link Gio.InputStream}.
-     * @param result a {@link Gio.AsyncResult}.
-     * @param is_truncated will be set to `true` if the `input_stream` contains more data   to be read, but the maximum number of bytes to read has been reached.
-     * @returns a {@link GLib.Bytes}, or `null` on error.
+     * This function can be called several times, but is meant to be called at the
+     * beginning of `main()`, before any other Gfls function call.
      * @since 0.1
      */
-    function input_stream_read_finish(input_stream: Gio.InputStream, result: Gio.AsyncResult, is_truncated: boolean): GLib.Bytes;
+    function init(): void;
 
     /**
      * Starts a basic file loading operation.
@@ -250,6 +263,13 @@ export namespace Gfls {
      */
     function utf8_find_very_long_line(str: string, max_n_bytes_per_line: number): string;
 
+    /**
+     * @gir-type Callback
+     */
+    interface SimpleProgressCallback {
+        (number: number): void;
+    }
+
     /**
      * @gir-type Callback
      */
@@ -463,6 +483,133 @@ export namespace Gfls {
     }
 
 
+    /**
+     * @gir-type Struct
+     */
+    abstract class BytesRegion {
+        static $gtype: GObject.GType<BytesRegion>;
+
+        // Methods
+        /**
+         * Frees `region`.
+         */
+        free(): void;
+
+        /**
+         * Frees `iter`.
+         * @param iter a {@link Gfls.BytesRegionIter}.
+         */
+        iter_free(iter: BytesRegionIter | null): void;
+
+        /**
+         * Gets the sub-region at this iterator.
+         * 
+         * `sub_region_size` and `offset` can be used as arguments to
+         * `g_bytes_get_region()`.
+         * 
+         * `is_part_of_region` has the same meaning as for
+         * `gfls_bytes_region_builder_append()`. {@link Gfls.BytesRegionIter} iterates on both the
+         * region and the holes, so that the corresponding {@link GLib.Bytes} is traversed from
+         * start to end.
+         * @param iter a {@link Gfls.BytesRegionIter}. It must not be the end iterator.
+         */
+        iter_get_sub_region(iter: BytesRegionIter): [number, number, boolean];
+
+        /**
+         * @param iter a {@link Gfls.BytesRegionIter}.
+         * @returns whether `iter` is the end iterator.
+         */
+        iter_is_end(iter: BytesRegionIter): boolean;
+
+        /**
+         * Moves `iter` to the next sub-region.
+         * 
+         * If all sub-regions have been traversed, `iter` is set to the end iterator.
+         * @param iter a {@link Gfls.BytesRegionIter}. The end iterator is accepted as an input   value.
+         */
+        iter_next(iter: BytesRegionIter): void;
+
+        /**
+         * @param bytes a {@link GLib.Bytes}.
+         * @returns whether `region` can be applied to `bytes` (it checks the total size).
+         */
+        match_bytes(bytes: GLib.Bytes | Uint8Array): boolean;
+
+        /**
+         * The format is:
+         * 
+         * `[offset, sub_region_size, is_part_of_region]\n`
+         * 
+         * One line per sub-region, in order.
+         * @returns a string representation of `region`.
+         */
+        to_string(): string;
+    }
+
+
+    /**
+     * @gir-type Struct
+     */
+    abstract class BytesRegionBuilder {
+        static $gtype: GObject.GType<BytesRegionBuilder>;
+
+        // Methods
+        /**
+         * Appends a sub-region at the end.
+         * 
+         * If `is_part_of_region` is `false` it creates a hole.
+         * 
+         * Contiguous sub-regions of the same kind are merged and will thus be treated
+         * as a single sub-region. So you can conveniently call this function several
+         * times in a row with the same value for `is_part_of_region`.
+         * 
+         * In order to create a {@link Gfls.BytesRegion} that will traverse a whole {@link GLib.Bytes}, it
+         * is required to call this function the right amount of times, even if it ends
+         * with a hole. See also `gfls_bytes_region_match_bytes()`.
+         * @param sub_region_length the length of the sub-region. Must not be equal to 0.
+         * @param is_part_of_region whether the sub-region is part of the region.
+         */
+        append(sub_region_length: bigint | number, is_part_of_region: boolean): void;
+
+        /**
+         * Creates a {@link Gfls.BytesRegion} and frees `builder`.
+         * @param free_data if `true`, the data is freed as well.
+         * @returns a {@link Gfls.BytesRegion}, or `null` if   `free_data` is `true`.
+         */
+        free(free_data: boolean): BytesRegion | null;
+
+        /**
+         * @returns the current total size, in number of bytes (holes included).
+         */
+        get_current_size(): number;
+    }
+
+
+    /**
+     * @gir-type Struct
+     */
+    abstract class BytesRegionIter {
+        static $gtype: GObject.GType<BytesRegionIter>;
+    }
+
+
+    /**
+     * @gir-type Struct
+     */
+    abstract class Iconv {
+        static $gtype: GObject.GType<Iconv>;
+
+        // Methods
+        /**
+         * Closes and frees `conv`.
+         * 
+         * If you need to know if closing `conv` returns an error, call
+         * `gfls_iconv_close()` explicitly beforehand.
+         */
+        free(): void;
+    }
+
+
     /**
      * @gir-type Alias
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@girs/gfls-1",
-    "version": "4.2.0",
+    "version": "4.3.0",
     "description": "GJS TypeScript type definitions for Gfls-1",
     "type": "module",
     "module": "gfls-1.js",
@@ -31,20 +31,20 @@
       "test": "tsc --project tsconfig.json"
     },
     "dependencies": {
-      "@girs/gjs": "^4.2.0",
-      "@girs/gtk-3.0": "^4.2.0",
-      "@girs/xlib-2.0": "^4.2.0",
-      "@girs/gdk-3.0": "^4.2.0",
-      "@girs/cairo-1.0": "^4.2.0",
-      "@girs/gobject-2.0": "^4.2.0",
-      "@girs/glib-2.0": "^4.2.0",
-      "@girs/pango-1.0": "^4.2.0",
-      "@girs/harfbuzz-0.0": "^4.2.0",
-      "@girs/freetype2-2.0": "^4.2.0",
-      "@girs/gio-2.0": "^4.2.0",
-      "@girs/gmodule-2.0": "^4.2.0",
-      "@girs/gdkpixbuf-2.0": "^4.2.0",
-      "@girs/atk-1.0": "^4.2.0"    },
+      "@girs/gjs": "^4.3.0",
+      "@girs/gtk-3.0": "^4.3.0",
+      "@girs/xlib-2.0": "^4.3.0",
+      "@girs/gdk-3.0": "^4.3.0",
+      "@girs/cairo-1.0": "^4.3.0",
+      "@girs/gobject-2.0": "^4.3.0",
+      "@girs/glib-2.0": "^4.3.0",
+      "@girs/pango-1.0": "^4.3.0",
+      "@girs/harfbuzz-0.0": "^4.3.0",
+      "@girs/freetype2-2.0": "^4.3.0",
+      "@girs/gio-2.0": "^4.3.0",
+      "@girs/gmodule-2.0": "^4.3.0",
+      "@girs/gdkpixbuf-2.0": "^4.3.0",
+      "@girs/atk-1.0": "^4.3.0"    },
     "devDependencies": {
       "typescript": "*"
     },