@lakutata/ffi 0.0.0-stage → 3.1.2

package/dist/cjs/lib/declarations/Platform.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What the sizes of the C types and the layout of the structs depend on
+ */
+export interface Platform {
+    /**
+     * The operating system, as process.platform names it
+     */
+    readonly os: string;
+    /**
+     * The architecture, as process.arch names it
+     */
+    readonly arch: string;
+    /**
+     * The size of a pointer (and of size_t), in bytes
+     */
+    readonly pointerSize: 4 | 8;
+    /**
+     * The size of long: 8 on 64-bit Unix systems (LP64), 4 on Windows (LLP64) and on 32-bit systems
+     */
+    readonly longSize: 4 | 8;
+    /**
+     * The size of wchar_t: 2 on Windows, 4 elsewhere
+     */
+    readonly wcharSize: 2 | 4;
+    /**
+     * The alignment of the 8-byte types (long long, double) as members: 4 on 32-bit Linux (i386), 8 elsewhere
+     */
+    readonly int64Alignment: 4 | 8;
+    /**
+     * How bitfields are laid out: by the rules of GCC and Clang (sysv), of the ARM procedure call standard where the
+     * type of every bitfield aligns the struct, the unnamed and the empty ones too (aapcs: ARM but on Apple systems), or
+     * of the compiler of Microsoft (msvc)
+     */
+    readonly bitfields: 'sysv' | 'aapcs' | 'msvc';
+    /**
+     * Whether the symbols of the C functions start with an underscore in the binaries (macOS): the labels of __asm
+     * name them so
+     */
+    readonly underscoredSymbols: boolean;
+}
+/**
+ * The platform of a system and an architecture
+ * @param os
+ * @param arch
+ */
+export declare function platformOf(os: string, arch: string): Platform;
+/**
+ * The platform the process runs on
+ */
+export declare const CURRENT_PLATFORM: Platform;

package/dist/cjs/lib/declarations/Platform.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_PLATFORM = void 0;
+exports.platformOf = platformOf;
+/**
+ * The platform of a system and an architecture
+ * @param os
+ * @param arch
+ */
+function platformOf(os, arch) {
+    const bits64 = !['ia32', 'arm', 'x32'].includes(arch);
+    const windows = os === 'win32';
+    return {
+        os: os,
+        arch: arch,
+        pointerSize: bits64 ? 8 : 4,
+        longSize: bits64 && !windows ? 8 : 4,
+        wcharSize: windows ? 2 : 4,
+        int64Alignment: !bits64 && !windows && arch === 'ia32' ? 4 : 8,
+        bitfields: windows ? 'msvc' : (arch === 'arm' || arch === 'arm64') && os !== 'darwin' ? 'aapcs' : 'sysv',
+        underscoredSymbols: os === 'darwin'
+    };
+}
+/**
+ * The platform the process runs on
+ */
+exports.CURRENT_PLATFORM = platformOf(process.platform, process.arch);

package/dist/cjs/lib/declarations/Types.d.ts

