@soundscript/soundscript 0.1.12 → 0.1.15

package/project-transform/src/frontend/macro_advanced_output.js

@@ -0,0 +1,21 @@
+const ADVANCED_MACRO_OUTPUT_BRAND = Symbol.for('soundscript.advanced-macro-output');
+export function createAdvancedValueRewriteOutput(preludeStatements, replacementExpr) {
+    return {
+        [ADVANCED_MACRO_OUTPUT_BRAND]: true,
+        kind: 'value_rewrite',
+        preludeStatements,
+        replacementExpr,
+    };
+}
+export function isAdvancedMacroOutput(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        ADVANCED_MACRO_OUTPUT_BRAND in value &&
+        value[ADVANCED_MACRO_OUTPUT_BRAND] === true &&
+        'kind' in value &&
+        value.kind === 'value_rewrite' &&
+        'preludeStatements' in value &&
+        Array.isArray(value.preludeStatements) &&
+        'replacementExpr' in value &&
+        typeof value.replacementExpr === 'string';
+}

package/project-transform/src/frontend/macro_advanced_output.ts

@@ -0,0 +1,41 @@
+const ADVANCED_MACRO_OUTPUT_BRAND = Symbol.for('soundscript.advanced-macro-output');
+
+interface AdvancedMacroOutputBase {
+  readonly [ADVANCED_MACRO_OUTPUT_BRAND]: true;
+}
+
+export type AdvancedMacroPlacementKind =
+  | 'statement-region';
+
+export interface AdvancedValueRewriteOutput extends AdvancedMacroOutputBase {
+  readonly kind: 'value_rewrite';
+  readonly preludeStatements: readonly string[];
+  readonly replacementExpr: string;
+}
+
+export type AdvancedMacroOutput = AdvancedValueRewriteOutput;
+
+export function createAdvancedValueRewriteOutput(
+  preludeStatements: readonly string[],
+  replacementExpr: string,
+): AdvancedValueRewriteOutput {
+  return {
+    [ADVANCED_MACRO_OUTPUT_BRAND]: true,
+    kind: 'value_rewrite',
+    preludeStatements,
+    replacementExpr,
+  };
+}
+
+export function isAdvancedMacroOutput(value: unknown): value is AdvancedMacroOutput {
+  return typeof value === 'object' &&
+    value !== null &&
+    ADVANCED_MACRO_OUTPUT_BRAND in value &&
+    value[ADVANCED_MACRO_OUTPUT_BRAND] === true &&
+    'kind' in value &&
+    value.kind === 'value_rewrite' &&
+    'preludeStatements' in value &&
+    Array.isArray(value.preludeStatements) &&
+    'replacementExpr' in value &&
+    typeof value.replacementExpr === 'string';
+}

package/project-transform/src/frontend/macro_api.js

