`Builder`

Class in Authoring

The statement collector every fn() body writes into.

import { Builder } from 'typeshade'

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

Syntax

class Builder

Description

let, var, assign, if, forRange, switch, ret, break, continue, discard and raw each push one statement onto .stmts in authored order. fn() hands its body the Builder as the second argument, and the ambient free functions (Let, Var, If, Loop, Return and the rest) resolve the innermost active Builder and forward to it, so b.let(...) and Let(...) emit the same statement. Use the Builder directly when a statement is authored outside an active fn(), If or Loop scope, for example when assembling a Stmt[] fragment by hand to splice into a body later; there the ambient functions throw SD0013 (no active scope).

Examples

Example

// Outside an active fn() scope, assembling a Stmt[] to splice in later.
const b = new Builder()
const base = b.let('base', fillExpr)
b.assign(out.color, vec4(base.swizzle('xyz'), base.w))
return b.stmts

Constructor

new Builder(private readonly autoNames: { n: number } = { n: 0 })

Instance properties

stmtsread only Stmt[]

Instance methods

child (): Builder

A builder for a nested scope (an if, loop or switch body) that shares this builder’s auto-name counter, so generated _v{n} names stay unique across the whole function.

let <K extends string>(value: ReadonlyNode<K>): ReadonlyNode<K>

Immutable binding, let name = expr;. The name is optional: omit it and the binding takes a function-unique generated name (_v0, _v1, and so on), which suits a value whose JavaScript const already carries the meaning, at the cost of an opaque name in the emitted source. Returns a read-only node of the bound value’s type.

let <K extends string>(name: string, value: ReadonlyNode<K>): ReadonlyNode<K>

let <K extends string>(nameOrValue: string | ReadonlyNode<K>, maybeValue?: ReadonlyNode<K>): ReadonlyNode<K>

var <T extends ShaderType>(type: T, init?: ReadonlyNode<KeyOf<T>>): Node<KeyOf<T>>

Mutable binding, var name: T = init;. The name is optional, as for let. Returns a mutable node whose .assign writes the variable.

var <T extends ShaderType>(name: string, type: T, init?: ReadonlyNode<KeyOf<T>>): Node<KeyOf<T>>

var <T extends ShaderType>(nameOrType: string | T, typeOrInit?: T | ReadonlyNode<KeyOf<T>>, maybeInit?: ReadonlyNode<KeyOf<T>>): Node<KeyOf<T>>

inferredVar (): { ref: (type: ShaderType) => Node; commit: (type: ShaderType) => void; cancel: () => void; }

A var whose type is filled in after its branch assignments are authored, for a value chosen by a branch (when uses it). The declaration is pushed now, ahead of the branches; ref(type) makes a node reading the variable once the type is known, commit(type) patches the declaration with it, and cancel() removes the declaration when no branch assigned a value. The build completes synchronously, so the emitter always sees a fully typed declaration.

assign <K extends string>(target: ReadonlyNode<K>, value: ReadonlyNode<K>): void

assignOp <K extends string>(target: ReadonlyNode<K>, bop: BinOp, value: ArithArg<K>): void

addAssign <K extends string>(target: Node<K>, value: ArithArg<K>): void

ret (value?: ReadonlyNode): void

break (): void

continue (): void

discard (): void

call (node: ReadonlyNode): void

Push a call as a statement, kept for its effect and nothing else: b.call(store(i)). The value is dropped; a user fn’s result is emitted bare, a value-returning builtin’s behind WGSL’s _ = phony assignment.

placeholder (tag: string): void

Push a placeholder statement carrying tag. A host that post-processes the module can walk the body and replace each tagged placeholder with statements of its own. A placeholder left in place emits as the comment // __placeholder: <tag>.

raw (payload: RawPayload): void

Push a raw statement, one verbatim spelling per target; the builder form of the free rawStmt factory. Use b.raw() inside a fn() body: a bare rawStmt(...) call there is a discarded expression, since the returned statement is never pushed and nothing is emitted. Use rawStmt() when assembling a Stmt[] body array by hand. The statement records its source location like every other statement.

if (cond: ReadonlyNode<'bool'>, body: (b: Builder) => ReadonlyNode | void): IfChain

if / else-if / else chain. Returns a chainer so .elif().else() reads top-to-bottom. The If stmt is pushed on the first call and mutated in place by subsequent .elif/.else.

A branch is a statement block, so a body that returns a value is rejected with SD0115 rather than having that value quietly dropped. Write Return(value) for an early return, when for a value, or assign to a Var.

forRange <K extends string>(init: ReadonlyNode<K>, cond: (i: Node<K>) => ReadonlyNode<'bool'>, body: (b: Builder, i: Node<K>) => ReadonlyNode | void, step?: ReadonlyNode<ScalarKey> | number): void

C-style for loop: for (var name = init; cond; name = name + step). A numeric or omitted step takes the loop variable’s scalar type, so a u32 or i32 counter emits i + 1u or i + 1; a float step on an integer counter would be rejected by both GPU compilers.

forRange <K extends string>(name: string, init: ReadonlyNode<K>, cond: (i: Node<K>) => ReadonlyNode<'bool'>, body: (b: Builder, i: Node<K>) => ReadonlyNode | void, step?: ReadonlyNode<ScalarKey> | number): void

switch (scrut: ReadonlyNode<'i32' | 'u32'>, cases: Array<[number, (b: Builder) => ReadonlyNode | void]>, defaultBody?: (b: Builder) => ReadonlyNode | void): void

Source

src/core/ir/builder.ts, line 139, at commit 26de7be8

Edit this page Report a problem

Builder