@gtkx/codegen 1.0.0-rc.1 → 1.0.0-rc.3

package/src/khronos/model.ts

@@ -1,6 +1,6 @@
 import { collectText, nodeAttr, nodeChildren, nodeTag, type OrderedNode, parseRegistryFile } from "./parse.js";
 
-export type GlParam = {
+type GlParam = {
     name: string;
     cType: string;
     group?: string;
@@ -8,26 +8,26 @@ export type GlParam = {
     objectClass?: string;
 };
 
-export type GlCommand = {
+type GlCommand = {
     name: string;
     returnCType: string;
     returnGroup?: string;
     params: GlParam[];
 };
 
-export type GlEnum = {
+type GlEnum = {
     name: string;
     value: string;
     groups: string[];
 };
 
-export type GlInterfaceBlock = {
+type GlInterfaceBlock = {
     profile?: string;
     commands: string[];
     enums: string[];
 };
 
-export type GlFeature = {
+type GlFeature = {
     api: string;
     name: string;
     number: number;
@@ -35,7 +35,7 @@ export type GlFeature = {
     removes: GlInterfaceBlock[];
 };
 
-export type GlRegistry = {
+type GlRegistry = {
     commands: Map<string, GlCommand>;
     enums: GlEnum[];
     features: GlFeature[];
@@ -44,18 +44,25 @@ export type GlRegistry = {
 const NAME_TAG = "name";
 const SKIP_IN_C_TYPE: Set<string> = new Set([NAME_TAG, "comment"]);
 
-const normalizeWhitespace = (text: string): string => text.replace(/\s+/g, " ").trim();
+const normalizeWhitespace = (text: string): string => text.replaceAll(/\s+/g, " ").trim();
 
 const childNamed = (node: OrderedNode, tag: string): OrderedNode | undefined => {
     for (const child of nodeChildren(node)) {
-        if (nodeTag(child) === tag) return child;
+        if (nodeTag(child) === tag) {
+            return child;
+        }
     }
+
     return undefined;
 };
 
 const elementName = (node: OrderedNode): string => {
     const nameChild = childNamed(node, NAME_TAG);
-    if (nameChild === undefined) return "";
+
+    if (nameChild === undefined) {
+        return "";
+    }
+
     return normalizeWhitespace(collectText(nameChild, new Set()));
 };
 
@@ -64,103 +71,197 @@ const parseParam = (node: OrderedNode): GlParam => {
         name: elementName(node),
         cType: normalizeWhitespace(collectText(node, SKIP_IN_C_TYPE)),
     };
+
     const group = nodeAttr(node, "group");
     const len = nodeAttr(node, "len");
     const objectClass = nodeAttr(node, "class");
+
     return {
         ...param,
-        ...(group !== undefined ? { group } : {}),
-        ...(len !== undefined ? { len } : {}),
-        ...(objectClass !== undefined ? { objectClass } : {}),
+        ...((group !== undefined) && { group }),
+        ...((len !== undefined) && { len }),
+        ...((objectClass !== undefined) && { objectClass }),
     };
 };
 
 const parseCommand = (node: OrderedNode): GlCommand | undefined => {
     const proto = childNamed(node, "proto");
-    if (proto === undefined) return undefined;
+
+    if (proto === undefined) {
+        return undefined;
+    }
+
     const params: GlParam[] = [];
+
     for (const child of nodeChildren(node)) {
-        if (nodeTag(child) === "param") params.push(parseParam(child));
+        if (nodeTag(child) === "param") {
+            params.push(parseParam(child));
+        }
     }
+
     const returnGroup = nodeAttr(proto, "group");
+
     return {
         name: elementName(proto),
         returnCType: normalizeWhitespace(collectText(proto, SKIP_IN_C_TYPE)),
-        ...(returnGroup !== undefined ? { returnGroup } : {}),
+        ...((returnGroup !== undefined) && { returnGroup }),
         params,
     };
 };
 
+const parseEnum = (child: OrderedNode): GlEnum | undefined => {
+    if (nodeTag(child) !== "enum") {
+        return undefined;
+    }
+
+    const name = nodeAttr(child, "name");
+    const value = nodeAttr(child, "value");
+
+    if (name === undefined || value === undefined) {
+        return undefined;
+    }
+
+    const group = nodeAttr(child, "group");
+
+    return {
+        name,
+        value,
+        groups: group === undefined ? [] : group.split(",").map((part) => part.trim()),
+    };
+};
+
 const parseEnums = (node: OrderedNode, into: GlEnum[]): void => {
     for (const child of nodeChildren(node)) {
-        if (nodeTag(child) !== "enum") continue;
-        const name = nodeAttr(child, "name");
-        const value = nodeAttr(child, "value");
-        if (name === undefined || value === undefined) continue;
-        const group = nodeAttr(child, "group");
-        into.push({
-            name,
-            value,
-            groups: group === undefined ? [] : group.split(",").map((part) => part.trim()),
-        });
+        const parsed = parseEnum(child);
+
+        if (parsed !== undefined) {
+            into.push(parsed);
+        }
+    }
+};
+
+const collectInterfaceMember = (child: OrderedNode, commands: string[], enums: string[]): void => {
+    const name = nodeAttr(child, "name");
+
+    if (name === undefined) {
+        return;
+    }
+
+    const tag = nodeTag(child);
+
+    if (tag === "command") {
+        commands.push(name);
+    } else if (tag === "enum") {
+        enums.push(name);
     }
 };
 
 const parseInterfaceBlock = (node: OrderedNode): GlInterfaceBlock => {
     const commands: string[] = [];
     const enums: string[] = [];
+
     for (const child of nodeChildren(node)) {
-        const name = nodeAttr(child, "name");
-        if (name === undefined) continue;
-        const tag = nodeTag(child);
-        if (tag === "command") commands.push(name);
-        else if (tag === "enum") enums.push(name);
+        collectInterfaceMember(child, commands, enums);
     }
+
     const profile = nodeAttr(node, "profile");
+
     return {
-        ...(profile !== undefined ? { profile } : {}),
+        ...((profile !== undefined) && { profile }),
         commands,
         enums,
     };
 };
 
+const collectFeatureBlock = (child: OrderedNode, requires: GlInterfaceBlock[], removes: GlInterfaceBlock[]): void => {
+    const tag = nodeTag(child);
+
+    if (tag === "require") {
+        requires.push(parseInterfaceBlock(child));
+    } else if (tag === "remove") {
+        removes.push(parseInterfaceBlock(child));
+    }
+};
+
 const parseFeature = (node: OrderedNode): GlFeature | undefined => {
     const api = nodeAttr(node, "api");
     const name = nodeAttr(node, "name");
     const number = nodeAttr(node, "number");
-    if (api === undefined || name === undefined || number === undefined) return undefined;
+
+    if (api === undefined || name === undefined || number === undefined) {
+        return undefined;
+    }
+
     const requires: GlInterfaceBlock[] = [];
     const removes: GlInterfaceBlock[] = [];
+
     for (const child of nodeChildren(node)) {
-        const tag = nodeTag(child);
-        if (tag === "require") requires.push(parseInterfaceBlock(child));
-        else if (tag === "remove") removes.push(parseInterfaceBlock(child));
+        collectFeatureBlock(child, requires, removes);
+    }
+
+    return { api, name, number: Number(number), requires, removes };
+};
+
+const addCommand = (child: OrderedNode, into: Map<string, GlCommand>): void => {
+    if (nodeTag(child) !== "command") {
+        return;
+    }
+
+    const command = parseCommand(child);
+
+    if (command !== undefined && command.name.length > 0) {
+        into.set(command.name, command);
     }
-    return { api, name, number: Number.parseFloat(number), requires, removes };
 };
 
 const parseCommandsSection = (section: OrderedNode, into: Map<string, GlCommand>): void => {
     for (const child of nodeChildren(section)) {
-        if (nodeTag(child) !== "command") continue;
-        const command = parseCommand(child);
-        if (command !== undefined && command.name.length > 0) into.set(command.name, command);
+        addCommand(child, into);
+    }
+};
+
+const parseSection = (section: OrderedNode, registry: GlRegistry): void => {
+    const tag = nodeTag(section);
+
+    if (tag === "commands") {
+        parseCommandsSection(section, registry.commands);
+
+        return;
+    }
+
+    if (tag === "enums") {
+        parseEnums(section, registry.enums);
+
+        return;
+    }
+
+    if (tag !== "feature") {
+        return;
+    }
+
+    const feature = parseFeature(section);
+
+    if (feature !== undefined) {
+        registry.features.push(feature);
     }
 };
 
-export const loadGlRegistry = (path: string): GlRegistry => {
-    const commands = new Map<string, GlCommand>();
-    const enums: GlEnum[] = [];
-    const features: GlFeature[] = [];
+const loadGlRegistry = (path: string): GlRegistry => {
+    const registry: GlRegistry = { commands: new Map<string, GlCommand>(), enums: [], features: [] };
+
     for (const section of parseRegistryFile(path)) {
-        const tag = nodeTag(section);
-        if (tag === "commands") {
-            parseCommandsSection(section, commands);
-        } else if (tag === "enums") {
-            parseEnums(section, enums);
-        } else if (tag === "feature") {
-            const feature = parseFeature(section);
-            if (feature !== undefined) features.push(feature);
-        }
+        parseSection(section, registry);
     }
-    return { commands, enums, features };
+
+    return registry;
+};
+
+export {
+    loadGlRegistry,
+    type GlParam,
+    type GlCommand,
+    type GlEnum,
+    type GlInterfaceBlock,
+    type GlFeature,
+    type GlRegistry,
 };

package/src/khronos/modules.ts

@@ -1,75 +1,115 @@
 import { sortStrings, sortStringsBy } from "@gtkx/utils";
-import { ModuleBuilder } from "../writer/module.js";
 import type { GlEnum } from "./model.js";
-import { GL_SCALARS } from "./plan.js";
 import type { RenderedCommand } from "./render.js";
+import { ModuleBuilder } from "../writer/module.js";
+import { GL_SCALARS } from "./plan.js";
 
-const LIB_CONSTANT = `export const LIB = "libGL.so.1";`;
+const LIB_CONSTANT = "export const LIB = \"libGL.so.1\";";
 
 const GENERATED_HEADER = `/**
  * GENERATED FILE: do not edit.
  */`;
 
-export const renderEnumsModule = (
+const TS_PRIMITIVES: Set<string> = new Set(["boolean", "string", "void", "number"]);
+
+const quotedGroupList = (groups: string[]): string => groups.map((group) => `\`${group}\``).join(", ");
+
+const renderEnumsModule = (
     tokens: { token: GlEnum; exportName: string; literal: string; feature: string }[],
 ): string => {
     const builder = new ModuleBuilder();
+
     for (const { token, exportName, literal, feature } of tokens) {
-        const groupNote = token.groups.length > 0 ? ` Groups: ${token.groups.map((g) => `\`${g}\``).join(", ")}.` : "";
+        const groupNote = token.groups.length > 0 ? ` Groups: ${quotedGroupList(token.groups)}.` : "";
+
         builder.appendDeclaration(
-            `/** \`${token.name}\`, provided by \`${feature}\`.${groupNote} */\nexport const ${exportName} = ${literal};`,
+            `/** \`${token.name}\`, provided by \`${feature}\`.${groupNote} */\n` +
+            `export const ${exportName} = ${literal};`,
         );
     }
+
     return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
 };
 
-export const renderTypesModule = (groupAliases: Map<string, string>): string => {
+const renderTypesModule = (groupAliases: Map<string, string>): string => {
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/native", "ExternalObject", true);
     builder.imports.addNamed("@gtkx/native", "Handle", true);
+
     builder.appendDeclaration(
-        `/** An opaque \`GLsync\` fence handle. */\nexport type GLsync = ExternalObject<Handle>;`,
+        "/** An opaque `GLsync` fence handle. */\nexport type GLsync = ExternalObject<Handle>;",
     );
+
     builder.appendDeclaration(
-        `/** An opaque native pointer handle (e.g. a \`glMapBufferRange\` mapping). */\nexport type GLpointer = ExternalObject<Handle>;`,
+        "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
+        "export type GLpointer = ExternalObject<Handle>;",
     );
-    const seen = new Set<string>();
+
+    const seen: Set<string> = new Set();
+
     for (const scalar of GL_SCALARS.values()) {
-        if (seen.has(scalar.tsAlias)) continue;
+        if (seen.has(scalar.tsAlias)) {
+            continue;
+        }
+
         seen.add(scalar.tsAlias);
+
         builder.appendDeclaration(
             `/** The C \`${scalar.tsAlias}\` scalar. */\nexport type ${scalar.tsAlias} = number;`,
         );
     }
-    for (const [group, base] of sortStringsBy(groupAliases.entries(), ([key]) => key)) {
+
+    const sortedAliases = sortStringsBy(groupAliases.entries(), ([key]) => key);
+
+    for (const [group, base] of sortedAliases) {
         builder.appendDeclaration(
-            `/** Registry enum group \`${group}\`; open and documentation-only, any \`${base}\` value is accepted. */\nexport type ${group} = ${base};`,
+            `/** Registry enum group \`${group}\`; open and documentation-only, ` +
+            `any \`${base}\` value is accepted. */\nexport type ${group} = ${base};`,
         );
     }
+
     return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
 };
 
-const TS_PRIMITIVES: Set<string> = new Set(["boolean", "string", "void", "number"]);
+const appendTypeImports = (builder: ModuleBuilder, usedTypes: Set<string>): void => {
+    for (const alias of sortStrings(usedTypes)) {
+        if (TS_PRIMITIVES.has(alias)) {
+            continue;
+        }
+
+        builder.imports.addNamed("./types.js", alias, true);
+    }
+};
 
-export const renderCommandsModule = (
+const appendCommandBindings = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {
+    for (const command of commands) {
+        if (command.binding !== undefined) {
+            builder.appendBinding(command.binding, command.binding);
+        }
+    }
+};
+
+const appendCommandDeclarations = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {
+    for (const command of commands) {
+        builder.appendDeclaration(command.declaration);
+    }
+};
+
+const renderCommandsModule = (
     rendered: RenderedCommand[],
     singulars: RenderedCommand[],
     usedTypes: Set<string>,
 ): string => {
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/runtime", "t");
-    for (const alias of sortStrings(usedTypes)) {
-        if (TS_PRIMITIVES.has(alias)) continue;
-        builder.imports.addNamed("./types.js", alias, true);
-    }
+    appendTypeImports(builder, usedTypes);
     builder.appendBinding(LIB_CONSTANT);
-    for (const command of rendered) {
-        if (command.binding !== undefined) builder.appendBinding(command.binding, command.binding);
-    }
-    for (const singular of singulars) {
-        if (singular.binding !== undefined) builder.appendBinding(singular.binding, singular.binding);
-    }
-    for (const command of rendered) builder.appendDeclaration(command.declaration);
-    for (const singular of singulars) builder.appendDeclaration(singular.declaration);
+    appendCommandBindings(builder, rendered);
+    appendCommandBindings(builder, singulars);
+    appendCommandDeclarations(builder, rendered);
+    appendCommandDeclarations(builder, singulars);
+
     return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
 };
+
+export { renderEnumsModule, renderTypesModule, renderCommandsModule };

package/src/khronos/param-pair.ts

@@ -0,0 +1,14 @@
+import type { GlParam } from "./model.js";
+import type { CommandPlan, ParamPlan } from "./plan.js";
+
+type ParamPair = {
+    paramPlan: ParamPlan | undefined;
+    param: GlParam | undefined;
+};
+
+const paramPairAt = (plan: CommandPlan & { ok: true }, index: number): ParamPair => ({
+    paramPlan: plan.params[index],
+    param: plan.command.params[index],
+});
+
+export { paramPairAt };

package/src/khronos/parse.ts

@@ -1,66 +1,86 @@
 import { readFileSync } from "node:fs";
-import { XMLParser } from "fast-xml-parser";
+import { createXmlParser } from "../xml.js";
 
-export type OrderedNode = { [key: string]: unknown };
+type OrderedNode = Record<string, unknown>;
 
 const ATTRIBUTES_KEY = ":@";
 const TEXT_KEY = "#text";
 
-const PARSER = new XMLParser({
-    ignoreAttributes: false,
-    attributeNamePrefix: "@_",
-    parseAttributeValue: false,
-    parseTagValue: false,
+const PARSER = createXmlParser({
     trimValues: false,
     preserveOrder: true,
 });
 
-export const parseRegistryFile = (path: string): OrderedNode[] => {
-    const xml = readFileSync(path, "utf-8");
+const parseRegistryFile = (path: string): OrderedNode[] => {
+    const xml = readFileSync(path, "utf8");
     const documentNodes = PARSER.parse(xml) as OrderedNode[];
+
     for (const node of documentNodes) {
-        if (nodeTag(node) === "registry") return nodeChildren(node);
+        if (nodeTag(node) === "registry") {
+            return nodeChildren(node);
+        }
     }
+
     throw new Error(`No <registry> root element found in ${path}`);
 };
 
-export const nodeTag = (node: OrderedNode): string => {
+const nodeTag = (node: OrderedNode): string => {
     for (const key of Object.keys(node)) {
-        if (key !== ATTRIBUTES_KEY && key !== TEXT_KEY) return key;
+        if (key !== ATTRIBUTES_KEY && key !== TEXT_KEY) {
+            return key;
+        }
     }
+
     return TEXT_KEY;
 };
 
-export const nodeChildren = (node: OrderedNode): OrderedNode[] => {
+const nodeChildren = (node: OrderedNode): OrderedNode[] => {
     const tag = nodeTag(node);
-    if (tag === TEXT_KEY) return [];
+
+    if (tag === TEXT_KEY) {
+        return [];
+    }
+
     const children = node[tag];
+
     return Array.isArray(children) ? (children as OrderedNode[]) : [];
 };
 
-export const nodeAttr = (node: OrderedNode, name: string): string | undefined => {
+const nodeAttr = (node: OrderedNode, name: string): string | undefined => {
     const attributes = node[ATTRIBUTES_KEY];
-    if (typeof attributes !== "object" || attributes === null) return undefined;
+
+    if (typeof attributes !== "object" || attributes === null) {
+        return undefined;
+    }
+
     const value = (attributes as Record<string, unknown>)[`@_${name}`];
+
     return typeof value === "string" ? value : undefined;
 };
 
 const nodeText = (node: OrderedNode): string | undefined => {
     const value = node[TEXT_KEY];
+
     return typeof value === "string" ? value : undefined;
 };
 
-export const collectText = (node: OrderedNode, skipTags: Set<string>): string => {
+const collectText = (node: OrderedNode, skipTags: Set<string>): string => {
     let text = "";
+
     for (const child of nodeChildren(node)) {
         const childText = nodeText(child);
+
         if (childText !== undefined) {
             text += childText;
             continue;
         }
+
         if (!skipTags.has(nodeTag(child))) {
             text += collectText(child, skipTags);
         }
     }
+
     return text;
 };
+
+export { parseRegistryFile, nodeTag, nodeChildren, nodeAttr, collectText, type OrderedNode };