`composeModule()`

Function in Variants

Compose a module by filling its placeholder statements.

import { composeModule } from 'typeshade'

The signature, the description and the examples come from the compiler's own source at commit 26de7be8.

Syntax

function composeModule(
  m: ModuleDecl,
  swaps: Record<string, readonly Stmt[]>,
  opts?: ComposeOptions,
): ModuleDecl

Parameters

m ModuleDecl: the base module carrying the placeholders.
swaps Record<string, readonly Stmt[]>: tag to statement list, one entry per placeholder to fill.
optsoptional ComposeOptions: allowUnswapped to let a placeholder stay unfilled.

Return value

ModuleDecl

a new module with the function bodies rewritten; m is not modified.

Exceptions

Error: Error when a swap key matches no placeholder, or when a placeholder is left un-swapped and allowUnswapped is not set.

Description

A base module marks each place where its builds differ with b.placeholder('tag'), and composeModule replaces each one with the statement list swaps holds under that tag, returning a new module. Function bodies are rewritten; consts, structs and bindings are copied unchanged.

It descends into if, for and switch bodies, so a placeholder may sit in a nested scope.

It is strict by default. A placeholder that receives no swap is otherwise easy to miss: the WGSL emitter writes it as a bare // __placeholder: <tag> comment and the shader still compiles, while the GLSL emitter and compileModule (the same module evaluated on the CPU in double precision) throw only when they reach it. A swap key that matches no placeholder, such as a typo, would do nothing at all. Here each case throws at compose time and names the tags involved.

allowUnswapped is for the deliberate case: a placeholder that is meant to stay empty in this build. It turns off the first check only; a swap key that matches no placeholder is still an error.

Examples

Example

import { composeModule, fn, module, f32, f32T, type Stmt } from 'typeshade'

const base = module({
  funcs: [fn('shade', {}, f32T, (_p, b) => b.placeholder('result'))],
})
const returnConstant = (v: number): Stmt => ({ s: 'return', expr: f32(v).expr })
const composed = composeModule(base, { result: [returnConstant(1)] })

In the guide

Source

src/core/passes/compose.ts, line 123, at commit 26de7be8

Edit this page Report a problem

composeModule()