@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/esm/lib/backend/KoffiTypes.js

@@ -0,0 +1,418 @@
+import koffi from 'koffi';
+import { NativeDeclarationException } from '../../exceptions/NativeDeclarationException.js';
+import { alignmentOf, layoutOf } from '../declarations/Layout.js';
+import { primitiveBig, primitiveSigned, typeText } from '../declarations/Types.js';
+/**
+ * The names koffi gives the arithmetic types (ssize_t and ptrdiff_t have the size and the sign of intptr_t)
+ */
+const KOFFI_NAMES = {
+    void: 'void',
+    bool: 'bool',
+    char: 'char',
+    schar: 'int8_t',
+    uchar: 'uchar',
+    short: 'short',
+    ushort: 'ushort',
+    int: 'int',
+    uint: 'uint',
+    long: 'long',
+    ulong: 'ulong',
+    longlong: 'longlong',
+    ulonglong: 'ulonglong',
+    int8: 'int8_t',
+    uint8: 'uint8_t',
+    int16: 'int16_t',
+    uint16: 'uint16_t',
+    int32: 'int32_t',
+    uint32: 'uint32_t',
+    int64: 'int64_t',
+    uint64: 'uint64_t',
+    size: 'size_t',
+    ssize: 'intptr_t',
+    intptr: 'intptr_t',
+    uintptr: 'uintptr_t',
+    ptrdiff: 'intptr_t',
+    char16: 'char16_t',
+    char32: 'char32_t',
+    wchar: 'wchar_t',
+    float: 'float',
+    double: 'double'
+};
+/**
+ * The prefix of the members the package adds to the structs it lays out itself (the bytes of the bitfields, padding):
+ * the names starting with two underscores are reserved to the compilers and the C library, never a struct of a user
+ */
+const INTERNAL = '__lakutata_';
+/**
+ * A value of a 64-bit integer type, as a bigint
+ * @param value
+ */
+export function toBigInt(value) {
+    return typeof value === 'number' ? BigInt(value) : value;
+}
+/**
+ * The integer type of a primitive or of an enumeration
+ * @param type
+ */
+function integerName(type) {
+    if (type.kind === 'primitive')
+        return type.name;
+    if (type.kind === 'enum')
+        return type.base;
+    return undefined;
+}
+/**
+ * Round up to a multiple
+ * @param value
+ * @param multiple
+ */
+function alignUp(value, multiple) {
+    return Math.ceil(value / multiple) * multiple;
+}
+/**
+ * The koffi types of the C types of the declarations, made once each (koffi never frees a type): anonymous, so the
+ * types of two libraries never meet; the structs koffi cannot lay out (bitfields, packing) laid out by the package
+ */
+export class KoffiTypes {
+    #platform;
+    #types = new WeakMap();
+    #converters = new WeakMap();
+    #prototypes = new WeakMap();
+    /**
+     * The koffi types of a platform.
+     * @param platform The platform of the process.
+     */
+    constructor(platform) {
+        this.#platform = platform;
+    }
+    /**
+     * The koffi type of a C type, as a value: a member, a result, a parameter without direction.
+     * @param type The C type.
+     */
+    type(type) {
+        switch (type.kind) {
+            case 'primitive':
+                return KOFFI_NAMES[type.name];
+            case 'enum':
+                return KOFFI_NAMES[type.base];
+            case 'pointer':
+                return this.#pointer(type.to);
+            case 'array':
+                return this.#cached(type, () => koffi.array(this.type(type.of), type.length));
+            case 'struct':
+            case 'union':
+                if (type.tag === 'va_list' && !type.members)
+                    throw new NativeDeclarationException('A va_list cannot be passed: call the function of the library that takes the arguments themselves');
+                return this.#record(type);
+            case 'function':
+                throw new NativeDeclarationException(`A function is not a value: use a pointer to it (${typeText(type)})`);
+        }
+    }
+    /**
+     * The koffi prototype of a function type: the type of its callbacks.
+     * @param type The function type.
+     */
+    prototype(type) {
+        const known = this.#prototypes.get(type);
+        if (known)
+            return known;
+        if (type.variadic)
+            throw new NativeDeclarationException(`A callback cannot be variadic: ${typeText(type)}`);
+        const prototype = koffi.proto(`__${type.convention}`, this.type(type.result), type.parameters.map((parameter) => this.type(parameter.type)));
+        this.#prototypes.set(type, prototype);
+        return prototype;
+    }
+    /**
+     * The converter of a C type, null when koffi gives and takes its values as the package does.
+     * @param type The C type.
+     */
+    converter(type) {
+        const known = this.#converters.get(type);
+        if (known !== undefined)
+            return known;
+        let converter = null;
+        switch (type.kind) {
+            case 'primitive':
+            case 'enum':
+                if (primitiveBig(integerName(type)))
+                    converter = { fromNative: toBigInt };
+                break;
+            case 'array': {
+                const element = this.converter(type.of);
+                if (element) {
+                    converter = {
+                        ...element.toNative ? { toNative: (value) => Array.isArray(value) ? value.map(element.toNative) : value } : {},
+                        ...element.fromNative ? { fromNative: (value) => value && typeof value !== 'string' ? Array.from(value, element.fromNative) : value } : {}
+                    };
+                }
+                break;
+            }
+            case 'struct':
+            case 'union':
+                if (type.members) {
+                    //Reserved first: a struct reached through its own members converts as it is being made
+                    this.#converters.set(type, null);
+                    converter = this.#recordConverter(type);
+                }
+                break;
+        }
+        this.#converters.set(type, converter);
+        return converter;
+    }
+    /**
+     * The koffi type of a pointer: the strings for char (and char16_t, wchar_t), the prototypes for functions
+     * @param to
+     */
+    #pointer(to) {
+        if (to.kind === 'primitive') {
+            if (to.name === 'char')
+                return 'char *';
+            if (to.name === 'char16')
+                return 'char16_t *';
+            if (to.name === 'wchar')
+                return 'wchar_t *';
+            if (to.name === 'void')
+                return 'void *';
+        }
+        if (to.kind === 'function')
+            return this.#cached(to, () => koffi.pointer(this.prototype(to)));
+        if ((to.kind === 'struct' || to.kind === 'union') && !to.members)
+            return this.#cached(to, () => koffi.pointer(koffi.opaque()));
+        return koffi.pointer(this.type(to));
+    }
+    /**
+     * A type made once for a C type
+     * @param type
+     * @param make
+     */
+    #cached(type, make) {
+        let made = this.#types.get(type);
+        if (!made) {
+            made = make();
+            this.#types.set(type, made);
+        }
+        return made;
+    }
+    /**
+     * The koffi type of a struct or a union, declared first as an opaque type its own members can point to
+     * @param record
+     */
+    #record(record) {
+        const known = this.#types.get(record);
+        if (known)
+            return known;
+        const layout = layoutOf(record, this.#platform);
+        const placeholder = koffi.opaque();
+        this.#types.set(record, placeholder);
+        const members = this.#members(record, layout);
+        const made = record.kind === 'union' ? koffi.union(placeholder, members) : koffi.struct(placeholder, members);
+        this.#types.set(record, made);
+        //What koffi lays out must be what the platform lays out: the size, the alignment, the offset of each member
+        const misplaced = record.kind === 'struct' ? layout.members.find((placed) => placed.bits === undefined && !!made.members?.[placed.member.name] && made.members[placed.member.name].offset !== placed.offset) : undefined;
+        if (made.size !== layout.size || made.alignment !== layout.alignment || misplaced) {
+            throw new NativeDeclarationException(`The layout of ${typeText(record)} could not be given to koffi (${made.size} bytes aligned on ${made.alignment}, ${layout.size} on ${layout.alignment} expected${misplaced ? `, ${misplaced.member.name} at ${made.members[misplaced.member.name].offset}, ${misplaced.offset} expected` : ''})`);
+        }
+        return made;
+    }
+    /**
+     * The members of a struct as koffi lays them out: each at the alignment the platform gives it (capped by the packing,
+     * raised by an aligned attribute), the bytes of the bitfields and the padding they need as arrays of bytes, the
+     * alignment of the struct on its first member when its members alone do not give it
+     * @param record
+     * @param layout
+     */
+    #members(record, layout) {
+        const entries = [];
+        if (record.kind === 'union') {
+            for (const placed of layout.members)
+                entries.push({ name: placed.member.name, type: this.type(placed.member.type), offset: 0, size: placed.size, alignment: this.#memberAlignment(placed.member, record) });
+        }
+        else {
+            let chunk = 0;
+            for (const group of this.#groups(layout)) {
+                if ('bitfields' in group) {
+                    entries.push({ name: `${INTERNAL}bits${chunk++}`, type: koffi.array('uint8_t', group.size, 'Typed'), offset: group.offset, size: group.size, alignment: 1 });
+                    continue;
+                }
+                //A flexible array member has no bytes: koffi does not need it
+                if (group.member.type.kind === 'array' && group.member.type.length === 0)
+                    continue;
+                entries.push({ name: group.member.name, type: this.type(group.member.type), offset: group.offset, size: group.size, alignment: this.#memberAlignment(group.member, record) });
+            }
+        }
+        const members = {};
+        let end = 0;
+        let alignment = 1;
+        let padding = 0;
+        entries.forEach((entry, index) => {
+            if (record.kind === 'struct' && alignUp(end, entry.alignment) !== entry.offset) {
+                members[`${INTERNAL}pad${padding++}`] = [1, koffi.array('uint8_t', entry.offset - end, 'Typed')];
+                end = entry.offset;
+            }
+            //The alignment of the struct, on its first member (at 0, aligned on anything)
+            const own = index === 0 && layout.alignment > entry.alignment && this.#alignmentShortfall(entries, layout) ? layout.alignment : entry.alignment;
+            members[entry.name] = own === this.#naturalAlignment(entry.type) ? entry.type : [own, entry.type];
+            alignment = Math.max(alignment, own);
+            end = record.kind === 'struct' ? entry.offset + entry.size : Math.max(end, entry.size);
+        });
+        if (!entries.length)
+            members[`${INTERNAL}pad${padding++}`] = [layout.alignment, koffi.array('uint8_t', layout.size || 1, 'Typed')];
+        else if (record.kind === 'struct' && alignUp(end, Math.max(alignment, layout.alignment)) < layout.size)
+            members[`${INTERNAL}pad${padding++}`] = [1, koffi.array('uint8_t', layout.size - end, 'Typed')];
+        return members;
+    }
+    /**
+     * Whether the members of a struct alone are aligned less than the struct (an aligned attribute on the struct, the
+     * type of a bitfield, a flexible array member)
+     * @param entries
+     * @param layout
+     */
+    #alignmentShortfall(entries, layout) {
+        return Math.max(1, ...entries.map((entry) => entry.alignment)) < layout.alignment;
+    }
+    /**
+     * The alignment koffi gives a type by itself
+     * @param type
+     */
+    #naturalAlignment(type) {
+        return koffi.type(type).alignment;
+    }
+    /**
+     * The alignment of a member on the platform: its type's, raised by its aligned attribute, capped by the packing
+     * @param member
+     * @param record
+     */
+    #memberAlignment(member, record) {
+        const natural = Math.max(alignmentOf(member.type, this.#platform), member.align ?? 1);
+        return record.pack ? Math.min(natural, record.pack) : natural;
+    }
+    /**
+     * The members of a struct in the order of their offsets, the bitfields sharing bytes grouped
+     * @param layout
+     */
+    #groups(layout) {
+        const groups = [];
+        for (const placed of layout.members) {
+            if (placed.bits === undefined) {
+                groups.push({ member: placed.member, offset: placed.offset, size: placed.size });
+                continue;
+            }
+            const first = Math.floor(placed.bitOffset / 8);
+            const last = Math.ceil((placed.bitOffset + placed.bits) / 8);
+            const previous = groups[groups.length - 1];
+            if (previous && 'bitfields' in previous && first <= previous.offset + previous.size) {
+                previous.bitfields.push(placed);
+                previous.size = Math.max(previous.size, last - previous.offset);
+            }
+            else {
+                groups.push({ bitfields: [placed], offset: first, size: last - first });
+            }
+        }
+        return groups;
+    }
+    /**
+     * The converter of a struct or a union: the converters of its members; its bitfields read from and written to the
+     * bytes holding them; the members the package added left out
+     * @param record
+     */
+    #recordConverter(record) {
+        const layout = layoutOf(record, this.#platform);
+        const groups = record.kind === 'struct' ? this.#groups(layout) : layout.members.map((placed) => ({ member: placed.member, offset: 0, size: placed.size }));
+        const made = this.#record(record);
+        const internal = Object.keys(made.members ?? {}).some((name) => name.startsWith(INTERNAL));
+        const members = [];
+        const bitfields = [];
+        let chunk = 0;
+        for (const group of groups) {
+            if ('bitfields' in group) {
+                const name = `${INTERNAL}bits${chunk++}`;
+                for (const placed of group.bitfields) {
+                    if (!placed.member.name)
+                        continue;
+                    const integer = integerName(placed.member.type);
+                    bitfields.push({ name: placed.member.name, chunk: name, offset: placed.bitOffset - group.offset * 8, bits: placed.bits, signed: primitiveSigned(integer, this.#platform), big: primitiveBig(integer) });
+                }
+                continue;
+            }
+            if (group.member.type.kind === 'array' && group.member.type.length === 0)
+                continue;
+            members.push({ name: group.member.name, converter: this.converter(group.member.type) });
+        }
+        const converted = members.filter((member) => !!member.converter);
+        if (!converted.length && !bitfields.length && !internal)
+            return null;
+        const chunks = new Map(groups.filter((group) => 'bitfields' in group).map((group, index) => [`${INTERNAL}bits${index}`, group.size]));
+        const toNativeMembers = converted.filter((member) => !!member.converter.toNative);
+        const writes = toNativeMembers.length > 0 || bitfields.length > 0;
+        return {
+            ...writes ? {
+                toNative: (value) => {
+                    if (!value || typeof value !== 'object' || ArrayBuffer.isView(value))
+                        return value;
+                    const native = { ...value };
+                    for (const member of toNativeMembers)
+                        if (member.name in native)
+                            native[member.name] = member.converter.toNative(native[member.name]);
+                    if (bitfields.length) {
+                        const bytes = new Map([...chunks].map(([name, size]) => [name, new Uint8Array(size)]));
+                        for (const field of bitfields) {
+                            const given = native[field.name];
+                            delete native[field.name];
+                            if (given === undefined || given === null)
+                                continue;
+                            writeBits(bytes.get(field.chunk), field.offset, field.bits, BigInt(given));
+                        }
+                        for (const [name, array] of bytes)
+                            native[name] = array;
+                    }
+                    return native;
+                }
+            } : {},
+            fromNative: (value) => {
+                if (!value || typeof value !== 'object')
+                    return value;
+                const result = {};
+                for (const member of members)
+                    if (member.name in value)
+                        result[member.name] = member.converter?.fromNative ? member.converter.fromNative(value[member.name]) : value[member.name];
+                for (const field of bitfields) {
+                    const bits = readBits(value[field.chunk], field.offset, field.bits, field.signed);
+                    result[field.name] = field.big ? bits : Number(bits);
+                }
+                return result;
+            }
+        };
+    }
+}
+/**
+ * The bits of a bitfield, from its bytes (the lowest bits first)
+ * @param bytes
+ * @param offset its first bit in the bytes
+ * @param bits its width
+ * @param signed whether its type is signed (its highest bit extended)
+ */
+function readBits(bytes, offset, bits, signed) {
+    let value = 0n;
+    for (let i = bits - 1; i >= 0; i--) {
+        const bit = offset + i;
+        value = (value << 1n) | BigInt((bytes[bit >> 3] >> (bit & 7)) & 1);
+    }
+    return signed ? BigInt.asIntN(bits, value) : value;
+}
+/**
+ * The bits of a bitfield written to its bytes
+ * @param bytes
+ * @param offset
+ * @param bits
+ * @param value
+ */
+function writeBits(bytes, offset, bits, value) {
+    const unsigned = BigInt.asUintN(bits, value);
+    for (let i = 0; i < bits; i++) {
+        const bit = offset + i;
+        if ((unsigned >> BigInt(i)) & 1n)
+            bytes[bit >> 3] |= 1 << (bit & 7);
+        else
+            bytes[bit >> 3] &= ~(1 << (bit & 7));
+    }
+}

package/dist/esm/lib/declarations/Builtins.js

@@ -0,0 +1,174 @@
+const primitive = (name) => ({ kind: 'primitive', name: name });
+const pointer = (to, constTarget = false) => ({ kind: 'pointer', to: to, constTarget: constTarget });
+/**
+ * The opaque FILE of the C library, the same object for every library: the pointers of two libraries are the same type
+ */
+const FILE = { kind: 'struct', tag: 'FILE' };
+/**
+ * The va_list of the variadic functions: declared, it cannot be passed (the functions taking one are for C callers)
+ */
+const VA_LIST = { kind: 'struct', tag: 'va_list' };
+/**
+ * The GUID of Windows (UUID, CLSID, IID)
+ */
+const GUID = {
+    kind: 'struct',
+    tag: '_GUID',
+    members: [
+        { name: 'Data1', type: primitive('uint32') },
+        { name: 'Data2', type: primitive('uint16') },
+        { name: 'Data3', type: primitive('uint16') },
+        { name: 'Data4', type: { kind: 'array', of: primitive('uint8'), length: 8 } }
+    ]
+};
+/**
+ * The handles of Windows: pointers to nothing known
+ */
+const HANDLES = [
+    'HANDLE', 'HWND', 'HINSTANCE', 'HMODULE', 'HKEY', 'HDC', 'HGLOBAL', 'HLOCAL', 'HMENU', 'HICON', 'HBITMAP', 'HBRUSH',
+    'HFONT', 'HPEN', 'HRGN', 'HCURSOR', 'HMONITOR', 'HRSRC', 'HGDIOBJ', 'HACCEL', 'HDESK', 'HWINSTA', 'HHOOK', 'HEVENT',
+    'HKL', 'HPALETTE', 'HDROP', 'HDEVINFO', 'SC_HANDLE', 'SERVICE_STATUS_HANDLE', 'PSID', 'HCRYPTPROV'
+];
+/**
+ * The types every declaration knows without declaring them: the ones of stdint.h and stddef.h, the ones of POSIX with
+ * their size on the platform, the ones of the Windows API (the same on every platform: DWORD is 32-bit everywhere).
+ * A declaration of the same name replaces them
+ * @param platform
+ */
+export function builtinTypes(platform) {
+    const windows = platform.os === 'win32';
+    const darwin = platform.os === 'darwin';
+    const types = new Map();
+    const set = (names, type) => {
+        for (const name of typeof names === 'string' ? [names] : names)
+            types.set(name, type);
+    };
+    //stdint.h, stddef.h, uchar.h, stdbool.h
+    for (const bits of [8, 16, 32, 64]) {
+        set([`int${bits}_t`, `int_least${bits}_t`, `int_fast${bits}_t`, `__int${bits}_t`], primitive(`int${bits}`));
+        set([`uint${bits}_t`, `uint_least${bits}_t`, `uint_fast${bits}_t`, `__uint${bits}_t`, `u_int${bits}_t`], primitive(`uint${bits}`));
+    }
+    set(['intmax_t'], primitive('int64'));
+    set(['uintmax_t'], primitive('uint64'));
+    set(['size_t', 'rsize_t'], primitive('size'));
+    set(['ssize_t'], primitive('ssize'));
+    set(['intptr_t'], primitive('intptr'));
+    set(['uintptr_t'], primitive('uintptr'));
+    set(['ptrdiff_t'], primitive('ptrdiff'));
+    set(['wchar_t'], primitive('wchar'));
+    set(['char16_t'], primitive('char16'));
+    set(['char32_t'], primitive('char32'));
+    set(['bool'], primitive('bool'));
+    //POSIX, with their size on the platform
+    set(['time_t'], primitive(windows ? 'int64' : 'long'));
+    set(['suseconds_t'], primitive(darwin ? 'int32' : 'long'));
+    set(['useconds_t'], primitive('uint32'));
+    set(['off_t'], primitive(darwin ? 'int64' : 'long'));
+    set(['clock_t'], primitive(darwin ? 'ulong' : 'long'));
+    set(['pid_t'], primitive('int32'));
+    set(['uid_t', 'gid_t', 'socklen_t'], primitive('uint32'));
+    set(['mode_t'], primitive(darwin ? 'uint16' : 'uint32'));
+    set(['FILE'], FILE);
+    set(['va_list', '__builtin_va_list', '__gnuc_va_list', '__darwin_va_list', '__va_list'], VA_LIST);
+    //The BSD types (sys/types.h)
+    set(['u_char'], primitive('uint8'));
+    set(['u_short'], primitive('uint16'));
+    set(['u_int'], primitive('uint32'));
+    set(['u_long'], primitive('ulong'));
+    set(['u_quad_t'], primitive('uint64'));
+    set(['quad_t'], primitive('int64'));
+    set(['caddr_t'], pointer(primitive('char')));
+    //The Windows API
+    set(['BYTE', 'UCHAR', 'BOOLEAN', 'UINT8'], primitive('uint8'));
+    set(['CHAR', 'CCHAR'], primitive('char'));
+    set(['INT8'], primitive('int8'));
+    set(['WCHAR'], primitive('char16'));
+    set(['SHORT', 'INT16'], primitive('int16'));
+    set(['USHORT', 'WORD', 'ATOM', 'LANGID', 'UINT16'], primitive('uint16'));
+    set(['INT', 'LONG', 'BOOL', 'HRESULT', 'NTSTATUS', 'LONG32', 'INT32', 'HFILE'], primitive('int32'));
+    set(['UINT', 'ULONG', 'DWORD', 'DWORD32', 'ULONG32', 'UINT32', 'COLORREF', 'LCID'], primitive('uint32'));
+    set(['LONGLONG', 'LONG64', 'INT64'], primitive('int64'));
+    set(['ULONGLONG', 'DWORDLONG', 'QWORD', 'DWORD64', 'ULONG64', 'UINT64'], primitive('uint64'));
+    set(['FLOAT'], primitive('float'));
+    set(['DOUBLE'], primitive('double'));
+    set(['INT_PTR', 'LONG_PTR', 'LPARAM', 'LRESULT', 'SSIZE_T'], primitive('intptr'));
+    set(['UINT_PTR', 'ULONG_PTR', 'DWORD_PTR', 'WPARAM', 'SIZE_T'], primitive('uintptr'));
+    set(HANDLES, pointer(primitive('void')));
+    set(['PVOID', 'LPVOID'], pointer(primitive('void')));
+    set(['LPCVOID', 'PCVOID'], pointer(primitive('void'), true));
+    set(['LPSTR', 'PSTR', 'PCHAR'], pointer(primitive('char')));
+    set(['LPCSTR', 'PCSTR'], pointer(primitive('char'), true));
+    set(['LPWSTR', 'PWSTR', 'PWCHAR'], pointer(primitive('char16')));
+    set(['LPCWSTR', 'PCWSTR'], pointer(primitive('char16'), true));
+    set(['LPBYTE', 'PBYTE', 'PUCHAR', 'PBOOLEAN'], pointer(primitive('uint8')));
+    set(['LPWORD', 'PWORD', 'PUSHORT'], pointer(primitive('uint16')));
+    set(['LPDWORD', 'PDWORD', 'PULONG', 'PUINT', 'LPUINT'], pointer(primitive('uint32')));
+    set(['LPLONG', 'PLONG', 'LPINT', 'PINT', 'LPBOOL', 'PBOOL'], pointer(primitive('int32')));
+    set(['PULONGLONG', 'PDWORD64'], pointer(primitive('uint64')));
+    set(['PLONGLONG'], pointer(primitive('int64')));
+    set(['PSIZE_T', 'PULONG_PTR', 'PDWORD_PTR'], pointer(primitive('uintptr')));
+    set(['PHANDLE', 'LPHANDLE'], pointer(pointer(primitive('void'))));
+    set(['GUID', 'UUID', 'CLSID', 'IID'], GUID);
+    return types;
+}
+/**
+ * The words naming a calling convention: the keywords of the compilers, the macros of the Windows API
+ */
+export const CONVENTIONS = new Map([
+    ['__cdecl', 'cdecl'], ['_cdecl', 'cdecl'], ['__stdcall', 'stdcall'], ['_stdcall', 'stdcall'],
+    ['__fastcall', 'fastcall'], ['_fastcall', 'fastcall'], ['__thiscall', 'thiscall'],
+    ['WINAPI', 'stdcall'], ['APIENTRY', 'stdcall'], ['CALLBACK', 'stdcall'], ['PASCAL', 'stdcall'], ['NTAPI', 'stdcall'],
+    ['STDMETHODCALLTYPE', 'stdcall'], ['STDAPICALLTYPE', 'stdcall'], ['WINAPIV', 'cdecl'], ['CDECL', 'cdecl']
+]);
+/**
+ * The words read and ignored where qualifiers go: the qualifiers that do not change how a value is passed, the macros of
+ * the Windows API that are empty
+ */
+export const IGNORED = new Set([
+    'volatile', 'restrict', '__restrict', '__restrict__', '_Nullable', '_Nonnull', '_Null_unspecified', '__nullable',
+    '__nonnull', '__null_unspecified', '_Nullable_result', '__unaligned', '__ptr32', '__ptr64', '__w64', '__sptr', '__uptr',
+    'FAR', 'NEAR', 'far', 'near', 'OPTIONAL', 'register', 'auto', '__extension__', '_Noreturn', 'noreturn', '__volatile__',
+    '__kindof', '__cdecl__', '__weak', '__strong', '__autoreleasing', '__unsafe_unretained'
+]);
+/**
+ * The words read as const
+ */
+export const CONSTS = new Set(['const', '__const', '__const__', 'CONST']);
+/**
+ * The words of inline functions, whose bodies are skipped
+ */
+export const INLINES = new Set(['inline', '__inline', '__inline__', '__forceinline', '_inline', 'FORCEINLINE']);
+/**
+ * The prefixes of the annotations of Microsoft (SAL): a word starting with one, not declared as a type, is an
+ * annotation, its arguments in parentheses skipped
+ */
+const SAL_PREFIXES = [
+    '_In_', '_Out', '_Inout', '_COM_Outptr', '_Ret_', '_Success_', '_Check_return_', '_Must_inspect_result_',
+    '_Printf_format_string_', '_Scanf_format_string_', '_Field_', '_Frees_ptr_', '_Pre_', '_Post_', '_Deref_', '_Reserved_',
+    '_Null_terminated_', '_NullNull_terminated_', '_Use_decl_annotations_', '_When_', '_At_', '_At_buffer_', '_Always_',
+    '_Return_type_success_', '_Struct_size_bytes_', '_Readable_', '_Writable_', '__drv_', '_IRQL_', '_Kernel_',
+    '_Function_class_', '_Callback_', '_Notnull_', '_Maybenull_', '_Const_', '_Translates_', '_Points_to_data_',
+    '_Literal_', '_Notliteral_', '_Strict_type_match_', '_Analysis_', '_Acquires_', '_Releases_', '_Requires_', '_Guarded_by_',
+    '_Interlocked_', '_Inexpressible_', '_Pre_satisfies_', '_Outref_', '_Ret_maybenull_', '_Result_', '_Group_', '_On_failure_'
+];
+/**
+ * The direction an annotation gives a parameter, if it is one: the ones of Microsoft (_Out_, _Inout_opt_,
+ * _Outptr_result_maybenull_…) and the macros IN and OUT of the Windows API; null for an annotation that gives none,
+ * undefined for a word that is not an annotation
+ * @param word
+ */
+export function annotationDirection(word) {
+    if (word === 'IN')
+        return 'in';
+    if (word === 'OUT')
+        return 'out';
+    if (!SAL_PREFIXES.some((prefix) => word.startsWith(prefix)) && !['_In_', '_Out_', '_Inout_'].includes(word))
+        return undefined;
+    if (word.startsWith('_Inout'))
+        return 'inout';
+    if (word.startsWith('_Out') || word.startsWith('_COM_Outptr'))
+        return 'out';
+    if (word.startsWith('_In_'))
+        return 'in';
+    return null;
+}