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

package/src/khronos/args.ts

@@ -1,4 +1,6 @@
 import { toCamelIdentifier } from "@gtkx/utils";
+import type { GlCommand, GlParam } from "./model.js";
+import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
 import {
     tArray,
     tBoolean,
@@ -10,31 +12,16 @@ import {
     tString,
     tUint64,
 } from "../analysis/descriptor.js";
-import type { GlCommand } from "./model.js";
-import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
-
-export const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
-    group !== undefined && scalar.groupBearing === true ? group : scalar.tsAlias;
-
-const paramIndexByName = (command: GlCommand, name: string): number => {
-    const index = command.params.findIndex((param) => param.name === name);
-    if (index < 0) throw new Error(`Command ${command.name} has no parameter named ${name}`);
-    return index;
-};
-
-const arrayInTsType = (scalar: GlScalar, group: string | undefined): string => {
-    const element = scalarAliasOrGroup(scalar, group);
-    return scalar.viewType === undefined ? `${element}[]` : `${element}[] | ${scalar.viewType}`;
-};
+import { paramPairAt } from "./param-pair.js";
 
-export type InArg = {
+type InArg = {
     out: false;
     name: string;
     tsType: string;
     descriptor: string;
 };
 
-export type OutArg = {
+type OutArg = {
     out: true;
     cellName: string;
     seed: string;
@@ -44,6 +31,16 @@ export type OutArg = {
 };
 
 type PlannedArg = InArg | OutArg;
+type OutArgCell = Pick<OutArg, "out" | "cellName" | "paramIndex">;
+type OutArgFields = Pick<OutArg, "seed" | "tsType" | "descriptor">;
+
+type OutArgFieldsOptions = {
+    command: GlCommand;
+    plan: ParamPlan;
+    param: GlParam;
+    cellName: string;
+    track: (alias: string) => string;
+};
 
 type BuildArgOptions = {
     command: GlCommand;
@@ -52,6 +49,27 @@ type BuildArgOptions = {
     outIndex: number;
 };
 
+const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fixed-out", "string-out"]);
+
+const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
+    group !== undefined && scalar.groupBearing === true ? group : scalar.tsAlias;
+
+const paramIndexByName = (command: GlCommand, name: string): number => {
+    const index = command.params.findIndex((param) => param.name === name);
+
+    if (index === -1) {
+        throw new Error(`Command ${command.name} has no parameter named ${name}`);
+    }
+
+    return index;
+};
+
+const arrayInTsType = (scalar: GlScalar, group: string | undefined): string => {
+    const element = scalarAliasOrGroup(scalar, group);
+
+    return scalar.viewType === undefined ? `${element}[]` : `${element}[] | ${scalar.viewType}`;
+};
+
 const inArg = (name: string, tsType: string, descriptor: string): InArg => ({
     out: false,
     name,
@@ -62,141 +80,192 @@ const inArg = (name: string, tsType: string, descriptor: string): InArg => ({
 const buildInArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): InArg => {
     const { command, index, plan } = options;
     const param = command.params[index];
-    if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${command.name}`);
+
+    if (param === undefined) {
+        throw new Error(`Parameter index ${String(index)} out of range on ${command.name}`);
+    }
+
     switch (plan.kind) {
-        case "scalar":
+        case "scalar": {
             return inArg(name, track(scalarAliasOrGroup(plan.scalar, param.group)), plan.scalar.descriptor);
-        case "boolean":
+        }
+        case "boolean": {
             return inArg(name, "boolean", tBoolean);
-        case "sync":
+        }
+        case "sync": {
             return inArg(name, track("GLsync"), tInlineStruct());
-        case "string-in":
+        }
+        case "string-in": {
             return inArg(name, "string", tString("borrowed"));
-        case "string-array-in":
+        }
+        case "string-array-in": {
             return inArg(name, "string[]", tArray(tString("borrowed")));
+        }
         case "array-in": {
             track(scalarAliasOrGroup(plan.scalar, param.group));
+
             return inArg(name, arrayInTsType(plan.scalar, param.group), tArray(plan.scalar.descriptor));
         }
-        case "buffer":
+        case "buffer": {
             return inArg(name, `ArrayBufferView | ${track("GLintptr")} | null`, tBuffer);
-        case "byte-offset":
+        }
+        case "byte-offset": {
             return inArg(name, track("GLintptr"), tUint64);
-        case "byte-offset-array":
+        }
+        case "byte-offset-array": {
             return inArg(name, `${track("GLintptr")}[]`, tArray(tUint64));
-        default:
+        }
+        case "ref-array-out":
+        case "ref-fixed-out":
+        case "ref-out":
+        case "string-out": {
             throw new Error(`Plan kind ${plan.kind} is not an input parameter`);
+        }
     }
 };
 
-const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string): OutArg => {
-    const { command, index, plan, outIndex } = options;
-    const param = command.params[index];
-    if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${command.name}`);
-    const cellName = `out${outIndex}`;
+const outArgFields = (options: OutArgFieldsOptions): OutArgFields => {
+    const { command, plan, param, cellName, track } = options;
+
     switch (plan.kind) {
-        case "ref-out":
+        case "ref-out": {
             return {
-                out: true,
-                cellName,
                 seed: `const ${cellName} = { value: 0 };`,
                 tsType: track(scalarAliasOrGroup(plan.scalar, param.group)),
                 descriptor: tRef(plan.scalar.descriptor),
-                paramIndex: index,
             };
+        }
         case "ref-array-out": {
             const sizeIndex = paramIndexByName(command, plan.lenParamName);
             const lenIdentifier = toCamelIdentifier(plan.lenParamName);
+
             return {
-                out: true,
-                cellName,
                 seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
                 tsType: `${track(plan.scalar.tsAlias)}[]`,
                 descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
-                paramIndex: index,
             };
         }
-        case "ref-fixed-out":
+        case "ref-fixed-out": {
             return {
-                out: true,
-                cellName,
-                seed: `const ${cellName} = { value: new Array<number>(${plan.length}).fill(0) };`,
+                seed: `const ${cellName} = { value: new Array<number>(${String(plan.length)}).fill(0) };`,
                 tsType: `${track(plan.scalar.tsAlias)}[]`,
                 descriptor: tRef(tFixedArray(plan.scalar.descriptor, plan.length)),
-                paramIndex: index,
             };
-        case "string-out":
+        }
+        case "string-out": {
             return {
-                out: true,
-                cellName,
                 seed: `const ${cellName} = { value: "" };`,
                 tsType: "string",
                 descriptor: tRef(tString("borrowed", toCamelIdentifier(plan.lenParamName))),
-                paramIndex: index,
             };
-        default:
+        }
+        case "array-in":
+        case "boolean":
+        case "buffer":
+        case "byte-offset":
+        case "byte-offset-array":
+        case "scalar":
+        case "string-array-in":
+        case "string-in":
+        case "sync": {
             throw new Error(`Plan kind ${plan.kind} is not an output parameter`);
+        }
     }
 };
 
-const isOutPlan = (plan: ParamPlan): boolean =>
-    plan.kind === "ref-out" ||
-    plan.kind === "ref-array-out" ||
-    plan.kind === "ref-fixed-out" ||
-    plan.kind === "string-out";
+const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string): OutArg => {
+    const { command, index, plan, outIndex } = options;
+    const param = command.params[index];
 
-export const trackInto =
+    if (param === undefined) {
+        throw new Error(`Parameter index ${String(index)} out of range on ${command.name}`);
+    }
+
+    const cellName = `out${String(outIndex)}`;
+    const cell: OutArgCell = { out: true, cellName, paramIndex: index };
+
+    return { ...cell, ...outArgFields({ command, plan, param, cellName, track }) };
+};
+
+const isOutPlan = (plan: ParamPlan): boolean => OUT_PLAN_KINDS.has(plan.kind);
+const isInArg = (arg: PlannedArg): arg is InArg => !arg.out;
+const isOutArg = (arg: PlannedArg): arg is OutArg => arg.out;
+
+const buildArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): PlannedArg =>
+    isOutPlan(options.plan) ? buildOutArg(options, track) : buildInArg(options, name, track);
+
+const trackInto =
     (usedTypes: Set<string>) =>
-    (alias: string): string => {
-        usedTypes.add(alias);
-        return alias;
-    };
+        (alias: string): string => {
+            usedTypes.add(alias);
 
-export const planArgs = (
+            return alias;
+        };
+
+const planArgs = (
     plan: CommandPlan & { ok: true },
     usedTypes: Set<string>,
 ): { args: PlannedArg[]; ins: InArg[]; outs: OutArg[] } => {
     const track = trackInto(usedTypes);
     const args: PlannedArg[] = [];
-    const ins: InArg[] = [];
-    const outs: OutArg[] = [];
-    plan.params.forEach((paramPlan, index) => {
+
+    for (const [index, paramPlan] of plan.params.entries()) {
         const param = plan.command.params[index];
-        if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${plan.command.name}`);
+
+        if (param === undefined) {
+            throw new Error(`Parameter index ${String(index)} out of range on ${plan.command.name}`);
+        }
+
         const options: BuildArgOptions = {
             command: plan.command,
             index,
             plan: paramPlan,
-            outIndex: outs.length,
+            outIndex: args.filter(isOutArg).length,
         };
-        if (isOutPlan(paramPlan)) {
-            const arg = buildOutArg(options, track);
-            args.push(arg);
-            outs.push(arg);
-        } else {
-            const arg = buildInArg(options, toCamelIdentifier(param.name), track);
-            args.push(arg);
-            ins.push(arg);
-        }
-    });
-    return { args, ins, outs };
+
+        args.push(buildArg(options, toCamelIdentifier(param.name), track));
+    }
+
+    return { args, ins: args.filter(isInArg), outs: args.filter(isOutArg) };
 };
 
-export const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<string>): InArg[] | undefined => {
+const scalarPrefixArg = (
+    plan: CommandPlan & { ok: true },
+    index: number,
+    track: (alias: string) => string,
+): InArg | undefined => {
+    const { paramPlan, param } = paramPairAt(plan, index);
+
+    if (param === undefined) {
+        return undefined;
+    }
+
+    if (paramPlan?.kind !== "scalar") {
+        return undefined;
+    }
+
+    return buildInArg(
+        { command: plan.command, index, plan: paramPlan, outIndex: 0 },
+        toCamelIdentifier(param.name),
+        track,
+    );
+};
+
+const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<string>): InArg[] | undefined => {
     const track = trackInto(usedTypes);
     const prefix: InArg[] = [];
+
     for (let index = 0; index < plan.params.length - 2; index++) {
-        const paramPlan = plan.params[index];
-        const param = plan.command.params[index];
-        if (param === undefined) return undefined;
-        if (paramPlan === undefined || paramPlan.kind !== "scalar") return undefined;
-        prefix.push(
-            buildInArg(
-                { command: plan.command, index, plan: paramPlan, outIndex: 0 },
-                toCamelIdentifier(param.name),
-                track,
-            ),
-        );
+        const arg = scalarPrefixArg(plan, index, track);
+
+        if (arg === undefined) {
+            return undefined;
+        }
+
+        prefix.push(arg);
     }
+
     return prefix;
 };
+
+export { scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };

package/src/khronos/jsdoc.ts

@@ -3,55 +3,90 @@ import type { InArg, OutArg } from "./args.js";
 import type { GlCommand } from "./model.js";
 import type { ReturnPlan } from "./plan.js";
 
+type CommandJsDocOptions = {
+    command: GlCommand;
+    feature: string;
+    ins: InArg[];
+    outs: OutArg[];
+    returnPlan: ReturnPlan;
+};
+
+type SingularJsDocOptions = {
+    commandName: string;
+    feature: string;
+    summary: string;
+    body: string[];
+};
+
 const REFPAGES_BASE = "https://registry.khronos.org/OpenGL-Refpages/gl4/html";
 
 const formatPrototype = (command: GlCommand): string => {
     const params = command.params
         .map((param) => (param.cType.endsWith("*") ? `${param.cType}${param.name}` : `${param.cType} ${param.name}`))
         .join(", ");
+
     return `${command.returnCType} ${command.name}(${params})`;
 };
 
-export const inParamDocLine = (command: GlCommand, arg: InArg): string => {
+const inParamDocLine = (command: GlCommand, arg: InArg): string => {
     const param = command.params.find((candidate) => toCamelIdentifier(candidate.name) === arg.name);
-    if (param === undefined) return ` * @param ${arg.name}`;
+
+    if (param === undefined) {
+        return ` * @param ${arg.name}`;
+    }
+
     const notes: string[] = [`\`${param.cType}\``];
-    if (param.group !== undefined) notes.push(`group \`${param.group}\``);
-    if (param.len !== undefined) notes.push(`length \`${param.len}\``);
-    if (param.objectClass !== undefined) notes.push(`object class \`${param.objectClass}\``);
+
+    if (param.group !== undefined) {
+        notes.push(`group \`${param.group}\``);
+    }
+
+    if (param.len !== undefined) {
+        notes.push(`length \`${param.len}\``);
+    }
+
+    if (param.objectClass !== undefined) {
+        notes.push(`object class \`${param.objectClass}\``);
+    }
+
     return ` * @param ${arg.name} - ${notes.join(", ")}`;
 };
 
+const outMember = (command: GlCommand, out: OutArg): string => {
+    const param = command.params[out.paramIndex];
+
+    if (param === undefined) {
+        throw new Error(`Output parameter index ${String(out.paramIndex)} out of range on ${command.name}`);
+    }
+
+    return `\`${param.name}\` (\`${param.cType}\`)`;
+};
+
 const returnsDocLine = (command: GlCommand, returnPlan: ReturnPlan, outs: OutArg[]): string | undefined => {
     const members: string[] = [];
-    if (returnPlan.kind !== "void") members.push(`\`${command.returnCType}\``);
+
+    if (returnPlan.kind !== "void") {
+        members.push(`\`${command.returnCType}\``);
+    }
+
     for (const out of outs) {
-        const param = command.params[out.paramIndex];
-        if (param === undefined)
-            throw new Error(`Output parameter index ${out.paramIndex} out of range on ${command.name}`);
-        members.push(`\`${param.name}\` (\`${param.cType}\`)`);
+        members.push(outMember(command, out));
     }
-    if (members.length === 0) return undefined;
-    if (members.length === 1) return ` * @returns ${members[0]}`;
-    return ` * @returns Tuple of ${members.join(", ")}`;
-};
 
-type CommandJsDocOptions = {
-    command: GlCommand;
-    feature: string;
-    ins: InArg[];
-    outs: OutArg[];
-    returnPlan: ReturnPlan;
-};
+    if (members.length === 0) {
+        return undefined;
+    }
 
-type SingularJsDocOptions = {
-    commandName: string;
-    feature: string;
-    summary: string;
-    body: string[];
+    const [single] = members;
+
+    if (single !== undefined && members.length === 1) {
+        return ` * @returns ${single}`;
+    }
+
+    return ` * @returns Tuple of ${members.join(", ")}`;
 };
 
-export const singularJsDoc = ({ commandName, feature, summary, body }: SingularJsDocOptions): string =>
+const singularJsDoc = ({ commandName, feature, summary, body }: SingularJsDocOptions): string =>
     [
         "/**",
         ` * ${summary}`,
@@ -62,15 +97,18 @@ export const singularJsDoc = ({ commandName, feature, summary, body }: SingularJ
         " */",
     ].join("\n");
 
-export const commandJsDoc = ({ command, feature, ins, outs, returnPlan }: CommandJsDocOptions): string => {
+const commandJsDoc = ({ command, feature, ins, outs, returnPlan }: CommandJsDocOptions): string => {
     const returnsLine = returnsDocLine(command, returnPlan, outs);
+
     return singularJsDoc({
         commandName: command.name,
         feature,
         summary: `\`${formatPrototype(command)}\``,
         body: [
             ...(ins.length > 0 ? [" *", ...ins.map((arg) => inParamDocLine(command, arg))] : []),
-            ...(returnsLine !== undefined ? [returnsLine] : []),
+            ...(returnsLine === undefined ? [] : [returnsLine]),
         ],
     });
 };
+
+export { inParamDocLine, singularJsDoc, commandJsDoc };