@@ -0,0 +1,173 @@
+import type { Platform } from './Platform.js';
+/**
+ * The arithmetic types of C, by their meaning (long is not int64: their sizes differ between the platforms)
+ */
+export type PrimitiveName = 'void' | 'bool' | 'char' | 'schar' | 'uchar' | 'short' | 'ushort' | 'int' | 'uint' | 'long' | 'ulong' | 'longlong' | 'ulonglong' | 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'int64' | 'uint64' | 'size' | 'ssize' | 'intptr' | 'uintptr' | 'ptrdiff' | 'char16' | 'char32' | 'wchar' | 'float' | 'double';
+/**
+ * How the arguments of a function are passed: different on 32-bit Windows only
+ */
+export type CallingConvention = 'cdecl' | 'stdcall' | 'fastcall' | 'thiscall';
+/**
+ * Which way a pointer argument carries its value: into the function, out of it (the object or the array given is
+ * filled once it returns), or both
+ */
+export type Direction = 'in' | 'out' | 'inout';
+export interface PrimitiveType {
+    readonly kind: 'primitive';
+    readonly name: PrimitiveName;
+}
+export interface PointerType {
+    readonly kind: 'pointer';
+    readonly to: CType;
+    /**
+     * Whether what it points to is const (const char * is a string given to the function)
+     */
+    readonly constTarget: boolean;
+}
+export interface ArrayType {
+    readonly kind: 'array';
+    readonly of: CType;
+    readonly length: number;
+}
+export interface Member {
+    /**
+     * Its name; the anonymous structs and unions inside a struct are named _0, _1… in the order of the struct
+     */
+    readonly name: string;
+    readonly type: CType;
+    /**
+     * The width of a bitfield
+     */
+    readonly bits?: number;
+    /**
+     * The alignment its aligned attribute asks for, in bytes
+     */
+    readonly align?: number;
+}
+/**
+ * A struct or a union. One without members is opaque (declared, not defined); it is completed in place when defined
+ */
+export interface RecordType {
+    readonly kind: 'struct' | 'union';
+    readonly tag?: string;
+    members?: Member[];
+    /**
+     * The alignment its members are capped at (#pragma pack, the packed attribute)
+     */
+    pack?: number;
+    /**
+     * The alignment its aligned attribute asks for, in bytes
+     */
+    align?: number;
+}
+export interface EnumType {
+    readonly kind: 'enum';
+    readonly tag?: string;
+    /**
+     * The integer type holding its values
+     */
+    readonly base: PrimitiveName;
+    readonly values: ReadonlyMap<string, bigint>;
+}
+export interface Parameter {
+    readonly name?: string;
+    readonly type: CType;
+    readonly direction: Direction;
+}
+export interface FunctionType {
+    readonly kind: 'function';
+    readonly result: CType;
+    readonly parameters: readonly Parameter[];
+    readonly variadic: boolean;
+    readonly convention: CallingConvention;
+}
+/**
+ * A C type, as the declarations describe it
+ */
+export type CType = PrimitiveType | PointerType | ArrayType | RecordType | EnumType | FunctionType;
+/**
+ * A function the library exports
+ */
+export interface FunctionDeclaration {
+    readonly name: string;
+    /**
+     * The name of its symbol in the library: its name, or the one of its __asm label
+     */
+    readonly symbol: string;
+    readonly type: FunctionType;
+}
+/**
+ * A variable the library exports
+ */
+export interface VariableDeclaration {
+    readonly name: string;
+    readonly symbol: string;
+    readonly type: CType;
+    readonly constant: boolean;
+}
+/**
+ * What a text of declarations declares
+ */
+export interface Declarations {
+    /**
+     * The typedefs
+     */
+    readonly types: Map<string, CType>;
+    /**
+     * The tags of the structs, unions and enums ("struct timeval")
+     */
+    readonly tags: Map<string, RecordType | EnumType>;
+    readonly functions: Map<string, FunctionDeclaration>;
+    readonly variables: Map<string, VariableDeclaration>;
+    /**
+     * The values of the enumerations, of the static constants and of the macros whose value is an integer
+     */
+    readonly constants: Map<string, bigint>;
+    /**
+     * The macros without arguments (#define): their tokens, empty for the ones that are removed where used (the
+     * markers of exported functions); null for the macros with arguments, which cannot be used
+     */
+    readonly macros: Map<string, MacroToken[] | null>;
+}
+/**
+ * A token of a macro: its kind and its text (and its value, for a number or a character)
+ */
+export interface MacroToken {
+    readonly kind: 'identifier' | 'number' | 'char' | 'string' | 'punctuator';
+    readonly text: string;
+    readonly value?: bigint;
+    readonly float?: boolean;
+}
+/**
+ * An empty set of declarations
+ */
+export declare function emptyDeclarations(): Declarations;
+export declare const VOID: PrimitiveType;
+/**
+ * The size of an arithmetic type, in bytes
+ * @param name
+ * @param platform
+ */
+export declare function primitiveSize(name: PrimitiveName, platform: Platform): number;
+/**
+ * Whether an arithmetic type is signed
+ * @param name
+ * @param platform
+ */
+export declare function primitiveSigned(name: PrimitiveName, platform: Platform): boolean;
+/**
+ * Whether an arithmetic type is an integer
+ * @param name
+ */
+export declare function primitiveInteger(name: PrimitiveName): boolean;
+/**
+ * Whether an integer type is 64-bit on one of the platforms at least: its values are bigints (long is 64-bit but on
+ * Windows, size_t but on 32-bit systems)
+ * @param name
+ */
+export declare function primitiveBig(name: PrimitiveName): boolean;
+/**
+ * A type, as C writes it (for the messages)
+ * @param type
+ */
+export declare function typeText(type: CType): string;

