wesl 0.6.0-pre10

package/src/AbstractElems.ts

@@ -0,0 +1,446 @@
+import { Span } from "mini-parse";
+import { DeclIdent, RefIdent, SrcModule } from "./Scope.ts";
+
+/**
+ * Structures to describe the 'interesting' parts of a WESL source file.
+ *
+ * The parts of the source that need to analyze further in the linker
+ * are pulled out into these structures.
+ *
+ * The parts that are uninteresting the the linker are recorded
+ * as 'TextElem' nodes, which are generally just copied to the output WGSL
+ * along with their containing element.
+ */
+export type AbstractElem = GrammarElem | SyntheticElem;
+
+export type GrammarElem = ContainerElem | TerminalElem;
+
+export type ContainerElem =
+  | AttributeElem
+  | AliasElem
+  | ConstAssertElem
+  | ConstElem
+  | UnknownExpressionElem
+  | SimpleMemberRef
+  | FnElem
+  | TypedDeclElem
+  | GlobalVarElem
+  | LetElem
+  | ModuleElem
+  | OverrideElem
+  | FnParamElem
+  | StructElem
+  | StructMemberElem
+  | StuffElem
+  | TypeRefElem
+  | VarElem
+  | StatementElem
+  | SwitchClauseElem;
+
+/** Inspired by https://github.com/wgsl-tooling-wg/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
+export type ExpressionElem =
+  | Literal
+  | TranslateTimeFeature
+  | RefIdentElem
+  | ParenthesizedExpression
+  | ComponentExpression
+  | ComponentMemberExpression
+  | UnaryExpression
+  | BinaryExpression
+  | FunctionCallExpression;
+
+export type TerminalElem =
+  | DirectiveElem
+  | DeclIdentElem //
+  | NameElem
+  | RefIdentElem
+  | TextElem
+  | ImportElem;
+
+export type GlobalDeclarationElem =
+  | AliasElem
+  | ConstElem
+  | FnElem
+  | GlobalVarElem
+  | OverrideElem
+  | StructElem;
+
+export type DeclarationElem = GlobalDeclarationElem | FnParamElem | VarElem;
+
+export type ElemWithAttributes = Extract<AbstractElem, HasAttributes>;
+
+export interface AbstractElemBase {
+  kind: AbstractElem["kind"];
+  start: number;
+  end: number;
+}
+
+export interface ElemWithContentsBase extends AbstractElemBase {
+  contents: AbstractElem[];
+}
+
+export interface HasAttributes {
+  attributes?: AttributeElem[];
+}
+
+/* ------   Terminal Elements  (don't contain other elements)  ------   */
+
+/**
+ * a raw bit of text in WESL source that's typically copied to the linked WGSL.
+ * e.g. a keyword  like 'var'
+ * or a phrase we needn't analyze further like '@diagnostic(off,derivative_uniformity)'
+ */
+export interface TextElem extends AbstractElemBase {
+  kind: "text";
+  srcModule: SrcModule;
+}
+
+/** a name that doesn't need to be an Ident
+ * e.g.
+ * - a struct member name
+ * - a diagnostic rule name
+ * - an enable-extension name
+ * - an interpolation sampling name
+ */
+export interface NameElem extends AbstractElemBase {
+  kind: "name";
+  name: string;
+}
+
+/** an identifier that 'refers to' a declaration (aka a symbol reference) */
+export interface RefIdentElem extends AbstractElemBase {
+  kind: RefIdent["kind"];
+  ident: RefIdent;
+  srcModule: SrcModule;
+}
+
+/** a declaration identifier (aka a symbol declaration) */
+export interface DeclIdentElem extends AbstractElemBase {
+  kind: DeclIdent["kind"];
+  ident: DeclIdent;
+  srcModule: SrcModule;
+}
+
+/** Holds an import statement, and has a span */
+export interface ImportElem extends AbstractElemBase {
+  kind: "import";
+  imports: ImportStatement;
+}
+
+/**
+ * An import statement, which is tree shaped.
+ * `import foo::bar::{baz, cat as neko};
+ */
+export interface ImportStatement {
+  kind: "import-statement";
+  segments: ImportSegment[];
+  finalSegment: ImportCollection | ImportItem;
+}
+
+/**
+ * A collection of import trees.
+ * `{baz, cat as neko}`
+ */
+export interface ImportSegment {
+  kind: "import-segment";
+  name: string;
+}
+
+/**
+ * A primitive segment in an import statement.
+ * `foo`
+ */
+export interface ImportCollection {
+  kind: "import-collection";
+  subtrees: ImportStatement[];
+}
+
+/**
+ * A renamed item at the end of an import statement.
+ * `cat as neko`
+ */
+export interface ImportItem {
+  kind: "import-item";
+  name: string;
+  as?: string;
+}
+
+/* ------   Synthetic element (for transformations, not produced by grammar) ------   */
+
+/** generated element, produced after parsing and binding */
+export interface SyntheticElem {
+  kind: "synthetic";
+  text: string;
+}
+
+/* ------   Container Elements  (contain other elements)  ------   */
+
+/** a declaration identifer with a possible type */
+export interface TypedDeclElem extends ElemWithContentsBase {
+  kind: "typeDecl";
+  decl: DeclIdentElem;
+  typeRef?: TypeRefElem; // TODO Consider a variant for fn params and alias where typeRef is required
+}
+
+/** an alias statement */
+export interface AliasElem extends ElemWithContentsBase, HasAttributes {
+  kind: "alias";
+  name: DeclIdentElem;
+  typeRef: TypeRefElem;
+}
+
+/** an attribute like '@compute' or '@binding(0)' */
+export interface AttributeElem extends ElemWithContentsBase {
+  kind: "attribute";
+  attribute: Attribute;
+}
+
+export type Attribute =
+  | StandardAttribute
+  | InterpolateAttribute
+  | BuiltinAttribute
+  | DiagnosticAttribute
+  | IfAttribute;
+
+export interface StandardAttribute {
+  kind: "@attribute";
+  name: string;
+  params?: UnknownExpressionElem[];
+}
+
+export interface InterpolateAttribute {
+  kind: "@interpolate";
+  params: NameElem[];
+}
+
+export interface BuiltinAttribute {
+  kind: "@builtin";
+  param: NameElem;
+}
+
+export interface DiagnosticAttribute {
+  kind: "@diagnostic";
+  severity: NameElem;
+  rule: [NameElem, NameElem | null];
+}
+
+export interface IfAttribute {
+  kind: "@if";
+  param: TranslateTimeExpressionElem;
+}
+
+/** a const_assert statement */
+export interface ConstAssertElem extends ElemWithContentsBase, HasAttributes {
+  kind: "assert";
+}
+
+/** a const declaration */
+export interface ConstElem extends ElemWithContentsBase, HasAttributes {
+  kind: "const";
+  name: TypedDeclElem;
+}
+
+/** an expression w/o special handling, used inside attribute parameters */
+export interface UnknownExpressionElem extends ElemWithContentsBase {
+  kind: "expression";
+}
+
+/** an expression that can be safely evaluated at compile time */
+export interface TranslateTimeExpressionElem {
+  kind: "translate-time-expression";
+  expression: ExpressionElem;
+  span: Span;
+}
+
+/** A literal value in WESL source. A boolean or a number. */
+export interface Literal {
+  kind: "literal";
+  value: string;
+  span: Span;
+}
+
+/** `words`s inside `@if` */
+export interface TranslateTimeFeature {
+  kind: "translate-time-feature";
+  name: string;
+  span: Span;
+}
+
+/** (expr) */
+export interface ParenthesizedExpression {
+  kind: "parenthesized-expression";
+  expression: ExpressionElem;
+}
+
+/** `foo[expr]` */
+export interface ComponentExpression {
+  kind: "component-expression";
+  base: ExpressionElem;
+  access: ExpressionElem;
+}
+
+/** `foo.member` */
+export interface ComponentMemberExpression {
+  kind: "component-member-expression";
+  base: ExpressionElem;
+  access: NameElem;
+}
+
+/** `+foo` */
+export interface UnaryExpression {
+  kind: "unary-expression";
+  operator: UnaryOperator;
+  expression: ExpressionElem;
+}
+
+/** `foo + bar` */
+export interface BinaryExpression {
+  kind: "binary-expression";
+  operator: BinaryOperator;
+  left: ExpressionElem;
+  right: ExpressionElem;
+}
+
+/** `foo(arg, arg)` */
+export interface FunctionCallExpression {
+  kind: "call-expression";
+  function: RefIdentElem;
+  arguments: ExpressionElem[];
+}
+
+export interface UnaryOperator {
+  value: "!" | "&" | "*" | "-" | "~";
+  span: Span;
+}
+
+export interface BinaryOperator {
+  value:
+    | ("||" | "&&" | "+" | "-" | "*" | "/" | "%" | "==")
+    | ("!=" | "<" | "<=" | ">" | ">=" | "|" | "&" | "^")
+    | ("<<" | ">>");
+  span: Span;
+}
+
+export type DirectiveVariant =
+  | DiagnosticDirective
+  | EnableDirective
+  | RequiresDirective;
+
+export interface DirectiveElem extends AbstractElemBase, HasAttributes {
+  kind: "directive";
+  directive: DirectiveVariant;
+}
+
+export interface DiagnosticDirective {
+  kind: "diagnostic";
+  severity: NameElem;
+  rule: [NameElem, NameElem | null];
+}
+
+export interface EnableDirective {
+  kind: "enable";
+  extensions: NameElem[];
+}
+
+export interface RequiresDirective {
+  kind: "requires";
+  extensions: NameElem[];
+}
+
+/** a function declaration */
+export interface FnElem extends ElemWithContentsBase, HasAttributes {
+  // LATER doesn't need contents
+  kind: "fn";
+  name: DeclIdentElem;
+  params: FnParamElem[];
+  body: StatementElem;
+  returnAttributes?: AttributeElem[];
+  returnType?: TypeRefElem;
+}
+
+/** a global variable declaration (at the root level) */
+export interface GlobalVarElem extends ElemWithContentsBase, HasAttributes {
+  kind: "gvar";
+  name: TypedDeclElem;
+}
+
+/** an entire file */
+export interface ModuleElem extends ElemWithContentsBase {
+  kind: "module";
+}
+
+/** an override declaration */
+export interface OverrideElem extends ElemWithContentsBase, HasAttributes {
+  kind: "override";
+  name: TypedDeclElem;
+}
+
+/** a parameter in a function declaration */
+export interface FnParamElem extends ElemWithContentsBase, HasAttributes {
+  kind: "param";
+  name: TypedDeclElem;
+}
+
+/** simple references to structures, like myStruct.bar
+ * (used for transforming refs to binding structs) */
+export interface SimpleMemberRef extends ElemWithContentsBase {
+  kind: "memberRef";
+  name: RefIdentElem;
+  member: NameElem;
+  extraComponents?: StuffElem;
+}
+
+/** a struct declaration */
+export interface StructElem extends ElemWithContentsBase, HasAttributes {
+  kind: "struct";
+  name: DeclIdentElem;
+  members: StructMemberElem[];
+  bindingStruct?: true; // used later during binding struct transformation
+}
+
+/** generic container of other elements */
+export interface StuffElem extends ElemWithContentsBase {
+  kind: "stuff";
+}
+
+/** a struct declaration that's been marked as a bindingStruct */
+export interface BindingStructElem extends StructElem {
+  bindingStruct: true;
+  entryFn?: FnElem;
+}
+
+/** a member of a struct declaration */
+export interface StructMemberElem extends ElemWithContentsBase, HasAttributes {
+  kind: "member";
+  name: NameElem;
+  typeRef: TypeRefElem;
+  mangledVarName?: string; // root name if transformed to a var (for binding struct transformation)
+}
+
+export type TypeTemplateParameter = TypeRefElem | UnknownExpressionElem;
+
+/** a reference to a type, like 'f32', or 'MyStruct', or 'ptr<storage, array<f32>, read_only>'   */
+export interface TypeRefElem extends ElemWithContentsBase {
+  kind: "type";
+  name: RefIdent;
+  templateParams?: TypeTemplateParameter[];
+}
+
+/** a variable declaration */
+export interface VarElem extends ElemWithContentsBase, HasAttributes {
+  kind: "var";
+  name: TypedDeclElem;
+}
+
+export interface LetElem extends ElemWithContentsBase, HasAttributes {
+  kind: "let";
+  name: TypedDeclElem;
+}
+
+export interface StatementElem extends ElemWithContentsBase, HasAttributes {
+  kind: "statement";
+}
+
+export interface SwitchClauseElem extends ElemWithContentsBase, HasAttributes {
+  kind: "switch-clause";
+}