@@ -0,0 +1,353 @@
+function createMacroSignatureOperand(kind, name, options = {}) {
+    return {
+        description: options.description,
+        kind,
+        name,
+        optional: (options.optional ?? false),
+        refinement: options.refinement,
+    };
+}
+function createMacroSignatureCase(caseName, operands) {
+    let sawOptional = false;
+    let sawTerminal = false;
+    operands.forEach((operand, index) => {
+        const isTerminal = operand.kind === 'block' || operand.kind === 'decl';
+        if (sawTerminal) {
+            throw new Error('Macro signatures cannot place operands after a block or declaration operand.');
+        }
+        if (isTerminal && index !== operands.length - 1) {
+            throw new Error('Macro block and declaration operands must be the final operand in a signature case.');
+        }
+        if (sawOptional && !operand.optional) {
+            throw new Error('Macro signature optional operands must appear at the end of a signature case.');
+        }
+        if (operand.optional) {
+            sawOptional = true;
+        }
+        if (isTerminal) {
+            sawTerminal = true;
+        }
+    });
+    return {
+        caseName,
+        operands: [...operands],
+    };
+}
+function normalizeMacroSignatureCases(cases) {
+    return cases.flatMap((candidate) => 'cases' in candidate ? candidate.cases : [candidate]);
+}
+function formatMacroSignatureOperand(operand) {
+    const required = formatRequiredMacroSignatureOperand(operand);
+    return operand.optional ? `[${required}]` : required;
+}
+function formatRequiredMacroSignatureOperand(operand) {
+    return operand.refinement?.displayText ?? (() => {
+        switch (operand.kind) {
+            case 'expr':
+                return `<${operand.name}>`;
+            case 'template':
+                return '`...`';
+            case 'block':
+                return '{ ... }';
+            case 'decl':
+                return '<declaration>';
+        }
+    })();
+}
+function formatMacroSignatureCaseExample(macroName, signatureCase) {
+    return formatMacroSignatureCaseExamples(macroName, signatureCase).at(-1) ?? `${macroName}()`;
+}
+function formatMacroSignatureCaseExamples(macroName, signatureCase) {
+    const exprOperands = signatureCase.operands.filter((operand) => operand.kind === 'expr' || operand.kind === 'template');
+    const terminalOperand = signatureCase.operands.find((operand) => operand.kind === 'block' || operand.kind === 'decl') ??
+        null;
+    const requiredExprCount = exprOperands.filter((operand) => !operand.optional).length;
+    const variants = [];
+    for (let exprCount = requiredExprCount; exprCount <= exprOperands.length; exprCount += 1) {
+        const includedExprOperands = exprOperands.slice(0, exprCount);
+        const templateOnly = !terminalOperand &&
+            includedExprOperands.length === 1 &&
+            exprOperands.length === 1 &&
+            includedExprOperands[0]?.kind === 'template';
+        const formattedArgs = includedExprOperands.map(formatRequiredMacroSignatureOperand);
+        let invocation = templateOnly
+            ? `${macroName}${formatRequiredMacroSignatureOperand(includedExprOperands[0])}`
+            : `${macroName}(${formattedArgs.join(', ')})`;
+        if (terminalOperand?.kind === 'block') {
+            invocation = `${macroName}(${[...formattedArgs, '() => { ... }'].join(', ')})`;
+        }
+        else if (terminalOperand?.kind === 'decl') {
+            invocation = includedExprOperands.length === 0
+                ? `// #[${macroName}] <declaration>`
+                : `${macroName}(${formattedArgs.join(', ')}) <declaration>`;
+        }
+        variants.push(invocation);
+    }
+    return variants;
+}
+export function formatMacroSignatureExamples(signature, macroName) {
+    return signature.cases.map((signatureCase) => formatMacroSignatureCaseExample(macroName, signatureCase));
+}
+export function formatMacroSignature(signature, macroName) {
+    return signature.cases
+        .flatMap((signatureCase) => formatMacroSignatureCaseExamples(macroName, signatureCase))
+        .join('; ');
+}
+function refineMacroSignatureOperandValue(operand, value) {
+    if (value === null || !operand.refinement) {
+        return value;
+    }
+    switch (operand.refinement.kind) {
+        case 'array_literal':
+            return value.kind === 'expr'
+                ? value.asArrayLiteral()
+                : null;
+        case 'call':
+            return value.kind === 'expr' && value.asCall() !== null
+                ? value
+                : null;
+        case 'class_decl':
+            return value.kind === 'decl'
+                ? value.asClass()
+                : null;
+        case 'function':
+            return value.kind === 'expr'
+                ? value.asFunction()
+                : null;
+        case 'function_decl':
+            return value.kind === 'decl'
+                ? value.asFunction()
+                : null;
+        case 'interface_decl':
+            return value.kind === 'decl'
+                ? value.asInterface()
+                : null;
+        case 'type_alias_decl':
+            return value.kind === 'decl'
+                ? value.asTypeAlias()
+                : null;
+        case 'identifier':
+            return value.kind === 'expr' && value.asIdentifier() !== null
+                ? value
+                : null;
+    }
+}
+function tryReadMacroSignatureCase(signatureCase, ctx) {
+    const args = {};
+    let exprIndex = 0;
+    const argCount = ctx.invocation.args.length;
+    const declarationSpan = ctx.declarationSpan();
+    const hasBlock = ctx.hasBlock();
+    for (const operand of signatureCase.operands) {
+        switch (operand.kind) {
+            case 'expr': {
+                if (exprIndex >= argCount) {
+                    if (operand.optional) {
+                        args[operand.name] = null;
+                        break;
+                    }
+                    return null;
+                }
+                const value = refineMacroSignatureOperandValue(operand, ctx.syntax.arg(exprIndex));
+                if (value === null) {
+                    return null;
+                }
+                args[operand.name] = value;
+                exprIndex += 1;
+                break;
+            }
+            case 'template': {
+                if (exprIndex >= argCount) {
+                    if (operand.optional) {
+                        args[operand.name] = null;
+                        break;
+                    }
+                    return null;
+                }
+                const template = ctx.syntax.template(exprIndex);
+                if (!template) {
+                    return null;
+                }
+                const value = refineMacroSignatureOperandValue(operand, template);
+                if (value === null) {
+                    return null;
+                }
+                args[operand.name] = value;
+                exprIndex += 1;
+                break;
+            }
+            case 'block': {
+                if (!hasBlock) {
+                    if (operand.optional) {
+                        args[operand.name] = null;
+                        break;
+                    }
+                    return null;
+                }
+                if (declarationSpan) {
+                    return null;
+                }
+                const value = refineMacroSignatureOperandValue(operand, ctx.syntax.block());
+                if (value === null) {
+                    return null;
+                }
+                args[operand.name] = value;
+                break;
+            }
+            case 'decl': {
+                if (!declarationSpan) {
+                    if (operand.optional) {
+                        args[operand.name] = null;
+                        break;
+                    }
+                    return null;
+                }
+                if (hasBlock) {
+                    return null;
+                }
+                const value = refineMacroSignatureOperandValue(operand, ctx.syntax.declaration());
+                if (value === null) {
+                    return null;
+                }
+                args[operand.name] = value;
+                break;
+            }
+        }
+    }
+    if (exprIndex !== argCount) {
+        return null;
+    }
+    const expectsBlock = signatureCase.operands.some((operand) => operand.kind === 'block');
+    const expectsDecl = signatureCase.operands.some((operand) => operand.kind === 'decl');
+    if (hasBlock && !expectsBlock) {
+        return null;
+    }
+    if (declarationSpan && !expectsDecl) {
+        return null;
+    }
+    if (!hasBlock && expectsBlock && !signatureCase.operands.find((operand) => operand.kind === 'block')
+        ?.optional) {
+        return null;
+    }
+    if (!declarationSpan && expectsDecl &&
+        !signatureCase.operands.find((operand) => operand.kind === 'decl')?.optional) {
+        return null;
+    }
+    return {
+        args: args,
+        caseName: signatureCase.caseName,
+        signatureCase,
+    };
+}
+export function tryReadMacroSignature(signature, ctx) {
+    for (const signatureCase of signature.cases) {
+        const decoded = tryReadMacroSignatureCase(signatureCase, ctx);
+        if (decoded) {
+            return decoded;
+        }
+    }
+    return null;
+}
+export function readMacroSignature(signature, ctx) {
+    const decoded = tryReadMacroSignature(signature, ctx);
+    if (decoded) {
+        return decoded;
+    }
+    ctx.error(`${ctx.name} only supports: ${formatMacroSignature(signature, ctx.name)}.`);
+}
+function macroSignatureBlock(name, options = {}) {
+    return createMacroSignatureOperand('block', name, options);
+}
+function macroSignatureCase(...operandsOrCaseName) {
+    if (typeof operandsOrCaseName[0] === 'string') {
+        const [caseName, ...operands] = operandsOrCaseName;
+        return createMacroSignatureCase(caseName, operands);
+    }
+    return createMacroSignatureCase(null, operandsOrCaseName);
+}
+function macroSignatureDecl(name, options = {}) {
+    return createMacroSignatureOperand('decl', name, options);
+}
+function macroSignatureExpr(name, options = {}) {
+    return createMacroSignatureOperand('expr', name, options);
+}
+function createRefinedMacroSignatureOperand(kind, name, refinement, options = {}) {
+    return createMacroSignatureOperand(kind, name, {
+        ...options,
+        refinement,
+    });
+}
+function macroSignatureArrayLiteral(name, options = {}) {
+    return createRefinedMacroSignatureOperand('expr', name, { displayText: '[ ... ]', kind: 'array_literal' }, options);
+}
+function macroSignatureCall(name, options = {}) {
+    return createRefinedMacroSignatureOperand('expr', name, { displayText: '<call>(...)', kind: 'call' }, options);
+}
+function macroSignatureFunctionExpr(name, options = {}) {
+    return createRefinedMacroSignatureOperand('expr', name, { displayText: '(() => ...)', kind: 'function' }, options);
+}
+function macroSignatureIdentifier(name, options = {}) {
+    return createRefinedMacroSignatureOperand('expr', name, { displayText: '<identifier>', kind: 'identifier' }, options);
+}
+function macroSignatureOf(...operands) {
+    return {
+        cases: [createMacroSignatureCase(null, operands)],
+    };
+}
+function macroSignatureOneOf(...cases) {
+    return {
+        cases: normalizeMacroSignatureCases(cases),
+    };
+}
+function macroSignatureOptional(operand) {
+    return {
+        ...operand,
+        optional: true,
+    };
+}
+function macroSignatureSignature(...operands) {
+    return {
+        cases: [createMacroSignatureCase(null, operands)],
+    };
+}
+function macroSignatureTemplate(name, options = {}) {
+    return createMacroSignatureOperand('template', name, options);
+}
+function macroSignatureClassDecl(name, options = {}) {
+    return createRefinedMacroSignatureOperand('decl', name, { displayText: 'class { ... }', kind: 'class_decl' }, options);
+}
+function macroSignatureFunctionDecl(name, options = {}) {
+    return createRefinedMacroSignatureOperand('decl', name, { displayText: 'function ...', kind: 'function_decl' }, options);
+}
+function macroSignatureInterfaceDecl(name, options = {}) {
+    return createRefinedMacroSignatureOperand('decl', name, { displayText: 'interface ...', kind: 'interface_decl' }, options);
+}
+function macroSignatureTypeAliasDecl(name, options = {}) {
+    return createRefinedMacroSignatureOperand('decl', name, { displayText: 'type ... = ...', kind: 'type_alias_decl' }, options);
+}
+function macroSignatureRefine(signature, validator) {
+    return {
+        ...signature,
+        validators: [...(signature.validators ?? []), validator],
+    };
+}
+export const macroSignature = {
+    arrayLiteral: macroSignatureArrayLiteral,
+    block: macroSignatureBlock,
+    case: macroSignatureCase,
+    call: macroSignatureCall,
+    classDecl: macroSignatureClassDecl,
+    decl: macroSignatureDecl,
+    expr: macroSignatureExpr,
+    functionDecl: macroSignatureFunctionDecl,
+    functionExpr: macroSignatureFunctionExpr,
+    identifier: macroSignatureIdentifier,
+    interfaceDecl: macroSignatureInterfaceDecl,
+    of: macroSignatureOf,
+    oneOf: macroSignatureOneOf,
+    optional: macroSignatureOptional,
+    refine: macroSignatureRefine,
+    signature: macroSignatureSignature,
+    template: macroSignatureTemplate,
+    typeAliasDecl: macroSignatureTypeAliasDecl,
+};