package/dist/cjs/lib/declarations/Types.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOID = void 0;
+exports.emptyDeclarations = emptyDeclarations;
+exports.primitiveSize = primitiveSize;
+exports.primitiveSigned = primitiveSigned;
+exports.primitiveInteger = primitiveInteger;
+exports.primitiveBig = primitiveBig;
+exports.typeText = typeText;
+/**
+ * An empty set of declarations
+ */
+function emptyDeclarations() {
+    return { types: new Map(), tags: new Map(), functions: new Map(), variables: new Map(), constants: new Map(), macros: new Map() };
+}
+exports.VOID = { kind: 'primitive', name: 'void' };
+/**
+ * The size of an arithmetic type, in bytes
+ * @param name
+ * @param platform
+ */
+function primitiveSize(name, platform) {
+    switch (name) {
+        case 'void':
+            return 0;
+        case 'bool':
+        case 'char':
+        case 'schar':
+        case 'uchar':
+        case 'int8':
+        case 'uint8':
+            return 1;
+        case 'short':
+        case 'ushort':
+        case 'int16':
+        case 'uint16':
+        case 'char16':
+            return 2;
+        case 'int':
+        case 'uint':
+        case 'int32':
+        case 'uint32':
+        case 'char32':
+        case 'float':
+            return 4;
+        case 'long':
+        case 'ulong':
+            return platform.longSize;
+        case 'longlong':
+        case 'ulonglong':
+        case 'int64':
+        case 'uint64':
+        case 'double':
+            return 8;
+        case 'size':
+        case 'ssize':
+        case 'intptr':
+        case 'uintptr':
+        case 'ptrdiff':
+            return platform.pointerSize;
+        case 'wchar':
+            return platform.wcharSize;
+    }
+}
+/**
+ * Whether an arithmetic type is signed
+ * @param name
+ * @param platform
+ */
+function primitiveSigned(name, platform) {
+    switch (name) {
+        case 'char':
+            //char is signed but on the ARM systems other than Apple's and Microsoft's (koffi reads it as signed everywhere)
+            return true;
+        case 'schar':
+        case 'short':
+        case 'int':
+        case 'long':
+        case 'longlong':
+        case 'int8':
+        case 'int16':
+        case 'int32':
+        case 'int64':
+        case 'ssize':
+        case 'intptr':
+        case 'ptrdiff':
+        case 'float':
+        case 'double':
+            return true;
+        case 'wchar':
+            return platform.os !== 'win32';
+        default:
+            return false;
+    }
+}
+/**
+ * Whether an arithmetic type is an integer
+ * @param name
+ */
+function primitiveInteger(name) {
+    return name !== 'void' && name !== 'float' && name !== 'double';
+}
+/**
+ * Whether an integer type is 64-bit on one of the platforms at least: its values are bigints (long is 64-bit but on
+ * Windows, size_t but on 32-bit systems)
+ * @param name
+ */
+function primitiveBig(name) {
+    switch (name) {
+        case 'long':
+        case 'ulong':
+        case 'longlong':
+        case 'ulonglong':
+        case 'int64':
+        case 'uint64':
+        case 'size':
+        case 'ssize':
+        case 'intptr':
+        case 'uintptr':
+        case 'ptrdiff':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * A type, as C writes it (for the messages)
+ * @param type
+ */
+function typeText(type) {
+    switch (type.kind) {
+        case 'primitive':
+            return PRIMITIVE_TEXT[type.name];
+        case 'pointer':
+            return `${type.constTarget ? 'const ' : ''}${typeText(type.to)} *`;
+        case 'array':
+            return `${typeText(type.of)}[${type.length}]`;
+        case 'struct':
+        case 'union':
+            return `${type.kind} ${type.tag ?? '(anonymous)'}`;
+        case 'enum':
+            return `enum ${type.tag ?? '(anonymous)'}`;
+        case 'function':
+            return `${typeText(type.result)} (${type.parameters.map((parameter) => typeText(parameter.type)).concat(type.variadic ? ['...'] : []).join(', ')})`;
+    }
+}
+const PRIMITIVE_TEXT = {
+    void: 'void',
+    bool: 'bool',
+    char: 'char',
+    schar: 'signed char',
+    uchar: 'unsigned char',
+    short: 'short',
+    ushort: 'unsigned short',
+    int: 'int',
+    uint: 'unsigned int',
+    long: 'long',
+    ulong: 'unsigned long',
+    longlong: 'long long',
+    ulonglong: 'unsigned long long',
+    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: 'ssize_t',
+    intptr: 'intptr_t',
+    uintptr: 'uintptr_t',
+    ptrdiff: 'ptrdiff_t',
+    char16: 'char16_t',
+    char32: 'char32_t',
+    wchar: 'wchar_t',
+    float: 'float',
+    double: 'double'
+};

package/dist/cjs/lib/generator/CText.d.ts

@@ -0,0 +1,14 @@
+import type { Token } from '../declarations/Lexer.js';
+/**
+ * The tokens of a declaration without what changes nothing of what it declares: the attributes but packed and aligned,
+ * the __declspec but align, the qualifiers the parser ignores
+ * @param tokens
+ */
+export declare function prunedTokens(tokens: readonly Token[]): Token[];
+/**
+ * A declaration written as C, one member of a struct or a value of an enum by line
+ * @param tokens Its tokens.
+ * @param indent The indentation of a level.
+ * @returns Its lines.
+ */
+export declare function declarationText(tokens: readonly Token[], indent?: string): string[];

package/dist/cjs/lib/generator/CText.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prunedTokens = prunedTokens;
+exports.declarationText = declarationText;
+/**
+ * The words that change nothing of what a declaration declares, removed from the declarations written
+ */
+const NOISE = new Set([
+    '__extension__', '__restrict', '__restrict__', 'restrict', '_Nullable', '_Nonnull', '_Null_unspecified', '__nullable', '__nonnull',
+    '__null_unspecified', '_Nullable_result', '__ptr32', '__ptr64', '__unaligned', '__w64'
+]);
+/**
+ * The words that can follow the parenthesis of a declarator of a pointer to a function: void (*f)(void), void (__stdcall *f)(void)
+ */
+const DECLARATOR_STARTS = new Set(['*', '__stdcall', '_stdcall', '__cdecl', '_cdecl', '__fastcall', '_fastcall', '__thiscall', '__vectorcall', '__clrcall']);
+/**
+ * The end of the balanced brackets opened at an index: the index of the closing one
+ * @param tokens
+ * @param open
+ */
+function closing(tokens, open) {
+    let depth = 0;
+    for (let index = open; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token.kind !== 'punctuator')
+            continue;
+        if (token.text === '(' || token.text === '[' || token.text === '{')
+            depth++;
+        else if ((token.text === ')' || token.text === ']' || token.text === '}') && --depth === 0)
+            return index;
+    }
+    return tokens.length - 1;
+}
+/**
+ * The tokens of a declaration without what changes nothing of what it declares: the attributes but packed and aligned,
+ * the __declspec but align, the qualifiers the parser ignores
+ * @param tokens
+ */
+function prunedTokens(tokens) {
+    const kept = [];
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token.kind === 'identifier' && NOISE.has(token.text))
+            continue;
+        const attribute = token.kind === 'identifier' && (token.text === '__attribute__' || token.text === '__attribute' || token.text === '__declspec');
+        if (attribute && tokens[index + 1]?.text === '(') {
+            const end = closing(tokens, index + 1);
+            const inner = tokens.slice(index + 2, end).map((part) => part.text.replace(/^__|__$/g, ''));
+            const meaningful = token.text === '__declspec' ? inner.includes('align') : inner.includes('packed') || inner.includes('aligned');
+            if (meaningful)
+                kept.push(...tokens.slice(index, end + 1));
+            index = end;
+            continue;
+        }
+        kept.push(token);
+    }
+    return kept;
+}
+/**
+ * The text of a token as C writes it
+ * @param token
+ */
+function textOf(token) {
+    if (token.kind === 'string')
+        return token.source ?? JSON.stringify(token.text);
+    if (token.kind === 'pragma')
+        return `#pragma ${token.text}`;
+    return token.text;
+}
+/**
+ * A declaration written as C, one member of a struct or a value of an enum by line
+ * @param tokens Its tokens.
+ * @param indent The indentation of a level.
+ * @returns Its lines.
+ */
+function declarationText(tokens, indent = '    ') {
+    const lines = [];
+    let line = '';
+    //The braces open: whether each one is the body of an enum
+    const braces = [];
+    let parens = 0;
+    const breakLine = () => {
+        if (line.trim())
+            lines.push(line.replace(/\s+$/, ''));
+        line = indent.repeat(braces.length);
+    };
+    let previous;
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        const text = textOf(token);
+        if (token.kind === 'pragma') {
+            breakLine();
+            line += text;
+            breakLine();
+            previous = undefined;
+            continue;
+        }
+        const punctuator = token.kind === 'punctuator' ? token.text : undefined;
+        if (punctuator === '{') {
+            const enumBody = tokens.slice(Math.max(0, index - 2), index).some((part) => part.kind === 'identifier' && part.text === 'enum');
+            line += `${line.trim() ? ' ' : ''}{`;
+            braces.push(enumBody);
+            breakLine();
+            previous = token;
+            continue;
+        }
+        if (punctuator === '}') {
+            braces.pop();
+            breakLine();
+            line += '}';
+            previous = token;
+            continue;
+        }
+        if (punctuator === '(' || punctuator === '[')
+            parens++;
+        if (punctuator === ')' || punctuator === ']')
+            parens--;
+        const glued = !previous
+            || [',', ';', ')', ']', '['].includes(punctuator ?? '')
+            || (previous.kind === 'punctuator' && ['(', '[', '*', '~', '!'].includes(previous.text))
+            || (punctuator === '(' && (previous.kind === 'identifier' || previous.text === ')') && !DECLARATOR_STARTS.has(tokens[index + 1]?.text ?? ''))
+            || !line.trim();
+        line += `${glued ? '' : ' '}${text}`;
+        previous = token;
+        //A member of a struct, a value of an enum: one by line
+        if (braces.length && !parens && (punctuator === ';' || (punctuator === ',' && braces[braces.length - 1]))) {
+            breakLine();
+            previous = undefined;
+        }
+    }
+    breakLine();
+    return lines;
+}