shaderkit 0.2.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2024 Cody Bennett
+Copyright (c) 2023-2025 Cody Bennett
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -14,32 +14,53 @@ Tools and IntelliSense for GLSL and WGSL.
 - [Parse](#parse)
 - [Generate](#generate)
 - [AST](#ast)
-  - [Literal](#literal)
+  - [Node Objects](#node-objects)
   - [Identifier](#identifier)
-  - [Type](#type)
-  - [VariableDeclaration](#variabledeclaration)
-    - [VariableDeclarator](#variabledeclarator)
-  - [StructDeclaration](#structdeclaration)
-  - [FunctionDeclaration](#functiondeclaration)
-  - [UnaryExpression](#unaryexpression)
-  - [BinaryExpression](#binaryexpression)
-  - [TernaryExpression](#ternaryexpression)
-  - [CallExpression](#callexpression)
-  - [MemberExpression](#memberexpression)
-  - [ArrayExpression](#arrayexpression)
-  - [BlockStatement](#blockstatement)
-  - [IfStatement](#ifstatement)
-  - [ForStatement](#forstatement)
-  - [WhileStatement](#whilestatement)
-  - [DoWhileStatement](#dowhilestatement)
-  - [SwitchStatement](#switchstatement)
-    - [SwitchCase](#switchcase)
-  - [ReturnStatement](#returnstatement)
-  - [PreprocessorStatement](#preprocessorstatement)
-  - [PrecisionStatement](#precisionstatement)
-  - [ContinueStatement](#continuestatement)
-  - [BreakStatement](#breakstatement)
-  - [DiscardStatement](#discardstatement)
+  - [Literal](#literal)
+  - [ArraySpecifier](#arrayspecifier)
+  - [Program](#program)
+  - Statements
+    - [ExpressionStatement](#expressionstatement)
+    - [BlockStatement](#blockstatement)
+    - [DiscardStatement](#discardstatement)
+    - [PreprocessorStatement](#preprocessorstatement)
+    - [PrecisionStatement](#precisionstatement)
+    - Control Flow
+      - [ReturnStatement](#returnstatement)
+      - [BreakStatement](#breakstatement)
+      - [ContinueStatement](#continuestatement)
+    - Choice
+      - [IfStatement](#ifstatement)
+      - [SwitchStatement](#switchstatement)
+        - [SwitchCase](#switchcase)
+    - Loops
+      - [WhileStatement](#whilestatement)
+      - [DoWhileStatement](#dowhilestatement)
+      - [ForStatement](#forstatement)
+  - Declarations
+    - [FunctionDeclaration](#functiondeclaration)
+      - [FunctionParameter](#functionparameter)
+    - [VariableDeclaration](#variabledeclaration)
+      - [VariableDeclarator](#variabledeclarator)
+    - [UniformDeclarationBlock](#uniformdeclarationblock)
+    - [StructDeclaration](#structdeclaration)
+  - Expressions
+    - [ArrayExpression](#arrayexpression)
+    - Unary operations
+      - [UnaryExpression](#unaryexpression)
+        - [UnaryOperator](#unaryoperator)
+      - [UpdateExpression](#updateexpression)
+        - [UpdateOperator](#updateoperator)
+    - Binary Operations
+      - [BinaryExpression](#binaryexpression)
+        - [BinaryOperator](#binaryoperator)
+      - [AssignmentExpression](#assignmentexpression)
+        - [AssignmentOperator](#assignmentoperator)
+      - [LogicalExpression](#logicalexpression)
+        - [LogicalOperator](#logicaloperator)
+      - [MemberExpression](#memberexpression)
+    - [ConditionalExpression](#conditionalexpression)
+    - [CallExpression](#callexpression)
 
 ## Installation
 
@@ -231,7 +252,7 @@ minify(`#version 300 es\nin vec2 c;out vec4 data[gl_MaxDrawBuffers];void main(){
 Parses a string of GLSL (WGSL is WIP) code into an [AST](#ast).
 
 ```ts
-const ast: AST[] = parse(code: string)
+const ast: Program = parse(code: string)
 ```
 
 ## Generate
@@ -239,7 +260,7 @@ const ast: AST[] = parse(code: string)
 Generates a string of GLSL (WGSL is WIP) code from an [AST](#ast).
 
 ```ts
-const code: string = generate(ast: AST[], {
+const code: string = generate(program: Program, {
   target: 'GLSL' // | 'WGSL'
 })
 ```
@@ -248,188 +269,184 @@ const code: string = generate(ast: AST[], {
 
 An [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) loosely based on [ESTree](https://github.com/estree/estree) for GLSL and WGSL grammars.
 
-### Literal
+### Node Objects
 
-A shader literal representing a `bool`, `float`, `int`, or `uint` type.
+AST nodes extend `Node` objects which implement the following abstract interface:
 
 ```ts
-class Literal {
-  value: string
+interface Node {
+  type: string
 }
 ```
 
+The `type` field is a string representing the AST variant type which can determine the interface a node implements.
+
 ### Identifier
 
 A variable identifier.
 
 ```ts
-class Identifier {
-  value: string
+interface Identifier extends Node {
+  type: 'Identifier'
+  name: string
 }
 ```
 
-### Type
+### Literal
 
-Represents a type specifier and its parameters (WGSL specific).
+A shader literal representing a `bool`, `float`, `int`, or `uint` type.
 
 ```ts
-class Type {
-  name: string
-  parameters: (Type | Literal | Identifier)[] | null
+interface Literal extends Node {
+  type: 'Literal'
+  value: string
 }
 ```
 
-### VariableDeclaration
+### ArraySpecifier
 
-A variable declaration with an optional binding layout, type qualifiers, kind (WGSL only), and declarators (e.g. a comma-separated list).
+An array and its dimensions.
 
 ```ts
-class VariableDeclaration {
-  layout: Record<string, string | boolean> | null
-  qualifiers: string[]
-  kind: 'var' | 'let' | 'const' | null
-  type: Type | Identifier
-  declarations: VariableDeclarator[]
+interface ArraySpecifier extends Node {
+  type: 'ArraySpecifier'
+  typeSpecifier: Identifier
+  dimensions: (Literal | Identifier | null)[]
 }
 ```
 
-#### VariableDeclarator
+### Program
 
-A single named declarator as part of a `VariableDeclaration`.
+Represents the root of an AST.
 
 ```ts
-class VariableDeclarator {
-  name: string
-  value: AST | null
+interface Program extends Node {
+  type: 'Program'
+  body: Statement[]
 }
 ```
 
-### StructDeclaration
+### ExpressionStatement
 
-A struct declaration. Can be used as a type or constructor.
+An expression as a standalone statement.
 
 ```ts
-class StructDeclaration {
-  name: string
-  members: VariableDeclaration[]
+interface ExpressionStatement extends Node {
+  type: 'ExpressionStatement'
+  expression: Expression
 }
 ```
 
-### FunctionDeclaration
+### BlockStatement
 
-A function declaration with an optional type qualifier and arguments.
+A block statement.
 
 ```ts
-class FunctionDeclaration {
-  name: string
-  type: Type | Identifier
-  qualifiers: string[]
-  args: VariableDeclaration[]
-  body: BlockStatement | null
+interface BlockStatement extends Node {
+  type: 'BlockStatement'
+  body: Statement[]
 }
 ```
 
-### UnaryExpression
+### DiscardStatement
 
-A unary expression with a left or right handed operator.
+A discard statement in fragment shaders.
 
 ```ts
-class UnaryExpression {
-  operator: string
-  left: AST | null
-  right: AST | null
+interface DiscardStatement extends Node {
+  type: 'DiscardStatement'
 }
 ```
 
-### BinaryExpression
+### PreprocessorStatement
 
-A binary expression with a left and right operand.
+A GLSL preprocessor statement with an optional value.
 
 ```ts
-class BinaryExpression {
-  operator: string
-  left: AST
-  right: AST
+interface PreprocessorStatement extends Node {
+  type: 'PreprocessorStatement'
+  name: string
+  value: Expression[] | null
 }
 ```
 
-### TernaryExpression
+### PrecisionStatement
 
-A ternary or conditional expression.
+A GLSL precision statement.
 
 ```ts
-class TernaryExpression {
-  test: AST
-  consequent: AST
-  alternate: AST
+interface PrecisionStatement extends Node {
+  type: 'PrecisionStatement'
+  precision: PrecisionQualifier
+  typeSpecifier: Identifier
 }
 ```
 
-### CallExpression
+### ReturnStatement
 
-A call expression.
+A return statement with an optional argument.
 
 ```ts
-class CallExpression {
-  callee: AST
-  args: AST[]
+interface ReturnStatement extends Node {
+  type: 'ReturnStatement'
+  argument: Expression | null
 }
 ```
 
-### MemberExpression
+### BreakStatement
 
-A member expression.
+A break statement.
 
 ```ts
-class MemberExpression {
-  object: AST
-  property: AST
+interface BreakStatement extends Node {
+  type: 'BreakStatement'
 }
 ```
 
-### ArrayExpression
+### ContinueStatement
 
-An array expression. `members` can be empty if uninitialized.
+A continue statement.
 
 ```ts
-class ArrayExpression {
-  type: Type
-  members: AST[]
+interface ContinueStatement extends Node {
+  type: 'ContinueStatement'
 }
 ```
 
-### BlockStatement
+### IfStatement
 
-A block statement.
+An if-else statement.
 
 ```ts
-class BlockStatement {
-  body: AST[]
+interface IfStatement extends Node {
+  type: 'IfStatement'
+  test: Expression
+  consequent: Statement
+  alternate: Statement | null
 }
 ```
 
-### IfStatement
+### SwitchStatement
 
-An if statement.
+A switch statement.
 
 ```ts
-class IfStatement {
-  test: AST
-  consequent: AST
-  alternate: AST | null
+interface SwitchStatement extends Node {
+  type: 'SwitchStatement'
+  discriminant: Expression
+  cases: SwitchCase[]
 }
 ```
 
-### ForStatement
+#### SwitchCase
 
-A for statement.
+A switch-case statement. `test` is null for a `default` case.
 
 ```ts
-class ForStatement {
-  init: AST | null
-  test: AST | null
-  update: AST | null
-  body: AST
+interface SwitchCase extends Node {
+  type: 'SwitchCase'
+  test: Expression | null
+  consequent: Statement[]
 }
 ```
 
@@ -438,9 +455,10 @@ class ForStatement {
 A while statement.
 
 ```ts
-class WhileStatement {
-  test: AST
-  body: AST
+interface WhileStatement extends Node {
+  type: 'WhileStatement'
+  test: Expression
+  body: Statement
 }
 ```
 
@@ -449,86 +467,265 @@ class WhileStatement {
 A do-while statement.
 
 ```ts
-class DoWhileStatement {
-  test: AST
-  body: AST
+interface DoWhileStatement extends Node {
+  type: 'DoWhileStatement'
+  body: Statement
+  test: Expression
 }
 ```
 
-### SwitchStatement
+### ForStatement
 
-A switch statement.
+A for statement.
 
 ```ts
-class SwitchStatement {
-  discriminant: AST
-  cases: SwitchCase[]
+interface ForStatement extends Node {
+  type: 'ForStatement'
+  init: VariableDeclaration | Expression | null
+  test: Expression | null
+  update: Expression | null
+  body: Statement
 }
 ```
 
-#### SwitchCase
+### FunctionDeclaration
 
-A switch-case statement. `test` is null for a `default` case.
+A function declaration. `body` is null for overloads.
 
 ```ts
-class SwitchCase {
-  test: AST | null
-  consequent: AST[]
+interface FunctionDeclaration extends Node {
+  type: 'FunctionDeclaration'
+  id: Identifier
+  qualifiers: PrecisionQualifier[]
+  typeSpecifier: Identifier | ArraySpecifier
+  params: FunctionParameter[]
+  body: BlockStatement | null
 }
 ```
 
-### ReturnStatement
+#### FunctionParameter
 
-A return statement with an optional argument.
+A function parameter within a function declaration.
 
 ```ts
-class ReturnStatement {
-  argument: Literal | Identifier | UnaryExpression | null
+interface FunctionParameter extends Node {
+  type: 'FunctionParameter'
+  id: Identifier
+  qualifiers: (ConstantQualifier | ParameterQualifier | PrecisionQualifier)[]
+  typeSpecifier: Identifier | ArraySpecifier
 }
 ```
 
-### PreprocessorStatement
+### VariableDeclaration
 
-A GLSL preprocessor statement with an optional value.
+A variable declaration.
 
 ```ts
-class PreprocessorStatement {
-  name: string
-  value: AST[] | null
+interface VariableDeclaration extends Node {
+  type: 'VariableDeclaration'
+  declarations: VariableDeclarator[]
 }
 ```
 
-### PrecisionStatement
+#### VariableDeclarator
 
-A GLSL precision statement.
+A variable declarator within a variable declaration.
 
 ```ts
-class PrecisionStatement {
-  precision: 'lowp' | 'mediump' | 'highp'
-  type: Type
+interface VariableDeclarator extends Node {
+  type: 'VariableDeclarator'
+  id: Identifier
+  qualifiers: (ConstantQualifier | InterpolationQualifier | StorageQualifier | PrecisionQualifier)[]
+  typeSpecifier: Identifier | ArraySpecifier
+  layout: Record<string, string | boolean> | null
+  init: Expression | null
 }
 ```
 
-### ContinueStatement
+### UniformDeclarationBlock
 
-A continue statement.
+A uniform declaration block with optional layout and qualifiers.
 
 ```ts
-class ContinueStatement {}
+interface UniformDeclarationBlock extends Node {
+  type: 'UniformDeclarationBlock'
+  id: Identifier | null
+  qualifiers: LayoutQualifier[]
+  typeSpecifier: Identifier | ArraySpecifier
+  layout: Record<string, string | boolean> | null
+  members: VariableDeclaration[]
+}
 ```
 
-### BreakStatement
+### StructDeclaration
 
-A break statement.
+A struct declaration. Can be used as a type or constructor.
 
 ```ts
-class BreakStatement {}
+interface StructDeclaration extends Node {
+  type: 'StructDeclaration'
+  id: Identifier
+  members: VariableDeclaration[]
+}
 ```
 
-### DiscardStatement
+### ArrayExpression
+
+An array initialization expression.
+
+```ts
+interface ArrayExpression extends Node {
+  type: 'ArrayExpression'
+  typeSpecifier: ArraySpecifier
+  elements: Expression[]
+}
+```
+
+### UnaryExpression
+
+A unary expression with a left or right handed operator.
+
+```ts
+interface UnaryExpression extends Node {
+  type: 'UnaryExpression'
+  operator: UnaryOperator
+  prefix: boolean
+  argument: Expression
+}
+```
+
+#### UnaryOperator
+
+```ts
+type UnaryOperator = '-' | '+' | '!' | '~'
+```
+
+### UpdateExpression
+
+An update expression with an optionally prefixed operator.
+
+```ts
+interface UpdateExpression extends Node {
+  type: 'UpdateExpression'
+  operator: UpdateOperator
+  argument: Expression
+  prefix: boolean
+}
+```
+
+#### UpdateOperator
+
+```ts
+type UpdateOperator = '++' | '--'
+```
+
+### BinaryExpression
+
+A binary expression with a left and right operand.
+
+```ts
+interface BinaryExpression extends Node {
+  type: 'BinaryExpression'
+  operator: BinaryOperator
+  left: Expression
+  right: Expression
+}
+```
 
-A discard statement.
+#### BinaryOperator
 
 ```ts
-class DiscardStatement {}
+type BinaryOperator =
+  | '=='
+  | '!='
+  | '<'
+  | '<='
+  | '>'
+  | '>='
+  | '<<'
+  | '>>'
+  | '+'
+  | '-'
+  | '*'
+  | '/'
+  | '%'
+  | '|'
+  | '^'
+  | '&'
+```
+
+### AssignmentExpression
+
+An assignment expression.
+
+```ts
+interface AssignmentExpression extends Node {
+  type: 'AssignmentExpression'
+  operator: AssignmentOperator
+  left: Expression
+  right: Expression
+}
+```
+
+#### AssignmentOperator
+
+```ts
+type AssignmentOperator = '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '<<=' | '>>=' | '>>>=' | '|=' | '^=' | '&='
+```
+
+### LogicalExpression
+
+A logical operation between two expressions.
+
+```ts
+interface LogicalExpression extends Node {
+  type: 'LogicalExpression'
+  operator: LogicalOperator
+  left: Expression
+  right: Expression
+}
+```
+
+#### LogicalOperator
+
+```ts
+type LogicalOperator = '||' | '&&' | '^^'
+```
+
+### MemberExpression
+
+A member expression.
+
+```ts
+interface MemberExpression extends Node {
+  type: 'MemberExpression'
+  object: Expression
+  property: Expression
+  computed: boolean
+}
+```
+
+### ConditionalExpression
+
+A conditional expression or ternary.
+
+```ts
+interface ConditionalExpression extends Node {
+  type: 'ConditionalExpression'
+  test: Expression
+  alternate: Expression
+  consequent: Expression
+}
+```
+
+### CallExpression
+
+A function call expression or struct initialization.
+
+```ts
+interface CallExpression extends Node {
+  type: 'CallExpression'
+  callee: Expression
+  arguments: Expression[]
+}
 ```

package/dist/index.d.ts

@@ -1 +1 @@
-export * from '../src'
+export * from '../src/index.ts'