package/src/Assertions.ts

@@ -0,0 +1,51 @@
+import { tracing } from "mini-parse";
+
+/** checks whether a condition is true, otherwise throws */
+export function assertThat(condition: any, msg?: string): asserts condition {
+  if (!condition) {
+    throw new Error(msg);
+  }
+}
+
+/** when debug testing is enabled, checks whether a condition is true, otherwise throws */
+export function assertThatDebug(
+  condition: any,
+  msg?: string,
+): asserts condition {
+  tracing && assertThat(condition, msg);
+}
+
+/** when debug testing is enabled throw an error */
+export function failDebug(msg = "FAIL"): void {
+  if (tracing) throw new Error(msg);
+}
+
+/**
+ * Typescript will complain at compile time if it thinks this could be executed.
+ * Useful to validate that all cases are handled.
+ *
+ * Does nothing at runtime.
+ */
+export function assertUnreachableSilent(_value: never): void {}
+
+/**
+ * Useful to validate that all cases are handled,
+ * TypeScript should complain if this statement could possibly be executed.
+ *
+ * If this is somehow executed at runtime, throw an exception.
+ */
+export function assertUnreachable(value: never): never {
+  throw new ErrorWithData("Unreachable value", { data: value }); // LATER optimize code size by reporting less in non debug builds
+}
+
+export interface ErrorWithDataOptions extends ErrorOptions {
+  data: any;
+}
+
+export class ErrorWithData extends Error {
+  data: any;
+  constructor(message?: string, options?: ErrorWithDataOptions) {
+    super(message, options);
+    this.data = options?.data;
+  }
+}